Planning Agent

Before implementing any coding task, create a structured plan using the framework below.

When to Trigger

Always trigger this skill when:

• •User asks to "create", "build", "implement", "add", "make"
• •User asks to "fix", "debug", "resolve", "repair"
• •User asks to "refactor", "rewrite", "restructure"
• •User asks to "update", "modify", "change"
• •User asks "how to" for implementation tasks
• •Any request that requires writing code

Quick Start

For simple tasks (1-2 files):

1. •Run python scripts/complexity-scorer.py "task description" --path . to confirm tier
2. •Create brief plan with Understanding, Breakdown, Verification sections
3. •Skip detailed architecture

For moderate+ tasks:

1. •Run complexity scorer to confirm tier: python scripts/complexity-scorer.py "task" --path .
2. •Load references/context-gathering.md and gather codebase context
3. •Load references/planning-frameworks.md for detailed methodology
4. •Load references/task-templates.md for task structure templates
5. •Create comprehensive plan with all 7 phases
6. •Validate with python scripts/plan-validator.py plan.md
7. •Present plan to user for approval

7-Phase Planning Workflow

Phase 1: Understanding

• •Restate the problem in your own words
• •Identify success criteria
• •List constraints and assumptions
• •Ask clarifying questions if gaps exist

Phase 2: Analysis (Context Gathering)

• •Consult references/context-gathering.md
• •Explore relevant files in the codebase using list_directory and glob
• •Identify related components and dependencies
• •Map current architecture or flow
• •Note existing patterns and conventions

Phase 3: Architecture

• •Propose solution approach
• •Document key design decisions
• •Consider alternatives and trade-offs
• •Select best option with reasoning

Phase 4: Breakdown

• •Decompose into atomic, verifiable tasks
• •Estimate effort for each task (1-5 scale)
• •Define clear completion criteria
• •Order tasks logically

Phase 5: Dependencies

• •Identify code dependencies (internal and external)
• •List environment prerequisites
• •Map task dependencies
• •Highlight critical path

Phase 6: Risk Assessment

• •Identify technical risks
• •Assess dependency risks
• •Consider scope and timeline risks
• •Plan mitigations and contingencies

Phase 7: Verification

• •Define testing strategy (Unit, Integration, E2E)
• •Identify success criteria
• •Plan manual verification steps with specific commands
• •Set quality gates

Complexity Assessment

Use the 4-tier system to match planning depth to task scope:

Run python scripts/complexity-scorer.py "task description" --path . for quick assessment.

Reference Files

Load these resources as needed:

• •context-gathering.md: Guide for effective codebase exploration
• •planning-frameworks.md: Detailed 7-phase methodology with techniques
• •complexity-assessment.md: Tier definitions and assessment checklist
• •risk-analysis.md: Risk categories and mitigation strategies
• •task-templates.md: Reusable templates for features, bugs, refactors, tests, migrations

Tools

Complexity Scorer

python scripts/complexity-scorer.py "task description" --path .
python scripts/complexity-scorer.py "task" --path . --json
python scripts/complexity-scorer.py --interactive

Plan Validator

python scripts/plan-validator.py plan.md
python scripts/plan-validator.py plan.md --json
python scripts/plan-validator.py --interactive

Planning Checklist

Use assets/planning-checklist.md as a reference:

• •Pre-implementation checklist
• •Task execution checklist
• •Pre-commit checklist
• •Pre-deployment checklist
• •Post-implementation checklist

Standard Plan Format

# Implementation Plan: [Task Name]

## 1. Understanding
- What is being asked?
- Success criteria:
  - [ ] [Criterion 1]
  - [ ] [Criterion 2]

## 2. Analysis
- Files to modify: [list]
- Files to create: [list]
- Related components: [list]

## 3. Architecture
- Proposed approach: [description]
- Alternatives considered: [list]
- Key design decisions: [list]

## 4. Task Breakdown
- [Task ID]: [Brief description]
  - Files: [list]
  - Depends: [none or task ID]
  - Effort: [1-5]
  - Verifies: [completion criteria]

## 5. Dependencies
- Internal: [list]
- External: [list]
- Environment: [list]

## 6. Risk Assessment
| Risk | Category | Impact | Mitigation |
|------|----------|--------|------------|
| [Risk] | [Category] | [H/M/L] | [Strategy] |

## 7. Verification
- Unit tests: [where and what]
- Integration tests: [where and what]
- Manual testing: [scenarios]
- Quality gates: [list]

## Complexity Assessment
- **Tier**: [Simple/Moderate/Complex/Epic]
- **Estimated Effort**: [time]
- **Risk Level**: [Low/Medium/High]

Planning Principles

1. •Context First: Never plan without exploring the codebase first.
2. •Never skip planning: Even small tasks benefit from a brief plan.
3. •Match depth to complexity: Simple tasks need light planning.
4. •Be specific: Reference actual files, functions, and code patterns.
5. •Break it down: Decompose into atomic, verifiable steps.
6. •Identify risks: Call out potential problems early.
7. •Validate plans: Use plan-validator.py before presenting.

Output

After creating the plan:

1. •Validate with python scripts/plan-validator.py
2. •Present to user with: "Does this plan align with your expectations?"
3. •Only proceed after user confirmation
4. •Use planning-checklist.md throughout implementation