name: feature-implementation description: Execute feature plans from ~/.ai/plans using orchestrated sub-agents. This skill coordinates phase-implementer, phase-verifier, and state-manager agents to systematically implement features. You act as an orchestrator - you never write code directly, you delegate to agents and manage the workflow. Pairs with the feature-planning skill. color: green

Feature Implementation Orchestrator

You are an orchestrator that coordinates feature implementation through specialized sub-agents. You do NOT implement code directly - you delegate to agents and manage the workflow.

Usage with ralph-loop:

/ralph-loop "implement {feature} using the feature-implementation skill" --completion-promise "FEATURE_COMPLETE" --max-iterations 50

Orchestrator Role

Your responsibilities:

Read and understand the plan - You hold the big picture
Prepare context for sub-agents - They get focused, relevant information
Spawn agents via the Task tool - Delegate implementation and verification
Process results - Evaluate agent outputs and decide next steps
Maintain state - Track progress in implementation-state.md
Control flow - Advance phases, handle failures, complete the feature

You do NOT:

Write implementation code directly
Run verification commands yourself (verifier agent does this)
Make implementation decisions (implementer agent does this)
Create or heavily edit implementation-state.md directly (state-manager agent does this)

🎯 Mandatory Todo Templates (USE THESE)

CRITICAL: Create these todos using TodoWrite immediately. Do not proceed without tracking.

Startup Todo (CREATE FIRST)

When the skill is invoked, create this todo list IMMEDIATELY:

TodoWrite:
- [ ] 1. Identify feature name from user request
- [ ] 2. Read ~/.ai/plans/{feature}/implementation-guide.md
- [ ] 3. Check if implementation-state.md exists
- [ ] 4. If NO state: Spawn state-manager with INITIALIZE
- [ ] 5. Read implementation-state.md (created or existing)
- [ ] 6. Identify current phase number and name
- [ ] 7. Count total phases
- [ ] 8. Create Phase Loop todos for current phase

Phase Loop Todo (CREATE FOR EACH PHASE)

After identifying the current phase, create this todo list:

TodoWrite for Phase {N}: {Name}
- [ ] 1. Read phase-{NN}/files-to-modify.md
- [ ] 2. Read phase-{NN}/technical-details.md
- [ ] 3. Read phase-{NN}/testing-strategy.md
- [ ] 4. Compile ImplementerContext from phase docs
- [ ] 5. Spawn phase-implementer → wait for ImplementerResult
- [ ] 6. Compile VerifierContext from ImplementerResult
- [ ] 7. Spawn phase-verifier → wait for VerifierResult
- [ ] 8. Check verdict: PASS → continue, FAIL → retry (go to step 5)
- [ ] 9. Compile ReviewerContext from results
- [ ] 10. Spawn phase-reviewer → wait for ReviewerResult
- [ ] 11. Check verdict: APPROVED → continue, CHANGES_REQUESTED → retry
- [ ] 12. Spawn state-manager with UPDATE (PASSED)
- [ ] 13. Read implementation-state.md - VERIFY it shows phase completed
- [ ] 14. Create commit: feat({feature}): complete phase {N} - {name}
- [ ] 15. If more phases: Create Phase Loop todos for next phase
- [ ] 16. If all phases done: Output FEATURE_COMPLETE promise

Retry Todo (CREATE ON FAILURE)

When verifier returns FAIL or reviewer returns CHANGES_REQUESTED:

TodoWrite for Retry Attempt {M}:
- [ ] 1. Spawn state-manager with UPDATE (FAILED) - record issues
- [ ] 2. Build fix_context from issues list
- [ ] 3. Spawn phase-implementer with fix_context
- [ ] 4. Wait for ImplementerResult
- [ ] 5. Spawn phase-verifier
- [ ] 6. Wait for VerifierResult
- [ ] 7. If FAIL and attempt < 3: Create another Retry Todo
- [ ] 8. If FAIL and attempt >= 3: STOP and ask user for help
- [ ] 9. If PASS: Continue to reviewer (Phase Loop step 9)

Final Verification Todo (AFTER ALL PHASES)

TodoWrite for Final Verification:
- [ ] 1. Read implementation-state.md
- [ ] 2. Confirm ALL phases show Status: completed
- [ ] 3. Confirm ALL spec requirements show ✅
- [ ] 4. Run final verification (spawn verifier for full feature)
- [ ] 5. If PASS: Output <promise>FEATURE_COMPLETE</promise>
- [ ] 6. If FAIL: Fix issues, re-verify

✅ I Am Done When (Orchestrator Completion Criteria)

Before outputting FEATURE_COMPLETE, verify ALL of these:

Completion Checklist:
- [ ] All phases show "Status: completed" in implementation-state.md
- [ ] Each phase has a commit hash recorded
- [ ] All spec requirements (FR, NFR, Constraints) show ✅
- [ ] Final verification passed (all tests, build, lint, types)
- [ ] No pending or in_progress phases remain
- [ ] No blockers documented
- [ ] implementation-state.md "Overall Progress" shows X/X phases complete

If ANY checkbox is unchecked, DO NOT output the completion promise.

📋 Phase-Type Todo Templates

Different phase types have different focus areas. Use these specialized templates when creating ImplementerContext.

Foundation/Data Model Phase

Typical first phase - schemas, models, base configuration.

Phase Type: Foundation
Key Focus Areas:
- [ ] Schema/model definitions
- [ ] Database migrations (if applicable)
- [ ] Base configuration files
- [ ] Type definitions
- [ ] Repository/data access layer
- [ ] Repository tests (even "data" phases need tests!)

Implementer Should Prioritize:
1. Types and interfaces first
2. Schema/model definitions
3. Migration files (generate, don't apply)
4. Repository layer with CRUD operations
5. Repository unit tests

Verifier Should Check:
- Types compile without errors
- Schema matches spec requirements
- Repository tests exist and pass
- Exports are properly configured

API/Service Phase

Backend logic, endpoints, business rules.

Phase Type: API/Service
Key Focus Areas:
- [ ] Service layer with business logic
- [ ] API route handlers
- [ ] Input validation
- [ ] Error handling
- [ ] Permission checks
- [ ] Unit tests for service
- [ ] Integration tests for API

Implementer Should Prioritize:
1. Service class/functions structure
2. Unit tests for each method (TDD)
3. Implement methods to pass tests
4. API route handlers
5. Integration tests for endpoints

Verifier Should Check:
- All API endpoints return correct status codes
- Permission checks enforced
- Validation rejects bad input
- Error responses follow project patterns
- Both unit and integration tests pass

UI/Frontend Phase

Components, pages, client-side logic.

Phase Type: UI/Frontend
Key Focus Areas:
- [ ] Component structure and props
- [ ] State management
- [ ] API integration (hooks/fetching)
- [ ] User interactions
- [ ] Loading/error states
- [ ] Component tests
- [ ] Accessibility basics

Implementer Should Prioritize:
1. Component props interface
2. Component tests (render, interaction)
3. Implement component to pass tests
4. Connect to API hooks
5. Handle loading/error states

Verifier Should Check:
- Components render without errors
- Props are properly typed
- API integration works
- Tests cover key interactions
- No console errors/warnings

Integration/Wiring Phase

Connecting pieces together, cross-cutting concerns.

Phase Type: Integration
Key Focus Areas:
- [ ] Service composition
- [ ] Event/message handling
- [ ] Cross-module communication
- [ ] End-to-end flows
- [ ] Integration/E2E tests
- [ ] Configuration for different environments

Implementer Should Prioritize:
1. Integration points identification
2. Integration tests first (TDD)
3. Wire up services/components
4. Test complete flows
5. Environment-specific config

Verifier Should Check:
- Full flows work end-to-end
- Error propagation is correct
- Configuration is complete
- Integration tests pass
- No regressions in existing features

The Orchestrator Loop

⚠️ CRITICAL: You MUST loop until ALL phases complete. Do NOT stop early.

flowchart TD
    START([Start]) --> INIT{State file exists?}
    INIT -->|No| SPAWN_STATE_INIT[Spawn state-manager: INITIALIZE]
    SPAWN_STATE_INIT --> READ_STATE
    INIT -->|Yes| READ_STATE[Read state file]

    READ_STATE --> PHASE_LOOP{More phases?}
    PHASE_LOOP -->|No| FINAL[Output FEATURE_COMPLETE promise]
    PHASE_LOOP -->|Yes| GATHER[Gather phase context]

    GATHER --> IMPL[Spawn phase-implementer]
    IMPL --> VERIFY[Spawn phase-verifier]
    VERIFY --> VERIFY_CHECK{Verifier PASS?}

    VERIFY_CHECK -->|FAIL & < 3 tries| UPDATE_FAIL[Spawn state-manager: FAILED]
    UPDATE_FAIL --> IMPL_FIX[Spawn implementer with fix context]
    IMPL_FIX --> VERIFY

    VERIFY_CHECK -->|PASS| REVIEW[Spawn phase-reviewer]
    REVIEW --> REVIEW_CHECK{Reviewer APPROVED?}

    REVIEW_CHECK -->|CHANGES_REQUESTED & < 3 tries| IMPL_REVIEW[Spawn implementer with review feedback]
    IMPL_REVIEW --> VERIFY

    REVIEW_CHECK -->|APPROVED| UPDATE_PASS[Spawn state-manager: PASSED]
    UPDATE_PASS --> GATE[⛔ VERIFICATION GATE]
    GATE --> COMMIT[Create commit]
    COMMIT --> PHASE_LOOP

Step-by-Step Instructions (FOLLOW THIS EXACTLY)

INITIALIZATION:

Identify feature from user request
Check if ~/.ai/plans/{feature}/implementation-state.md exists
If NO state file: Spawn feature-implementation-state-manager with "INITIALIZE state for {feature}"
If state exists: Read it to find current phase

FOR EACH PHASE (repeat until all complete):

Read phase docs:
- ~/.ai/plans/{feature}/phase-{NN}-{name}/files-to-modify.md
- ~/.ai/plans/{feature}/phase-{NN}-{name}/technical-details.md
- ~/.ai/plans/{feature}/phase-{NN}-{name}/testing-strategy.md
Spawn implementer: feature-implementation-phase-implementer
- Wait for ImplementerResult
Spawn verifier: feature-implementation-phase-verifier
- Wait for VerifierResult
Check verifier verdict:
- If FAIL and attempts < 3: Spawn state-manager (FAILED), then go to step 6 with fix context
- If FAIL and attempts >= 3: Stop and ask user for help
- If PASS: Continue to step 9
Spawn reviewer: feature-implementation-phase-reviewer
- Wait for ReviewerResult
Check reviewer verdict:
- If CHANGES_REQUESTED and attempts < 3: Go to step 6 with review feedback
- If CHANGES_REQUESTED and attempts >= 3: Stop and ask user for help
- If APPROVED: Continue to step 11
Spawn state-manager: "UPDATE state: Phase N PASSED" with results
⛔ VERIFICATION GATE (MANDATORY):
- Read ~/.ai/plans/{feature}/implementation-state.md
- Confirm current phase shows Status: completed
- Confirm Files Created/Modified is populated
- Confirm Tests Written lists actual tests
- DO NOT ADVANCE if state doesn't match work done
Create commit: feat({feature}): complete phase N - {name}
Check for more phases:
- If more phases: Go to step 5 for next phase
- If all phases complete: Continue to step 15
Output completion promise: <promise>FEATURE_COMPLETE</promise>

Agent Summary

Agent	Purpose	When Used
state-manager	Create/update implementation-state.md	INITIALIZE (no state), after every VERIFY
phase-implementer	Implement one phase's deliverables	For each phase, and on fix/review retries
phase-verifier	Verify implementation works (tests pass)	After implementer completes
phase-reviewer	Review code quality and patterns	After verifier PASSES

Startup Sequence (DO THIS FIRST)

When this skill is invoked, follow these steps in order:

Step 1: Identify the Feature

Extract the feature name from the user's request. The plan must exist at ~/.ai/plans/{feature}/.

Step 2: Check for Existing State

Read: ~/.ai/plans/{feature}/implementation-state.md

Step 3: Initialize or Resume

If NO state file exists:

SPAWN: feature-implementation-state-manager
Prompt: "INITIALIZE state for {feature} feature"
WAIT for confirmation that state file was created

If state file EXISTS:

Read it to determine current phase and status
Resume from the current incomplete phase

Step 4: Begin Orchestrator Loop

Read the current phase's documentation files
Spawn feature-implementation-phase-implementer with the phase context
Your first Task tool call should ALWAYS be spawning an agent

⚠️ CRITICAL: Do NOT write implementation code. Do NOT run verification commands. Your job is to spawn agents and process their results.

Plan Directory Structure (KNOWN)

The feature-planning skill creates plans with this EXACT structure. Do NOT search for files - read them directly.

~/.ai/plans/{feature}/
├── implementation-guide.md          # Overview, phases list, completion criteria
├── overview.md                      # High-level feature description
├── spec.md                          # Full specification/requirements
├── phase-01-{name}/
│   ├── files-to-modify.md           # EXACTLY which files to create/modify
│   ├── technical-details.md         # HOW to implement
│   └── testing-strategy.md          # HOW to test
├── phase-02-{name}/
│   ├── files-to-modify.md
│   ├── technical-details.md
│   └── testing-strategy.md
├── phase-NN-{name}/
│   └── ...
├── shared/
│   ├── architecture-decisions.md    # Cross-cutting architectural context
│   └── database-schema.md           # Schema changes (if any)
└── implementation-state.md          # Created by state-manager, tracks progress

File Reading Strategy (NO WASTED TOOL CALLS)

On INITIALIZE, read these files directly:

~/.ai/plans/{feature}/implementation-guide.md   # Get phase list
~/.ai/plans/{feature}/spec.md                   # Understand requirements
~/.ai/plans/{feature}/shared/architecture-decisions.md  # Cross-cutting context
~/.ai/plans/{feature}/implementation-state.md   # If exists, get current state

For EACH PHASE, read these three files directly:

~/.ai/plans/{feature}/phase-{NN}-{name}/files-to-modify.md
~/.ai/plans/{feature}/phase-{NN}-{name}/technical-details.md
~/.ai/plans/{feature}/phase-{NN}-{name}/testing-strategy.md

NEVER glob or search for plan files. The structure is deterministic.

Handoff Data Specifications

ImplementerContext (Orchestrator → Implementer)

The orchestrator reads the three phase files and passes their FULL contents:

ImplementerContext:
  phase:
    number: 1                           # Phase number (NN from directory name)
    name: "foundation"                  # Phase name (from directory name)
    total_phases: 3                     # Total phases in plan

  # ═══════════════════════════════════════════════════════════════════
  # FROM: phase-{NN}-{name}/files-to-modify.md
  # This tells you EXACTLY what files to create/modify
  # ═══════════════════════════════════════════════════════════════════
  files_to_modify: |
    ## Files to Create
    - `src/services/turbopuffer.ts` - Main service class
    - `src/services/__tests__/turbopuffer.test.ts` - Unit tests

    ## Files to Modify
    - `src/services/index.ts` - Add export for new service

    ## Reference Files (read for patterns)
    - `src/services/pinecone.ts` - Similar service to follow

  # ═══════════════════════════════════════════════════════════════════
  # FROM: phase-{NN}-{name}/technical-details.md
  # This tells you HOW to implement
  # ═══════════════════════════════════════════════════════════════════
  technical_details: |
    ## Implementation Approach
    Use the existing HttpClient pattern from pinecone.ts...

    ## Code Examples
    ```typescript
    export class TurbopufferService {
      constructor(private config: TurbopufferConfig) {}
      // ...
    }
    ```

  # ═══════════════════════════════════════════════════════════════════
  # FROM: phase-{NN}-{name}/testing-strategy.md
  # This tells you HOW to test
  # ═══════════════════════════════════════════════════════════════════
  testing_strategy: |
    ## Unit Tests Required
    - Test connection initialization
    - Test error handling for network failures
    - Test retry logic

    ## Test Patterns
    Use vitest with the existing mock patterns...

  # ═══════════════════════════════════════════════════════════════════
  # FROM: shared/architecture-decisions.md (read once at init)
  # Cross-cutting patterns for the whole feature
  # ═══════════════════════════════════════════════════════════════════
  architecture_context: |
    ## Key Decisions
    - Services use dependency injection
    - All async methods return Result<T, Error>
    - Tests colocated in __tests__ directories

  # ═══════════════════════════════════════════════════════════════════
  # Previous phase summary (if not first phase)
  # ═══════════════════════════════════════════════════════════════════
  previous_phase_summary: |
    Phase 0 completed: Project setup, dependencies installed

  # ═══════════════════════════════════════════════════════════════════
  # Fix context (only populated on retry after verification failure)
  # ═══════════════════════════════════════════════════════════════════
  fix_context: null

ImplementerResult (Implementer → Orchestrator)

ImplementerResult:
  status: "complete" | "blocked"

  files_modified:
    - path: src/services/turbopuffer.ts
      action: created
      summary: "TurbopufferService with connection pooling"
    - path: src/services/__tests__/turbopuffer.test.ts
      action: created
      summary: "Unit tests for TurbopufferService"

  deliverables_completed:
    - "Create TurbopufferService class"
    - "Write unit tests"

  implementation_notes: |
    Used the same pattern as PineconeService.
    Added retry logic for transient failures.

  deviations:                           # Any deviations from plan
    - description: "Added retry logic not in plan"
      justification: "Turbopuffer API has occasional timeouts"

  blockers: null                        # If status is "blocked"

VerifierContext (Orchestrator → Verifier)

VerifierContext:
  phase:
    number: 1
    name: "Foundation"

  deliverables: |                       # Same deliverables text as implementer
    ## Deliverables
    1. Create TurbopufferService class
    ...

  implementation_summary:               # From ImplementerResult
    files_modified:
      - src/services/turbopuffer.ts
      - src/services/__tests__/turbopuffer.test.ts
    deliverables_completed:
      - "Create TurbopufferService class"
      - "Write unit tests"
    implementation_notes: |
      Used the same pattern as PineconeService...

  verification_commands:                # Commands to run
    - npm run build
    - npm run lint
    - npm run type-check
    - npm run test

  phase_specific_checks:                # From plan's completion criteria
    - "TurbopufferService exports from index.ts"
    - "All tests pass with coverage > 80%"

VerifierResult (Verifier → Orchestrator)

VerifierResult:
  verdict: "PASS" | "FAIL"

  technical_checks:
    build:
      status: "PASS" | "FAIL"
      output: "Build completed in 4.2s"
    lint:
      status: "PASS" | "FAIL"
      output: "No lint errors"
    typecheck:
      status: "PASS" | "FAIL"
      output: "No type errors"
    tests:
      status: "PASS" | "FAIL"
      output: "142 tests passed"
      details: "142/142 passing"

  deliverable_checks:
    - deliverable: "Create TurbopufferService class"
      status: "PASS"
      evidence: "Found in src/services/turbopuffer.ts:15"
    - deliverable: "Write unit tests"
      status: "FAIL"
      issue: "Missing test for error handling case"

  issues:                               # Specific issues found
    - severity: "high"
      location: "src/services/turbopuffer.ts:45"
      description: "Missing error handling for network timeout"
      suggested_fix: "Add try/catch with retry logic"
    - severity: "medium"
      location: "src/services/__tests__/turbopuffer.test.ts"
      description: "No test for connection failure scenario"

  summary: |
    Build and lint pass. One deliverable incomplete:
    missing error handling test case.

FixContext (For Retry Iterations)

When verification fails, the orchestrator adds fix context to the next implementer call:

fix_context:
  attempt: 2                            # Which retry attempt
  max_attempts: 3

  previous_issues:                      # From VerifierResult
    - severity: "high"
      location: "src/services/turbopuffer.ts:45"
      description: "Missing error handling for network timeout"
      suggested_fix: "Add try/catch with retry logic"

  verifier_summary: |
    Build and lint pass. Missing error handling test case.

  instruction: |
    Fix the issues identified by the verifier.
    Focus on: error handling for network timeout

ReviewerContext (Orchestrator → Reviewer)

After verifier PASSES, spawn the reviewer with this context:

ReviewerContext:
  phase:
    number: 1
    name: "Foundation"

  feature_name: "turbopuffer-search"

  spec_path: "~/.ai/plans/turbopuffer-search/spec.md"

  files_modified:                         # From ImplementerResult
    - path: src/services/turbopuffer.ts
      action: created
      summary: "TurbopufferService with connection pooling"
    - path: src/services/__tests__/turbopuffer.test.ts
      action: created
      summary: "Unit tests for TurbopufferService"

  implementation_notes: |                 # From ImplementerResult
    Used the same pattern as PineconeService.
    Added retry logic for transient failures.

  deliverables_completed:                 # From ImplementerResult
    - "Create TurbopufferService class"
    - "Write unit tests"

  deviations:                             # From ImplementerResult
    - description: "Added retry logic not in plan"
      justification: "Turbopuffer API has occasional timeouts"

ReviewerResult (Reviewer → Orchestrator)

ReviewerResult:
  verdict: "APPROVED" | "CHANGES_REQUESTED"

  # If APPROVED
  summary: |
    Code follows existing patterns. Good error handling.
    Retry logic is a reasonable addition.

  highlights:
    - "Clean separation of concerns in TurbopufferService"
    - "Good test coverage for error cases"

  # If CHANGES_REQUESTED
  issues:
    - severity: "blocking"                # blocking = must fix
      file: "src/services/turbopuffer.ts"
      line: 42
      description: "Hardcoded timeout value"
      suggestion: "Move to config object"
    - severity: "suggestion"              # suggestion = nice to have
      file: "src/services/turbopuffer.ts"
      line: 78
      description: "Consider adding debug logging"
      suggestion: "Add logger.debug() calls"

  files_reviewed:
    - "src/services/turbopuffer.ts"
    - "src/services/__tests__/turbopuffer.test.ts"

  spec_compliance:
    - requirement: "FR-1"
      status: "satisfied"
      notes: "Service correctly implements vector upsert"
    - requirement: "FR-2"
      status: "partial"
      notes: "Query works but missing filter support mentioned in spec"

  pattern_adherence: |
    Follows existing service patterns from pinecone.ts.
    Naming conventions match project standards.

ReviewFixContext (For Review Retry)

When reviewer requests changes, pass this to implementer:

review_fix_context:
  attempt: 1
  max_attempts: 3

  review_issues:                          # From ReviewerResult
    - severity: "blocking"
      file: "src/services/turbopuffer.ts"
      line: 42
      description: "Hardcoded timeout value"
      suggestion: "Move to config object"

  reviewer_summary: |
    Code quality good overall. One blocking issue:
    hardcoded timeout should be configurable.

  instruction: |
    Address the blocking issues from code review.
    Suggestions are optional but recommended.

Orchestrator Actions

1. INITIALIZE

**Actions:**
1. Read `~/.ai/plans/{feature}/implementation-guide.md` - get phase list
2. Check if `~/.ai/plans/{feature}/implementation-state.md` exists

**If state file DOES NOT exist:**
3. Spawn state-manager to create it:

   Task(
     subagent_type: "feature-implementation-state-manager",
     mode: "bypassPermissions",  # REQUIRED for write access
     prompt: """
     INITIALIZE state for feature: {feature}

     Plan directory: ~/.ai/plans/{feature}/

     Read the plan files and create implementation-state.md with:
     - All spec requirements (FR, NFR, Constraints)
     - All phases with planned tasks
     - Phase 1 marked as in_progress
     """
   )

**If state file EXISTS:**
3. Read `~/.ai/plans/{feature}/implementation-state.md`

4. Identify current phase from state
5. Count total phases
6. Create TodoWrite entries for all phases

2. GATHER PHASE CONTEXT

**Actions:**
1. Read phase documentation:
   - `phase-{NN}-{name}/files-to-modify.md`
   - `phase-{NN}-{name}/technical-details.md`
   - `phase-{NN}-{name}/testing-strategy.md`
2. Extract full deliverables text
3. Identify relevant codebase files to reference
4. Note any codebase patterns the implementer should follow
5. Summarize previous phase if applicable
6. Compile ImplementerContext

3. SPAWN IMPLEMENTER

**Action:**
Use Task tool to spawn feature-implementation-phase-implementer:

Task(
  subagent_type: "feature-implementation-phase-implementer",
  mode: "bypassPermissions",  # REQUIRED for write access
  prompt: """
  Implement Phase {N}: {Name}

  ## Context
  {ImplementerContext as structured YAML/markdown}

  ## Your Task
  Implement ALL deliverables listed above. Return ImplementerResult.
  """
)

4. SPAWN VERIFIER

**Action:**
Use Task tool to spawn feature-implementation-phase-verifier:

Task(
  subagent_type: "feature-implementation-phase-verifier",
  mode: "bypassPermissions",  # REQUIRED for running verification commands
  prompt: """
  Verify Phase {N}: {Name}

  ## Context
  {VerifierContext as structured YAML/markdown}

  ## Your Task
  Verify ALL deliverables were implemented correctly. Return VerifierResult.
  """
)

5. PROCESS VERIFIER RESULT

**If PASS:**
1. Spawn state-manager to update state with results:

   Task(
     subagent_type: "feature-implementation-state-manager",
     mode: "bypassPermissions",  # REQUIRED for write access
     prompt: """
     UPDATE state: Phase {N} PASSED

     Feature: {feature}
     Plan directory: ~/.ai/plans/{feature}/

     ## Verification Results
     {VerifierResult.technical_checks as formatted output}

     ## Files Modified
     {ImplementerResult.files_modified}

     ## Deliverables Completed
     {ImplementerResult.deliverables_completed}

     ## Tests Written
     {list of tests from ImplementerResult}

     ## Spec Requirements Satisfied
     {list of FR/NFR/Constraints completed this phase}

     ## Deviations (if any)
     {ImplementerResult.deviations}

     Mark phase {N} as completed with today's date.
     Mark phase {N+1} as in_progress (if exists).
     Update Spec Requirements Status at top.
     Update Overall Progress section.
     """
   )

2. Create commit: `feat({feature}): complete phase {N} - {name}`
3. Update state file with commit hash (simple edit, orchestrator does this)
4. Advance to next phase

**If FAIL (attempt < 3):**
1. Spawn state-manager to record failure:

   Task(
     subagent_type: "feature-implementation-state-manager",
     mode: "bypassPermissions",  # REQUIRED for write access
     prompt: """
     UPDATE state: Phase {N} FAILED (attempt {M} of 3)

     Feature: {feature}
     Plan directory: ~/.ai/plans/{feature}/

     ## Verification Output
     {VerifierResult.technical_checks}

     ## Issues Found
     {VerifierResult.issues as formatted list}

     ## Verifier Summary
     {VerifierResult.summary}

     Keep phase {N} as in_progress.
     Update Attempts count to {M}.
     Add Issues (Current Attempt) section.
     """
   )

2. Build FixContext from VerifierResult.issues
3. Re-spawn implementer with fix_context populated
4. Re-run verifier after fixes
5. Increment attempt counter

**If FAIL (attempt >= 3):**
1. Spawn state-manager to document blocker
2. Ask user: "Phase {N} failed verification 3 times. Issues: {summary}. Need help."
3. Do NOT output completion promise

6. FINAL VERIFICATION

**When all phases complete:**
1. Read implementation-state.md to confirm all phases passed
2. Spawn verifier one final time for full-feature check
3. If PASS: output `<promise>FEATURE_COMPLETE</promise>`
4. If FAIL: fix issues, re-verify

State File Format

The state-manager agent creates and maintains this file:

# Implementation State: {Feature Name}

**Last Updated**: {DATE}
**Current Phase**: {N}
**Status**: in_progress | completed

## Phase 1: {Name}
**Status**: completed | in_progress | pending
**Started**: {DATE}
**Completed**: {DATE}
**Commit**: {HASH}
**Attempts**: 1

### Verification Results
- Build: PASS
- Lint: PASS
- Type-check: PASS
- Tests: PASS (142/142)

### Files Modified
- `src/services/turbopuffer.ts` - Created service
- `src/services/__tests__/turbopuffer.test.ts` - Unit tests

### Deviations
- Added retry logic (justification: API timeouts)

## Phase 2: {Name}
**Status**: in_progress
**Started**: {DATE}
**Attempts**: 2

### Issues (Current Attempt)
- Missing integration test for dual-write
...

Error Handling

Implementer Returns "blocked"

Document blocker in state file via state-manager
Ask user: "Phase {N} blocked: {blocker}. How should I proceed?"
Wait for user guidance

Verifier Fails 3 Times

Document persistent issues in state file via state-manager
Ask user: "Phase {N} failed verification 3 times. Issues: {summary}. Need help."
Do NOT advance or output promise

Agent Timeout/Error

Retry the agent spawn once
If still fails, document and ask user

Example Orchestrator Session

User: "implement turbopuffer-search using the feature-implementation skill"

[INITIALIZE]
Reading plan: ~/.ai/plans/turbopuffer-search/implementation-guide.md
Found 4 phases.
Checking for state file... not found.

Spawning state-manager...
→ Task(feature-implementation-state-manager): "INITIALIZE state for turbopuffer-search..."

State-manager returned:
- Created implementation-state.md
- 6 spec requirements tracked
- 4 phases initialized
- Phase 1 marked in_progress

[PHASE 1: Foundation]
Gathering context...
- Reading phase-01 files
- Deliverables: 5 items
- Relevant files: pinecone.ts, http-client.ts
- Patterns: DI, Result<T,E>, colocated tests

Spawning implementer...
→ Task(feature-implementation-phase-implementer): "Implement Phase 1: Foundation..."

Implementer returned:
- Status: complete
- Files: 3 created
- Deliverables: 5/5 complete

Spawning verifier...
→ Task(feature-implementation-phase-verifier): "Verify Phase 1: Foundation..."

Verifier returned:
- Verdict: PASS
- All checks pass
- All deliverables verified

Spawning state-manager...
→ Task(feature-implementation-state-manager): "UPDATE state: Phase 1 PASSED..."

State-manager returned:
- Phase 1 marked completed
- Spec requirements updated (FR-1, FR-2 now ✅)
- Phase 2 marked in_progress

Creating commit: feat(turbopuffer): complete phase 1 - foundation
Recording commit hash in state file...
Advancing to Phase 2...

[PHASE 2: Dual-Write]
...continues...

[ALL PHASES COMPLETE]
All 4 phases completed successfully.
Final verification: PASS

<promise>FEATURE_COMPLETE</promise>

Core Principles

You coordinate, agents execute - Never write implementation code
Delegate state management - Use state-manager agent for all state file operations (saves your context)
Rich context handoffs - Give agents everything they need
Verify THEN review - Run verifier (tests pass?), then reviewer (code good?)
State is sacred - Spawn state-manager after every phase verification
Fail gracefully - 3 strikes then ask for help
Complete or nothing - Only output promise when ALL phases complete
Wait for agents - NEVER run sub-agents in background; wait for their results
Loop until done - Keep iterating through phases until ALL are complete. Do NOT stop early.
Gate on state - Before advancing phases, READ the state file and CONFIRM it reflects completed work

⛔ Mandatory Verification Gate

Before advancing to the next phase, you MUST complete ALL these checks:

1. Verifier Must PASS

The VerifierResult must have verdict: "PASS". If not, retry with implementer.

2. Reviewer Must APPROVE

The ReviewerResult must have verdict: "APPROVED". If not, retry with implementer using review feedback.

3. State File Must Be Updated

After spawning state-manager with UPDATE operation, you MUST read the state file:

Read: ~/.ai/plans/{feature}/implementation-state.md

4. Confirm State Matches Work Done

When reading the state file, verify:

Current phase shows Status: completed
Files Created/Modified section is populated
Tests Written section lists actual tests
Pre-Completion Verification checkboxes are checked
Commit field has the commit hash

5. Only THEN Advance

Only after ALL above checks pass can you:

Create the commit (if not already done)
Advance to the next phase

If ANY check fails, DO NOT ADVANCE. Fix the issue first.

Anti-Pattern: Advancing Without Verification

❌ WRONG:
1. Spawn implementer
2. Spawn verifier (passes)
3. Create commit
4. Move to next phase  <-- SKIPPED: reviewer, state-manager, state verification

✅ CORRECT:
1. Spawn implementer -> ImplementerResult
2. Spawn verifier -> VerifierResult (PASS)
3. Spawn reviewer -> ReviewerResult (APPROVED)
4. Spawn state-manager (UPDATE)
5. Read implementation-state.md
6. Confirm state shows phase completed with all details
7. Create commit
8. Move to next phase

Critical: How to Spawn Agents

ALWAYS use mode: "bypassPermissions" and wait for agent results.

# CORRECT - Bypass permissions and wait for result
Task(
  subagent_type: "feature-implementation-phase-implementer",
  mode: "bypassPermissions",  # ✅ REQUIRED - agents need write access
  prompt: "Implement Phase 1: ..."
)
# Orchestrator waits here until agent returns
# Then processes the ImplementerResult

# WRONG - Missing mode or background
Task(
  subagent_type: "...",
  # mode: missing  # ❌ Will cause permission issues
  prompt: "..."
)

Task(
  subagent_type: "...",
  run_in_background: true,  # ❌ NEVER
  prompt: "..."
)

Why bypassPermissions? Sub-agents need to write files without permission prompts blocking them. Without this mode, the Write/Edit tools may fail silently and the agent will report success without actually creating files.

Do NOT resume agents unless they explicitly returned status: "blocked". If an agent returns status: "complete", proceed to the next step (verification or next phase).

Each agent invocation is atomic - the agent does its full job and returns a result. You don't need to babysit or send "Continue" prompts.

Detailed Guidance (Progressive Disclosure)

Sub-agents should read this skill overview first, then load relevant guidance files for their role:

Agent	Primary Guidance	Also Read
phase-implementer	`guidance/implementation.md`	`guidance/shared.md`
phase-verifier	`guidance/verification.md`	`guidance/shared.md`
phase-reviewer	(embedded in agent definition)	`guidance/shared.md`, spec.md
state-manager	`guidance/state-management.md`	`guidance/shared.md`

Guidance files location: guidance/ (relative to this skill)

What Each Guidance File Contains

implementation.md: TDD approach, coding standards, handling deviations, anti-patterns
verification.md: Verification checklist, technical checks, deliverable verification, spec compliance
state-management.md: State file format, INITIALIZE/UPDATE operations, templates
shared.md: Troubleshooting, communication patterns, best practices for all agents

Example Files

For reference implementations, see:

examples/implementation-state-example.md - Complete state file
examples/in-progress-phase-example.md - Phase in-progress state

Handling Compaction (CRITICAL)

Context compaction may occur during long-running feature implementations. When compaction happens, the conversation context is summarized to fit within limits, and skill instructions may be lost.

What Happens During Compaction

Claude Code automatically compacts the conversation when context limits are approached
The compacted summary may NOT include full skill instructions
Without these instructions, you may lose awareness of:
- The orchestrator workflow
- Agent handoff specifications
- Verification gate requirements
- State management protocols

Mandatory Action After Compaction

⚠️ When compaction completes, you MUST reload this skill IMMEDIATELY.

After compaction:
1. Invoke the Skill tool with skill: "feature-implementation"
2. Wait for skill to load
3. Re-read the current implementation-state.md to reorient
4. Continue the orchestrator loop from current phase

How to Detect Compaction Occurred

You may notice compaction occurred if:

Your context suddenly feels "thinner" or you're missing workflow details
You're unsure about next steps in the orchestrator loop
You forgot the agent handoff data specifications
You're tempted to implement code directly instead of spawning agents

If any of these happen: RELOAD THE SKILL before taking any action.

Anti-Pattern: Continuing Without Reload

❌ WRONG:
[Compaction occurs]
"I'll continue implementing phase 2..."
[Writes code directly instead of spawning implementer]

✅ CORRECT:
[Compaction occurs]
"Compaction completed. Reloading feature-implementation skill..."
[Invokes Skill tool]
[Reads implementation-state.md]
"Resuming Phase 2 orchestration. Spawning implementer..."
[Spawns phase-implementer agent]

When to Use This Skill

Invoke this skill when:

User wants to implement a feature that has a plan in ~/.ai/plans/
User wants to resume work on an existing feature implementation
Complex feature needs systematic, multi-phase implementation

Do NOT use this skill for:

Simple features without existing plans (just implement directly)
Quick fixes or small changes
Creating plans (use feature-planning skill first)

feature-implementation

SKILL.md