--- name: build-workflow description: "Sweep all build-phase agents over ONE workflow (which may span many interdependent modules), wiring real backend behind the reconstructed UI. The main thread is the single writer; subagents are stateless and receive explicit context. Usage: /build-workflow " --- > **Specialization:** Read `CLAUDE.md` first and bind every `<…>` placeholder and every “per `CLAUDE.md`” reference from it (stack, project/module names, paths, design-system prefix, naming grammar, domain compliance). This file hard-codes no project or domain value. If a needed value is missing from `CLAUDE.md`, STOP-and-ask. See `SPECIALIZE.md`. You are the **orchestrator** for a workflow sweep. You are a **thin router and the single writer** (Law 3): you sequence the agents, hand each one explicit context (Law 4), enforce the gates, and are the ONLY actor that writes shared trackers and closes cross-module seams. You write no production code yourself. ## Preconditions - The foundation is built (SharedKernel, Contracts, Infrastructure behaviours, app shell, design-system extraction). If not, STOP — that is human-in-the-loop work, not a sweep. - Read `CONSTITUTION.md`, `CLAUDE.md`, `PROGRESS.md`, and `LESSONS.md` first. Resolve the workflow's touched modules + entities from `_WORKFLOW.md` and the dependency graph. ## The sweep (run in order; pass each agent the spec path, module name, prior outputs, and the CLAUDE.md path) 1. **Understand & enrich** - Dispatch `spec-architect` → reconcile the workflow spec + each touched module spec to the current design, write UIMAPs, emit the delta report. **Hard gate:** do not proceed unless reconciliation ran THIS sweep (provenance fresh). - Dispatch `spec-researcher` → parity findings (advisory). - **Build-backlog fold-in:** if the project maintains a build-backlog board (per `CLAUDE.md`), read it and list every open row whose module matches one this sweep touches. Fold each into this sweep's scope (the agents below fix it alongside their normal work — same module, same pass, no separate dispatch) unless it is Must-severity/compliance-tagged, in which case run `/build-backlog`'s own checkpoint for that row before folding it in. Surface the fold-in list at Checkpoint 1 so the human sees scope grew, not just the reconciled spec. 2. **■ HUMAN CHECKPOINT 1** — present the delta report + the Must-have research findings + any design gaps. Wait for approval; fold approved deltas into the specs (you, the single writer). Do not continue without it. - **Design-backlog triage (sub-step of C1):** if `spec-researcher` emitted a `DesignBacklog:` block, surface each entry explicitly: - **Must-have, no prototype coverage** → decide with the human: **(a) park** this workflow until the screen is designed + added to the prototype + reconstructed (use the Claude Design prompt template from `PROMPT_TEMPLATES.md §J`; file the row to the project's design backlog per `CLAUDE.md` with status `☐`) — or **(b) proceed with stub** (full-fidelity stub + `Marked-stub` affordance marker; row still filed as `☐`). If (a), stop the sweep here. - **Nice-to-have** → proceed; write the row to the project's design backlog (status `☐`, severity Nice-to-have) and mark its affordance `Marked-stub`. - All triage decisions are written to the project's design backlog by you (single writer) before leaving C1. **For each `☐` row filed, emit its design-tool brief as a successive output** via the **`design-prompt-authoring`** skill — it appends a per-row block to the design-prompts companion board (per `CLAUDE.md`) so the row ships ready-to-send, not merely listed. 3. **Build the slices** — for each touched module in dependency order: - `backend-builder` → domain + application layer (MediatR + validators + value objects + events; append new contracts to `.Contracts`). - `migration-engineer` → per-module migration. **■ Gate only if it reports a destructive change** — approve before apply. - `seed-builder` → reference + demo data. - `crosscutting-weaver` → behaviours + compliance hooks + events + SignalR + jobs. - `module-wirer` → wire the slice's screens to handlers, add states, preserve design. Independent modules in the workflow MAY run in parallel — but only if isolated (own output dir / own browser-port) and they do not both modify a shared kernel/Contracts type; cap concurrency with the semaphore; apply the per-module seed gate (a seedless module's first slice lays its shared types alone). 4. **Automated quality gates** — `test-engineer` → xUnit + integration + contract + Playwright e2e + NetArchTest + a11y + visual regression; **also writes `_MANUAL.md`** to the project's workflow spec path (per `CLAUDE.md`) as a required artifact — see agent spec for the five required sections. Hooks also run build + lint on stop and block on failure. - **Preflight gate (where wired):** if the project installed the opt-in preflight gate (`.claude/hooks/preflight/preflight.ps1`), run it **full** here and require exit 0 before advancing to **R**; re-run it `-Fast` post-merge at **I**. Projects without it rely on the reviewer + CI as the gate. - **File-scope check:** re-derive each agent's real file scope from `git diff --stat`, never from the agent's prose report — a report can omit or misstate what it actually touched, and the single writer integrates from the real diff. - **Interaction closure (mandatory — the affordance ledger):** dispatch `interaction-auditor` over the workflow's touched screens. It enumerates **every** interactive affordance (buttons, links, click-to-actions, keyboard shortcuts, form submits), classifies each `Wired | Marked-stub | Unmarked-stub | Mis-wired | Dead-end | Design-gap`, reconciles them against the UIMAP's `action→effect`, and risk-tags every gap. **You (orchestrator) rule the gate:** auto-remediate the **low-risk + trivially-constructable** rows (route to `module-wirer`/`backend-builder`, or apply a visible "preview · not saved" marker — additive + reversible), and **ask the human** on **medium/high-risk** rows (choices interactively, or an approval-inbox entry carrying the agent's 2–4 options). Write the ruled rows to `INTERACTION_REGISTRY.md` (single writer); re-run auto-remediated screens through the gates. **Do not advance to R until the ledger is complete — zero unmarked stubs, zero mis-wired seams (deferrals must be `Marked-stub` or ticketed, never silent).** 5. **Reviewer** — `reviewer` → audit vs Constitution + CLAUDE.md. - **FAIL →** route each finding to its owning agent (contract test → `backend-builder`; visual diff → `module-wirer`; missing acceptance criterion → `spec-architect`; etc.), re-dispatch, **capped at 2 retries**, then STOP and write the case to `docs/APPROVAL_INBOX/`. - **PASS →** continue. 6. **■ HUMAN CHECKPOINT 2 (lightweight)** — present the run digest (include a link to `_MANUAL.md` so the human can preview the walkthrough before approving merge); approve merge (or rely on CI + reviewer for auto-merge to staging). 7. **Single-writer integration (you only)** — close every cross-module seam the agents surfaced; dedup new design-system classes and **graduate** repeated patterns into primitives; update the registries' Sync state; append the `PROGRESS.md` line; record harvested `INSIGHTS`/`LESSONS`; mark the workflow ✅ in the registry. **Then (C1):** append the sweep's METRICS line to `docs/metrics/.jsonl` (shard = the run id when a RUN_STATE exists, else `sweep--`; schema + single-writer contract per `docs/METRICS_README.md` — durations from RUN_STATE `stageTimes` when available, else in-session best-effort). **And (A3):** if `backend-builder` reported appended contracts this sweep, run `.claude/tools/Update-ContractsSnapshot.ps1` and include the regenerated `Contracts.approved.txt` in the integration commit — snapshot regeneration is yours alone (single-writer); agents never touch it. **Finally (graph freshness — mandatory, not deferred):** if the project indexes its code in a code-discovery graph (per `CLAUDE.md §0`), re-index it now as the **last** integration action — a full re-index of the just-merged tree — so the merged slice is queryable before the next sweep and the graph never lags `main`. This is the orchestrator's single-writer duty (Law 3): it is a closure step of *this* fold-in, never left for a later session to remember. **Stage timing (optional):** when the session ledger is wired (`SESSION_SETUP.md`), bracket each sweep stage with `node .claude/hooks/session-ledger.js stage start|end` so the METRICS `durMin` derives from real `stageTimes` instead of best-effort wall clock. - **Close folded-in build-backlog rows:** for every row folded in at step 1, flip its status to done on the build-backlog board with a short "closed ``" note, same as `/build-backlog`'s own integration step. If a fold-in row could not actually be resolved this sweep (scope grew but the fix didn't land), leave it open and say so explicitly in the report — do not mark it done on the strength of having been on the list. ## Routing table (reviewer/test FAIL → owning agent) - design-token drift / visual diff / missing UI state → `module-wirer` - failing contract test / wrong DTO shape / missing `[Permission]` / unenforced `BR-*` → `backend-builder` - destructive or broken migration → `migration-engineer` - missing/incorrect behaviour, audit, authz, compliance hook → `crosscutting-weaver` - missing/incorrect seed → `seed-builder` - missing acceptance criterion / spec-vs-design conflict → `spec-architect` - missing/failing test → `test-engineer` - un-dispositioned affordance / silent stub / mis-wired or dead-end seam on a finished screen → `interaction-auditor` (find + risk-tag) → orchestrator rules → `module-wirer` / `backend-builder` / `screen-reconstructor` (fix) — low-risk auto, med/high asked ## Invariants you never break - Subagents get only what you pass them; always include spec paths + module name + prior outputs + `CLAUDE.md` path. - You are the single writer of trackers and seams; agents return reports and touch only their own files + append-only shared files. - Capped autonomy: 2 retries then escalate to the approval inbox. Never an infinite loop. - Parallelism only across disjoint module sets; serialise anything sharing a kernel/Contracts type.