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 0: Load Project Rules

Teammates don't inherit all parent rules — only

alwaysApply

Read these two files (they contain universal conventions for all code):

Read ~/.claude/rules/coding-style.md
Read ~/.claude/rules/patterns.md

If either file doesn't exist, skip it — the project may not have those rules configured.

These rules cover import ordering, error handling, server-only guards, data fetching patterns, service patterns, and route structure. Follow them throughout your implementation.

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, then proceed
  • Current phase TDD failures: expected, proceed

IMPORTANT — "pre-existing" is not an excuse. After a context compact, you may not know whether failures existed before your work started. It doesn't matter. You own every failure present when you report completion. If tests or typecheck are failing, fix them — regardless of who caused them.

Step 3: Invoke Domain Skill and Find Reference

Your spawn prompt includes a

Skill:

skill

postgres-expert

supabase/migrations/*.sql

server-action-builder

app/home/[account]/**/*server-actions*.ts

react-form-builder

app/home/[account]/**/_components/*.tsx

playwright-e2e

e2e/tests/**/*.spec.ts

vercel-react-best-practices

app/home/[account]/**/_components/*.tsx

web-design-guidelines

app/home/[account]/**/_components/*.tsx

service-builder

app/home/[account]/**/*service*.ts

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

Prefix all task subjects with

[Step]

in_progress

completed

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"

"[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.

Conditional Testing by Phase Type

The phase's

skill:

react-form-builder

pnpm test:e2e

vercel-react-best-practices

pnpm test:e2e

web-design-guidelines

pnpm test:e2e

playwright-e2e

pnpm test:e2e

postgres-expert

pnpm test:db

server-action-builder

service-builder

E2E test scoping:

1. Extract keywords from the phase title/slug (e.g.,

   notes

   ,

   billing

   ,

   auth

   )
2. Glob for

   e2e/**/*{keyword}*.spec.ts

3. If matches found:

   pnpm test:e2e -- [matched spec files]

4. If no matches:

   pnpm test:e2e

   (full suite)

Graceful skip: If a test command doesn't exist (exit code from missing script), skip it and note in your completion report. Projects without E2E or DB tests should not fail verification.

All extra tests must pass before reporting completion.

Scope boundary: Your job ends here. Do NOT run

/code-review

Step 7: Commit Changes (Worktree)

You are running in an isolated git worktree. Your changes live on a separate branch that the orchestrator will merge into the main tree. Uncommitted changes cannot be merged — they are lost when the worktree is cleaned up.

Commit all changes before reporting:

git add -A && git commit -m "feat(phase-{NN}): {phase-title}"

git add -A

If you have nothing to commit (e.g., the phase only modified test expectations that already pass), note this in your completion report.

Step 8: 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.