planning
Generate and optimize PRDs, Implementation Plans, and Progress Tracking documents optimized as AI artifacts for development agents. Use when creating new feature plans, breaking down long planning docs (>800 lines), or setting up progress tracking. Supports: 1) Create PRD from feature request, 2) Create Implementation Plan from PRD with phase breakdown and subagent assignments, 3) Optimize existing plans by breaking into phase-specific files, 4) Create progress tracking with task assignments. Example: "Create a PRD for user authentication feature" or "Break down the sidebar-polish implementation plan into phase files" or "Create progress tracking for data-layer-fixes PRD".
When & Why to Use This Skill
This Claude skill is a comprehensive technical planning and project management tool designed to streamline the software development lifecycle. It automates the creation of high-quality PRDs, modular implementation plans, and progress tracking documents by performing deep codebase analysis and research. By adhering to core engineering principles like YAGNI and KISS, it ensures that complex requirements are broken down into actionable, scalable, and maintainable tasks optimized for both human developers and AI agents.
Use Cases
- Feature-to-PRD Transformation: Convert vague feature requests into structured Product Requirements Documents with clear objectives and specifications.
- Technical Roadmap Architecting: Generate multi-phase implementation plans from PRDs, including architecture design, sub-agent assignments, and technical trade-off analysis.
- Document Optimization: Decompose monolithic planning documents (over 800 lines) into modular, phase-specific files to improve focus and execution clarity.
- Automated Progress Tracking: Create and maintain structured task assignments and milestone tracking to monitor development velocity and project health.
- Codebase-Aware Solution Design: Conduct research and codebase analysis to ensure new technical plans are compatible with existing patterns and infrastructure.
| 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
| Type | Env Var | Meaning |
|---|---|---|
| Active | $CK_ACTIVE_PLAN |
Explicitly set via set-active-plan.cjs - use for reports |
| Suggested | $CK_SUGGESTED_PLAN |
Branch-matched, hint only - do NOT auto-use |
How It Works
Plan context is managed through:
$CK_ACTIVE_PLANenv var: Only set for explicitly activated plans (via session state)$CK_SUGGESTED_PLANenv var: Branch-matched plans shown as hints, not directives- Session temp file:
/tmp/ck-session-{id}.jsonstores explicit activations only - SubagentStart hook: Injects differentiated context (Active vs Suggested)
Rules
- Check
$CK_ACTIVE_PLANfirst: If set and valid directory, ask "Continue with existing plan? [Y/n]" - Check
$CK_SUGGESTED_PLANsecond: If set, inform user "Found suggested plan from branch: {path}"- This is a hint only - do NOT auto-use it
- Ask user if they want to activate it or create new
- If neither set: Proceed to create new plan
- Update on create: Run
node .claude/scripts/set-active-plan.cjs plans/...
Report Output Location
All agents writing reports MUST:
- Check
Plan Contextsection injected by hooks forReports Path - Only
$CK_ACTIVE_PLANplans use plan-specific reports path $CK_SUGGESTED_PLANplans use defaultplans/reports/(not plan folder)- Use naming:
{agent}-{date}-{slug}.md
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.