Writing Implementation Plans

Create detailed plans for engineers with minimal codebase familiarity. Break work into granular, testable tasks following TDD principles.

When to Use

• Before implementing new features
• Before complex refactoring
• When work spans multiple files/components
• When coordinating multi-agent work

Plan Location

Save all plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

Plan Structure

Header (Required)

# Plan: [Feature Name]

**Goal:** [One sentence describing what this achieves]

**Architecture:** [2-3 sentences on approach]

**Tech Stack:** [Relevant technologies]

**Files Affected:**

- `path/to/file1.ts` - [what changes]
- `path/to/file2.ts` - [what changes]

Task Format

Each task = single 2-5 minute action:

## Task 1: [Descriptive Name]

**Action:** Create | Modify | Test

**Files:**

- Create: `src/components/Button.tsx`
- Test: `src/components/Button.test.tsx`

**Steps:**

1. Write failing test for [behavior]
2. Verify test fails with expected error
3. Implement minimal code to pass
4. Verify test passes
5. Commit: `test(button): add click handler test`

**Verification:**

- [ ] Test fails initially
- [ ] Test passes after implementation
- [ ] No other tests broken

Task Granularity

Each step should be:

• Single action (one file, one change)
• Independently verifiable
• Following TDD (test first)
• Committable

Too big: "Implement authentication system" Right size: "Write failing test for login validation"

Design Principles

• DRY - Don't Repeat Yourself
• YAGNI - You Aren't Gonna Need It (no speculative features)
• TDD - Test first, always

After Writing Plan

Offer execution options:

1. Subagent-Driven: Execute in current session with fresh subagent per task
2. Parallel Session: User opens new session with executing-plans skill

Example Plan

# Plan: Add User Avatar Component

**Goal:** Display user avatar with fallback initials

**Architecture:** React component with image loading state, fallback to initials derived from user name

**Tech Stack:** React, TypeScript, Tailwind CSS

**Files Affected:**

- `src/components/Avatar.tsx` - new component
- `src/components/Avatar.test.tsx` - tests
- `src/components/index.ts` - export

## Task 1: Create Avatar Test File

**Action:** Create
**Files:** `src/components/Avatar.test.tsx`

**Steps:**

1. Create test file with describe block
2. Write failing test: renders initials when no image
3. Verify test fails (component doesn't exist)

**Verification:**

- [ ] Test file created
- [ ] Test fails with "Cannot find module"

## Task 2: Create Basic Avatar Component

**Action:** Create
**Files:** `src/components/Avatar.tsx`

**Steps:**

1. Create component that renders initials
2. Accept `name` prop, extract initials
3. Verify test from Task 1 passes

**Verification:**

- [ ] Component renders
- [ ] Test passes
- [ ] Initials display correctly