Workflow Plan Phases

Plan Phases

Creates a phased implementation plan from a feature description, optimized for context-efficient sub-agent execution.

Usage

/workflow-plan-phases <description>
/workflow-plan-phases "Build a user authentication system with OAuth, MFA, and session management"
/workflow-plan-phases --output=docs/plans/auth-system.md "Build authentication system..."

Arguments

• description (required): What the user wants to build
• --output: Custom output path (default: docs/plans/{slugified-name}.md)

Instructions

1. Read the user's description from the command argument
2. Ask clarifying questions before creating the plan — never skip this step
3. Wait for user responses before proceeding
4. Create the plan document following the plan-phases skill methodology
5. Save to docs/plans/ (create directory if needed) using a slugified filename
6. Present the plan and ask if changes are needed
7. Stop — do not implement

Workflow

1. Ask clarifying questions (always — never skip)
2. Size phases for context efficiency (30-50k tokens each)
3. Use whole numbers only (no Phase 1.1 sub-phases)
4. Define clear acceptance criteria per phase
5. Map dependencies and recommend execution strategy
6. Output structured markdown to docs/plans/
7. STOP — do not implement the plan

Important

This command only creates the plan. Do NOT proceed to implement any phases.

After the plan is written:

• Present the plan document to the user
• Ask if they want to make any changes
• Inform them they can use /workflow-implement-phases when ready to execute

Never start writing code or implementing phases after creating the plan.

Phase Planning Skill

This skill provides methodology for creating implementation plans that are optimized for sub-agent execution, with properly sized phases that respect context window constraints.

Overview

A good phase plan:

1. Breaks work into independently executable chunks
2. Sizes phases to fit within sub-agent context budgets
3. Minimizes dependencies between phases where possible
4. Provides clear acceptance criteria for verification
5. Uses whole number phases only (no 1.1, 1.2 sub-phases)

Step 1: Gather Requirements (Always Ask Questions)

Never skip this step. Even if the description seems complete, clarifying questions:

• Reveal implicit assumptions
• Uncover edge cases
• Establish scope boundaries
• Identify existing constraints

Question Categories

Scope & Boundaries

• What's explicitly OUT of scope?
• Is this greenfield or integrating with existing code?
• Are there existing patterns/conventions to follow?
• What's the target completion state? MVP or production-ready?

Technical Context

• What's the tech stack? (language, framework, database)
• Are there existing models/services this builds on?
• What authentication/authorization exists?
• Are there performance requirements?

Integration Points

• What external services/APIs are involved?
• Are there existing interfaces to conform to?
• What other systems will consume this?
• Are there upstream dependencies not yet built?

User Experience

• Who are the users? (end users, admins, developers, APIs)
• What's the primary workflow/happy path?
• What error states need handling?
• Are there accessibility requirements?

Constraints

• Security requirements? (OWASP, compliance, data sensitivity)
• Testing requirements? (coverage, E2E, specific frameworks)
• Documentation requirements?
• Deployment constraints?

Question Presentation Format

Present 3-5 targeted questions based on the description:

Before I create the implementation plan, I have a few questions:

1. **Existing Code**: Is this a new feature in an existing codebase, or greenfield?
   If existing, what patterns should I follow?

2. **Auth Context**: You mentioned user roles - is there an existing auth system
   to integrate with, or is that part of this work?

3. **Data Layer**: What database are you using? Are there existing models
   this relates to?

4. **Scope Boundary**: Should this include the admin UI for managing X,
   or just the core functionality?

5. **Testing**: What level of test coverage do you need? Unit only,
   or integration/E2E as well?

Wait for answers before proceeding.

Step 2: Phase Sizing Guidelines

Context Budget Per Phase

Target each phase to consume 30-50k tokens of sub-agent context:

• ~10k tokens: Phase spec + project context (CLAUDE.md, conventions)
• ~15-25k tokens: File reads and code analysis
• ~10-15k tokens: Implementation work and verification

Sizing Heuristics

RIGHT-SIZED Phase (~30-50k tokens):

• Creates/modifies 2-5 files
• Implements 1-2 closely related features
• Can be verified with a clear test or check
• Completes in one sub-agent session without compacting

TOO LARGE Phase (>60k tokens - split it):

• Creates/modifies 6+ files
• Implements multiple unrelated features
• Requires reading large portions of codebase
• Description exceeds ~500 words
• Contains words like "and also", "as well as", "plus"

TOO SMALL Phase (<15k tokens - combine it):

• Single file change
• Config-only changes
• Simple additions with no logic
• Could be done in 5 minutes manually

Splitting Strategy

When a phase is too large, split by:

1. Layer: Separate data model, business logic, API, UI
2. Entity: One phase per core entity/resource
3. Operation: Separate CRUD operations if complex
4. Concern: Separate core logic from error handling, logging, etc.

Example - Too Large:

Phase 1: Build user management with registration, login, profile
editing, password reset, email verification, and admin user listing

Split Into:

Phase 1: User model and registration endpoint
Phase 2: Login and session management
Phase 3: Password reset flow
Phase 4: Email verification
Phase 5: Profile editing
Phase 6: Admin user listing

Step 3: Dependency Planning

Dependency Types to Track

Hard Dependencies (must complete first):

• Schema/model that other phases import
• Auth middleware other phases use
• Shared utilities or helpers
• Base classes being extended

Soft Dependencies (preferred order, but parallelizable):

• Related features that share patterns
• Test setup that other tests use
• Documentation that references implementation

No Dependencies (fully parallel):

• Isolated features
• Different layers of same feature (if interfaces defined upfront)
• Independent utilities

Minimizing Dependencies

Strategies to reduce coupling between phases:

1. Define interfaces early: First phase exports types/interfaces, later phases implement against them

2. Stub dependencies: Phase can stub what it needs, later phase replaces stub with real implementation

3. Feature flags: Phases can merge independently, enable via flag

4. Vertical slices: Each phase is a thin vertical slice through all layers rather than horizontal layers

Step 4: Plan Document Structure

File Location

docs/plans/{feature-name}.md

Slugify the feature name:

• "User Authentication System" -> user-authentication-system.md
• "API Rate Limiting" -> api-rate-limiting.md

Document Template

# {Feature Name} Implementation Plan

## Overview
{2-3 sentence summary of what this plan delivers}

## Goals
- {Primary goal}
- {Secondary goal}
- {Tertiary goal}

## Non-Goals (Out of Scope)
- {Explicit exclusion 1}
- {Explicit exclusion 2}

## Technical Context
- **Stack**: {language, framework, database}
- **Existing Code**: {relevant existing modules/patterns}
- **Integration Points**: {external services, APIs}

---

## Phase 1: {Phase Name}

### Objective
{One sentence describing what this phase accomplishes}

### Specification
{Detailed description of the work. Include:}
- What to create/modify
- Specific requirements
- Edge cases to handle
- Error handling expectations

### Files to Create/Modify
- `path/to/file.ts` - {purpose}
- `path/to/other.ts` - {purpose}

### Acceptance Criteria
- [ ] {Verifiable criterion 1}
- [ ] {Verifiable criterion 2}
- [ ] {Verifiable criterion 3}

### Dependencies
- **Requires**: {None | Phase X}
- **Blocks**: {Phase Y, Phase Z}

### Estimated Scope
- Files: {2-5}
- Complexity: {Low | Medium | High}

---

## Phase 2: {Phase Name}

{Same structure as Phase 1}

---

## Execution Strategy

### Dependency Graph

Phase 1 --+-- Phase 3 | Phase 2 --+ | Phase 4 <-+-- Phase 5

### Recommended Execution
- **Parallel Group 1**: Phase 1, Phase 2
- **Sequential**: Phase 3 (after Phase 1)
- **Parallel Group 2**: Phase 4, Phase 5 (after Phase 3)

---

## Verification Checklist

After all phases complete:
- [ ] {Integration verification 1}
- [ ] {Integration verification 2}
- [ ] {End-to-end test}

## Open Questions

- {Any unresolved decisions to revisit}

Step 5: Phase Writing Guidelines

Phase Names

Use action-oriented names:

Good:
- "Create User Model and Repository"
- "Implement JWT Authentication"
- "Add Rate Limiting Middleware"
- "Build Password Reset Flow"

Bad:
- "User Stuff"
- "Part 1"
- "Backend Work"
- "Misc Improvements"

Specification Writing

Be specific enough that a sub-agent can implement without guessing:

Vague:
"Add user authentication"

Specific:
"Create POST /api/auth/login endpoint that:
- Accepts { email, password } body
- Validates against User model
- Returns JWT token with 24h expiry on success
- Returns 401 with { error: 'Invalid credentials' } on failure
- Rate limits to 5 attempts per 15 minutes per IP
- Logs failed attempts with IP and email (not password)"

Acceptance Criteria

Write testable criteria:

Not Testable:
- "Works correctly"
- "Handles errors"
- "Is secure"

Testable:
- "POST /api/users returns 201 with user object (excluding password)"
- "Invalid email format returns 400 with validation error"
- "Passwords are hashed with bcrypt cost factor 12"
- "JWT tokens expire after 24 hours"

Anti-Patterns to Avoid

No Sub-Phases

Wrong:
Phase 1: Setup
  Phase 1.1: Database schema
  Phase 1.2: Model classes
  Phase 1.3: Repository layer

Right:
Phase 1: Database Schema and Migrations
Phase 2: User Model and Repository
Phase 3: Authentication Service

No Kitchen Sink Phases

Wrong:
Phase 3: Implement all remaining features including search,
filtering, pagination, sorting, export, and batch operations

Right:
Phase 3: List Endpoint with Pagination
Phase 4: Search and Filtering
Phase 5: Sorting Options
Phase 6: Export Functionality
Phase 7: Batch Operations

No Vague Phases

Wrong:
Phase 2: Handle edge cases and fix bugs

Right:
Phase 2: Input Validation and Error Handling
- Validate email format, password strength
- Handle duplicate email registration
- Return structured error responses

No Dependency Spaghetti

Wrong:
Phase 1 depends on Phase 3
Phase 3 depends on Phase 2
Phase 2 depends on Phase 4
Phase 4 depends on Phase 1  (circular!)

Right:
Phase 1: Foundation (no dependencies)
Phase 2: Core Logic (depends on 1)
Phase 3: Extended Features (depends on 2)
Phase 4: Polish and Edge Cases (depends on 3)

Final Checklist

Before delivering plan:

• Asked clarifying questions and incorporated answers
• Each phase is 30-50k tokens of work (2-5 files)
• No sub-phases (whole numbers only)
• Every phase has clear acceptance criteria
• Dependencies are explicit and acyclic
• Specifications are detailed enough to implement without guessing
• File saved to docs/plans/{feature-name}.md

IMPORTANT: Planning Only — Do Not Implement

This skill is for planning only. After creating the plan, STOP.

Do NOT:

• Start implementing any phases
• Write any code
• Create any files other than the plan document
• Begin execution automatically

After the plan is complete:

1. Present the plan document to the user
2. Ask if they want to make any revisions
3. Inform them to use /workflow-implement-phases or the implement-phases skill when ready to execute

The user decides when to proceed with implementation.

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