Writing Plans

Writing Implementation Plans

Create structured plans that chain to plan-execution for execution.

Core principle: Plan with bite-sized tasks, model recommendations, and TDD embedded.

When to Use

• Have spec or requirements
• Task requires multiple steps (3+)
• Need to coordinate work across multiple files/components
• Want to ensure thorough testing and review

Don't use for:

• Single-file, single-step changes (just implement)
• Trivial updates (config changes, version bumps)
• Exploratory work (use brainstorming first)

Plan Structure

# Implementation Plan: [Feature/Component Name]

**Skill:** `dev-workflow:plan-execution`

## Overview
[1-2 sentences on what we're building and why]

## Prerequisites
- [Required context, dependencies, or setup]

## Phase 1: [Phase Name]
[Brief description of what this phase accomplishes]

### Task 1.1: [Brief imperative title]
**Model:** haiku | sonnet | opus
**Complexity:** SIMPLE | STANDARD | COMPLEX
**Parallelizable:** yes | no

[Description of what to implement]

**Acceptance criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]

**Testing approach:** [TDD steps or test types needed]

### Task 1.2: [Next task]
...

## Phase 2: [Next Phase Name]
...

## Verification
- [ ] All tests pass
- [ ] Typecheck passes
- [ ] Build succeeds
- [ ] Manual testing: [specific scenarios]

## Review Checkpoints
- After Phase 1: spec + quality review
- After Phase 2: spec + quality review
- Final: staff-code-reviewer (opus)

Model Selection Guide

Choose model based on task complexity:

Default to sonnet unless the task clearly fits SIMPLE or explicitly requires COMPLEX reasoning.

Reserve opus for:

• Staff-level reviews (phase boundaries, final review)
• Complex architectural decisions in implementation (rare)
• Main conversation orchestration

Task Structure

Anatomy of a Good Task

### Task 1.1: Add user authentication endpoint
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** yes

Create POST /auth/login endpoint that validates credentials and returns JWT token.

**Implementation details:**
- Accept email + password in request body
- Validate against database
- Return JWT with 1h expiration
- Return 401 for invalid credentials

**Acceptance criteria:**
- [ ] Endpoint responds at POST /auth/login
- [ ] Valid credentials return 200 with JWT
- [ ] Invalid credentials return 401
- [ ] Token includes user ID and expires in 1h

**Testing approach:**
- RED: Write test for valid credentials → expect JWT
- GREEN: Implement validation and token generation
- RED: Write test for invalid credentials → expect 401
- GREEN: Add error handling
- REFACTOR: Extract token generation to service

What Makes a Task "Bite-Sized"

✅ Good task size:

• Implementable in one focused session (30-60 min)
• Single responsibility or feature slice
• Clear acceptance criteria
• Self-contained (minimal dependencies on incomplete work)

❌ Too large:

• "Implement entire authentication system"
• "Add user management"
• Multiple independent features bundled

❌ Too small:

• "Add import statement"
• "Fix typo in comment"
• Trivial changes that aren't worth separate tasks

Task Dependencies

Prefer independent tasks that can be worked on in any order.

If dependencies exist:

### Task 1.2: Add token refresh endpoint
**Model:** sonnet
**Complexity:** STANDARD
**Depends on:** Task 1.1 (uses same token generation)

[Task description...]

TDD Embedded in Tasks

Every task that writes code should specify testing approach.

For Features (TDD Cycle)

**Testing approach:**
- RED: Write test for [expected behavior]
- GREEN: Implement [minimal code to pass]
- RED: Write test for [edge case]
- GREEN: Handle [edge case]
- REFACTOR: [Extract/improve code]

For Bugs (Systematic Debugging → TDD)

**Testing approach:**
- Reproduce bug in failing test (exposes root cause)
- RED: Confirm test fails with bug present
- GREEN: Implement fix
- Verify original issue resolved

For Refactoring (Test-First Safety)

**Testing approach:**
- Ensure existing tests cover current behavior
- Add tests for edge cases if missing
- Refactor while keeping all tests green

Phase Boundaries

Break work into phases when:

• Natural checkpoint exists (e.g., "core implementation" then "integration")
• Want to review intermediate state before continuing
• Tasks in later phases depend on earlier ones

Review at phase boundaries:

• SIMPLE-only phases: Skip phase review
• STANDARD+ phases: staff-code-reviewer (opus)

Anti-Patterns to Avoid

❌ Tasks too large

• "Implement entire feature" → Break into smaller pieces
• Multiple independent changes → Separate tasks

❌ No model recommendations

• Every task should specify haiku/sonnet/opus
• Defaults to sonnet if unspecified, but be explicit

❌ Missing testing approach

• Tasks that write code must specify how to test
• TDD should be the default, not optional

❌ Vague acceptance criteria

• "Works correctly" → Specify exactly what "works" means
• "Handles errors" → Which errors? What responses?

❌ No complexity classification

• Needed for review path selection
• Helps estimate effort and choose model

❌ Sequential dependencies everywhere

• Makes parallel work impossible
• Prefer independent tasks when possible

Example Plans

Example 1: Simple Feature (3 Tasks)

# Implementation Plan: Add Health Check Endpoint

**Skill:** `dev-workflow:plan-execution`

## Overview
Add GET /health endpoint that returns service status and dependencies.

## Prerequisites
- Express server already set up
- Database connection exists

## Phase 1: Implementation

### Task 1.1: Create health check endpoint
**Model:** haiku
**Complexity:** SIMPLE
**Parallelizable:** yes

Add GET /health that returns 200 OK with JSON status.

**Acceptance criteria:**
- [ ] GET /health returns 200
- [ ] Response includes { status: "ok", timestamp: ISO string }

**Testing approach:**
- RED: Request GET /health → expect 200 with status
- GREEN: Create endpoint handler
- REFACTOR: Extract status builder if needed

### Task 1.2: Add database health check
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** no

Extend health endpoint to check database connectivity.

**Acceptance criteria:**
- [ ] Health check attempts database ping
- [ ] Returns db: "healthy" if connection succeeds
- [ ] Returns db: "unhealthy" if connection fails
- [ ] Overall status is "ok" only if all checks pass

**Testing approach:**
- RED: Test with healthy db → expect db: "healthy"
- GREEN: Implement db ping check
- RED: Test with failed db → expect db: "unhealthy"
- GREEN: Add error handling
- REFACTOR: Extract check logic to service

### Task 1.3: Add documentation
**Model:** haiku
**Complexity:** SIMPLE
**Parallelizable:** yes

Document the health check endpoint in API docs.

**Acceptance criteria:**
- [ ] API.md includes GET /health
- [ ] Response format documented
- [ ] Status values explained

**Testing approach:** N/A (documentation only)

## Verification
- [ ] All tests pass
- [ ] GET /health returns correct format
- [ ] Manual test: kill database, verify unhealthy status

## Review Checkpoints
- After Phase 1: spec + quality review
- Final: staff-code-reviewer (opus)

Example 2: Multi-Phase Feature

# Implementation Plan: User Profile Management

**Skill:** `dev-workflow:plan-execution`

## Overview
Implement CRUD operations for user profiles with validation and permissions.

## Prerequisites
- User authentication system exists (JWT auth)
- Database schema includes users table

## Phase 1: Core Profile Operations

### Task 1.1: Create profile data model
**Model:** haiku
**Complexity:** SIMPLE
**Parallelizable:** yes

Define TypeScript interface and database schema for user profiles.

**Acceptance criteria:**
- [ ] Profile interface includes: name, email, bio, avatarUrl
- [ ] Database migration creates profiles table
- [ ] Foreign key to users table

**Testing approach:**
- Verify migration runs successfully
- Verify schema matches interface

### Task 1.2: Implement GET /profile/:id
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** yes

Create endpoint to fetch user profile by ID.

**Acceptance criteria:**
- [ ] GET /profile/:id returns profile data
- [ ] Returns 404 if profile doesn't exist
- [ ] Excludes sensitive fields (password, etc.)

**Testing approach:**
- RED: Request existing profile → expect 200 with data
- GREEN: Implement fetch logic
- RED: Request missing profile → expect 404
- GREEN: Add not-found handling
- REFACTOR: Extract data mapping to service

### Task 1.3: Implement PUT /profile/:id
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** yes

Create endpoint to update user profile with permission checks.

**Acceptance criteria:**
- [ ] PUT /profile/:id updates profile fields
- [ ] Requires authentication
- [ ] Users can only update their own profile
- [ ] Returns 403 for unauthorized updates
- [ ] Validates input (email format, bio length, etc.)

**Testing approach:**
- RED: Authenticated user updates own profile → expect 200
- GREEN: Implement update logic
- RED: User tries to update different profile → expect 403
- GREEN: Add permission check
- RED: Invalid input → expect 400 with validation errors
- GREEN: Add validation
- REFACTOR: Extract permission logic to middleware

## Phase 2: Profile Features

### Task 2.1: Add profile picture upload
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** yes

Allow users to upload profile pictures with validation.

**Acceptance criteria:**
- [ ] POST /profile/:id/avatar accepts image file
- [ ] Validates file type (jpg, png, max 5MB)
- [ ] Stores in S3/storage service
- [ ] Updates avatarUrl in profile
- [ ] Returns 400 for invalid files

**Testing approach:**
- RED: Upload valid image → expect 200 with URL
- GREEN: Implement upload to storage
- RED: Upload invalid file → expect 400
- GREEN: Add validation
- RED: Upload over size limit → expect 400
- GREEN: Add size check
- REFACTOR: Extract upload logic to service

### Task 2.2: Add profile search
**Model:** sonnet
**Complexity:** STANDARD
**Parallelizable:** yes

Create endpoint to search profiles by name or email.

**Acceptance criteria:**
- [ ] GET /profiles?q=query returns matching profiles
- [ ] Searches name and email fields
- [ ] Case-insensitive search
- [ ] Returns max 20 results
- [ ] Excludes private profiles

**Testing approach:**
- RED: Search by name → expect matching results
- GREEN: Implement basic search
- RED: Search with case variations → expect same results
- GREEN: Make search case-insensitive
- REFACTOR: Extract query builder

## Verification
- [ ] All tests pass (unit + integration)
- [ ] Typecheck passes
- [ ] Manual testing: CRUD operations work end-to-end
- [ ] Permission checks enforced

## Review Checkpoints
- After Phase 1: spec + quality review
- After Phase 2: spec + quality review
- Final: staff-code-reviewer (opus)

Integration

Creates plans for:

• dev-workflow:plan-execution - executes with agent teams or subagents based on availability

Works with:

• dev-workflow:brainstorming - use before planning if requirements unclear
• dev-workflow:test-driven-development - embedded in task structure
• dev-workflow:systematic-debugging - for bug fix plans

Success Criteria

✅ Plan has clear phases and bite-sized tasks ✅ Every task specifies model (haiku/sonnet/opus) ✅ Every task classified by complexity (SIMPLE/STANDARD/COMPLEX) ✅ Every task specifies parallelizable (yes/no) ✅ Tasks that write code include testing approach ✅ Acceptance criteria are specific and testable ✅ Review checkpoints identified ✅ Plan chains to plan-execution for execution

Chains To

After writing plan, invoke:

/skill dev-workflow:plan-execution

The execution skill will:

1. Select mode (agent teams if enabled, subagents otherwise)
2. Read this plan and extract all tasks with model recommendations
3. Execute tasks in parallel with verification and review gates
4. Run staff-code-reviewer at phase boundaries and final
5. Create PR and run /pr-status loop until ready

Converted and distributed by TomeVault — claim your Tome and manage your conversions.