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 — it re-accepts a single 529's blast radius across the phase, so it's an explicit opt-in for tiny, tightly-coupled phases only.

Steps

1. Parse the arguments. Split into <feature>, <phaseName>, optional --force, optional --bulk. If <phaseName> is missing, ask the user (offer list_phases({ featureId })). Default dispatch is per-task (step 7); --bulk switches to one whole-phase builder Task.

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 this with clear_active_build() on every terminal path (steps 8 and 9 below).

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 → haiku (complexity 1), standard → sonnet (complexity 2), strong → opus (complexity 3, and anything >3 / unscored). Offer the defaults as the recommended option plus an "all opus" / custom alternative. Hold the chosen table in session state for the rest of this build. 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), map complexity → tier → alias via the session table (default 1→cheap/haiku, 2→standard/sonnet, 3→strong/opus, >3 or null → strong), and dispatch Task({ 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 and spends the cheapest adequate model on each.

   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). This trades per-task isolation/tier savings for one builder context — use only on tiny, tightly-coupled phases. Then fall through to step 8's re-resolve exactly as the per-task path does.