How /forge-deliver works
The one command that carries a feature from an idea to a merged, tested, reviewed pull request — and exactly where you, the human, step in. Plain-English guide.
TL;DR
/forge-deliver F5-a takes a feature from backlog all the way to done. Along the way it:
- writes the spec and reviews it;
- breaks the work into small vertical slices and writes their plans;
- writes the code, and writes and runs the tests;
- fixes the failures it can fix on its own;
- opens the pull requests;
- finishes with a short “what did we learn” step.
Your job is not to drive the machinery. Your job is to make the calls a machine shouldn’t: approve the spec, approve the plans, and merge each pull request when you’re happy with it. That’s most of it.
The one-line mental model: you are the pilot deciding where to go and signing off at each checkpoint; /forge-deliver is the crew that does the flying; the harness is the set of rails that stops the crew wandering off course.
1. The big picture
The harness is a set of rails, not software
The “Forge harness” is a collection of files — rules, templates, checklists, and workflow definitions — that keep AI-assisted work structured instead of ad-hoc. It exists so that every feature is specced, reviewed, tested, and traceable, no matter who (or which model) is at the keyboard on a given day. Its core beliefs: a human stays in the loop at every important gate, and context lives in files, not in the chat — so any session can be picked up cold by re-reading the tree.
Parent harness vs. this one
- Parent —
forge-harness. The generic, reusable template (inDocuments/Repositories/forge/forge-harness). It’s the source of truth for the method; new projects are bootstrapped from itstemplates/project-harness/. You rarely touch it directly. - This one —
forge-et-harness. The Empire Teas instance, created from the parent and then customised (the AD table, the stack, the phasing). It’s pinned to a parent version and pulls in upstream improvements through a controlled sync. This is where you actually work.
The “front door”
The harness has many small skills — one writes specs, one reviews plans, one opens PRs, and so on. You are not meant to run those one by one. /forge-deliver is the single front door that sequences all of them in the right order, with the gates and pauses built in. (If you ask in plain language — “how do I start F5-a?” — a routing skill just points you back here.)
flowchart LR You["You<br/>type /forge-deliver F5-a"] --> Orch["Orchestrator<br/>the 'driver' session"] Orch --> Subs["Sub-agents<br/>code · tests · reviews"]
2. The 7 phases every feature passes through
This is the spine. No phase is ever skipped — that’s a hard rule.
flowchart LR A[Spec<br/>what to build] --> B[Plan<br/>how to build it] B --> C[Implement<br/>write the code] C --> D[Check<br/>lint · tests · build] D --> E[Review<br/>diff vs. intent] E --> F[Ship<br/>open the PR] F --> G[Reflect<br/>what did we learn]
Two rules worth remembering:
- No code before an approved spec and plan.
- Reflect is mandatory. A feature isn’t “done” until the learning step has updated at least one file (a rule, a lesson, a template). If nothing changed, Reflect didn’t happen.
3. What you actually type
Almost always just the first line. The flags are for special cases.
/forge-deliver F5-a # the normal way — start or resume a feature
/forge-deliver --next # pick the next unblocked backlog feature for me
/forge-deliver F5-a --no-implement # stop once all plans are approved (no code yet)
/forge-deliver F5-a --wave 3 # work a specific wave (for running waves in parallel)
/forge-deliver F5-a --from <stage> # jump to a stage (rare; use with care)
You run the same first command over and over as the feature progresses. Each time, the orchestrator reads the tracker, figures out exactly where the feature is, and picks up at the next unfinished step. You never have to remember “which stage am I on” — it does.
4. What’s expected from you
The whole point of the harness is that these — and only these — are your decisions. Everything else runs on its own.
| Checkpoint | When | What you do |
|---|---|---|
| Approve the spec | early | The orchestrator drafts the spec and runs a 2-pass review on it. You read the verdict and say approve or reject. Reject halts everything — nothing gets built on a spec you don’t agree with. |
| Answer: one plan or many? | after spec | It asks whether the feature is small enough for a single plan or should be split into waves of small work items. A quick judgement call from you. (Most user-facing features are “many”.) |
| Approve the decomposition | if multi-plan | If you chose “many”, it produces a plan for how the feature is sliced into waves and work items. You review and approve that breakdown before any detailed planning starts. |
| Approve each plan | per work item | Each small slice gets its own implementation plan. You approve them one by one. This is where review effort matters most — a wrong plan produces wrong code that’s expensive to unwind later. |
| Carry out a manual wave | if a wave is manual | Some waves are steps a person does by hand (a console change, a check in another system). The orchestrator hands you the run sheets and stops. You do the steps, record each result on the harness wave branch, push, and re-run the command; it asks whether every result is recorded, and only a yes closes the wave. |
| Merge each wave’s PR | per wave | When a wave’s code is built and tested, the orchestrator opens the pull request(s) and reviews each one itself with /forge-review-pr. It has the safe fixes made, writes the review record (a PR comment plus a Forge review status on the PR’s latest commit), and stops. You merge in GitHub when CI is green, the Forge review status is success, and you’re happy. Then re-run /forge-deliver to start the next wave. No approval is currently required. |
| Review again after a later push | when it happens | If you push to an open app-repo PR later (a merge of main, “Update branch”), the new commit has no Forge review or Test record status. 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> (for example forge-et-be#124), which reviews only the new commits and records the new head. |
And occasionally… if something genuinely ambiguous happens — a test fails in code that wasn’t part of this wave, or two slices disagree about a shared interface — the orchestrator stops and asks you instead of guessing. These are rare, and each halt tells you exactly what to decide and how to resume.
5. What it does automatically (so you don’t)
Everything between your checkpoints. This is the bulk of the work.
- Draft the spec — runs a gap-check first, then writes the spec body from the PRD, prototype, and locked decisions.
- Slice into waves — breaks an approved spec into small, end-to-end work items grouped into waves.
- Freeze the contract — for any slice where backend meets frontend, it locks the shared interface first so both sides build to the same shape.
- Write the plans — drafts every work item’s plan in parallel, then runs a consistency check across them.
- Provision worktrees — sets up isolated git worktrees and branches so slices don’t step on each other.
- Write the code — dispatches specialist agents to implement each slice against its approved plan.
- Run the tests — the orchestrator itself runs the real API and browser test suites, not just writes them.
- Fix failures — on a failing test it decides “bad test or bad code?”, dispatches a fix, and re-runs — up to 2 tries before asking you.
- Integrate + open PRs — merges the slices into a wave branch and opens one clean pull request per repo.
- Check the look — for UI waves, it screenshots each new screen and compares it to the design of record.
- Heal drift — on every run it reconciles the tracker against GitHub + git so a crashed agent never causes double-work.
- Record + reflect — harvests test stats, then runs the mandatory learning step and promotes lessons.
6. Who does the work — the cast
The orchestrator is the conductor. It never writes app code itself — it hands work to specialists and runs the tests.
| Player | Role |
|---|---|
| Orchestrator (driver) | The session you launch. Sequences the stages, runs the live test suites, classifies failures, dispatches fixes, opens PRs. The only part that keeps servers and browsers running across a whole test run. |
| backend-implementer | Writes server-side code (Java / Spring Boot) for a slice, plus its unit and integration tests. |
| frontend-implementer | Writes UI code (React / Vite) for a slice, plus its component tests. |
| seam-test-implementer | Writes the API-level tests that prove backend and frontend actually agree on the shared contract — no browser needed. |
| e2e-test-implementer | Writes the full browser + accessibility tests for a wave or the whole feature. |
| spec-reviewer / plan-reviewer | Read-only auditors. They produce findings and a verdict on specs and plans; the orchestrator applies the fixes. |
| backend/frontend-reviewer | Read-only code reviewers that catch framework-specific mistakes generic review misses. |
Why the orchestrator runs the tests itself: a dispatched sub-agent is shut down the instant it finishes replying — so it can’t keep a dev server and a browser alive across a test run. The test agents therefore write and static-check the tests; the long-lived orchestrator session runs them. That split is the reason the whole thing can test against real, running software.
7. Waves vs. a single plan
The fork in the road that your “one plan or many?” answer decides.
- Single plan — small, self-contained work, usually backend or data-layer only. One plan, one implementer, one PR. Fast. (Guardrail: if the plan needs live browser tests, the harness refuses single-plan and tells you to split it — because single-plan has no place to run those.)
- Multi-plan (waves) — anything bigger, especially user-facing features. The feature is cut into small vertical slices — each one a real thin end-to-end piece — grouped into waves. One wave is built, tested, and merged before the next starts.
What a wave looks like inside:
flowchart TD P["① Plan + freeze the contract<br/>plans authored in parallel; BE↔FE interface locked"] --> I["② Implement in parallel<br/>specialist agents build each slice in its own worktree"] I --> N["③ Integrate<br/>slices merge into one wave branch"] N --> T["④ Test + auto-fix loop<br/>orchestrator runs API then browser suites; fixes failures (≤2 tries)"] T --> S["⑤ Wave PR opens → it STOPS<br/>your turn: review + merge, then re-run /forge-deliver"]
Each wave branches fresh from main after the previous wave merges, so every wave is a small, independently revertable change. The last wave is usually the full end-to-end test suite for the whole feature.
8. The rhythm — why you re-run the command
A feature isn’t one long session. It’s a handful of short ones, on purpose. The command works in bounded chunks and then stops, for two reasons: it keeps each session’s context small (so the long procedure is followed faithfully), and it puts a natural pause at every human decision. Because all state lives in files, a fresh session picks up exactly where the last left off.
- Shape session — spec → review → decompose → approve the breakdown. Then it stops and says “start the next one now” (no waiting).
- Wave 1 session — plan → build → test → open the wave PR. Then it stops and waits for you to merge.
- You merge Wave 1, re-run the command — it advances to Wave 2, same shape.
- …repeat per wave… until the last wave merges.
- Final session — confirms everything merged, runs Reflect, flips the feature to done.
So the loop you’ll feel in practice is simple: run → approve what it asks → merge the PR → run again.
9. The safety net — why it rarely loses or corrupts work
- State reconciliation runs first, every time. Before doing anything, it compares three sources of truth — the tracker file, GitHub PR state, and pushed branches. If a background agent died halfway (say, it opened a PR but never recorded it), the command heals the record automatically; if the situation is ambiguous, it stops and shows you a drift report rather than guessing.
- Context lives in files, not the chat. The approved spec, the plans, the tracker — all on disk. Any new session re-derives the full picture, so nothing depends on one long conversation staying alive.
- Deterministic hooks enforce the gates. The important rules (no code before approval, no direct commits to
main, protected files) are enforced by hooks on every edit — not by hoping the model remembers. This is why the workflow is robust even across different models. - Every wave is independently revertable. Each branches from
main; a bad wave can be backed out without unpicking the others.
10. How it performs — honest expectations
- What it’s good at: consistency and traceability. Every feature gets the same specced-planned-tested-reviewed treatment. Parallelism helps — plans are drafted together, slices are built together, and later waves can be planned while the current one builds.
- Where the time really goes: wall-clock time is dominated by human queue time — how quickly specs get reviewed, plans approved, and PRs merged — not by agent compute. The estimation baselines measure agent time only, so they under-count the calendar. The faster you clear your checkpoints, the faster features ship.
- It is not one-shot: a feature moves through several sessions with your merges in between. That’s by design, not slowness — it keeps a human in control and each context small enough to be reliable.
- It measures itself: when metrics are enabled, it records spec-authoring time, per-wave cycle time, and throughput to
.forge/metrics/, plus per-feature test stats — so “how are we doing” is answerable from data, not vibes.
11. Which model + effort to run it with
The model and effort we use are set in one place, team-guide.md § Choosing a Claude model and effort, so this guide does not repeat them. That covers the driver, every sub-agent it dispatches, and any other session. Check the claude-api skill for current model facts. Two things about how /forge-deliver uses the setting are worth knowing:
- Sub-agents follow the driver. Every agent in
.claude/agents/declaresmodel: inheritand no effort of its own, so implementers, test implementers and reviewers run on the driver session’s model at the driver session’s effort. Raising the driver’s effort for a hard problem raises it for everything that session dispatches. - Set effort before a run starts. Claude Code saves effort separately for each model, and switching model partway through a run re-reads the whole context without the prompt cache.
12. Gotchas & good habits
- Don’t hand-run the sub-skills. Resist running
forge-spec-author,forge-wave-decompose, etc. by hand./forge-deliversequences them with the right gates; running them loose skips checkpoints. - Turn 1 is read-only when the session opens with
./forge-start.shor an open-ended question. Such a session orients before it writes; a first message that names one task may do that task. Don’t expect it to spec-and-build in one turn — that would leapfrog the gates. - User-facing = multi-plan. If a feature needs browser tests, choose “many plans”. The single-plan path can’t run live browser suites and will halt to tell you so.
- Merges are yours. The command opens PRs and stops. It never merges. You merge once CI is green (no approval is currently required). Then re-run to continue.
- Re-running is always safe. Re-invoking on a feature mid-flight just resumes. Re-running a finished feature is a no-op that prints its status.
- A halt is information. When it stops and asks, it’s because a machine shouldn’t decide that. Read the halt message — it names the decision and the resume command.
13. Glossary
| Term | Plain meaning |
|---|---|
| Wave | A batch of small slices that get built, tested, and merged together as one PR before the next batch starts. |
| Work item (WI) | One small vertical slice of a feature, with its own plan and branch. |
| Seam | The boundary where backend meets frontend — the shared API contract. |
| Contract | The frozen, agreed shape of that seam, written before code so both sides match. |
| Tier (T1–T-E2E) | How deeply a slice is tested: T1 unit, T2 integration, T3 API-seam, T-E2E full browser. |
| sub / verify / e2e | Work-item kinds: sub builds code; verify proves the seam; e2e drives the browser. |
| Worktree | An isolated checkout of a repo so parallel slices don’t collide. |
| Orchestrator / driver | The main session running /forge-deliver that coordinates everything. |
| Reflect | The mandatory closing step: what worked, what didn’t, what to change — recorded to files. |
Sources. This guide summarises the orchestrator at .claude/commands/forge-deliver.md and the doctrine in .forge/forge-harness-framework.md (this repo), plus the generic parent at forge/forge-harness. For the authoritative, up-to-date detail, read those files — this is the plain-English map, not the contract. See also forge-deliver-cheatsheet.md for the one-page version and f5-a-worked-example.md for a concrete walkthrough.