The Constitution

The single source of truth for a screen is the rendered prototype, then the live UI. Precedence: prototype > reconciled spec > screenshot > draft. A prototype-vs-spec conflict is a STOP-and-surface.

A module never references another module. Cross-module needs are met only by a published event or a public query DTO from Contracts. A broken contract is a compile error, not a 2 a.m. surprise.

Exactly one actor — the orchestrator — writes shared trackers and closes seams. Workers touch only their own files plus append-only shared files, and return a structured report.

A subagent starts with a fresh context window; the only channel in is the prompt. Every delegation hands over spec paths, design references, prior output, and the path to CLAUDE.md.

Workers run in parallel only when isolated: own output dir, own browser-port, append-only to the shared stylesheet. A semaphore caps concurrency; a seed gate orders shared declarations.

No agent self-attests completion. “Done” means passing the phase gate: clean build, visual assertions, value-not-literal checks, tests, contract tests, a11y, and a reviewer PASS.

An agent may freely change its own slice and the contracts it emits. Touching the shared kernel, the Contracts surface, or another module needs a foundation-level gate.

Modules self-register via Add<Module>(); nav and routes come from a registry; the shared stylesheet is appended to, never rewritten. No merge contention, no forced serial work.

Specs are reconciled to the current design at the moment a slice is built, not perfected up front. Draft md files are inputs, not truth. Each slice carries a provenance header; the registries’ Sync state tracks fresh/stale.

Build design-first and add capability as development reaches it. Parity research informs the spec but never overrides the design; only the Must-haves a slice needs now are adopted.

Self-correction loops retry at most twice, then stop and file the case in an approval inbox. Never an infinite loop. Human supervision is on the loop, not in it.

Durable facts go to INSIGHTS; corrections to LESSONS as Mistake/Trigger/Rule; status to PROGRESS. Read PROGRESS + LESSONS at session start. Stable lessons graduate into CLAUDE.md.

Learning

New to the method? Read Start here, then scroll the lifecycle phase by phase.

Referencing

Mid-build? Jump to a phase or agent and copy the exact command or file. ⌘K opens search anywhere.

Sharing

Every heading is a deep link. Send a teammate to the precise section, not the whole document.

The session ledger — multi-session coordination + the story that survives

Constitution, prompt templates, sixteen subagents, sixteen commands, the eight-skill expertise layer, bootstrap + preflight + governance tooling, the cross-platform session ledger, and the memory templates — one versioned, manifest-verified bundle.

Unzip, point the installer at your repo. Non-destructive — existing files are skipped, re-runs are idempotent.

cd constitution
./bootstrap.sh /path/to/your-repo

Use the naming grammar

FR-<X>-NNN · BR-<X>-NNN · EVT-<X>-Name · PERM-<X>-Entity.Action · WF-<X>-NN. Consistent identifiers let every later phase cross-reference cleanly.

Mark the priority journeys

Name the journeys to build first — they become the continuity proof in Design and the golden workflow in Build.

Flag every assumption

Each open question is written as “ASSUMPTION — confirm”, never silently resolved.

Design-system only

Every screen uses only design-system components and tokens — no off-system colours, no hand-rolled controls where a component exists.

Continuity is built in

Priority journeys are designed end-to-end first; every screen satisfies the continuity invariants — one primary CTA, guarded CTAs disabled-with-reason, no dead-ends.

Match the voice

Sentence case, verb-led CTAs, numbers and units in status lines.

The fidelity gate

0-error build; the captured screen is the rendered screen; the design-system CSS actually applied; computed-style assertions match the prototype; every bound value renders its value, not the literal.

Single writer integrates

Workers return structured reports; the orchestrator gate-reviews them, dedups design-system classes, graduates primitives, and closes seams.

Provenance + Sync state

Every spec records the design source it was derived from, a last_synced timestamp, and a hash; the registries’ Sync chip tracks fresh/stale. A hash mismatch marks it stale.

UI-driven extraction

The built UI is the most reliable spec of the contract surface — lift the mock-data shapes into the first draft of DTOs and read models (the UIMAP).

Generate the boards

Generate docs/SCREEN_REGISTRY.md and docs/WORKFLOW_REGISTRY.md from CLAUDE.md following the contract at the top of each.

SharedKernel + Contracts

Freeze the primitives; establish the append-only integration-event and public-DTO surface.

Infrastructure behaviours once

Validation, fail-closed authorization, audit, caching, telemetry, plus the compliance hooks — applied uniformly through the pipeline.

Host + architecture tests

Composition root with a module-discovery loop; NetArchTest boundary rules green before any feature module.

Scale-out

Redis backplane + sticky sessions (or a managed SignalR service); right-size circuit memory; load-test the SignalR path, not just request throughput; ship the reconnection UX.

Observability

OpenTelemetry through Aspire ServiceDefaults — traces (including Blazor circuit activities), metrics, structured logs with no sensitive data; health checks on every backing service.

Security & CI/CD

Fail-closed authz, RBAC, immutable audit, break-the-glass, TLS 1.3, encryption at rest; visual-regression and a11y run on every PR.

A module references only SharedKernel, Contracts, and DesignSystem. Need another module’s data? Subscribe to its event or call its public query DTO.

Each module exposes one Add<Module>() that registers handlers, EF, validators, nav item, and permissions. The Host calls them in a loop — no hand-edited menu.

A separate DbContext and schema per module (reg.*, clin.*, …) so migrations never collide — which is what lets migration work parallelize.

Reproduce ONE screen 1:1 as the design-system Blazor classes. Also runs in re-sync mode — applying a design-sync delta to an existing screen while preserving its wiring, instead of rebuilding it.

The in-repo design lane: authors ONE net-new prototype screen from its design-prompts brief — closed vocabulary (grep-verified against the prototype), sandbox render + sign-off screenshot, contract sidecar + provenance hash at birth, and a self-critique → revise pass against an excellence rubric. Never wires or flips boards.

Read-only journey-continuity auditor over the PROTOTYPE: traces ONE end-to-end journey, builds the mechanical route/edge ledgers (OK / DEAD-END / LEGACY / WRONG), walks each role's day, and returns severity-ranked gap rows. The phase-1 gate: zero S1 gaps on the golden journeys.

Read-only dead-edge auditor over ONE module's prototype screens: finds affordances that lie — toast-only lifecycle CTAs, no-handler buttons, placeholders, phantom-prefilled create forms — classifies each on two axes, and re-verifies the accepted-toast exceptions ledger.

Detect + triage prototype drift; emit a routed re-sync plan. Advisory — reads code, specs, and the updated prototype and writes ONLY its plan; never edits screens, specs, or trackers. The /design-sync command executes the plan. Pipeline-born and graduated screens are out of scope.

Reconcile the spec to the current design; write the UIMAP and the delta report. Lifts each screen's contract sidecar as the UIMAP's first draft.

Feature-parity vs the domain's market leader and its interop standards. Advisory only. Also dispatched in triage mode by /design-help and /design-full-sweep for retrospective design-gap discovery.

Domain + application layer: MediatR records, validators, value objects, events. Durable IDs from SQL sequences behind an allocator port — never a process-static counter.

Per-module EF migration; gated on any destructive change.

Idempotent reference data plus domain-plausible demo data.

Pipeline behaviours, compliance hooks, events, SignalR, and jobs.

Wire the reconstructed UI to handlers, add states, preserve the design.

xUnit, Playwright e2e, NetArchTest, and visual regression — including the persistence-invariant negative path (every unique index / sequence / constraint made to FIRE against real SQL) and restart-simulation tests for anything minting durable state.

Read-only affordance auditor: enumerates EVERY button, link, CTA, shortcut, and form submit on the touched screens, classifies each (wired / stub / mis-wired / dead-end / design-gap), reconciles against the UIMAP, and returns a risk-gated remediation worklist.

Read-only audit against the Constitution and CLAUDE.md. PASS / FAIL.

Read-only cross-sweep auditor for a parallel wave: audits the combined union diff across all surviving worktree branches for failure modes no per-sweep reviewer can see — design-system duplication, Contracts collisions, repeated cross-cutting behaviour, seam interference.

get_architecture to surface the de-facto module seams → search_graph for exact qualified names → get_code_snippet for source. Trace with trace_path (direction both — outbound-only misses cross-module callers); detect_changes maps a diff to its blast radius before a seam edit.

The ten graph(read) agents in the roster. Builders use the graph to find code, never to edit outside their slice. migration-engineer, seed-builder, and screen-reconstructor are deliberately excluded — narrow scope and visual fidelity need no code discovery. No subagent gets the index-mutating tools.

The index can go stale as sessions advance main — only the orchestrator re-indexes, after a wave fold-in or a large branch sync (Law 3). Subagents treat the graph as possibly-stale and confirm any load-bearing finding against the file.

Builders conform to the approved spec; spec-researcher and spec-architect propose changes upward — an advisory loop gated behind a human. Requirements sharpen each sweep, never silently.

module-wirer preserves the design pixel-for-pixel; test-engineer’s visual-regression baseline enforces it. A new state is composed from existing primitives and flagged for review, never invented.

A failing contract test → backend-builder; a visual diff → module-wirer; a missing criterion → spec-architect. Capped at two attempts, then the case lands in the approval inbox.

One record per workflow sweep — the modules it traverses, the contracts and SharedKernel it touches, and its dependencies. Mined from the workflow registry into spans.json.

A set of spans that share no module, contract type, or kernel touch — so they can run in parallel, each in its own git worktree. The scheduler caps wave width.

Verify-WaveDisjoint.ps1 re-checks the plan before fan-out under the same conflict rule. Exit 0 = disjoint, proceed; 1 = a conflict, re-plan; 2 = bad args.

Each session gets a RUN_STATE shard (asks, mode, declared write-claims, heartbeat, stage times). At session start you see who else is active and what they claim; a new foreign claim is injected mid-session exactly once. A stale heartbeat expires the claim — a crashed session never blocks the checkout.

When real work exists with no journal entry, the turn-end gate demands the session story once (Law 11): purpose · plan · done-with-evidence · pending · decisions-to-give, via progress-reporting --kind session. Session end always appends a mechanical envelope — asks, diff, boards touched — so the skeleton survives even a storyless close.

docs/STATUS.md is regenerated at every turn end — derived from board rows, the corpus, and git, stamped with the HEAD it was derived at, never hand-edited. /construct-help reads it, cross-checks the stamp, and flags it stale if behind.

Independently re-derives every number the trackers assert (board-integrity checks) before reporting current phase, registry roll-ups, open backlogs, and decisions awaiting a human — and, when the session ledger is wired, which sessions are active right now and which closed without a story. Hands off to /construct-run on your pick. Writes nothing.

Resolves (or auto-detects) the current phase, checks the prior phase's gate, then loops the right existing engine — /reconstruct, /build-workflow, the design loop — over the next units of work, pausing only at mandatory human checkpoints. A unit with no prototype source routes through /design-build first.

Resolves ☐ design-backlog rows (firing design-prompt-authoring for any missing brief), lane-routes, dispatches design-builder per row in parallel, holds a human sign-off checkpoint on the render, then integrates as single writer — wiring, provenance-at-birth registry row, board flips, and a journey continuity delta check.

Runs the zero-dependency promote-design.js helper (dry-run by default): classifies each file NEW / IDENTICAL / OVERWRITE / UNEXPECTED, hashes, sidecar-checks, and inserts entry-point includes. OVERWRITEs are never applied — they are drift, routed to design-sync. A delivery batch ends with a journey edge-ledger re-check.

Dispatches spec-researcher in triage mode over workflows (including already-built ✅ ones) to find net-new screen requirements, dedups them, and files each to the design-backlog board with a ready-to-send design brief. Read-only + board-write only.

Fans out journey-auditor per journey, merges and dedups the gap rows across journeys, STOPs for approval, then routes fixes as single writer — backlog rows + briefs, unbuilt micro-edits with provenance refresh, design-sync handoffs. Verdict: PASS/FAIL — zero S1 gaps on the golden journeys.

Dispatches edge-auditor per module in parallel, surfaces accepted-toast candidates separately (accepting a toast is a product decision), applies approved additive fixes as single writer with provenance refresh, and proves closure by re-running the mechanical tells. Excluded buckets become registered debt.

Fans out spec-researcher (triage), journey-auditor, and edge-auditor read-only, merges findings across screen existence, between-screen continuity, and within-screen affordance honesty into one severity-ranked per-module report, then files backlog rows + design-sync handoffs at a single checkpoint.

Dispatches the design-sync agent, presents the NEW/MODIFIED/REMOVED drift table at one checkpoint, then executes the whole routed plan as single writer — re-sync mode for nudges, spec-architect for contract drift, reconstruct-sweep for new screens, human decisions for removals — closing with a /journey-audit over the flagged journeys.

Dispatches the screen-reconstructor per target, runs the fidelity gate — including branch coverage: one built branch per state key in the source, gated on the branch ledger — integrates, updates the screen registry, graduates repeated classes into primitives, and appends PROGRESS.

One pass of the build pipeline over a single workflow that may span many interdependent modules. The main thread stays the single writer; the two human checkpoints are front-loaded; integration appends the METRICS line and regenerates the Contracts snapshot.

Runs a cohort of workflows that touch disjoint module sets concurrently — admission, worktree provisioning, staged fan-out, per-sweep gates, a cross-sweep wave-reviewer, then serial integration into main. Phase 0 is a hard wave-disjointness gate.

The inverse of the design backlog: every row is work with a prototype anchor that isn't finished — a reconstruction gap, wiring gap, data-seam stub, or environment defect. Routes each to the matching build agent (reconstruction → screen-reconstructor, wiring → module-wirer, …) and closes the row as single writer.

Runs Verify-KitInstall.ps1: classifies every installed kit file OK / MODIFIED / OVERRIDE (declared in KIT_OVERRIDES.txt) / MISSING / STALE / CONFLICT against the SHA-256 manifest written at bootstrap. Seeded files are recorded but never flagged. Report-only by default; -Strict for CI.

Orient → completeness-sweep Part A (board integrity) → optional Part B fan-out → file exactly one snapshot plus one index line → recommend the next action. A phase-exit gate files a snapshot as its evidence artifact — a transition approved with no snapshot is a self-attestation (Law 6).

Orphaned isolated-build and headless-browser processes (targeted by the kit's own isolation markers + age, never kill-by-name), stale obj/_v* dirs, aged scratch screenshots, pruned worktrees. Dry-run by default; skips reclamation entirely while a run is active; never touches visual-regression baselines.

Audits the boards, then reports: §0 re-derives every number a tracker asserts before the dashboard renders — current phase, registry roll-ups, backlogs (design + build), and decisions awaiting a human. A tripped integrity check leads the report; the next action becomes closing that gap, not advancing a phase.

Phase-aware dispatcher: resolves the phase, checks the prior gate, then loops the right engine over the next units of work — pausing only at mandatory human checkpoints. A unit with no prototype source is not a phase-2 unit: it routes through the design loop first.

For scaffold-conforming screens. design-builder authors the prototype screen from its brief — closed vocabulary grep-verified against the prototype, a self-critique → revise pass against an excellence rubric, an isolated sandbox render, and a sign-off screenshot. The human sign-off checkpoint on the render is preserved; then the single writer wires it in.

For novel or exploratory design that needs interactive canvas iteration. The brief goes to the design tool; the delivery comes back as an expected batch that /promote-design ingests atomically — each file classified NEW / IDENTICAL / OVERWRITE / UNEXPECTED. OVERWRITEs are never applied: they are drift, routed to design-sync.

Pipeline-born screens carry their source hash and sidecar from creation — so expected work never triggers a drift sweep. Drift triage shrinks to what it should be: changes made outside the pipeline.

Once a screen is wired and reviewer-PASSed, the live UI becomes the contract: the prototype source freezes and exits drift-sweep scope. A later redesign is a briefed, preserve-wiring event — never a silent re-sync.

A create form's true initial state is blank. The prototype's show-mock-data convention is overridden for a create form's field values — a phantom-prefilled create form is a defect the audits and the PhantomPrefillCreateForm detector both catch, not fidelity.

Builders conform to the approved spec; spec-researcher and spec-architect propose changes upward — advisory and human-gated, so the spec sharpens each sweep but never silently.

Authoritative and effectively read-only to builders. module-wirer preserves it; the visual-regression baseline enforces it. A genuinely new state is composed from primitives and flagged for design review.

Agents produce results; the orchestrator routes failures back to the owning agent, capped at two retries, then escalates to the approval inbox.

KIT_VERSION (yyyy.MM.dd-letter, mechanically asserted against the changelog). Upgrades are commit series, never side-car zips.

tools/Kit.Tests.ps1 discovers and runs every kit self-test suite in child processes plus the preflight self-tests — one verdict line. No release without KIT GATE: PASS; run it after bootstrap before day zero.

Bootstrap writes .claude/KIT_MANIFEST.json as its last act — kit version + a normalized SHA-256 per installed file. /kit-verify is design-sync for installs: OK / MODIFIED / OVERRIDE (declared in KIT_OVERRIDES.txt) / MISSING / STALE / CONFLICT; seeded files are recorded but never flagged. A -Force re-bootstrap runs the drift check first.

CLAUDE.md is the single source of project specifics. At session start, Claude reads it (plus PROGRESS + LESSONS) and builds a placeholder→value binding.

Every <…> token resolves to a CLAUDE.md value. If a needed value is missing or ambiguous, STOP-and-ask — never guess a project value.

Only CLAUDE.md is filled per project, plus the two boards which Claude generates from it. You never rewrite the generic documents.

Durable build status and a dated activity log (newest first).

Non-obvious codebase facts and gotchas, with the why.

Corrections and self-caught mistakes as Mistake / Trigger / Rule.

The per-route board (☐ → ◐ → ✅) — the orchestrator’s claim/integrate board, with a Sync chip per row.

The per-workflow sweep board (☐ → ◐ → ✅) — what each workflow has delivered, with a Sync chip per row.

The affordance-closure board — every interactive element on a screen and its disposition (wired / stub / mis-wired / dead-end / design-gap), plus the accepted-toasts exceptions ledger.

The design-gap board — screens a workflow needs that have no prototype coverage, each with a lane (in-repo vs console) and a Must-have flag.

The design-prompts companion board — a Global preamble plus one ready-to-send design brief per backlog row.

Quantitative memory — one append-only JSONL event line per sweep / wave / gate / park / flake, sharded per run. The schema, freeze rule, and the >40% ×3-waves graduation trigger.

tools/Show-Metrics.ps1: summary roll-up, stage-duration medians, the gate-failure Pareto, and the retry leaderboard — turning "refine prompts when a run misbehaves" into a ranked backlog.

Law 12, quantified: when one agent causes >40% of retries across 3 waves, its skill earns a trap entry. Lessons graduate on evidence, not anecdote.

Roll-ups, totals, and "next / blocked" prose are the part no sweep re-reads — they rot while their rows stay correct. Recompute from rows at every integration, keep row + derived edits atomic, date-stamp status prose.

A skill is a folder with a SKILL.md: only its name + description sit in context until a task matches, then the body and references load. Dozens cost almost nothing.

Five layers: CLAUDE.md (always loaded) · skills (on-demand how-to) · subagents (scoped roles) · commands (workflows) · hooks (automation) — plus MCP servers for access; a code-discovery graph MCP is the recommended optional one.

A repeatable procedure or body of knowledge — not always-on project rules (those go in CLAUDE.md) and not a role's identity (that is a subagent).

Stress-test a module/workflow spec for completeness, clarity, and consistency before building — a pre-build quality gate.

Consolidate duplicated UI markup into one verified-fidelity reusable primitive — without moving a pixel.

Turn design-backlog rows into ready-to-send design-tool briefs in a design-prompts companion board.

The <screen>.uimap.json schema: capture each screen's action→effect contract at birth, so downstream agents validate instead of re-derive.

The 5-phase journey audit — route/edge ledgers, role×journey traces, the gap catalog, and the fix-routing table. One method, two venues (console + in-repo).

Affordance honesty on the prototype: the mechanical tells, the two-axis classification, the additive fix grammar, and the accepted-toasts exceptions ledger.

Gates that can see an absence: Part A re-derives every number a board asserts (eleven checks); Part B proves completeness against the corpus, never the trackers.

Dated, immutable progress snapshots — the 11-section structure, the depth × kind contract (status · progress · gate · session, the end-of-session story the session ledger demands), and the discipline invariants that make findings outlive their session.

Act as a product owner + domain expert for <domain>. From the idea below, produce a PRD.md for an enterprise solution.

Idea: <one paragraph>

The PRD must cover, per module: entities, functional requirements (FR-<X>-NNN), workflows (WF-<X>-NN) step by step, business rules (BR-<X>-NNN), domain/integration events, permissions, integration points, and cross-cutting/compliance requirements. Mark the module list, the priority journeys to build first, and the NFR targets. Flag every assumption as "ASSUMPTION — confirm".

Using the attached PRD.md and our pre-built design system, design the clickable prototype for <App>.

Constraints: every screen uses ONLY design-system components and tokens. Match the design system’s voice (sentence case, verb-led CTAs, numbers+units). Build the priority journeys end-to-end first as the continuity proof. Each screen satisfies the continuity invariants — single primary CTA per state, guarded CTAs disabled-with-reason, no dead-ends or orphans, resumable drafts. Refine until ~90% of screens are designed, then export.

From the rendered prototype (the contract) and the reconstructed screens for <module/workflow>, author its spec.

<X>_MODULE.md: purpose; entities + persistence placement (SQL vs Mongo); data contracts; BR-<X>-NNN enforced in the domain; UI states required (incl. loading/empty/error/permission-denied); dependencies; cross-cutting (roles, audited actions, cached reads, jobs, SignalR, AI); acceptance criteria. Add a provenance header.
<X>_DB_SCHEMA.md: the database design of record — tables/collections, columns+types, keys, indexes, constraints, placement, encryption, retention.
<X>_WORKFLOW.md: trigger + actors; modules involved; step-by-step flow naming the handler each step hits; data crossing each boundary (→ contracts); failure/edge cases; acceptance criteria.

Build the foundation for <App>, human-in-the-loop. Do NOT build feature modules yet.

1. SharedKernel: freeze the primitives.
2. Contracts: the append-only integration-event + public-DTO surface.
3. Infrastructure: MediatR behaviours once — validation, fail-closed authorization, audit (SQL header + Mongo diff), caching, OpenTelemetry; plus the compliance hooks.
4. DesignSystem extraction: tokens, component library, scaffolds; stand up the visual-regression baseline.
5. Host: composition root, global InteractiveServer, the module-discovery loop, Aspire ServiceDefaults.
6. ArchitectureTests: NetArchTest boundary rules green.

Stop at a foundation gate: boundary tests pass, app shell renders, behaviours apply uniformly.

/build-workflow <WorkflowName>

Golden-workflow first: pick one workflow that exercises the full stack (real SQL + a Mongo document type + a SignalR update + an audited sensitive write) before scaling out. Then parallelise across workflows that touch DISJOINT module sets.

Use the <agent-name> subagent on <module/workflow> "<name>".
Read first: CLAUDE.md · <reconciled spec path> · <UIMAP/related paths>.
Prior outputs to build on: <paths to upstream agents’ artifacts>.
Scope: touch ONLY <your module’s files> + append-only <shared stylesheet>; do NOT edit siblings, central files, or trackers.
Parallel context: you are one of up to <N> isolated siblings — use an isolated output dir and an isolated headless browser; path-attribute a sibling-caused red build.
Return your structured report (Item/Status/Files changed/Contracts/Evidence/Insights/Lessons/Blockers).

The whole bundle: Constitution, prompt templates, sixteen subagents, sixteen commands, eight shipped skills, the memory + board templates, the cross-platform session ledger, and the bootstrap + preflight + governance tooling — versioned, self-gating, manifest-verified.

All files