/build

description: "Execute an approved design plan through gated phases (BUILD → REVIEW → commit) with subagent dispatch. Produces JOURNEY.md, DESIGN.md, design-system tokens, and final mocks. Use when a design plan exists and the direction is approved — per-phase quality gates, design execution evidence (contrast/token/heuristic), and a final trust report."
argument-hint: "[plan path]"

Command: build

**Load Plan → Setup → Execute → Verify → Report.**

Execute an approved design plan phase by phase. Each phase dispatches the **`design-build-agent`** (produces the phase artifact with design execution evidence) then the **`design-review-agent`** (independent cross-pillar critique on the rendered pixels), then the orchestrator commits. This command **dispatches** the two agents — it never inlines the design or the review work.

This command runs a per-phase gate machinery (BUILD → REVIEW → commit) for design, and obeys the shared contract in `docs/workflow-conventions.md` (the lifecycle, the DESIGN.md/JOURNEY.md gates, the design done-when vocabulary). "Tests" are design execution evidence: contrast (`palette.mjs`), render (`prototype`), token coverage, heuristic pass (workflow-conventions.md §3).

---

Invariants

Each of these exists because its absence has a specific failure mode:

• **Worktree isolation** — building on main/master leaves multi-phase commits with no rollback boundary
• **Load plan before any design work** — no plan means no done-when criteria, and artifacts get forgotten
• **One phase at a time** — parallel phases cause merge conflicts and lost context
• **BUILD before REVIEW** (Full and Standard gates) — REVIEW runs on every phase except Minimal
• **DESIGN.md locked before tokens/mocks; JOURNEY.md page specs before page mocks** (workflow-conventions.md §2) — a token machine has nothing to systematize until the DNA is fixed
• **Evidence before commit** — Full/Standard: REVIEW must PASS; Minimal: design execution evidence is the gate
• **Reviewer gets NO intent-framing** — intent-framing collapses defect detection; requirements + rendered artifact only
• **Mark a phase complete only when gates pass** — premature completion ships unverified design
• **Update the execution log** — it anchors later phases and is what you debug a failed build from

---

Phase 1: LOAD (Read Plan File)

Worktree Gate (first check)

Clear this gate before any other work. Multi-phase commits on `main` have no rollback and pollute history.

git branch --show-current
git status
git worktree list

| Situation | Action | |-----------|--------| | Already in a worktree (`.git` is a file) | On a feature branch — proceed | | On feature branch, clean | Proceed (single-build mode) | | On `main`/`master`, clean | Ask the user (below) before proceeding | | Dirty working tree | Ask the user (below) before proceeding |

**On main/master or a dirty tree, resolve via `AskUserQuestion`** — both are decisive picks with 2-3 self-contained options, so the dialog is the right channel (unlike the content-review checkpoints in `commands/plan.md`, there's nothing here the user needs to read first):

You're on [main]. Building a design plan requires an isolated workspace.

Worktree or feature branch?
- [ ] Worktree — isolated copy; main checkout stays free
- [ ] Feature branch — simpler, but blocks this checkout during build
- [ ] Abort

Uncommitted changes in the working tree.

Stash, commit, or abort?
- [ ] Stash — set changes aside, restore after the build
- [ ] Commit — commit them now, then proceed
- [ ] Abort

• **Worktree:** `git worktree add .claude/worktrees/<plan-slug> -b feature/<plan-slug>`, copy the plan file in, `cd` into it. Run dependency setup only if the project has a lockfile (a design-doc plan usually does not).
• **Feature branch:** `git checkout -b feature/<plan-topic>`.

Record the workspace mode (worktree path + branch, or branch) for the REPORT merge instructions. **Never proceed on main/master** — a multi-phase build committed there has no rollback boundary, and a failed phase leaves the default branch broken.

Locate + Parse the Plan

Read the plan path from `$ARGUMENTS` (or `.design-foundations/plans/`). If none given, `ls .design-foundations/plans/*.md` and ask which to execute. Extract:

1. **Context** — used for goal anchoring in BUILD dispatch prompts (NOT for REVIEW). 2. **Phases** — the lifecycle stages (Discover / Design). 3. **Done-when items per phase** — every `- [ ]` under each `**Done when:**` (passed verbatim to both agents). 4. **`**Doctrine:**` per phase** — the doctrine names; become the `## Doctrine` block in each agent dispatch. 5. **`**Gate:**` per phase** — Full / Standard / Minimal. 6. **`**Model:**` per phase** — optional override (ladder: fable/sonnet/haiku; `opus` valid only as an explicit override). 7. **Edge cases per phase** — passed to REVIEW with DW-item verdict standing.

Verify Plan is Ready

| Plan status | Action | |-------------|--------| | `ready` / `in-progress` | Proceed (resume from `**Current Phase:**` if in-progress) | | `complete` | Ask: "Plan already complete. Re-execute or archive?" | | `blocked` | Show blockers, ask how to proceed |

---

Phase 2: SETUP (Initialize Tracking)

Update Plan Status

Set in the plan file: `**Status:** in-progress`, `**Started:** YYYY-MM-DD HH:MM`, `**Current Phase:** 1`.

Doctrine Resolution

For each phase, read its `**Doctrine:**` field. Validate each name against the resolver in `docs/pillar-taxonomy.md §5`. A name absent from the resolver → STOP and surface the gap to the user. A missing field → match the phase goal/scope against the stage map in `commands/plan.md` and add the right doctrine names. These become the `## Doctrine` block in each agent dispatch.

Model Resolution

Use the phase's `**Model:**` field if present, else omit (agents run on the active model). The ladder is fable → sonnet → haiku (`opus` a valid override, resolved the same as fa