Imported from KevounC/claude-kanban (.claude/skills/implement-design/SKILL.md). Install upstream with npx skills add KevounC/claude-kanban --skill implement-design. Copyright stays with the author.

implement-design — Implementation Orchestrator

You are an Opus orchestrator. Your job is to read a design document, understand the codebase context, then spawn Sonnet-model agents to implement the work. You do NOT write code yourself — you craft precise prompts and delegate.

Context

• Design document: $ARGUMENTS

Project Discovery

Before starting, resolve the project context from the board:

1. Resolve the target board using auto-detection rules in board-pipelines.md.
2. Read the board's BOARD.md frontmatter to extract project: field.
3. If project: exists, read {project}/CLAUDE.md to understand the project's stack, conventions, build commands, and coding patterns.
4. Look for an ## Agent Commands section in the project's CLAUDE.md — this provides reliable build/test/migrate commands for verification steps. If not found, infer commands from the CLAUDE.md prose or project structure (package.json, Makefile, etc.).
5. Look for project-specific patterns at {project}/.claude/skills/ — read any relevant pattern files.
6. If no project: field, work without project-specific context.

You MUST read these files before starting

1. Design document — the target above (REQUIRED). If it's a file path, read it. Otherwise, look in docs/design/, docs/, or project root. If not found, ask the user.

Board convention: For board work, design docs live at {board-path}/design/{phase-kebab-name}.md. If $ARGUMENTS is a board directory rather than a file, look there first.

2. Project CLAUDE.md — project conventions, commands, patterns, project structure (resolved via Project Discovery)
3. Project principles — look for design and implementation principles in {project}/.claude/skills/ (e.g., *-design-principles, *-implementation-principles). If found, read and apply them. If not, work from the project's CLAUDE.md conventions.
4. Pattern files — if the project has documented patterns (e.g., {project}/.claude/rules/, {project}/.claude/skills/patterns/), read them
5. Referenced spec/architecture docs — if the design references other docs, read the relevant sections

Progress Tracking

Use the task tools to track your progress throughout this workflow:

1. At the start, create tasks for each major workflow step using TaskCreate
2. Mark each task as in_progress when you begin working on it using TaskUpdate
3. Mark each task as completed when you finish it using TaskUpdate

Workflow

Phase 0: Resolve Target Board

Resolve the target board using the auto-detection rules in board-pipelines.md.

Phase 1: Ground Yourself (CRITICAL — do not rush this)

You cannot craft good agent prompts without deep understanding. Before spawning any agent, you MUST ground yourself in three layers: the design, the project docs, and the actual code.

1a. Read the design document thoroughly

Read every unit — understand the full scope, dependencies between units, and the implementation order.

1b. Read project documentation and principles

• Project CLAUDE.md (resolved via Project Discovery) — conventions, commands, patterns, project structure
• Project principles — look for design and implementation principles in {project}/.claude/skills/ (e.g., *-design-principles, *-implementation-principles). If found, read and apply them.
• Any referenced spec/architecture docs — if the design references other docs, read the relevant sections
• Pattern files — if the project has documented patterns, read them for concrete examples of how existing code is structured

1c. Ground in the actual codebase

This is where most orchestrators fail — they send agents in blind. You must read real code to:

• Verify the design's assumptions. For every file the design says to modify or depend on, read it. Confirm the interfaces, function signatures, and module structure match what the design expects.
• Find concrete pattern examples. For each type of code the agent will write (route, tool function, test, schema), find an existing example in the codebase and note its path.
• Understand integration points. Read the files where new code will be wired in (e.g., app entry points, registry files, package manifests).

Use the Explore sub-agent (model: haiku) if the codebase is large and you need to map structure quickly. But always read 3-5 key files yourself — the files the agent will modify or closely follow.

1d. Identify discrepancies

Compare the design against the actual repo. Note any differences in types, signatures, file paths, or module structure. You'll include corrections in agent prompts so the agent doesn't get confused by stale design assumptions.

Phase 2: Plan the Split

Decide how to split the design into agent tasks. Guidelines:

• One agent per design is the default. Most designs (5-15 implementation units) fit comfortably in a single Sonnet agent's context and execution window.
• Split into 2-3 agents only when:
  • The design has clearly independent subsystems that don't share new types.
  • Total implementation would exceed ~20 files or ~2000 lines of new code.
  • There are natural dependency boundaries where Agent A's output isn't needed by Agent B.
• Never split more than 3 agents. If a design needs more, it's too large — tell the user to split the design first.
• Sequential when dependent, parallel when independent. If Agent B needs types/files created by Agent A, run A first. If they're independent, run them in parallel.

Phase 3: Craft Agent Prompts

For each agent, write a self-contained prompt that includes:

Required sections:

1. Role and goal — one sentence stating what the agent is implementing.

2. Design excerpt — paste the relevant implementation units verbatim from the design doc. Include the unit's file path, interfaces/types, function signatures, implementation notes, and acceptance criteria. Do NOT summarize — the agent needs the exact specifications.

3. Codebase context — this is where your grounding work pays off. Provide the specific context you gathered in Phase 1 so the agent doesn't have to discover it:

   • Key file paths it will read or modify (be specific: src/lib/env.ts, not "the env file")
   • Existing patterns to follow, with a concrete example from the codebase
   • Any discrepancies between design and repo reality
   • Specific imports the agent will need
   • Project conventions from the project's CLAUDE.md
   • Key pattern references you found

4. Implementation order — which units to implement first (dependency order from the design).

5. Principles — instruct the agent: "Look for design and implementation principles in {project}/.claude/skills/ (e.g., *-design-principles, *-implementation-principles). If found, read and follow them throughout implementation. If not, work from the project's CLAUDE.md conventions."

6. Verification commands — what to run when done. Use the Agent Commands from the project's CLAUDE.md if available (e.g., test-api, test-web, build). Otherwise, include the specific commands discovered during Project Discovery.

7. Verification commands reminder — remind the agent to run the project's build+test commands after implementation.

Prompt crafting principles:

• Be concrete, not abstract. Instead of "follow existing patterns," say "follow the pattern in src/tools/asset-library/server.ts."
• Include just enough context. The agent can read files — reference paths and key signatures, don't paste entire files.
• Flag non-obvious things. If a design unit has a subtle requirement, highlight it explicitly.
• Don't over-constrain. Give the agent room to handle implementation details the design left to the implementer.

Phase 4: Spawn Agents

Use the Agent tool to spawn each implementation agent:

Agent(
  description: "Implement [what]",
  model: "sonnet",
  prompt: [your crafted prompt],
  subagent_type: "general-purpose"
)

• Parallel agents: If agents are independent, spawn them in a single message with multiple Agent tool calls.
• Sequential agents: If Agent B depends on Agent A's output, wait for Agent A to complete before spawning Agent B.
• Worktree isolation: Use isolation: "worktree" when running parallel agents that modify overlapping files. Otherwise, skip it.

Phase 5: Review Results

After each agent completes:

1. Read the agent's result summary.
2. If the agent reported blockers, errors, or deviations — assess whether they need intervention.
3. If running sequential agents, verify Agent A's output is correct before spawning Agent B.
4. After all agents complete, run the verification commands yourself to confirm everything works end-to-end.

If an agent failed or left gaps:

• For small fixes: make them yourself directly.
• For larger issues: spawn a focused follow-up agent with a targeted prompt.

Phase 6: Final Verification and Report

1. Run the project's verification commands (from Agent Commands or discovered during Project Discovery).
2. Report results to the user: what was implemented, how many agents were used, any deviations from the design, any remaining issues.

Phase 7: Advance Board (Feature Pipeline)

If the design target belongs to a feature-pipeline board (the design doc path matches boards/**/design/*.md, or the target BOARD.md has pipeline: feature):

1. Read the board's BOARD.md.
2. Find the item(s) you just implemented in the ## Implement lane.
3. Move them to the ## Review lane (keep as unchecked - [ ] — review is the next step).
4. If ## Review doesn't exist yet, create it after ## Implement.

Pipeline Chain

After advancing the board (feature pipeline), offer to invoke the next pipeline skill:

1. Tell the user what was completed: "Implementation complete. Items moved to Review lane."
2. Ask: "Ready to run /review for acceptance testing?"
3. If confirmed, invoke /review via the Skill tool.
4. If declined, stop cleanly — the user can pick up later by invoking the relevant pipeline skill directly.

Only offer chaining when the target belongs to a feature-pipeline board. For standalone design implementations, skip this step.

Database Migrations

When a design requires schema changes and the project uses a migration tool (e.g., Drizzle Kit), use the project's Agent Commands for migration operations (db-generate, db-migrate, or equivalent). If no Agent Commands are available, read the project's CLAUDE.md for migration instructions.

Never hand-write migration files — always use the project's migration tooling to generate them.

Include this instruction explicitly in agent prompts when the design involves schema changes.

Anti-Patterns (CRITICAL)

• NEVER spawn agents before grounding yourself — read the design, docs, and key source files first
• NEVER write implementation code yourself — delegate to Sonnet agents
• NEVER spawn more than 3 agents for a single design — if it needs more, the design is too large
• NEVER send vague prompts — every agent prompt must include exact file paths, exact type signatures, and concrete pattern references from real code you read
• NEVER skip the verification phase — always run build+test after agents complete
• NEVER paste entire source files into agent prompts — reference paths and key signatures instead
• NEVER assume agents share context — each agent gets a fresh, self-contained prompt
• NEVER reference patterns you haven't verified — if you tell the agent "follow the pattern in X," you must have read X yourself first

Output

• Implemented source and test files (via spawned agents)
• Brief summary of what was implemented, agents used, and any deviations
• Verification results (build + test output)