Builder Workflow

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 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+:

pnpm test

• 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: Identify Domain Skill and Reference

Check the phase frontmatter for a skill field, or determine from content:

1. Glob the reference pattern → read ONE file
2. Extract 3-5 key patterns: function signatures, imports, naming, error handling, post-operation hooks
3. 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 TaskCreate 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 [Step] to distinguish from the orchestrator's phase-level tasks in the shared team task list. Mark each task in_progress before starting and completed 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

1. Step 0 (TDD) first — write failing tests before implementation code
2. Remaining steps sequentially — follow the phase document exactly
3. After each step: run pnpm test, fix failures before moving on
4. Mark each task completed via TaskUpdate 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: createXxxService(client) factory wrapping private class, import 'server-only'
• 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:

pnpm test
pnpm run typecheck

Both must pass. Fix any failures before proceeding.

Scope boundary: Your job ends here. Do NOT run /code-review — 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:

1. TaskList → find the in_progress or first pending task
2. TaskGet on that task → read the self-contained description
3. Continue from that task — don't restart the phase
4. 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.