planning

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

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

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.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
    └── ...

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:

1. $CK_ACTIVE_PLAN env var: Only set for explicitly activated plans (via session state)
2. $CK_SUGGESTED_PLAN env var: Branch-matched plans shown as hints, not directives
3. Session temp file: /tmp/ck-session-{id}.json stores explicit activations only
4. SubagentStart hook: Injects differentiated context (Active vs Suggested)

Rules

1. Check $CK_ACTIVE_PLAN first: If set and valid directory, ask "Continue with existing plan? [Y/n]"
2. Check $CK_SUGGESTED_PLAN second: 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
3. If neither set: Proceed to create new plan
4. Update on create: Run node .claude/scripts/set-active-plan.cjs plans/...

Report Output Location

All agents writing reports MUST:

1. Check Plan Context section injected by hooks for Reports Path
2. Only $CK_ACTIVE_PLAN plans use plan-specific reports path
3. $CK_SUGGESTED_PLAN plans use default plans/reports/ (not plan folder)
4. 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.