Plan Generator Skill

This skill creates standalone plan files for complex projects that enable autonomous, phased execution with real-time progress tracking.

When to Use This Skill

Use this skill when:

• User asks to create a project plan or PLAN file
• User wants to break down a complex project into phases and steps
• User needs a self-contained planning document for large initiatives

Do NOT use this skill when:

• User wants to EXECUTE an existing plan (use plan-executor skill instead)
• User references an existing PLAN file to continue work

Plan File Naming

Plans are feature/project-specific and can be named flexibly:

• Single feature: PLAN-{feature}.md (e.g., PLAN-auth.md, PLAN-api.md)
• Main project plan: PLAN.md
• Multiple plans can coexist in one repository for different features

Always ask the user what filename they want or suggest based on the project/feature name.

Plan File Structure

When creating a plan file, follow this exact structure:

1. Instructions for Claude Code (TOP OF FILE)

This section MUST be first. Keep it concise (~15 lines):

## Instructions for Claude Code

When working on this plan:
1. **Use the `plan-executor` skill** to execute this plan
2. **Work autonomously** through phases without stopping for approval (unless blocked)
3. **Document findings** in the Notes & Decisions section

**Execution Mode:** [direct|worker]
**Auto-continue:** [yes|no]
**Commit after phase:** [yes|no] (include PLAN file: [yes|no])

2. Current Phase Indicator

Simple status at the top:

• **Current Phase:** Phase 1: [Phase Name]
• **Current Phase:** COMPLETE

3. Project Overview

• Clear description of the end goal
• Context about what the project achieves
• Key requirements (bulleted list)
• Any constraints or dependencies

4. Phase Breakdown

Each phase should include:

## Phase N: [Phase Name]

Brief description of what this phase accomplishes.

### Step N.1: [Step title]
Detailed, actionable step description with context and requirements.

### Step N.2: [Another step title]
Description for this step...

Step Format Notes:

• Steps are markdown headings (### Step N.X: Title), NOT checkbox list items
• Each step ID follows the format {phase}.{step} (e.g., 0.1, 1.2, 2.3)
• Include inline examples within phases when helpful (e.g., config structures, code snippets)

5. Notes & Decisions Section

Major section after all phases: ## Notes & Decisions

Template structure for each phase:

### Phase N: [Phase Name] (Status)
- Implementation details and approach taken
- Why decisions were made
- Deviations from original plan with explanations
- Technical details for future reference

6. Completion Checklist

Final section with overall project readiness criteria:

## Completion Checklist

Before marking this project complete:
- [ ] All phases marked complete
- [ ] All tests passing
- [ ] Build successful
- [ ] Documentation complete

Generating the Plan File

When this skill is invoked:

1. Determine filename: Ask user for desired filename or suggest based on project (e.g., "I'll create PLAN-auth.md for this authentication feature")

2. Ask about preferences:

   a) Execution mode:

   • Direct mode: Execute steps in the main session (simpler, good for small plans)
   • Worker mode: Delegate to sub-agents (recommended for large/complex plans)

   b) Auto-continue preference:

   • Yes: Automatically start the next phase without asking
   • No: Ask for confirmation before each new phase (default)

   c) Commit preferences:

   • Yes, include PLAN file: Commit code changes AND updated PLAN file together
   • Yes, exclude PLAN file: Commit only code changes
   • No: User will handle commits manually

3. Gather project details from the user if not already provided

4. Break down the project:

   • Identify logical phases (typically 3-8 phases, including Phase 0 for setup if needed)
   • For each phase, identify concrete steps (3-10 steps per phase)
   • Consider including inline examples (configs, schemas) in relevant phases

5. Create the plan file with:

   • Instructions section at the TOP (referencing plan-executor skill)
   • Current Phase indicator with execution preferences
   • Complete project overview
   • All phases with detailed, actionable steps
   • Empty Notes & Decisions section
   • Completion checklist
   • (JSON state will be initialized automatically by plan-executor on first run)

6. Make it standalone: The file should contain enough context that referencing it in a fresh session gives Claude complete understanding of the project

Key Principles

• Instructions first: Always put Claude instructions at the top of the file
• Reference plan-executor: The instructions section should tell Claude to use the plan-executor skill
• Detailed steps: Each step should be actionable with clear requirements
• Include examples: Inline examples (configs, schemas, code snippets) make steps clearer
• Self-referential: Plan should reference "this file" not a hardcoded filename

Example Usage

Example 1: Single Feature Plan

User: "Create a plan for building a JWT authentication system with refresh tokens"

Claude should:

1. Suggest: "I'll create PLAN-auth.md for this authentication feature"
2. Ask about execution mode, auto-continue, and commit preferences
3. Break down into phases like:
   • Phase 0: Dependencies and project structure
   • Phase 1: JWT token generation and validation
   • Phase 2: Refresh token implementation
   • Phase 3: Middleware integration
   • Phase 4: Testing
4. Create detailed steps for each phase with inline examples (e.g., JWT payload structure)
5. Generate PLAN-auth.md with all structure including the JSON state block
6. Inform user: "I've created PLAN-auth.md. Reference it with @PLAN-auth.md to begin execution"

Example 2: Main Project Plan

User: "Create a plan for building a CLI tool with subcommands and configuration support"

Claude should:

1. Suggest: "I'll create PLAN.md for this project"
2. Follow same process as Example 1
3. User can later create additional feature-specific plans alongside (e.g., PLAN-config.md)