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
109 changes: 20 additions & 89 deletions .agents/skills/github-prs/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,106 +1,37 @@
---
name: github-prs
description: How every agent verifies and attests locally (`make ci-local RAN="…"`), opens, stacks and merges pull requests in this repo, fast. Use before any `git commit`, `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, or re-running a check, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time".
description: How every agent opens, stacks and merges pull requests in this repo, after verifying with the local-ci skill. Use before any `gh pr create`, `gh pr merge`, retargeting or rebasing a stacked PR, and whenever you are about to wait on CI, write a merge script, or merge PRs "one at a time".
---

# Pull requests: run what you need, attest, stack, merge at once
# Pull requests

Run the checks your change needs (lint, tests, build), then attest with `make ci-local RAN="…"` and merge right away. `make ci-local` runs nothing: it tells the PR you checked, and what. GitHub runs no verification on `main`, and on a PR only two small jobs that check the attestation. Stack PRs and merge each the moment it is attested; after the merge, check its staging deploy.
Verify and attest first: the [local-ci](../local-ci/SKILL.md) skill.

The rules on what may merge are in `AGENTS.md` ("Verifying", "Pull requests", "Environments: staging is always current"). This skill is how you do it.
## Open

## 1. Before every commit
- `gh pr create --base <base>` from `.github/pull_request_template.md`, ready (never draft), no labels.
- Title: a conventional commit in plain language (`fix(api): PATCH /users no longer drops the image`). Body: the problem in a sentence or two, then the fix; UI changes need before/after images. The body ends with the attribution line.
- One concern per PR; push follow-ups to the same branch. Never close and reopen a PR.

- **Never skip the hooks.** `make hooks` installs the pre-push hook (`make check-fast`); when it fails, fix what it found and push again; never skip it.
- **Default: `make check-pr`.** It runs what the branch's changes need (the table is in `scripts/check-pr.sh`), fails when the affected-package selection does not match the diff, and prints the `make ci-local RAN="…"` line to attest with. By hand: `make lint LINT_DIRS=<dirs>` and `make test TEST_PKGS=<pkgs>` for the Go packages it can affect (`scripts/affected.sh` prints them; `make check-fast` is the seconds-long pass), `make check-generated` for sqlc, templ or mock inputs, `make check-migrations` for a migration, `make deploy-check` for `deploy/`, `make actionlint` for workflows, `make release-smoke` for a Dockerfile or what it builds, `make ci` for a change to the tooling. In a Davit box, `make box-ci COMMIT=<sha>` runs check-generated, lint, build and test on exactly that commit and prints one PASS/FAIL line; never hand-write an inline `davit box run -- bash -lc "... rm ..."`. Tests only at the test boundaries (`AGENTS.md`, "Test boundaries"); never a test in `deploy/` or the UI.
- A change adds no lint or format findings, warnings included.
- Add the paths you changed; never `git add -A` in an old worktree.
## Stack

## 2. Attest: `make ci-local RAN="…"`
- Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch.
- `make pr-merge` retargets children to `main` before their parent merges. Then `git rebase --onto origin/main <old parent head> <child>`, `git push --force-with-lease`, attest.

After **every** push or rebase, once you have run what the change needs:
## Merge

```bash
git push # pushed head, clean worktree
make check-pr # runs what the change needs, prints the RAN line
make ci-local RAN="make lint LINT_DIRS='./apps/web/internal/services ...'; make test TEST_PKGS='...'; make secret-scan"
```

- It runs nothing and takes seconds. It refuses a dirty worktree, a detached HEAD (except `COMMIT=<sha>` of a `main` commit), a head that is not the pushed branch head, or a head that already has a failed `local-ci`.
- It posts `local-ci` on that exact SHA and fills the PR body's **Local verification** section (head, who, and your statement). **Never edit the section by hand:** the status carries its digest.
- **One attestation, one commit.** Any push, amend or rebase needs a new one. No PR yet? Open it (section 3) and run it again.
- **Something failed?** Fix it before attesting. If you attest a failure (`make ci-local FAILED="<what>"`), that head is final: fix forward with a new commit. Code this PR touched: fix it here. Anything else: its own PR off `main` with a test that fails before the fix, then rebase. Add the prevention.
- Say exactly what ran; a reviewer reads the scope from it.

## 3. Open and stack

- `gh pr create --base <base>` with `.github/pull_request_template.md`, open and ready, no labels: problem, fix, and the Local verification section. Conventional commit title; the body ends with the attribution line.
- **Base per layer.** Needs nothing unmerged: base `main`. Needs an open PR: base that PR's branch. Independent work gets its own PR on `main`.
- One concern per PR; push follow-ups to the same branch. **Never close and reopen a PR.**

## 4. What PR CI and the merge script refuse

PR CI runs only `Secret scan` and `Local verification`, the two checks the main ruleset requires, on the `CI_RUNNER` runner. It runs only on a PR body edit, and until `make ci-local` claims the head (posts `local-ci` or fills the section for it) the check runs as `Awaiting make ci-local`, so the required one shows **Expected**, not red; red is a real problem. `Local verification` and `make pr-merge` share one rule (`scripts/cilocal/verify`, `LocalVerificationProblems`):

| Refused because | Fix |
|---|---|
| no `local-ci` status on the head (never attested, or a new push) | run what it needs, `make ci-local RAN="…"` |
| `local-ci` is `failure`, or failed on this head before | fix forward with a new commit, push, attest |
| no Local verification section, it names another head or no "Ran:" | `make ci-local RAN="…"` |
| the section is not the attested one (edited by hand) | `make ci-local RAN="…"` again restores it |
| `Secret scan` found a credential | remove it (rotate it if real), push, attest |
| it conflicts with `main` | rebase onto `main`, push, attest |

`make ci-local` posts the status before it edits the body, and that edit starts the PR run, so you never re-run `Local verification` by hand; when the body was already current, `make ci-local` re-runs the run itself.

## 5. Merge

```bash
make pr-merge PR="<PR> [<PR> ...]" # merges every green PR now, reports the rest
make pr-merge PR="<PR> [<PR> ...]" # merges every attested, green PR now, reports the rest
make pr-merge PR=<PR> ARGS=--dry-run # says what it would do
make land PR=<PR> # rebase, make ci-pg, attest and merge inside one hold of the CI lock
```

- **Green** means `local-ci` and the section attest the exact head, GitHub can merge it without conflicts, and the checks passed. It squash-merges with `--match-head-commit <head>`, so only the attested head lands. A head behind `main` is refused ("rebase onto origin/main and re-attest"): the merged tree must be the one you verified. Where Actions cannot run (no CI job ran, or GitHub never started them), it merges on `local-ci` alone and says so.
- Anything else (draft, unattested, pending, failing, conflicting, stacked) is reported with its next step; the script never waits. A head behind `main` or a conflict needs rebase, push, run what it needs, attest; after each merge in a burst, rebase the next PR.
- **After each merge, check its deploy** (a follow-up, never a gate; merge the next PR now): it prints `make pr-merge ARGS="--check-deploy <squash sha>"`. Run it once "Deploy staging" has run for that commit. Failed or refused: top priority, fix forward. Cancelled by a newer main deploy: `make pr-merge ARGS=--check-staging` checks main's head. A dry run (`RAILWAY_DEPLOY` not `true`) deployed nothing. With Actions off, it reads what Railway runs instead: deploy with `make railway-up PLATFORM_ENV=staging` from a clean checkout of the commit, which records it. After a burst, `ARGS=--then-check-staging` follows main's deploy (bounded).
- **Stacked children** are retargeted to `main` before their parent merges. Then `git rebase --onto origin/main <old parent head> <child>`, `git push --force-with-lease`, attest.
- Integration branches (`feat/<x>`): `make pr-merge PR=<PR> ARGS=--any-base`.
- Never `gh pr merge --delete-branch`: it closes every PR stacked on the branch and deletes any worktree holding it. Never write your own merge or queue script; change `scripts/cilocal` (rules and tests in `scripts/cilocal/verify`).
- **Admin bypass** only when the developer authorized it and a GitHub check is red for a reason outside the code, and only after `make ci-local RAN="…"` attested the head: `gh pr merge <n> --squash --admin --match-head-commit <sha>`, then a PR comment "Authorized by <who>, merged by <agent>" with the attestation.

## 6. Checks that fail outside the code

- **Lost runner** ("lost communication with the server", "received a shutdown signal", "The operation was canceled.", a timeout with no log): `gh run rerun <run id> --failed`, once, by hand. Nothing re-runs it automatically.
- **Actions blocked** (billing or a spending limit: "The job was not started because…"): those jobs count as not run; `make pr-merge` merges on `local-ci` alone.
- A real failure belongs to the PR's owner; the rest of the burst doesn't wait for it.
- One read per question (`gh pr checks <n>`, `gh run view <id> --json jobs`), never a polling loop.

## 7. Staging deploys itself

`main` runs no CI. "Deploy staging" deploys a push to Railway staging only when `make ci-local` attested it (`cilocal attest`): the squash of an attested PR head, or a commit with its own `local-ci`. `make pr-merge` refuses a head behind `main`, so every squash is a tree someone verified. The hourly "Staging catch-up" deploys `main` whenever staging is behind and `main` is attested. Never wait for a deploy or for another PR to settle: merge each PR when its own head is attested and conflict-free, and stack the next at once; check its deploy afterwards (section 5); "Post-merge report" comments on the PR when a push workflow on its commit fails. A failed deploy is fixed forward in parallel and blocks no unrelated merge.

An unattested `main` is the top priority: both workflows fail and say why. Fix it forward: `git worktree add --detach <dir> <sha>`, run what the commits since the last attested one need (`make ci` when there is none, as in a new project's first attestation), then `make ci-local COMMIT=<sha> RAN="…"` there. It refuses a dirty tree, a commit off `origin/main` or one that already failed, and posts `local-ci` on the commit; then dispatch "Deploy staging".

## 8. Waiting without losing the work

- **Never end a turn while your own wait, watcher or helper still runs.** Register it (`t3_background_wait`) or wait for it.
- **Never `pgrep -f`, `pkill -f` or kill a process found by name**; wait on a PID captured at spawn or the background task's ID.
- A background command from a T3 tool call dies with that tool's scope and has a two-hour limit. A merge never needs one.

## Rules and what enforces them

| Rule | Enforced by |
|---|---|
| Every PR is attested on its exact head | `Local verification` (`ci.yml`) and `verify.Decide`, through `verify.LocalVerificationProblems`; a skipped `Secret scan` is never green |
| The section is the script's, never hand-edited | the section digest in the `local-ci` status |
| Merge only the verified head, never a conflict | `--match-head-commit` and the conflict refusal in `make pr-merge` |
| Staging deploys only an attested PR head or commit | `cilocal attest` in Deploy staging's plan, `verify.Attestation` and its test |
| Merge every green PR at once; stacks survive | `make pr-merge` (no wait path, retargets children), `scripts/cilocal/verify/merge_test.go` |
| A push workflow that fails on main is reported | `Post-merge report`; a verify test fails when a push-to-main workflow is missing from its list |
| Never skip the pre-push hook, no reopen, no `pgrep -f` | this skill only; add a check if an agent repeats one |
- Merge only with `make pr-merge` (or `make land`). Never `gh pr merge` (`--delete-branch` closes every PR stacked on the branch) and never your own merge or queue script.
- It never waits: anything not mergeable is reported with its next step. Merge each PR the moment it is attested; never wait for another PR or a deploy.
- Integration branches (`feat/<x>`): `ARGS=--any-base`.
- Admin bypass only when the developer authorized it, after `make ci-local` attested the head: `gh pr merge <n> --squash --admin --match-head-commit <sha>`, then comment "Authorized by <who>, merged by <agent>".

## Done means
## After the merge

- Every PR you were asked to land is merged, or reported with its blocker and next step.
- Every PR you pushed to is attested on its current head, and each merge's staging deploy was checked.
- No PR was closed and reopened, and no hooks were skipped.
- Once "Deploy staging" has run, check it once with the command `make pr-merge` prints: `make pr-merge ARGS="--check-deploy <squash sha>"`. One read, never a polling loop.
- **A failed staging deploy, or an unattested `main` staging refuses, is the top priority.** Fix it forward before merging anything else: attest `main` (local-ci, "An unattested `main` commit"), then `gh workflow run deploy-staging.yml --ref main`.
21 changes: 21 additions & 0 deletions .agents/skills/local-ci/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
name: local-ci
description: Every CI check in this repo runs locally; GitHub Actions is never what you wait on. Use before any commit, push or PR, and whenever asked to "run CI" or check that a change passes.
---

# Local CI

Every check runs on your machine (or a Davit box). GitHub only checks that you attested them.

1. **Before every push: `make check-fast`.** The pre-push hook runs it (`make hooks`). Fix what it finds; never skip the hook. A change adds no lint or format findings, warnings included.
2. **Run what the change needs: `make check-pr`.** It picks the checks from the diff, stops at the first failure, and prints the `make ci-local RAN="…"` line. `ARGS=--dry-run` only lists them. A user-visible UI change also gets one pass in a real browser against a running `make dev`.
3. **Attest the pushed head: `make ci-local RAN="…"`.** Commit, push, then run it in the clean worktree. It runs nothing: it posts `local-ci` on the exact SHA and fills the PR's "Local verification" section. Every push or rebase needs a new attestation; no PR yet, open it and attest again. Never edit that section by hand.
4. **A failed head is final.** Never attest a red head. `make ci-local FAILED="<what>"` marks it failed for good. Fix forward with a new commit: in this PR if this branch caused it, otherwise in its own PR off `main`.
5. **Never rerun remotely what you ran locally.** No GitHub Actions run, no `gh workflow run` and no "re-run checks" as verification. The only remote checks are the attestation and the secret scan, and they take seconds.
6. **Busy machine: `make box-ci COMMIT=<sha>`.** The one exception: when a heavy check reports every slot busy, or for a long suite, it runs check-generated, lint, build and test on that commit in a Davit box, instead of locally, never in addition. Attest the `PASS` line it prints. With no Docker, `make ci-pg` runs `make ci` on a throwaway Postgres.

**An unattested `main` commit:** `git worktree add --detach <dir> <sha>`, run what the commits since the last attested one need (`make ci` when there is none), then `make ci-local COMMIT=<sha> RAN="…"` there.

Tests only at the test boundaries (`AGENTS.md`, "Test boundaries").

Opening, stacking and merging PRs: the [github-prs](../github-prs/SKILL.md) skill.
Loading
Loading