Implementation Plan Companion

Your agent for generating detailed, executable implementation plans — designed to produce step-by-step plans that other AI agents or developers can follow precisely to build features or refactor systems.

When to Use This Agent

Choose Implementation Plan Companion when:

• Breaking down a feature request into detailed implementation steps
• Creating plans for AI-to-AI workflows (one agent plans, another implements)
• Generating sprint-ready task breakdowns from high-level requirements
• Planning complex refactoring operations with clear dependencies
• Creating implementation roadmaps with ordered steps and verification points

Consider alternatives when:

• You need to implement the plan yourself — use a developer or coding agent
• You need architecture design — use an architect agent
• You need project management — use a planning or Jira agent

Quick Start

Copy
# .claude/agents/implementation-plan.yml
name: Implementation Plan Companion
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
description: Implementation planning agent that generates executable step-by-step plans for features and refactors

Example invocation:

claude "Create a detailed implementation plan for adding real-time notifications to our app — cover WebSocket setup, event handling, UI components, and database schema changes"

Core Concepts

Plan Structure

Copy
# Implementation Plan: [Feature Name]

## Prerequisites
- [What must exist before starting]
- [Required dependencies or access]

## Step 1: [First Task]
### Files to Modify
- `path/to/file.ts` — [What to change]
### Implementation
[Specific code changes or instructions]
### Verification
- [ ] [How to verify this step works]

## Step 2: [Second Task]
### Dependencies
- Requires: Step 1
### Files to Create
- `path/to/new-file.ts` — [Purpose]
### Implementation
[Detailed instructions]
### Verification
- [ ] [Verification steps]

## Integration Verification
- [ ] [End-to-end verification after all steps]

Plan Quality Criteria

Criterion	Description	Test
Executable	Steps can be followed literally	Can an AI agent execute each step?
Ordered	Steps respect dependencies	No step references future work
Verifiable	Each step has success criteria	Can you confirm each step worked?
Complete	No missing steps or assumptions	Following the plan produces the result
Scoped	No unnecessary work included	Every step contributes to the goal

Configuration

Parameter	Description	Default
plan_audience	Who follows the plan (developer, ai-agent, team)	ai-agent
detail_level	Plan granularity (high-level, detailed, line-by-line)	detailed
include_verification	Add verification steps per task	true
include_rollback	Add rollback instructions for each step	false
output_format	Plan format (markdown, checklist, json)	markdown

Best Practices

1. Start every plan by exploring the current codebase. Before planning changes, understand the existing code structure, patterns, and conventions. Plans that assume a structure different from reality produce incorrect implementation steps.

2. Order steps by dependencies, not by perceived importance. Database schema changes come before API endpoints that query them. API endpoints come before frontend components that call them. Each step should be implementable using only what previous steps have created.

3. Include specific file paths and function names. "Update the user service" is vague. "Add sendNotification(userId, message) method to src/services/userService.ts after the existing updateUser method" is executable.

4. Add verification steps after every implementation step. Each step should include how to confirm it worked: "Run npm test -- userService.test.ts — the new sendNotification test should pass." Verification catches issues before they compound.

5. Keep plans to 10-15 steps maximum. Longer plans indicate the task should be split into multiple phases. Each phase should produce a working, shippable increment. If step 15 depends on step 1 and everything in between, the plan is too monolithic.

Common Issues

Plan assumes code structure that doesn't exist. Plans generated without reading the codebase first describe changes to files that don't exist or functions that are named differently. Always start with codebase exploration before writing implementation steps.

Steps are too vague for the implementer to follow. "Add error handling" doesn't tell the implementer what errors to handle, what pattern to follow, or where to add it. Include specific exception types, handling patterns consistent with the codebase, and exact locations.

Plan doesn't account for test changes needed. Implementation plans that only cover production code leave the implementer to figure out test updates independently. Include test file modifications as explicit plan steps, with specific test cases to add or update.