planning
Use when you need to plan technical solutions that are scalable, secure, and maintainable.
When & Why to Use This Skill
This Claude skill facilitates comprehensive technical planning and architecture design for software projects. It enables developers to create scalable, secure, and maintainable solutions through structured research, deep codebase analysis, and detailed implementation roadmaps, ensuring high-quality engineering outcomes before a single line of code is written.
Use Cases
- Architecting new system designs: Creating robust technical foundations and high-level designs for complex software applications.
- Feature implementation planning: Breaking down high-level requirements into detailed, actionable tasks and step-by-step development roadmaps.
- Technical trade-off evaluation: Analyzing different architectural approaches to identify the most efficient, secure, and cost-effective solutions.
- Codebase analysis and integration: Researching existing code patterns to ensure new features are integrated seamlessly and maintain consistency.
- Documentation and knowledge transfer: Generating comprehensive technical documentation that serves as a clear guide for junior developers and stakeholders.
| name | planning |
|---|---|
| description | Use when you need to plan technical solutions that are scalable, secure, and maintainable. |
| license | MIT |
Planning
Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
When to Use
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
Core Responsibilities & Rules
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
Workflow Process
- Initial Analysis → Read codebase docs, understand context
- Research Phase → Spawn researchers, investigate approaches
- Synthesis → Analyze reports, identify optimal solution
- Design Phase → Create architecture, implementation design
- Plan Documentation → Write comprehensive plan
- Review & Refine → Ensure completeness, clarity, actionability
Output Requirements
- 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.mdfile.
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
└── ...
Active Plan State
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
- If "Plan:" shows a path: Ask "Continue with existing plan? [Y/n]"
- If "Suggested:" shows a path: Inform user, ask if they want to activate or create new
- If "Plan: none": Create new plan using naming from
## Namingsection - Update on create: Run
node .claude/scripts/set-active-plan.cjs {plan-dir}
Report Output Location
All agents writing reports MUST:
- Check
## Namingsection injected by hooks for the computed naming pattern - Active plans use plan-specific reports path
- 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.
Quality Standards
- 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.