The loop

This is the core standard. Everything else supports it.

One work item = one issue = one worktree = one branch = one PR.

If you are an agent picking up work with no other context, this document plus the work item’s spec is enough to complete it.

Why the loop is shaped this way

The failure mode being designed against is confident false completion — reporting success that wasn’t achieved. Every step below exists to make “done” machine-checkable rather than self-assessed.

Two corollaries that explain most of the specifics:

The gate decides, not you. Your own assessment of whether the work is finished carries no weight. The gate’s exit code does.
A slice you can’t verify in one iteration is a slice you will drift on. Hence vertical slices, hence small work items.

The steps

0. Pick

Take the lowest-numbered item with label status:ready whose dependencies are all closed.

gh issue list --label status:ready --json number,title,labels

Do not pick an item labelled status:blocked, needs:human, or needs:adr.

1. Spec

Write or refine docs/work/WI-###-slug.md following the template in work-items.md. It must contain:

The problem, in a sentence
In scope / out of scope — the second is as important as the first
A Definition of Done as a checklist, each line independently checkable
The exact verification commands a reviewer can run

If the item is size:L, label it needs:spec-review and stop — a human reads the spec before any code is written.

2. Branch

git worktree add ../wt-wi-### -b wi-###-slug
gh issue edit ### --add-label status:in-progress --remove-label status:ready

Work in the worktree. Never on main.

3. Red

Write the failing test(s) that encode the Definition of Done. Commit them failing.

This is not ceremony. A test written after the implementation tends to assert what the code does; a test written before asserts what the code should do. The commit history should show the red.

4. Green

Make the smallest change that passes. No unrelated refactors, no opportunistic cleanups, no “while I’m here”. Those are separate work items.

5. Verify

Run the full gate locally — see ci-and-gates.md.

pnpm turbo lint typecheck test build
pnpm --filter db exec drizzle-kit check

Not “it looks right”. Not “the change is straightforward”. The gate.

6. Document

Update the docs subsite page(s) affected. Write an ADR if you made a decision — see decisions.md.

Docs ship in this PR, not a follow-up. The docs-diff gate step enforces this; the reason behind it is that a documentation follow-up PR is a documentation PR that doesn’t get written.

7. Review

Self-review pass before asking for a human’s attention:

Anything here that duplicates something that already exists?
Anything simpler that would pass the same tests?
Anything left in that step 4 said not to do?
Does the diff match the spec’s scope, including its out-of-scope list?

Re-run the gate after any change.

8. PR

gh pr create --fill --label status:in-review

The body must carry evidence, following .github/pull_request_template.md:

Gate output, pasted
The DoD checklist, each line ticked with proof — the test name, the command, the output
A link to the docs diff

Adjectives are not evidence. “Works correctly”, “fully tested” and “handles all cases” tell a reviewer nothing. A test name tells them something.

9. Merge

A human reviews and merges. Agents never push to main and never merge — see ADR-0015.

10. Retro

If you got a platform fact wrong during this item — a Cloudflare binding, a Clerk tier, an Expo constraint — add one line to AGENTS.md. That is the learning loop: the fix for a repeated mistake is a line in AGENTS.md, not a comment in the code.

Then close the issue.

Stop conditions

Halt and ask. Do not decide.

Condition	What to do
A fork with no ADR covering it	Draft the ADR as `Proposed`, label the item `needs:adr`, stop
The Definition of Done itself needs to change	The spec was wrong. That’s a human call — label `needs:spec-review`, stop
The gate fails three times for the same reason	Stop and report. No thrash loops
Anything needing money, credentials, or an external human	See agent-boundaries.md

The three-strikes rule matters. An agent that keeps trying variations on a failing approach burns budget and produces increasingly speculative changes. Three failures for the same reason means the problem is not where you think it is — report what you tried and what happened.

Parallelism

Parallel across work items that have no dependency relationship, each in its own worktree.
Strictly serial within a work item.
Slices are vertical, never horizontal layers. “Log a play, tier-one, Expo tap → Neon row, with a test” is a work item. “Build the sessions schema” is not.

Two agents must never both be editing the schema. The dependency graph in ../work/README.md exists to make that impossible to do by accident.