planning

Use this skill when:

• Planning new feature implementations
• Architecting system designs
• Evaluating technical approaches
• Creating implementation roadmaps
• Breaking down complex requirements
• Assessing technical trade-offs

Always honoring YAGNI, KISS, and DRY principles.

Be honest, be brutal, straight to the point, and be concise.

1. Research & Analysis

Load: references/research-phase.md

Skip if: Provided with researcher reports

2. Codebase Understanding

Load: references/codebase-understanding.md

Skip if: Provided with scout reports

3. Solution Design

Load: references/solution-design.md

4. Plan Creation & Organization

Load: references/plan-organization.md

5. Task Breakdown & Output Standards

Load: references/output-standards.md

1. Initial Analysis → Read codebase docs, understand context
2. Research Phase → Spawn researchers, investigate approaches
3. Synthesis → Analyze reports, identify optimal solution
4. Design Phase → Create architecture, implementation design
5. Plan Documentation → Write comprehensive plan
6. Review & Refine → Ensure completeness, clarity, actionability

• DO NOT implement code - only create plans
• Respond with plan file path and summary
• Ensure self-contained plans with necessary context
• Include code snippets/pseudocode when clarifying
• Provide multiple options with trade-offs when appropriate
• Fully respect the ./docs/development-rules.md file.

Plan Directory Structure

```

plans/

└── {date}-plan-name/

├── research/

│ ├── researcher-XX-report.md

│ └── ...

├── reports/

│ ├── XX-report.md

│ └── ...

├── scout/

│ ├── scout-XX-report.md

│ └── ...

├── plan.md

├── phase-XX-phase-name-here.md

└── ...

```

Prevents version proliferation by tracking current working plan via session state.

Active vs Suggested Plans

Check the ## Plan Context section injected by hooks:

• "Plan: {path}" = Active plan, explicitly set via set-active-plan.cjs - use for reports
• "Suggested: {path}" = Branch-matched, hint only - do NOT auto-use
• "Plan: none" = No active plan

Rules

1. If "Plan:" shows a path: Ask "Continue with existing plan? [Y/n]"
2. If "Suggested:" shows a path: Inform user, ask if they want to activate or create new
3. If "Plan: none": Create new plan using naming from ## Naming section
4. Update on create: Run node .claude/scripts/set-active-plan.cjs {plan-dir}

Report Output Location

All agents writing reports MUST:

1. Check ## Naming section injected by hooks for the computed naming pattern
2. Active plans use plan-specific reports path
3. Suggested plans use default reports path (not plan folder)

Important: Suggested plans do NOT get plan-specific reports - this prevents pollution of old plan folders.

• Be thorough and specific
• Consider long-term maintainability
• Research thoroughly when uncertain
• Address security and performance concerns
• Make plans detailed enough for junior developers
• Validate against existing codebase patterns

Remember: Plan quality determines implementation success. Be comprehensive and consider all solution aspects.