Builder Phase Workflow
You have been assigned a full phase to implement. Your spawn prompt contains the phase file path and plan folder. This skill teaches you how to handle the entire phase end-to-end.
Why This Workflow Exists
The user experienced builders that guessed at patterns, skipped tests, and produced inconsistent code. Each step below prevents a specific failure:
| Step | Prevents |
|---|
| Read phase completely | Missing requirements, user has to re-explain |
| Pre-flight test check | Cascading failures from broken previous phases |
| Find reference file | Guessing at patterns, code doesn't match codebase |
| Invoke domain skill | Missing project-specific conventions |
| TDD first (Step 0) | Untested code, bugs discovered in production |
Step 1: Read the Phase
Read the phase file from your spawn prompt. Extract:
- Prerequisites & Clarifications — check for unanswered questions first
- Requirements (Functional + Technical)
- Implementation Steps (Step 0 through Step N)
- Acceptance Criteria (your success metrics)
If ANY prerequisite question is unanswered:
SendMessage({
type: "message",
recipient: "team-lead",
content: "Phase has unanswered prerequisite questions. Cannot proceed.",
summary: "Blocked: unanswered prerequisites"
})
Then STOP and wait for instructions.
Step 2: Pre-Flight Test Check
Skip for Phase 01 — no previous phases exist.
For Phase 02+:
- Exit code 0 → proceed to Step 3
- Exit code ≠ 0 → check if failures are from current phase's TDD (expected) or previous phases
- Previous phase failures: fix them first, re-run to confirm green
- Current phase TDD failures: expected, proceed
Step 3: Invoke Domain Skill and Find Reference
Your spawn prompt includes a
field (extracted from the phase frontmatter by the orchestrator). If present, use that value. Otherwise, check the phase frontmatter for a
field, or determine from content:
| Phase Focus | Skill | Reference Glob |
|---|
| Database schema, migrations, RLS | | supabase/migrations/*.sql
|
| Server actions, services, API | | app/home/[account]/**/*server-actions*.ts
|
| React forms with validation | | app/home/[account]/**/_components/*.tsx
|
| E2E tests | | |
| React components, pages | vercel-react-best-practices
| app/home/[account]/**/_components/*.tsx
|
| UI/UX | | app/home/[account]/**/_components/*.tsx
|
| Service layer | | app/home/[account]/**/*service*.ts
|
- Glob the reference pattern → read ONE file
- Extract 3-5 key patterns: function signatures, imports, naming, error handling, post-operation hooks
- Invoke the domain skill:
Skill({ skill: "skill-name" })
The reference file is your ground truth. Your code must structurally match it.
Step 4: Create Internal Task List
Create tasks via
for each implementation step.
This is not optional — tasks survive context compacts and are your only recovery mechanism if context is compacted mid-phase. Without them, you must restart the entire phase from scratch.
Prefix all task subjects with to distinguish from the orchestrator's phase-level tasks in the shared team task list. Mark each task
before starting and
when done.
Task descriptions must be self-contained:
- File paths to create/modify
- Function signatures, key parameters
- Which services/actions to call
- Acceptance criteria for that step
Bad:
"Create the dropdown component"
Good:
"[Step] Create change-role-dropdown.tsx at app/home/[account]/roles/_components/. Props: { membershipId, accountSlug }. Fetch roles via listRolesAction, filter by hierarchy_level. Use @/components/ui Select, Badge."
Always start with Step 0: TDD.
Step 5: Implement
- Step 0 (TDD) first — write failing tests before implementation code
- Remaining steps sequentially — follow the phase document exactly
- After each step: run , fix failures before moving on
- Mark each task completed via as you finish it
Scope boundary — implement ONLY what's in the phase:
- Do NOT add improvements not specified in the phase
- Do NOT refactor adjacent code
- Do NOT create documentation files
Key project patterns:
- Server actions: validate with Zod, verify auth before processing
- Services: factory wrapping private class,
- Imports: path aliases, ordering: React > third-party > internal > local
- After mutations:
revalidatePath('/home/[account]/...')
IMPORTANT: Before using the Write tool on any existing file, you MUST Read it first or the write will silently fail. Prefer Edit for modifying existing files.
Step 6: Final Verification
Run the full verification before reporting:
bash
pnpm test
pnpm run typecheck
Both must pass. Fix any failures before proceeding.
Scope boundary: Your job ends here. Do NOT run
— an independent validator teammate will review your work after you report. This separation ensures blind spots are caught by a fresh set of eyes.
Step 7: Report Completion
Send completion message to the orchestrator:
SendMessage({
type: "message",
recipient: "team-lead",
content: "Phase [NN] implementation complete — ready for review.\n\nFiles created/modified:\n- [list]\n\nTests: passing\nTypecheck: passing\n\nAcceptance criteria met:\n- [list key criteria]",
summary: "Phase NN implemented — ready for review"
})
Then go idle. The orchestrator will either assign the next phase or send a shutdown request.
Resuming After Context Compact
If your context was compacted mid-phase:
- → find the or first task
- on that task → read the self-contained description
- Continue from that task — don't restart the phase
- The task list is your source of truth, not your memory
Troubleshooting
Tests fail but code looks correct
Cause: Reference patterns may have changed since the phase was written.
Fix: Re-read the reference file (Step 3). If the phase's code blocks differ from the current reference, follow the reference — it's the ground truth.
Domain skill not found
Cause: Skill name in phase frontmatter doesn't match available skills.
Fix: Check the table in Step 3 for the correct skill name. If the phase focus doesn't match any skill, skip skill invocation and rely on the reference file.