source: .forge/guides/f5-a-worked-example.md · generated — edit the markdown, not this file

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.md first 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

  1. 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, branch feature/F5-a-spec → main. (merged)
  2. It asked “one plan or many?” — F5-a is user-facing, so: many.
  3. 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, branch feature/F5-a-plan → stacked on the spec branch. (merged)

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:

  1. 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.md before any planning — so both sides built to the same shape (the /api/v1/me, /oauth2/..., stub-login shapes).
  2. Wrote the plans in parallel, ran the cross-WI consistency check, and presented each for your approval (checkpoint 4).
  3. Provisioned worktrees and dispatched the sub WIs — frontend-implementer for 1.1/1.2, backend-implementer for 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).
  4. Integrated (Pass 1) the three sub branches into the wave branch feature/F5-a-wave-1.
  5. 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 Origin header, 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.
  6. Opened the wave PRs (one per touched repo) and stopped:
    • forge-et-be#32 — “feat(F5-a): wave 1 — first-administrator bootstrap”, branch feature/F5-a-wave-1 → main (open)
    • forge-et-fe#21 — “feat(F5-a): wave 1 — Microsoft sign-in, session gate, sign-out”, branch feature/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:

  1. The review record on each wave PR. Today /forge-deliver runs the review itself before it stops (Stage 12’s last step) and writes the record — a PR comment plus a Forge review status on the head. When this example ran, that step did not exist; the equivalent is /forge-review-pr forge-et-be#32 and /forge-review-pr forge-et-fe#21.
  2. Confirm CI is green and the head carries a success Forge review status on each wave PR, and merge them (no approval is currently required; asking a teammate to look first is still good practice).
  3. 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 to done.

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.

Generated from .forge/guides/f5-a-worked-example.md by .claude/lib/render-docs-html.js. Markdown is canonical.