source: .forge/guides/forge-deliver-cheatsheet.md · generated — edit the markdown, not this file

/forge-deliver cheat-sheet

One page for Dinil, Biseni, Nanndish, and anyone new. The full explanation is in forge-deliver-explained.md; a concrete run is in f5-a-worked-example.md.

The loop you’ll actually do

run → approve what it asks → merge the PR → run again.

/forge-deliver <ticket>     # start it, and re-run it after every merge to advance

That one command is the whole front door. It reads the tracker, works out where the feature is, and picks up at the next unfinished step. Re-running is always safe.

The seven things it asks of you

# It stops and asks You…
1 Spec drafted + 2-pass reviewed Approve or reject the spec
2 “One plan or many?” Answer — many for anything user-facing
3 Decomposition (the wave/slice breakdown) Approve the breakdown
4 Each work-item plan Approve each plan
5 A manual wave (steps a person carries out, such as a console change) Carry out the run sheets it hands you, record each result on the harness wave branch, push, and re-run the command; it then asks whether every result is recorded
6 Wave PR(s) opened, tests green Merge in GitHub, then re-run the command
7 You push to an open app-repo PR later (a merge of main, “Update branch”) After the last push, run the local record once (backend: git push, then the build record; frontends: git push, then pnpm test:record), then /forge-review-pr <repo>#<N> — a delta that records the new head

Everything else — contracts, code, running the tests, fixing failures (≤2 tries), integration, opening PRs, reviewing every app-repo PR and writing its review record (the Forge review status on the head) — is automatic. A PR that needs no review gets a skip record with a reason: bash .claude/lib/forge-review-record.sh <owner/repo> <N> <head-sha> --skip "<reason>".

Hard rules

  • You can merge your own wave PR. Branch protection on main currently requires green CI but no approval; asking a teammate to look first is still good practice.
  • No code before an approved spec + plan. Enforced by hooks.
  • Reflect is mandatory — the feature isn’t done until the closing learning step updates at least one file.
  • Turn 1 is read-only when the session opens with ./forge-start.sh or an open-ended question — it orients, then stops. A first message that names one task may do that task.

Run it with the right model

The model and effort are set in one place: team-guide.md § Choosing a Claude model and effort. Sub-agents inherit the driver’s model and effort, so the driver’s setting is the only one that matters. The project’s .claude/settings.json sets both, so a session started in this repo opens on the default; check with /model and /effort only if you changed either earlier in the session, for example to xhigh for a hard problem. Current model facts: the claude-api skill.

When it stops and it’s not a checkpoint

It halts and asks only when a machine shouldn’t decide — e.g. a test fails in code this wave didn’t touch, or two slices disagree on a shared interface. The halt message names the decision and the exact command to resume. Don’t work around it; answer it.

Common mistakes

  • Running forge-spec-author / forge-wave-decompose by hand → skips gates. Use /forge-deliver.
  • Choosing “single plan” for a UI feature → it will halt (single-plan can’t run browser tests). Choose many.
  • Forgetting to re-run after merging a wave → nothing advances on its own; re-run the command.

Source: .claude/commands/forge-deliver.md. This is the short version — read forge-deliver-explained.md once, keep this pinned.

Generated from .forge/guides/forge-deliver-cheatsheet.md by .claude/lib/render-docs-html.js. Markdown is canonical.