Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows-optional/warm-cache.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Warm cache

# OPT-IN. Move this file into .github/workflows/ to use it.
#
# GitHub lets a PR read caches saved on main but not caches saved by another
# PR, and CI only runs on PRs. This job saves a cache from main, so the PR
# runs in ci.yml find it. Use it when a job downloads something slow or large
# on every run (dependencies, a browser, a toolchain).
#
# Fill in the two placeholders. The cache path and key must match the
# actions/cache step in ci.yml exactly, or the PRs never hit this cache.
on:
push:
branches: [main]
paths: [LOCKFILE]
schedule:
# Caches unused for 7 days are dropped; refresh twice a week.
- cron: '17 4 * * 1,4'
workflow_dispatch:

permissions:
contents: read

jobs:
warm:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7

- name: Cache
id: cache
uses: actions/cache@v6
with:
path: PATH_TO_CACHE
key: cache-${{ runner.os }}-${{ hashFiles('LOCKFILE') }}

- name: Fill the cache
if: steps.cache.outputs.cache-hit != 'true'
run: YOUR_COMMAND_THAT_DOWNLOADS_INTO_PATH_TO_CACHE
78 changes: 68 additions & 10 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
name: CI

# push to main is kept so a fresh repo gets a first run. If you adopt the
# solo-maintainer auto-merge workflows (README.md), drop the push trigger: with
# "require branches to be up to date" every PR is tested against current main
# before it merges, so a second run after the merge tests the same code again.
# PRs only: with strict branch protection every PR is tested against current
# main before it merges, so a run on push to main would test the same code
# again. If you do not use strict protection, add this back under `on:` so a
# fresh repo gets a first run:
# push:
# branches: [main]
on:
push:
branches: [main]
pull_request:
branches: [main]

Expand All @@ -15,11 +15,69 @@ concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

# Stack-neutral repo hygiene checks only. Add your project's own
# format/lint/typecheck/test/build job(s) alongside this once the stack is
# chosen; that is a separate job so this one keeps working with no stack at
# all.
# Layout:
# - changes: says whether the PR touches anything besides docs and Markdown.
# - repo-hygiene: stack-neutral checks, always runs.
# - your own jobs: add them with the `needs`/`if` lines of the example below,
# so a docs-only PR skips them and clears in seconds.
# - checks: the one required status check. It passes when every job it needs
# passed or was skipped. Branch protection names only this job, so adding or
# renaming a stack job never means touching the protection rules.
jobs:
changes:
runs-on: ubuntu-latest
permissions:
pull-requests: read
outputs:
code: ${{ steps.diff.outputs.code }}
steps:
- id: diff
env:
GH_TOKEN: ${{ github.token }}
PR: ${{ github.event.pull_request.number }}
run: |
files=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR}/files" --paginate --jq '.[].filename')
if printf '%s\n' "$files" | grep -qvE '^docs/|\.md$'; then
echo "code=true" >> "$GITHUB_OUTPUT"
else
echo "code=false" >> "$GITHUB_OUTPUT"
fi

# Example stack job, to copy once the stack is chosen. Add its name to the
# `needs` list of `checks` below.
#
# build:
# needs: changes
# if: needs.changes.outputs.code == 'true'
# runs-on: ubuntu-latest
# steps:
# - uses: actions/checkout@v7
# # Setup, install, then format/lint/typecheck/test/build for your stack.
# #
# # Caching a slow-to-fetch dependency or tool: restore it with
# # actions/cache and a key from your lockfile. A PR can read caches
# # saved on main but not caches saved by another PR, so also add
# # workflows-optional/warm-cache.yml with the same key.
# - uses: actions/cache@v6
# with:
# path: PATH_TO_CACHE
# key: cache-${{ runner.os }}-${{ hashFiles('LOCKFILE') }}
# - run: YOUR_BUILD_AND_TEST_COMMAND

checks:
needs: [changes, repo-hygiene]
if: always()
runs-on: ubuntu-latest
steps:
- name: All jobs passed or were skipped
env:
RESULTS: ${{ join(needs.*.result, ' ') }}
run: |
echo "results: $RESULTS"
case "$RESULTS" in
*failure*|*cancelled*) exit 1 ;;
esac

repo-hygiene:
runs-on: ubuntu-latest
steps:
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ node_modules/
dist/
coverage/
*.tsbuildinfo
__pycache__/
playwright-report/
test-results/

# Logs and temp
*.log
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ All notable changes to this project are documented here. The format is based on

### Added

- CI: `changes` job so docs-only PRs skip stack jobs, a single required
`checks` job, a commented cache example, and an opt-in `warm-cache.yml`.
- Hints in `CLAUDE.md`, `CONTRIBUTING.md`, `.gitignore` and the handoff
template.
- Initial project harness: issue and PR templates, contribution and security
policies, docs structure (design, decisions, handoffs), and Claude Code
working rules.

### Changed

- `ci.yml` runs on pull requests only; `bootstrap-repo-settings.sh` gates on
`checks` by default.
11 changes: 7 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,17 @@ under `src/core/` so it is unit-testable"). Link to the relevant ADR(s) in
## Commands

{{The everyday commands: run, test, lint/typecheck, build. One line each, and
mark which ones are gates (non-zero exit blocks a merge). Fill in once the
stack is chosen; `CONTRIBUTING.md` Setup should match.}}
mark which ones are gates (non-zero exit blocks a merge). Say how long the
slow ones take and which ones CI skips, so nobody runs a 20 minute suite by
accident. Fill in once the stack is chosen; `CONTRIBUTING.md` Setup should
match.}}

## Repo structure

{{Optional: a short map of top-level directories, only if it adds real
orientation beyond exploring the tree. Keep it brief and expect it to drift;
when in doubt, explore the tree rather than trusting this section.}}
orientation beyond exploring the tree. State layering rules here too, such as "`core/` never imports from `ui/`".
Keep it brief and expect it to drift; when in doubt, explore the tree rather
than trusting this section.}}

## Working rules

Expand Down
7 changes: 6 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,12 @@ The workflow is:

## Setup

TODO: setup and local-run instructions once the stack is chosen.
TODO: setup and local-run instructions once the stack is chosen. A good shape:

- Prerequisites (tool and version).
- A short block that installs, runs, and checks. Make its last line the
command CI runs, and say so.
- Pointers to `CLAUDE.md` for anything stack-specific or slow.

## Conventions

Expand Down
25 changes: 17 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,16 @@ and Claude Code working rules (`CLAUDE.md`, `.claude/settings.json`).
`.github/workflows/ci.yml`, alongside the existing stack-neutral
`repo-hygiene` job (markdown lint, no-em-dash check, docs-structure
check, workflow lint). Do not replace that job; add another one next to
it.
it, copying the commented example, and add its name to the `needs` list
of the `checks` job. The `changes` job lets a docs-only PR skip it.
- Add a `package-ecosystem` entry to `.github/dependabot.yml` for your
package manager (see the commented example there).
7. Run `scripts/bootstrap-repo-settings.sh` once (requires the GitHub CLI,
authenticated with admin access on the new repo) to set branch protection
on `main`, enable auto-merge, and create the starter label set. Templates
do not carry repo settings over, only files, so this step is manual.
Pass your CI job names as extra arguments (for example
`scripts/bootstrap-repo-settings.sh owner/repo repo-hygiene build`) once
you have added your stack's job; the default gates on `repo-hygiene` only.
It gates on the single `checks` job of `ci.yml`, which collects all the
others, so adding a stack job later needs no change to branch protection.
Note this only lets a PR *request* auto-merge; someone still has to click
it. For a solo-maintainer repo, see "Solo-maintainer auto-merge" below.
8. Add your first ADR to `docs/decisions/` (see `docs/decisions/README.md`
Expand All @@ -60,9 +60,17 @@ One-time setup: create a fine-grained personal access token for this repo only
(Contents, Pull requests and Workflows: read/write) and store it as the
`AUTO_MERGE_TOKEN` secret. `GITHUB_TOKEN` cannot be used because GitHub starts
no workflows for pushes or merges made with it, so the PR's checks would never
run on the updated branch. Rotate the PAT before it expires. Then drop the
`push` trigger from `ci.yml`: with strict protection every PR is tested against
current `main` before it merges.
run on the updated branch. Rotate the PAT before it expires. `ci.yml` already
runs on PRs only: with strict protection every PR is tested against current
`main` before it merges.

## Cache warming (optional)

`.github/workflows-optional/warm-cache.yml` saves a cache from `main`, because
a PR can read caches saved on `main` but not caches saved by another PR. Use it
if a CI job downloads something slow on every run. Move it into
`.github/workflows/`, fill in the two placeholders, and use the same path and
key in the `actions/cache` step of your CI job.

## What's included

Expand All @@ -75,7 +83,8 @@ current `main` before it merges.
- `docs/handoffs/`: session handoff template for continuity between work
sessions.
- `.github/`: issue forms, PR template, Dependabot config, a stack-neutral CI
workflow, and optional solo-maintainer auto-merge workflows.
workflow (docs-only PRs skip stack jobs, one required `checks` status), and
optional solo-maintainer auto-merge and cache-warming workflows.
- `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, `LICENSE`.
- `scripts/bootstrap-repo-settings.sh`: one-time repo settings setup (branch
protection, auto-merge, labels) that a template cannot carry over on its
Expand Down
2 changes: 2 additions & 0 deletions docs/handoffs/HANDOFF_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Session Handoff: YYYY-MM-DD

<!-- Open the handoff PR in the same session. The next session starts by reading the latest file in this folder. -->

## Summary

One short paragraph: what this session was about and where things stand.
Expand Down
10 changes: 5 additions & 5 deletions scripts/bootstrap-repo-settings.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@
#
# Usage: scripts/bootstrap-repo-settings.sh [owner/repo [check ...]]
# If owner/repo is omitted, it is inferred from the current git remote.
# Each check is the name of a CI job that must pass before a PR can merge;
# the default is "repo-hygiene". Once you add your stack's own job (README.md
# step 6), re-run with both, e.g.:
# scripts/bootstrap-repo-settings.sh owner/repo repo-hygiene build
# Each check is the name of a CI job that must pass before a PR can merge.
# The default is "checks", the job in ci.yml that gathers all the others, so
# adding a stack job needs no re-run; list other names only if you want
# protection on them directly.

set -euo pipefail

REPO="${1:-$(gh repo view --json nameWithOwner --jq .nameWithOwner)}"
shift || true
CHECKS=("$@")
[ ${#CHECKS[@]} -gt 0 ] || CHECKS=(repo-hygiene)
[ ${#CHECKS[@]} -gt 0 ] || CHECKS=(checks)
CONTEXTS=$(printf '"%s",' "${CHECKS[@]}")
CONTEXTS="[${CONTEXTS%,}]"
echo "Bootstrapping settings for $REPO"
Expand Down
Loading