Build

Build

Execute an implementation plan by reading a spec file and running the strategy matching its declared mode.

Variables

SPECPATH: $ARGUMENTS AVAILABLEAGENTS: ${CLAUDE_PLUGIN_ROOT}/agents/*.md

Cost Awareness

Agent spawning has real cost — each sub-agent consumes tokens for context loading, tool calls, and reporting. Before dispatching, ask: "Is this task complex enough to justify a separate agent?" A one-line config change does not need a builder agent, a review agent, and a validation agent. Use judgment:

• Trivial tasks: do them directly in the orchestrator
• Scout agents (haiku) are cheap — use them liberally for reconnaissance on unfamiliar code
• Do not skip reviews for non-trivial code changes, but do skip them for config, docs, and research tasks (per the Review Policy's Skip Review For setting)

Instructions

• If no SPEC_PATH is provided, stop and ask the user to provide it.
• Read the spec file at SPEC_PATH.
• Parse the YAML frontmatter to extract mode, complexity, type, playwright, frontend-design, spec-version, and branch.
• If spec-version is missing from frontmatter, log a warning ("spec written before spec-version was introduced — consider updating") but proceed normally. This ensures backwards compatibility.
• If branch is present in frontmatter, this is a resumed build — see Resuming a Build below.
• Based on mode, follow the corresponding execution strategy below.
• If playwright: true, append the Playwright instructions (see below) to every builder and tester agent dispatch prompt. If playwright: false or missing, do NOT mention Playwright to agents.
• If frontend-design: true, read ${CLAUDE_PLUGIN_ROOT}/templates/frontend-design-guidelines.md and the spec's ## Design Direction section. Append the Frontend Design Instructions (see below) to every builder agent dispatch prompt. If frontend-design: false or missing, do NOT mention frontend design to agents.
• Create a feature branch before starting any work (see Git Workflow below). After creating the branch, write branch: feat/ into the spec file's frontmatter to mark the build as started.
• Use TaskCreate to register every task from the spec's ## Step by Step Tasks section.
• Use TaskUpdate with addBlockedBy to set dependencies per each task's Depends On field.
• Execute tasks according to the mode.
• After all tasks complete: run ## Validation Commands and verify ## Acceptance Criteria.
• Present a final report.

Resuming a Build

If the spec's frontmatter contains a branch field, this is a resumed build:

1. Check out the existing branch (do not create a new one).
2. Derive the state directory path from the spec filename (strip date prefix and .md extension, e.g., specs/2026-03-14-my-feature.md → specs/.build-state/my-feature).
3. Read all task state files from the state directory (each .json file).
4. Use TaskCreate to re-create tasks, setting their status from the state files:

• "completed" tasks: create with status completed. Set the task description to the saved description field from the state file (this preserves agent reports and context).
• "in_progress" tasks: create with status in_progress. Set the description to the saved description (if any) plus a note: "RESUMED: This task was interrupted in a previous session. Check git log and changed files to determine what was completed before continuing."
• "pending" tasks: create normally.

1. Set dependencies via TaskUpdate addBlockedBy per each task's dependsOn field from the state files.
2. Skip dispatching/executing completed tasks.
3. For in_progress tasks: assess what was done (check git log, read files on disk) and continue from there rather than restarting from scratch.
4. For pending tasks: proceed normally according to the mode.

If the state directory does not exist but branch does, fall back to git-history-based resume: check out the branch, inspect commits with git log, and infer progress from what files exist and what tests pass.

Build State

Build state is persisted to disk so builds can resume from a fresh session. State directory: specs/.build-state// (derived by stripping the date prefix and .md extension from the spec filename).

On Build Start (new build, not resume)

After creating the feature branch and before creating tasks:

1. Derive the state directory path from the spec filename.
2. Create the directory and write _meta.json with: specFile (spec path), branch (feature branch name), mode (from frontmatter), startedAt (current ISO timestamp), lastUpdated (same as startedAt), compactions (0).
3. For each task in the spec's ## Step by Step Tasks section, write a .json file with: name (task name), status "pending", agentType (from spec Agent Type field, or "sequential" for sequential mode), startedAt null, completedAt null, lastUpdated (current ISO timestamp), description null, commitSha null, filesChanged [], dependsOn (array of task IDs from the Depends On field).

On Task Completion

The TaskCompleted hook automatically updates the task state file to "completed" with the agent's description, timestamp, and commit info. You do NOT need to manually update state files for task status transitions — the hook handles it.

After committing code, update the completed task's state file: set commitSha to the commit SHA and filesChanged to the list of files in that commit.

Git Workflow

Delegated mode: Builder and debugger agents running in worktrees MUST commit their own changes inside the worktree before marking the task complete. The orchestrator then merges the worktree branch back into the feature branch. Read-only agents do not commit.

Team mode: Agents do NOT touch git. All git operations are handled by the orchestrator (teammates have no worktree isolation).

Branch

Before executing any tasks:

1. Check if the spec frontmatter contains a branch field. If yes, check out that branch — this is a resumed build (see Resuming a Build above).
2. If no branch field, create a new feature branch:

`` git checkout -b feat/ ` Derive the branch name from the spec filename. For example, specs/2026-02-07-user-auth-api.md becomes feat/user-auth-api`.

1. After creating a new branch, write branch: feat/ into the spec file's YAML frontmatter (before the closing ---). This marks the spec as "build started" so it can be resumed if interrupted.
2. If the branch already exists but there's no branch field in frontmatter, check it out and add the field.

Commits

Commit after each task passes review — never before review approval. This ensures only reviewed code enters the history.

• Sequential mode: commit after you finish each task's self-review step.
• Delegated mode: commit after the reviewer agent approves the builder's work.
• Team mode: commit after the reviewer teammate approves.

Use this commit message format:

git add 
git commit -m "(): "

Where ` is one of: feat, fix, refactor, test, docs, chore`. Keep the first line under 72 characters. Do NOT include internal task IDs in commit messages.

After Validation

After all acceptance criteria pass, do NOT merge or push. Report the branch name and let the user decide what to do next.

Mode: Sequential

You execute tasks directly — no sub-agents.

Follow the spec literally. When the spec provides exact values (hex colors, string templates, element types, class names, timeout values, API parameters, units), use those exact values. Do not substitute your own preferences — the spec author chose specific values to ensure reproducible builds. If the spec says #e57373, use #e57373 — not a "similar" red. If the spec says createElement("div"), use a div — not a p or span. If the spec says timeout: 10000, use 10000 — not 5000. Treat the spec as a blueprint, not a suggestion.

1. Create the feature branch (see Git Workflow).
2. Create all tasks via TaskCreate. Set dependencies so each task blocks on the previous.
3. If frontend-design: true, read ${CLAUDE_PLUGIN_ROOT}/templates/frontend-design-guidelines.md. When executing tasks that involve frontend/UI code, apply these guidelines along with the spec's ## Design Direction section.
4. For each task in order:

• Mark it in_progress via TaskUpdate.
• Execute the task yourself — read files, write code, run commands.
• When the spec gives exact values, use them verbatim. When the spec is silent on a detail, make a reasonable choice but keep it minimal.
• If playwright: true and the task involves UI changes, verify visually using Playwright MCP tools (navigate, screenshot, interact, check console). If Playwright tools are not available, skip and note it.
• Mark it completed via TaskUpdate.

1. After completing all builder tasks and before the final code review task: run a security review. Read the security-reviewer agent definition from AVAILABLE_AGENTS to load the security checklist. List all files changed on the feature branch (git diff --name-only main...HEAD). Read every changed file and work through the 7-category security checklist systematically. Report findings using Critical/Important/Minor severity. Fix any Critical or Important issues before proceeding to the code review task.
2. After the security review and before the code review task: run the documentation step. Read the docs agent definition from AVAILABLE_AGENTS. Read the spec's ## Documentation Requirements section. List all files changed on the feature branch (git diff --name-only main...HEAD). Read every changed file. Produce all required documentation: README updates, changelog entries, API docs, and inline comments for complex logic. Commit documentation changes with git add && git commit -m "docs(): ".
3. When you reach a code review task: re-read every file you changed since the last commit, check for bugs, missing edge cases, security issues, and style problems. Fix anything you find. Then commit all changes from the reviewed task(s) and mark the review task as completed.
4. If a task fails: stop, report what succeeded and what failed, ask the user how to proceed.
5. After all tasks: run validation commands, check acceptance criteria.

Mode: Delegated

You are the orchestrator. You NEVER write code directly — you dispatch agents. When dispatching builder agents, emphasize that they must follow the spec literally — exact values specified in the task description (hex colors, string formats, element types, timeouts, units) must be used verbatim, not creatively interpreted.

1. Create the feature branch (see Git Workflow).
2. Read agent definitions from AVAILABLE_AGENTS to understand each agent's capabilities.
3. Create all tasks via TaskCreate. Set dependencies per spec.
4. Read the ## Review Policy section to understand review rules.
5. Assess task complexity before dispatching. For each task, evaluate its complexity before choosing the dispatch strategy:

• Simple (1-2 files, well-understood area, config or minor tweak): Execute the task directly in the orchestrator session. Do not spawn a sub-agent. This saves the cost of agent creation for trivial work.
• Moderate (2-5 files, straightforward implementation): Dispatch a single builder agent as normal.
• Complex (5+ files, unfamiliar area, multiple subsystems, or the task description flags uncertainty): Dispatch a scout agent (model: haiku) first to reconnoiter the target area. Use the scout's findings to enrich the builder's dispatch prompt with specific file paths, conventions, and gotchas. Then dispatch the builder.

When in doubt, lean toward dispatching rather than doing it yourself — the cost of a wrong direct implementation exceeds the cost of a sub-agent.

1. For each unblocked task:

• If Background: true and no dependency conflicts, dispatch with run_in_background: true.
• Dispatch the assigned agent via Task(subagent_type: "", model: "", ...).
• Agent dispatch rules:
• Always pass model matching the agent definition: builder=opus, researcher=sonnet, reviewer=sonnet, tester=sonnet, validator=haiku, architect=opus, debugger=opus, security-reviewer=opus, docs=sonnet, scout=haiku, merger=sonnet.
• For builder/debugger: always pass isolation: "worktree" and always spawn fresh (never reuse — worktrees are cleaned up after completion).
• For read-only agents (reviewer, researcher, validator, architect, security-reviewer, tester, docs): no isolation needed, CAN be reused.
• For scout: model haiku. No isolation. Read-only. Can be reused.
• For merger: model sonnet. No isolation. Dispatched for branch integration after builder review approval (replaces the inline merge protocol).
• Provide the FULL task description, relevant file paths, and acceptance criteria in the prompt. Do not tell the agent to read the spec — give it everything.

1. MANDATORY: After every builder task that writes code, dispatch a reviewer agent. Do NOT skip this step. Do NOT mark the builder task as completed until the reviewer has approved it.

• Dispatch a reviewer agent (model: sonnet) with the task spec, files changed, and a summary of what the builder did, and, if an architect produced a design for this task, the architect's design output so the reviewer can verify the implementation followed it.
• If reviewer reports Critical or Important issues:
• Spawn a fresh builder agent (with isolation: "worktree") and include the review feedback plus original task context in the prompt. Do NOT resume the previous builder — its worktree is gone.
• After fixes, dispatch reviewer again.
• Repeat up to Max Retries times.
• If max retries exceeded: stop and escalate to the user.
• If reviewer approves (or only Minor issues): merge the worktree branch (see Worktree Merge below), then mark task completed.
• Research, architecture, and validation tasks do NOT need review. No merge needed (read-only agents).

1. After all builder tasks are complete and reviewed, dispatch a security-reviewer agent (model: opus) to audit all files changed on the feature branch. Provide the list of changed files (git diff --name-only main...HEAD) and the spec's acceptance criteria.

• If the security reviewer reports Critical issues: resume the relevant builder agent to fix them, then re-dispatch the security reviewer. Repeat up to Max Retries times.
• Important issues: send to the builder for fixing but do not require a security re-review.
• Commit security fixes before proceeding to documentation.

1. After the security review is complete (and any security fixes are committed), dispatch a docs agent (model: sonnet) to produce documentation. Provide: the spec's ## Documentation Requirements section, the list of files changed on the feature branch (git diff --name-only main...HEAD), and the spec's acceptance criteria. The docs agent commits its own changes. After the docs agent completes, proceed to the validator.
2. After all tasks: dispatch a validator agent for final verification.

Worktree Merge (Delegated Mode)

Builder and debugger agents run with isolation: "worktree", each on its own branch. The agent commits its work inside the worktree before marking the task complete. After review approval, the orchestrator merges the worktree branch back into the feature branch.

Protocol:

1. After a builder/debugger task completes and the reviewer approves, identify the worktree branch from the task output or git worktree list / git branch.
2. Ensure you are on the feature branch: git checkout feat/.
3. For clean merges (no expected conflicts): merge directly with git merge --no-ff -m "merge: ".
4. If merge conflicts occur OR if multiple builders worked on related areas: dispatch a merger agent (model: sonnet) with the

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Ratler
• Source: Ratler/dream-team
• License: MIT

Install and usage instructions live in the source repository linked above.