Build
TDD-first. Follow the plan. No improvising.
Why this phase exists
Agents without a plan tend to hallucinate solutions. Build exists to execute a pre-validated specification with discipline. The craftsman following blueprints, not the architect drawing them.
It comes after Plan because the spec is its contract. Without a spec, Build has no objective completion criteria. A well-scoped plan lets the Build phase focus on implementation without second-guessing what to build.
TDD-first means the agent writes its own success criteria before writing the solution. This is the quality contract every downstream phase validates against. Tests are not an afterthought; they are the foundation.
Methodology
Receive plan artifact
Parse $plan_artifact from the Plan phase. Verify it includes file targets, change descriptions, and test strategy.
Read existing code
Before modifying any file, read it in full. Understand the current implementation, patterns, imports, and adjacent code. Never assume file contents.
Write tests first
Based on the plan's test strategy, write failing tests. These tests define the build's success criteria. One test per acceptance criterion. Follow existing test patterns.
Implement changes
Write code to make the tests pass. Follow the plan's file:line targets exactly. Track every file and line modified. Follow existing code patterns and conventions.
Run tests locally
Execute the test suite to verify the implementation passes. All new and existing tests must pass. If tests fail, fix the implementation, not the tests.
Generate build report
Produce structured output listing all changes, tests written, verification steps, and any deviations from the plan.
Inputs and outputs
Inputs
- • Plan artifact ($plan_artifact)
- • Full codebase access
- • Test command and working directory
Outputs
- • Modified code files
- • New test files
- • Build Report (Markdown)
Consumed by: Test phase as $build_report
# Build Report
## Status: ${build_status} # complete | partial | blocked
## Changes Made
| File | Lines | Action | Description |
|------|-------|--------|-------------|
| src/api/pagination.ts | 78-95 | Modified | Fixed off-by-one in cursor calculation |
| src/api/__tests__/pagination.test.ts | 1-65 | Created | Regression tests for cursor edge cases |
## Tests Written
- test_cursor_at_boundary_returns_correct_page -- PASS
- test_empty_result_set_returns_empty_cursor -- PASS
- test_last_page_cursor_is_null -- PASS
## Verification Steps
1. Run: npm test -- --testPathPattern=pagination
2. Expected: 3 new tests pass, 0 regressions
## Deviations from Plan
- None (or list any necessary deviations with justification)Example: a bug fix for an off-by-one pagination error. The Build report uses the same structure regardless of issue type.
Agent pattern
Why delegation? Context-window protection. The main agent holds the plan and tracks progress. The subagent does the actual file editing, which consumes context window rapidly.
When to delegate: when the plan involves more than 3-4 files, delegate to a subagent. For tiny patches (1-2 files), a single agent is sufficient.
Tool permissions
Build is one of only two phases (along with Test) that needs full access. It must read existing code, write new code, and execute tests to verify its work.
Full access does not mean unrestricted behavior. The plan is the constraint. The agent should only modify files listed in the plan. "I have write access" does not mean "I can change anything."
Prompt template
# Build Phase -- Software Engineer
## Role
You are a Software Engineer. Your job is to implement the
changes described in the plan below. You follow TDD: write
tests first, then implementation.
You do NOT deviate from the plan. You do NOT add features
the plan didn't ask for. You do NOT refactor code outside
the plan's scope.
## Context
Plan Artifact:
${plan_artifact}
Branch: ${branch_name}
Test Command: ${test_command} # e.g., npm test, pytest, go test
Working Directory: ${working_directory}
## Methodology -- TDD First
### Step 1: Read Before Writing
For every file listed in the plan's "Files to Modify" section,
read the full file first. Understand:
- Current implementation and patterns
- Import structure and dependencies
- Adjacent code that might be affected
- Existing test patterns for this module
### Step 2: Write Tests
Based on the plan's Test Strategy, create test files:
- One test per acceptance criterion
- Follow existing test patterns in the codebase
- Tests MUST fail initially (they test unwritten code)
- Name tests descriptively: test_[scenario]_[expected_result]
### Step 3: Implement
Write code to make the failing tests pass:
- Follow existing code patterns and conventions
- Import style matches the rest of the codebase
- Only modify files listed in the plan
- Track every file:line you change
### Step 4: Verify
Run the test command: ${test_command}
- All new tests must pass
- All existing tests must still pass
- If tests fail, fix the implementation (not the tests)
## Constraints
- Follow the plan exactly. No scope creep.
- Read existing code before modifying it.
- Write tests before implementation.
- Track every file and line number changed.
- Do not modify files not listed in the plan.
- Do not refactor adjacent code "while you're in there."
## Output Format
Produce a Build Report with:
1. Status -- complete | partial | blocked
2. Changes Made -- Table: File | Lines | Action | Description
3. Tests Written -- List with names and pass/fail status
4. Verification Steps -- Commands to run, expected results
5. Deviations from Plan -- Any necessary deviations with justificationBest practices
Do
- Read every file before modifying it
- Write tests before implementation
- Track every change with file:line precision
- Follow existing code patterns and conventions
- Run tests after every significant change
Don't
- Add features not in the plan
- Refactor code outside the plan scope
- Skip the test-first step
- Use git add -A
- Assume file contents; always read first
Nuances
"Read existing code before modifying" is the single most impactful instruction
Without it, agents overwrite existing logic, break imports, and create style inconsistencies. This one constraint eliminates most build failures.
Context-window protection
For large builds, the main agent should delegate to a subagent. The subagent does the editing work, which eats through tokens fast. The main agent keeps the plan and tracks progress.
Handling plan ambiguity
If the plan is unclear about a specific implementation detail, the Build agent should choose the most conservative approach and note the ambiguity in the Deviations section. Never guess.
Partial completion
If the Build cannot complete all changes (e.g., blocked by a missing dependency), it should produce a partial status with clear documentation of what was completed and what remains.