specmanager-build

Build one phase of the plan for $ARGUMENTS.

$ARGUMENTS is <feature> <phaseName | "next"> [--force] [--bulk].

• next resolves to the first phase whose tasks aren't all done (get_next_phase).
• Otherwise <phaseName> must match a ## Phase <name> heading from plan.md exactly.
• --force allows building out of order. Off by default.
• --bulk dispatches the whole phase in one builder Task (max tier of its tasks) instead of the default per-task loop. Off by default — an explicit opt-in for tiny, tightly-coupled phases, since it re-accepts one 529's blast radius across the whole phase.

Steps

1. Parse the arguments. Split into <feature>, <phaseName>, optional --force, optional --bulk. If <phaseName> is missing, ask the user (offer list_phases({ featureId })).

2. Resolve the feature. list_features → match by id/slug. Stop if not found.

3. Check the Plan is approved. check_gate({ featureId, stage: "plan" }) must be ok: true AND an approved plan doc must exist (list_documents({ featureId, stage: "plan" })). If not, report and stop — the builder needs a stable plan.

4. Resolve the target phase. next → get_next_phase({ featureId }); null means "All phases done — nothing to build", stop. Otherwise find <phaseName> in list_phases({ featureId }); if absent, list available phases and stop. 4c. Mark the build active (arms the Stop-gate). set_active_build({ featureId, phase: <resolvedPhaseName> }) — use the concrete resolved phase name, never "next". This writes the .cache/active-build.json marker that pins the Stop-gate to this exact phase; without it the gate is a no-op. Pair it with clear_active_build() on the terminal paths only — phase complete (step 8) and persistent-fail blocked (step 7b). A mid-phase stop, an exhausted retry budget included, must not clear: the build is still in flight and a re-entered session resumes this phase.

5. Order check (unless --force). If any phase with a lower order than the target has status !== "done", refuse: "Phase X has open tasks — build it first, or pass --force."

6. Idempotency. If the target phase is already done, report and stop — suggest /specmanager-walkthrough <feature> <phaseName> instead. 6b. Confirm the session tier→model table (R2). Once per build session, AskUserQuestion to confirm or remap which Claude Code model alias each complexity tier dispatches at. Pre-fill the defaults from core/tiers.ts: cheap → sonnet (complexity 1), standard → sonnet (complexity 2), strong → opus (complexity 3, and anything >3 / unscored) — cheap is sonnet, not haiku: Haiku 4.5's 200K context cap is a correctness cliff, not a cost preference. Offer the defaults as the recommended option plus an "all opus" / custom alternative. Hold it in session state for this build — aliasForTier takes it as sessionTable, so what you return is live. Always use aliases, never dated model ids. If the user declines, keep the defaults.

7. Invoke the builder (per-task tier dispatch is the enforced default; --bulk is the opt-in). Work the phase's tasks in dependsOn order.

   Default — per task (N=1, no flag). For each task: read its complexity (list_tasks), resolve it through the session table (1 → cheap, 2 → standard, 3 → strong, >3 or null → strong), and dispatch Agent({ subagent_type: "builder", model: <alias>, prompt: ... }) with: feature id/title/slug, the resolved phase name (not next), the single task id + title, the Plan doc id, and the phase's exit-test line lifted from plan.md. If the resolved alias is unknown/unavailable, omit model: so the builder runs at the session default (inherit) — never error or block (AC4). The builder marks that task in_progress→done with artifacts; on its return move to the next task. Per-task is the default because it isolates a 529 to a single card.

   Opt-in — --bulk. When --bulk was passed (step 1), dispatch all the phase's tasks in one builder Task at the max tier of its tasks (resolve each task's alias, pick the strongest). Then fall through to step 8's re-resolve exactly as the per-task path does.