5-phase-workflow 1.1.1 → 1.2.0

package/src/commands/5/plan-implementation.md

@@ -1,6 +1,6 @@
 ---
 name: 5:plan-implementation
-description: Creates a precise, AI-executable implementation plan. Performs all codebase analysis upfront and produces self-contained component prompts that can be executed by haiku without exploration. Phase 2 of the 5-phase workflow.
+description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
 allowed-tools: Read, Glob, Grep, Task, AskUserQuestion, Write
 context: fork
 user-invocable: true
@@ -8,432 +8,207 @@ user-invocable: true
 
 # Plan Implementation (Phase 2)
 
-## Overview
+Create an implementation plan that maps a feature spec to concrete components.
 
-This skill is the **second phase** of the 5-phase workflow:
-1. **Feature Planning** - Understand requirements, create feature spec (completed)
-2. **Implementation Planning** (this skill) - Analyze codebase, produce AI-executable plan
-3. **Orchestrated Implementation** - Execute plan with haiku agents
-4. **Verify Implementation** - Check completeness and correctness
-5. **Code Review** - Apply automated quality improvements
+## Scope
 
-**Critical design constraint:** The plan must be executable by haiku-model agents without any codebase exploration. This means YOU must do all analysis upfront and embed everything into the plan: exact file paths, exact code patterns, reference snippets, imports, and complete instructions.
+**This command creates the plan. It does NOT implement.**
 
-## Prerequisites
+After creating the plan, tell the user to run `/5:implement-feature`.
 
-Before invoking this skill, ensure:
-1. Feature spec exists at `.5/{TICKET-ID}-{description}/feature.md`
-2. Feature spec has been reviewed and approved by developer
-3. You have the feature name/ticket ID ready
+## Process
 
-## Planning Process
+### Step 1: Load Feature Spec
 
-### Step 1: Read Feature Specification
-
-Read the feature spec from `.5/{feature-name}/feature.md`.
+Read `.5/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
 
 Extract:
 - Ticket ID
-- Summary
 - Requirements (functional and non-functional)
-- Affected domains
-- Entity definitions
-- Business rules
 - Acceptance criteria
+- Affected components mentioned
 
-### Step 2: Deep Codebase Analysis
-
-**This is the most important step.** You must gather all context that the executor agents will need, because they cannot explore the codebase themselves.
-
-**2a. Project structure:**
-- Use Glob to map the directory structure
-- Identify source directories, test directories, config locations
-- Understand module/package organization
-
-**2b. Existing patterns (read actual files):**
-- Find 1-2 existing examples of each component type needed (e.g., an existing service, model, controller)
-- Read them fully to extract:
-  - Import statements and patterns
-  - Class/function structure
-  - Naming conventions (file names, variable names, export style)
-  - Error handling patterns
-  - Test patterns
-
-**2c. Dependencies and integration points:**
-- Read registration files, route files, module declarations
-- Understand how new components get wired in
-- Identify exact locations where modifications are needed (file path + line context)
-
-**2d. Build/test configuration:**
-- Read `.claude/.5/config.json` for build commands
-- Read available skills from `.claude/skills/`
+If the file doesn't exist, tell the user to run `/5:plan-feature` first.
 
-### Step 3: Technical Collaboration (3-5 Questions)
+### Step 2: Quick Codebase Scan
 
-Ask targeted technical questions using AskUserQuestion:
-- Data layer decisions (persistence, query patterns)
-- Validation requirements
-- API design choices
-- Whether to create new vs extend existing components
-- Challenge the approach: suggest simpler alternatives
+Understand the project structure:
+- Use Glob to find source directories
+- Identify where similar components live (models, services, controllers, tests)
+- Note naming conventions from existing files
 
-### Step 4: Map Components to Skills
+This is a quick scan, not deep analysis. The executor agent will do detailed pattern matching.
 
-For each component, determine:
-- Which skill creates it (from `.claude/skills/`)
-- Or `null` if no matching skill exists (component will be created directly via Write/Edit)
+### Step 3: Ask 2-3 Technical Questions
 
-### Step 5: Determine Dependency Steps
+Use AskUserQuestion to clarify:
+- Data layer decisions (if applicable)
+- Key implementation choices
+- Anything unclear from the feature spec
+- Software Architecture
+- Testing behaviour
 
-Group components by dependencies:
-1. Components with no dependencies → first step (parallel)
-2. Components depending on step 1 → second step
-3. Continue until all assigned
-4. Name steps based on content
+Keep it brief. Don't over-question. Don't ask feature questions already answered in the plan-feature phase. 
 
-### Step 6: Build Component Prompts
+### Step 4: Design Components
 
-**For each component, create a complete, self-contained execution prompt.** This prompt must contain everything a haiku agent needs to create the file without exploring anything.
+Based on the feature spec and codebase scan, identify:
+- What files need to be created
+- What files need to be modified
+- The order of implementation (dependencies)
 
-**For `action: create` components, the prompt must include:**
-- The complete file content to write, OR
-- A reference snippet from an existing file + clear instructions on what to change
-- All import statements
-- All type definitions needed
-- Exact file path
+Group into steps:
+- **Step 1**: Foundation (models, types, interfaces)
+- **Step 2**: Logic (services, business rules)
+- **Step 3**: Integration (controllers, routes, wiring)
+- **Step 4**: Tests (if not created alongside components)
 
-**For `action: modify` components, the prompt must include:**
-- The exact file path
-- The exact `old_string` to find (copied from the actual file)
-- The exact `new_string` to replace it with
-- Context about what's above/below to ensure uniqueness
+Not every feature needs all steps. Use what makes sense.
 
-**Prompt quality checklist:**
-- Could a developer who has never seen this codebase execute this prompt? If no, add more context.
-- Are all imports specified? If the component imports from other new components in this plan, are those paths correct?
-- Is the file path correct relative to the project root?
-- For modifications: is the old_string unique in the file?
-
-### Step 7: Write Implementation Plan
-
-Create the plan directory `.5/{feature-name}/plan/` and write atomic plan files:
-
-#### 7a. Create plan directory
-
-Use Bash to create the directory:
-```bash
-mkdir -p .5/{feature-name}/plan
-```
+### Step 5: Write the Plan
 
-#### 7b. Write plan/meta.md
-
-Write metadata file using this format:
+Create a single file at `.5/{feature-name}/plan.md`:
 
 ```markdown
 ---
+ticket: {TICKET-ID}
 feature: {feature-name}
-ticket: {ticket-id}
-total_steps: {N}
-total_components: {N}
-new_files: {N}
-modified_files: {N}
-created_at: {ISO timestamp}
-format_version: "2.0"
+created: {ISO-timestamp}
 ---
 
-# Plan Metadata: {TICKET-ID} - {Title}
+# Implementation Plan: {TICKET-ID}
 
-{1-2 sentence summary of what this plan builds}
+{One sentence summary}
 
-## Steps Overview
-- Step 1: {Name} ({N} components)
-- Step 2: {Name} ({N} components)
-- Step N: {Name} ({N} components)
+## Components
 
-## Risks
-- {risk 1}: {mitigation}
-- {risk 2}: {mitigation}
-```
+| Step | Component | Action | File | Description | Complexity |
+|------|-----------|--------|------|-------------|------------|
+| 1 | {name} | create | {path} | {what it does} | simple |
+| 1 | {name} | create | {path} | {what it does} | simple |
+| 2 | {name} | create | {path} | {what it does} | moderate |
+| 2 | {name} | modify | {path} | {what to change} | moderate |
+| 3 | {name} | create | {path} | {what it does} | complex |
 
-#### 7c. Write plan/step-N.md files (one per step)
+## Implementation Notes
 
-For each step, create a separate file `plan/step-{N}.md` using this format:
+{Any important context for the executor:}
+- Follow the pattern from {existing-file} for {component-type}
+- {Key business rule to remember}
+- {Integration point to wire up}
 
-```markdown
----
-step: {N}
-feature: {feature-name}
-name: "{Step Name}"
-mode: parallel | sequential
-components: {N}
----
+## Complexity Guide
 
-# Step {N}: {Step Name}
+**simple** → Use haiku (fast, cheap)
+- Creating files that closely follow existing patterns
+- Type definitions, interfaces, simple models
+- Adding imports/exports
+- Straightforward CRUD without custom logic
 
-{Brief description of what this step accomplishes}
+**moderate** → Use haiku with sonnet fallback
+- Services with some business logic
+- Files requiring understanding of multiple patterns
+- Modifications to existing files
 
-## Components
+**complex** → Use sonnet (better reasoning)
+- Integration points wiring multiple systems
+- Complex validation or business rules
+- Components requiring architectural decisions
+- Significant refactoring of existing code
 
-```yaml
-components:
-  - id: {component-id}
-    action: create | modify
-    file: "{exact/path/to/file.ext}"
-    skill: "{skill-name}" | null
-    depends_on: []
-    prompt: |
-      {Complete, self-contained execution instructions.
-
-      For create: include full file content or reference snippet.
-      For modify: include exact old_string and new_string.
-      Include all imports, types, and context.}
-
-  - id: {component-id-2}
-    action: create | modify
-    file: "{exact/path/to/file.ext}"
-    skill: "{skill-name}" | null
-    depends_on: ["{component-id}"]
-    prompt: |
-      {Complete instructions}
-```
+## Verification
 
-## Expected Outputs
-**Files Created:**
-- {path1}
-- {path2}
+- Build: {command or "auto"}
+- Test: {command or "auto"}
+```
 
-**Files Modified:**
-- {path3}
+**Key principle:** The plan describes WHAT to build, not HOW. The executor agent will figure out patterns by reading existing code.
 
-## Verification Targets
-**Build Targets:**
-- {module1}
-- {module2}
+### Step 6: Done
 
-**Test Targets:**
-- {test-module-1}
+Tell the user:
 ```
+Plan created at `.5/{feature-name}/plan.md`
 
-**Important:** Use YAML block within Markdown for components. This provides easy parsing while maintaining readability.
+{N} components across {M} steps.
 
-#### 7d. Write plan/verification.md
+Review the plan, then:
+1. Run `/clear` to reset context (recommended between phases)
+2. Run `/5:implement-feature {feature-name}`
+```
 
-Write verification configuration file:
+## Example Plan
 
 ```markdown
-# Verification Configuration
-
-build_command: "{from config}"
-test_command: "{from config}"
-
-## Expected New Files
-- {path1}
-- {path2}
-
-## Expected Modified Files
-- {path3}
-- {path4}
+---
+ticket: PROJ-1234
+feature: PROJ-1234-add-emergency-schedule
+created: 2026-01-28T10:00:00Z
+---
 
-## Build Targets
-- {module1}
-- {module2}
+# Implementation Plan: PROJ-1234
 
-## Test Modules
-- {test-module-1}
-```
+Add emergency schedule tracking to products with date validation.
 
-### Step 8: Inform Developer
+## Components
 
-After creating the implementation plan, tell the developer:
+| Step | Component | Action | File | Description | Complexity |
+|------|-----------|--------|------|-------------|------------|
+| 1 | Schedule model | create | src/models/Schedule.ts | Schedule entity with name, startDate, endDate, isEmergency | simple |
+| 1 | Schedule types | create | src/types/schedule.ts | TypeScript interfaces for schedule data | simple |
+| 2 | Schedule service | create | src/services/ScheduleService.ts | CRUD operations with date validation (endDate > startDate) | moderate |
+| 2 | Schedule repository | create | src/repositories/ScheduleRepository.ts | Database access for schedules | simple |
+| 3 | Schedule controller | create | src/controllers/ScheduleController.ts | REST endpoints: GET/POST/DELETE /api/schedules | moderate |
+| 3 | Register routes | modify | src/routes/index.ts | Add schedule routes to router | simple |
+| 4 | Schedule service tests | create | src/services/__tests__/ScheduleService.test.ts | Test validation and CRUD | moderate |
 
-1. "Implementation plan created at `.5/{feature-name}/plan/`"
-2. "{N} components across {M} steps"
-3. "Atomic plan structure: meta.md, step-1.md, step-2.md, ..., verification.md"
-4. "Each component has a self-contained execution prompt for haiku agents"
-5. "Please review the plan files"
-6. "Then run `/clear` followed by `/5:implement-feature {feature-name}`"
+## Implementation Notes
 
-## Component Prompt Examples
+- Follow the pattern from src/services/UserService.ts for the service
+- Follow the pattern from src/controllers/UserController.ts for the controller
+- Date validation: endDate must be after startDate, throw ValidationError if not
+- Emergency schedules have `isEmergency: true` flag
 
-### Example: Create a new TypeScript service
+## Verification
 
+- Build: npm run build
+- Test: npm test
 ```
-#### component: schedule-service
-action: create
-file: "src/services/ScheduleService.ts"
-skill: null
-depends_on: ["schedule-model"]
-prompt: |
-  Create file `src/services/ScheduleService.ts` with this content:
-
-  ```typescript
-  import { Schedule } from '../models/Schedule';
-  import { ScheduleRepository } from '../repositories/ScheduleRepository';
-  import { ValidationError } from '../errors/ValidationError';
-
-  export class ScheduleService {
-    constructor(private readonly repo: ScheduleRepository) {}
-
-    async create(data: { name: string; startDate: Date; endDate: Date }): Promise<Schedule> {
-      if (data.endDate <= data.startDate) {
-        throw new ValidationError('endDate must be after startDate');
-      }
-      return this.repo.save(new Schedule(data));
-    }
-
-    async findById(id: string): Promise<Schedule | null> {
-      return this.repo.findById(id);
-    }
-
-    async delete(id: string): Promise<void> {
-      return this.repo.delete(id);
-    }
-  }
-  ```
-
-  This follows the pattern from `src/services/UserService.ts`.
-```
-
-### Example: Modify an existing router file
 
-```
-#### component: register-schedule-routes
-action: modify
-file: "src/routes/index.ts"
-skill: null
-depends_on: ["schedule-controller"]
-prompt: |
-  Modify file `src/routes/index.ts`.
-
-  Find this exact string:
-  ```
-  // Route registrations
-  app.use('/api/users', userRoutes);
-  ```
-
-  Replace with:
-  ```
-  // Route registrations
-  app.use('/api/users', userRoutes);
-  app.use('/api/schedules', scheduleRoutes);
-  ```
-
-  Also add this import at the top of the file, after the existing imports:
-  Find: `import { userRoutes } from './userRoutes';`
-  Replace with:
-  ```
-  import { userRoutes } from './userRoutes';
-  import { scheduleRoutes } from './scheduleRoutes';
-  ```
-```
+## Structuring Steps for Parallel Execution
 
-### Example: Create a test file
+Components in the same step run in parallel. Structure your plan accordingly:
 
+**Good - parallel-friendly:**
 ```
-#### component: schedule-service-test
-action: create
-file: "src/services/__tests__/ScheduleService.test.ts"
-skill: null
-depends_on: ["schedule-service"]
-prompt: |
-  Create file `src/services/__tests__/ScheduleService.test.ts` with this content:
-
-  ```typescript
-  import { ScheduleService } from '../ScheduleService';
-  import { ScheduleRepository } from '../../repositories/ScheduleRepository';
-  import { ValidationError } from '../../errors/ValidationError';
-
-  describe('ScheduleService', () => {
-    let service: ScheduleService;
-    let mockRepo: jest.Mocked<ScheduleRepository>;
-
-    beforeEach(() => {
-      mockRepo = {
-        save: jest.fn(),
-        findById: jest.fn(),
-        delete: jest.fn(),
-      } as any;
-      service = new ScheduleService(mockRepo);
-    });
-
-    describe('create', () => {
-      it('creates a schedule with valid dates', async () => {
-        const data = {
-          name: 'Test',
-          startDate: new Date('2026-01-01'),
-          endDate: new Date('2026-01-31'),
-        };
-        mockRepo.save.mockResolvedValue({ id: '1', ...data } as any);
-        const result = await service.create(data);
-        expect(mockRepo.save).toHaveBeenCalled();
-        expect(result).toBeDefined();
-      });
-
-      it('throws if endDate <= startDate', async () => {
-        const data = {
-          name: 'Test',
-          startDate: new Date('2026-01-31'),
-          endDate: new Date('2026-01-01'),
-        };
-        await expect(service.create(data)).rejects.toThrow(ValidationError);
-      });
-    });
-  });
-  ```
-
-  This follows the test pattern from `src/services/__tests__/UserService.test.ts`.
+| Step | Component | File |
+| 1 | Model | src/models/Schedule.ts |        ← parallel (no deps)
+| 1 | Types | src/types/schedule.ts |         ← parallel (no deps)
+| 2 | Service | src/services/ScheduleService.ts |  ← parallel
+| 2 | Repository | src/repositories/ScheduleRepo.ts | ← parallel
+| 3 | Controller | src/controllers/ScheduleCtrl.ts | ← needs service
+| 3 | Routes | src/routes/index.ts |           ← needs controller
 ```
 
-## Instructions Summary
-
-1. **Read feature spec** from `.5/{feature-name}/feature.md`
-2. **Deep codebase analysis** - Read actual files, extract patterns, imports, conventions. This is the critical step.
-3. **Ask 3-5 technical questions** - Clarify implementation details
-4. **Map components to skills** - Check `.claude/skills/` for available skills
-5. **Group into dependency steps** - Based on component dependencies
-6. **Build self-contained prompts** - Each prompt must be executable by haiku without exploration
-7. **Write plan** to `.5/{feature-name}/plan.md` in the structured format
-8. **Inform developer** to review and run `/5:implement-feature`
-
-## Key Principles
-
-1. **Haiku-ready prompts** - Every component prompt is self-contained with all context baked in
-2. **No exploration by executors** - All codebase analysis happens here in Phase 2
-3. **Exact file paths** - No guessing, no pattern matching needed
-4. **Reference code inline** - Include actual snippets, not "look at file X"
-5. **Dependency-driven steps** - Step grouping from component dependencies
-6. **Verify prompt quality** - Could someone with no codebase knowledge execute it?
-
-## DO NOT
-
-- DO NOT start implementation (that's Phase 3's job)
-- DO NOT create state files (that's `/implement-feature`'s job)
-- DO NOT write vague prompts like "follow existing patterns" without including the pattern
-- DO NOT skip codebase analysis - reading actual files is mandatory
-- DO NOT leave file paths ambiguous
-- DO NOT write prompts that require the executor to read other files to understand what to do
-- DO NOT assume the executor can figure things out - be explicit
-
-## Example Usage
-
+**Bad - forces sequential:**
 ```
-User: /plan-implementation PROJ-1234-add-emergency-schedule
-
-Skill:
-1. Reads .5/PROJ-1234-add-emergency-schedule/feature.md
-2. Explores codebase: reads existing models, services, routes, tests
-3. Extracts patterns: import style, naming, structure, test framework
-4. Asks technical questions about validation, persistence, API
-5. Maps components to skills (or null for direct execution)
-6. Groups into steps by dependencies
-7. Builds self-contained prompts with inline code and exact paths
-8. Creates .5/PROJ-1234-add-emergency-schedule/plan/ directory
-9. Writes plan/meta.md with metadata and risks
-10. Writes plan/step-1.md, plan/step-2.md, plan/step-3.md with YAML components
-11. Writes plan/verification.md with build/test config
-12. Tells user: "Plan created with 7 components across 3 steps. Atomic plan structure at `.5/PROJ-1234-add-emergency-schedule/plan/`. Review the plan files, then run `/clear` followed by `/5:implement-feature PROJ-1234-add-emergency-schedule`"
+| Step | Component | File |
+| 1 | Model | ... |
+| 2 | Types | ... |        ← could be step 1
+| 3 | Service | ... |
+| 4 | Repository | ... |   ← could be step 3
 ```
 
-## Related Documentation
+**Rules:**
+- Group independent components in the same step
+- Only separate into different steps when there's a real dependency
+- More components per step = more parallelization = faster execution
+
+## What NOT To Do
 
-- [5-Phase Workflow Guide](../docs/workflow-guide.md)
+- Don't write complete code in the plan
+- Don't spend time on "haiku-ready prompts"
+- Don't create multiple plan files (meta.md, step-N.md, etc.)
+- Don't over-analyze the codebase - the executor will do detailed pattern matching
+- Don't ask more than 3 questions
+- Don't create unnecessary sequential steps - group independent work together