Worked example — F5-a through /forge-deliver
One real feature walked end to end, with the actual branch and PR names, so the pipeline stops being abstract. Read
forge-deliver-explained.mdfirst for the concepts. Branch/PR states here were true when written (2026-09-18) — check GitHub for the live state.Later change (2026-09-24): the first-administrator bootstrap that WI-1.3 built is retired by F5-k (AD #34) — the first administrator now comes from a Flyway migration that seeds an IT Admin role and user. The walk-through below records F5-a as it was built and is not rewritten.
The feature
F5-a — “Sign in with Microsoft and sign out.” The first slice of authentication: a login page, the Microsoft (Entra) OAuth2 redirect, a gated session, and sign-out. It’s user-facing (it has screens and a real backend↔frontend handshake), so it went the multi-plan / waves route.
It touches all three governed repos:
forge-et-harness— the spec, the plans, the tracker (the governance record).forge-et-be— the backend (login handshake, session, first-admin bootstrap).forge-et-fe— the frontend (login page, session gate, sign-out).
Step 0 — kick it off
/forge-deliver F5-a
The orchestrator read the tracker, saw F5-a at backlog, and entered the Shape phase.
Shape — spec, review, decompose
- It drafted the spec, ran the 2-pass review, and asked for approval. On approval the spec was opened as its own PR:
- Spec PR —
altrium-io/forge-et-harness#122, branchfeature/F5-a-spec→main. (merged)
- Spec PR —
- It asked “one plan or many?” — F5-a is user-facing, so: many.
- It produced the decomposition (the wave + work-item breakdown) and asked for approval. On approval the plan branch opened:
- Plan PR —
altrium-io/forge-et-harness#123, branchfeature/F5-a-plan→ stacked on the spec branch. (merged)
- Plan PR —
At the end of Shape it printed a “start the next session now” handoff (soft boundary — no waiting) and stopped.
Wave 1 — the actual build
F5-a’s Wave 1 has four work items — three that build code (sub) and one that proves it works (verify):
| WI | Kind | What it built | Repo | Per-WI PR (review surface) |
|---|---|---|---|---|
| WI-1.1 | sub | Session & HTTP foundation (the apiClient, session bootstrap, 401 handling) |
fe | forge-et-fe#18 (closed — superseded by the wave PR) |
| WI-1.2 | sub | Login page, Microsoft sign-in, sign-out | fe | forge-et-fe#19 (closed — superseded) |
| WI-1.3 | sub | First-administrator bootstrap | be | forge-et-be#31 (closed — superseded) |
| WI-1.4 | verify | Wave-1 verify — sign-in, session, sign-out (seam + browser E2E) | fe | forge-et-fe#20 |
What the orchestrator did automatically, in order:
- Froze the contract. Because the wave has both a backend WI (1.3) and frontend WIs (1.1/1.2) meeting at a seam, it authored and froze
.forge/plans/F5-a/F5-a-Wave-1-contract.mdbefore any planning — so both sides built to the same shape (the/api/v1/me,/oauth2/..., stub-login shapes). - Wrote the plans in parallel, ran the cross-WI consistency check, and presented each for your approval (checkpoint 4).
- Provisioned worktrees and dispatched the
subWIs —frontend-implementerfor 1.1/1.2,backend-implementerfor 1.3 — each on its own branch (feature/F5-a-WI-1.1-session-http-foundation,…-WI-1.2-login-page-flow,…-WI-1.3-first-admin-bootstrap). - Integrated (Pass 1) the three
subbranches into the wave branchfeature/F5-a-wave-1. - Ran the seam + browser tests for the verify WI (1.4) itself — the orchestrator, not a sub-agent, kept both servers and the browser alive across the run. This is where a real bug surfaced: the Vite dev proxy had to strip the browser
Originheader, or the backend’s empty local CORS list rejected writes. The auto-fix loop routed it to the owning implementer, fixed it, and re-ran to green. - Opened the wave PRs (one per touched repo) and stopped:
forge-et-be#32— “feat(F5-a): wave 1 — first-administrator bootstrap”, branchfeature/F5-a-wave-1→main(open)forge-et-fe#21— “feat(F5-a): wave 1 — Microsoft sign-in, session gate, sign-out”, branchfeature/F5-a-wave-1→main(open)
The per-WI PRs (#18/#19/#31) auto-closed with a “superseded by the wave PR” comment when the wave PRs opened — they were review surfaces during the build; the wave PRs are the ship surface.
Your turn (right now, for F5-a)
The wave PRs are open. To finish Wave 1:
- The review record on each wave PR. Today
/forge-deliverruns the review itself before it stops (Stage 12’s last step) and writes the record — a PR comment plus aForge reviewstatus on the head. When this example ran, that step did not exist; the equivalent is/forge-review-pr forge-et-be#32and/forge-review-pr forge-et-fe#21. - Confirm CI is green and the head carries a
successForge reviewstatus on each wave PR, and merge them (no approval is currently required; asking a teammate to look first is still good practice). - Re-run
/forge-deliver F5-a— it will detect the merges, advance past Wave 1, and either dispatch the next wave or, if Wave 1 was the last, run Reflect and flip F5-a todone.
What this shows
- The spec/plan PRs are small and merge early; the real code ships wave by wave.
- The orchestrator opens PRs but never merges — that’s your gate.
- The seam contract caught the shape before the code and the auto-fix loop caught the CORS bug at test time — neither reached your review as a surprise.
- You re-run the same command to move between waves; the tracker + reconciliation make each run self-orienting.
Sources. Live PR/branch state from altrium-io/forge-et-{harness,be,fe} on 2026-09-18; the workflow from .claude/commands/forge-deliver.md. F5-a’s own record lives in .forge/specs/F5-a-*-spec.md, .forge/plans/F5-a/, and the tracker.