implement-plan

Implement Plan

Turn a plan into working, verified, tested code with automatic task tracking.

Workflow Overview

1. Plan Selection — file path or inline markdown
2. Model Selection — pick Sonnet (default), Haiku, or Opus
3. Worktree Setup — delegate to /create-worktree skill
4. Phase-by-Phase Implementation — sequential execution
5. Quality Verification — delegate to project's /verify skill
6. Task Tracking — check off completed phases in plan file
7. Report — summary, worktree path, status

Step 0: Pre-Flight (MANDATORY before any implementation work)

Before reading source files, writing code, or invoking other skills, you MUST collect three answers in order:

1. Plan path/content (Step 1)
2. Model choice (Step 2)
3. Worktree decision (Step 3) — and if yes, complete /create-worktree and note the new worktree path, then proceed immediately

Do NOT begin Step 4 (Read Plan Structure) or any code reading until Steps 1–3 are answered and the worktree (if requested) exists. Skipping Step 3 has caused users to implement features on main and then manually migrate diffs — never acceptable.

If the user supplied a plan path as an argument, you have answered Step 1 but you have NOT answered Steps 2 and 3. Ask them now.

Step 1: Plan Selection

Prompt user:

Plan file path (or paste markdown content):

Accept either:

• File path: docs/plans/add-recipe-favorites.md, ./my-plan.md, etc.
• Inline markdown: (user pastes plan content directly)

If file path, read it. If inline, use content directly.

Then validate plan structure: must have phases (markdown sections starting with ###) with checkboxes (- [ ] for incomplete, - [x] for complete).

Step 2: Model Selection

Prompt:

Which model?
  1. Sonnet 4.6 (default) — balanced speed & quality
  2. Haiku — fast, cost-effective
  3. Opus — maximum quality for complex work

Enter choice (default: 1):

Use selected model for implementation phase. Store choice for reference in final report.

Step 3: Worktree Setup

Ask: "Should I create a new worktree? (y/n, default: y)"

If yes, call /create-worktree skill. Let the project implement worktree creation strategy (branch naming, isolation, etc.). Once the worktree is created, proceed directly to Step 4 — do NOT pause to confirm the worktree path with the user.

Step 4: Read Plan Structure

Plans must have this structure:

# Feature Name

## Overview
Brief description of what's being implemented.

## Phases

### Phase 1: Foundation Setup
- [ ] Task 1a: description
- [ ] Task 1b: description

### Phase 2: Core Implementation
- [ ] Task 2a: description
- [ ] Task 2b: description
- [ ] Task 2c: description

## Tests
List of expected test coverage.

## Edge Cases
Known edge cases to handle.

Key: Each phase is a section with checkboxes for tasks. The skill tracks and updates these.

Step 5: Phase-by-Phase Implementation

Before starting, invoke /clean-architecture to load the project's architectural rules into context:

/clean-architecture

Follow those rules throughout every phase.

For each phase in the plan:

1. Read the phase tasks
2. Implement all tasks in the phase, honoring the architecture rules loaded above
3. After implementation, run quality verification (Step 6)
4. If verification fails, retry (Step 6)
5. If verification passes, IMMEDIATELY perform Step 7 (check off phase in plan file) before moving to the next phase. Do not batch checkbox updates — write the file after each phase or they will be forgotten.

No parallelization — phases run sequentially, one at a time.

No sub-agents — implement directly, inline.

Step 6: Quality Verification

After each phase is implemented, call the project's /verify skill:

/verify

Expect response: pass or fail.

Retry Logic:

• Fail → fix issues → rerun /verify
• Max 3 attempts per phase
• 3rd failure → hard stop

On Hard Stop (3x failure):

Before paging the user, escalate to /deep-dive for a focused rescue attempt with a stronger model. The deep-dive skill is the dedicated escalation path for this exact case — one sub-agent, capped retry budget, explicit halt if it can't converge.

1. Capture the last /verify error output verbatim

2. Annotate the plan with a BLOCKED marker so the failure persists across sessions and is visible to anyone reading the plan. Append a callout block immediately under the failed phase heading:

   ### Phase <N>: <name>
   
   > ⚠️ **BLOCKED**: 3x `/verify` failure. Deep-dive in progress.
   > **Last error:** <one-line summary of the verify error>
   > **Worktree:** <worktree path>
   
   - [ ] Task ...
   

   Write the updated plan back to disk before handoff. This way, if the session ends mid-rescue, the plan still reflects reality and a future run can pick up the thread.

3. Invoke /deep-dive with:

   • Plan file path
   • Failed phase name/section
   • Last /verify error output (raw)
   • Worktree path
   • Model override (default: opus)

4. Read the deep-dive result:

   • Pass → deep-dive will have cleared the BLOCKED callout. Check off the phase and continue to the next phase.
   • Halt (deep-dive exhausted its 3 attempts) → deep-dive will have replaced the BLOCKED callout with a HALTED callout. Fall through to user-wait below.

User-Wait (deep-dive exhausted):

1. Report what failed (deep-dive halt report already covers attempt history)
2. Call /notify-me with error summary:

   /notify-me "implement-plan hard stop: Phase <N> failed verification 3x and deep-dive halted. Error: <summary>"
   

3. Wait for user intervention — do NOT check off phase or continue
4. User fixes issue in the worktree, signals ready to retry
5. Skill resumes from the failed phase

If /deep-dive is not available in the project, skip directly to the user-wait path.

Step 7: Task Tracking

When a phase passes verification, update the plan file locally:

1. Read the plan file
2. Change phase checkbox from - [ ] to - [x]
3. Write the updated plan back to the file

Then print updated plan state so user can see progress:

Phases completed:
✓ Phase 1: Foundation Setup
✓ Phase 2: Core Implementation
- Phase 3: Testing & Refinement (in progress)
- Phase 4: Documentation (pending)

The plan file is updated in your working directory — you decide what to do with it (commit, discard, etc.).

Step 8: Final Report

Before writing the report, re-read the plan file and confirm every implemented phase shows - [x]. If any are still - [ ], update them now (Step 7) before continuing.

Once all phases are checked off:

# Implementation Summary

**Plan:** <plan-name>
**Model:** <selected model>
**Worktree:** <path>
**Branch:** <branch-name>

## Phases Completed
- Phase 1: <description>
- Phase 2: <description>
- Phase 3: <description>

## Verification Status
✓ All phases passed verification

## What's Next
- Worktree is ready at <path>
- Review code and decide: merge, iterate, or cleanup
- Skill does NOT auto-merge or cleanup — that's your call

If hard-stopped due to failure:

# Implementation Stopped

**Plan:** <plan-name>
**Failed Phase:** <phase-name>
**Failure Point:** 3x verification failure

## Error Summary
<error output from last /verify call>

## Recovery
- Review the error above
- Fix the issue manually in the worktree
- Signal ready to retry
- Skill will rerun verification on the failed phase

Configuration

Projects can override via environment or project CLAUDE.md:

• VERIFY_SKILL — project's verification skill (default: /verify)
• NOTIFY_SKILL — notification skill (default: /notify-me)

Plan Format Example

# Feature: Recipe Favorites

## Overview
Add ability to mark recipes as favorites and filter by them.

## Phases

### Phase 1: Domain Layer
- [ ] Create Favorite use case in domain/favorites/
- [ ] Create FavoritesRepository interface
- [ ] Add unit tests for use case

### Phase 2: Data Layer
- [ ] Implement FavoritesRepositoryImpl
- [ ] Add Room entity and DAO
- [ ] Add data layer tests

### Phase 3: UI Layer
- [ ] Create FavoritesViewModel with UDF state
- [ ] Build Favorites Compose screens
- [ ] Add UI tests

### Phase 4: Integration
- [ ] Wire up navigation
- [ ] Integration tests across layers
- [ ] Manual testing (happy path + edge cases)

## Tests
- FavoritesUseCaseTest: ≥80% coverage
- FavoritesRepositoryImplTest: ≥80% coverage
- FavoritesViewModelTest: ≥80% coverage

## Edge Cases
- Favorite a recipe, then delete it from system
- Toggle favorite state rapidly
- Sync favorites across multiple devices (if applicable)

Notes

• No auto-cleanup — worktree stays on disk until you decide (merge, delete, etc.)
• No auto-commit — all code is staged/uncommitted in the worktree, ready for your review
• User review is required — don't merge automatically, inspect first
• Skill failures are explicit — hard stops make it clear when user input is needed