builder-workflow

name	builder-workflow
description	Phase-level implementation workflow for builder agents. Handles reading phase files, finding references, invoking domain skills, implementing all steps, and running verification (tests + typecheck). Preloaded into builder agents via skills: field — not user-invocable.
user-invocable	false
metadata	{"version":"1.0.0","category":"workflow-automation","tags":["implementation","building","phase-execution"]}

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

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:

Phase Focus	Skill	Reference Glob
Database schema, migrations, RLS	postgres-expert	supabase/migrations/*.sql
Server actions, services, API	server-action-builder	app/home/[account]/**/*server-actions*.ts
React forms with validation	react-form-builder	app/home/[account]/**/_components/*.tsx
E2E tests	playwright-e2e	e2e/tests/**/*.spec.ts
React components, pages	vercel-react-best-practices	app/home/[account]/**/_components/*.tsx
UI/UX	web-design-guidelines	app/home/[account]/**/_components/*.tsx
Service layer	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 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.