create-plan

name	create-plan
description	Create detailed implementation plans from feature specs or bug reports with testable acceptance criteria. Use proactively when planning features, refactors, or fixes. Every task MUST have minimum 2 testable ACs and map to requirements.
degree-of-freedom	medium
allowed-tools	Bash(project-intel.mjs:*), Read, Write, Edit

@.claude/shared-imports/constitution.md @.claude/shared-imports/CoD_Σ.md @.claude/templates/plan.md

Planning Skill

Overview

This skill creates detailed implementation plans from feature specifications or bug reports, breaking requirements into implementable tasks with testable acceptance criteria.

Core Workflow: Load Spec → Task Breakdown → Dependencies → Validate Plan

Article III Enforcement: Every task MUST have minimum 2 testable acceptance criteria (Test-First Imperative).

Announce at start: "I'm using the create-plan skill to create an implementation plan with testable acceptance criteria."

Note: For the main SDD workflow, use create-implementation-plan skill instead, which provides constitutional pre/post-design gates, automatic research.md/data-model.md generation, and automatic generate-tasks invocation. This skill (create-plan) is for simpler planning or legacy compatibility.

---

Quick Reference

Phase	Key Activities	Output
Phase 1	Load spec, extract requirements, intel queries	Requirements, constraints, context
Phase 2	Break into tasks, define ≥2 ACs per task	Tasks with testable ACs
Phase 3	Identify file/task dependencies via intel	Dependency graph, critical path
Phase 4	Validate coverage, ACs, dependencies	plan.md file

---

Workflow Files

Detailed Phase Instructions:

• @.claude/skills/create-plan/workflows/load-spec.md - Phase 1: Load Input Spec (3 input types)
• @.claude/skills/create-plan/workflows/task-breakdown.md - Phase 2: Task breakdown with ≥2 ACs
• @.claude/skills/create-plan/workflows/dependency-analysis.md - Phase 3: File and task dependencies
• @.claude/skills/create-plan/workflows/plan-validation.md - Phase 4: Validate plan quality

Planning Strategies:

• @.claude/skills/create-plan/references/planning-patterns.md - Feature, Refactor, Migration patterns
• @.claude/skills/create-plan/references/enforcement-rules.md - Quality gates and anti-patterns

Examples:

• @.claude/skills/create-plan/examples/feature-planning-example.md - Complete OAuth planning walkthrough

---

Phase 1: Load Input Spec

See: @.claude/skills/create-plan/workflows/load-spec.md

Summary:

Input Options (priority order):

1. feature-spec.md - For new features (Article IV: Specification-First)
2. bug-report.md - For bug fixes (from debug-issues skill)
3. Natural language - Create spec first with specify-feature skill

Extract:

• Requirements (REQ-001, REQ-002, etc.)
• Constraints (technical, timeline, scope)
• Success criteria

Intelligence Queries (Article I):

project-intel.mjs --search "auth|oauth" --type ts --json > /tmp/plan_patterns.json
project-intel.mjs --overview --json > /tmp/plan_overview.json

Article IV Enforcement: Specification (WHAT/WHY) MUST exist before planning (HOW).

---

Phase 2: Task Breakdown with Acceptance Criteria

See: @.claude/skills/create-plan/workflows/task-breakdown.md

Summary:

Task Sizing: 2-8 hours per task

CRITICAL Article III Requirement: Minimum 2 testable ACs per task

Task Format:

### Task N: <specific description>
- **ID:** TN
- **Owner:** executor-agent
- **Estimated:** 2-8 hours
- **Dependencies:** [Tasks that must complete first]

**Acceptance Criteria:**
- [ ] AC1: <testable condition with pass/fail clarity>
- [ ] AC2: <independent verification without implementation knowledge>
- [ ] AC3: <optional third AC for complex tasks>

Testable AC Examples:

• ✓ "users table has google_id VARCHAR(255) column"
• ✓ "OAuth redirect returns HTTP 302 with Google authorization URL"
• ❌ "OAuth works" (vague, unverifiable)
• ❌ "System is secure" (subjective)

Requirement Coverage Check: Every requirement maps to at least one task (100% coverage required).

---

Phase 3: Identify Dependencies

See: @.claude/skills/create-plan/workflows/dependency-analysis.md

Summary:

Intelligence Queries:

# Find target files
project-intel.mjs --search "<feature-keyword>" --json

# Check file dependencies
project-intel.mjs --dependencies src/file.ts --direction upstream --json
project-intel.mjs --dependencies src/file.ts --direction downstream --json

# Analyze symbols
project-intel.mjs --symbols src/file.ts --json

Dependency Graph:

T1 (DB)
 ├→ T2 (Backend) ─→ T3 (UI) ─→ T6 (E2E test)
 └→ T4 (Service) ─→ T5 (Endpoint) ─┘

Identify:

• Critical path (longest sequence)
• Parallel opportunities (mark with [P] per Article VIII)
• Circular dependencies (break if found)

Token Efficiency: Intel queries (~500 tokens) + targeted reads (~800 tokens) = ~1,300 tokens vs 15,000+ full file reads (91% savings).

---

Phase 4: Validate Plan

See: @.claude/skills/create-plan/workflows/plan-validation.md

Summary:

Validation Checklist:

### Requirement Coverage
- [ ] REQ-001 → T1, T2, T3 ✓
- [ ] REQ-002 → T4, T5 ✓
- [ ] Coverage: 100% ✓

### Task Quality (Article III)
- [ ] All tasks have ≥2 ACs ✓
- [ ] All ACs testable ✓

### Dependencies
- [ ] All dependencies identified ✓
- [ ] No circular dependencies ✓
- [ ] Critical path documented ✓

File Naming: YYYYMMDD-HHMM-plan-<id>.md OR specs/<feature>/plan.md

Template: @.claude/templates/plan.md

Constitutional Compliance:

• Article I: Intelligence queries executed, evidence saved to /tmp/
• Article II: CoD^Σ traces with file:line references
• Article III: ≥2 testable ACs per task
• Article IV: Derived from spec.md, not invented
• Article V: Follows plan.md template
• Article VII: User-story organization (if applicable)
• Article VIII: Parallel work marked [P]

---

Planning Patterns

See: @.claude/skills/create-plan/references/planning-patterns.md

Summary:

Pattern 1: Feature Planning - Multiple requirements, cross-cutting changes

• Strategy: Start with DB schema → backend → frontend → E2E tests
• Organization: By user story priority (P1, P2, P3), not layer

Pattern 2: Refactor Planning - Improve existing code, maintain behavior

• Strategy: Understand current → tests FIRST → incremental refactors → verify

Pattern 3: Migration Planning - Large-scale change, gradual rollout

• Strategy: Run old and new in parallel → incremental migration → feature flags → deprecate old

Pattern 4: Bug Fix Planning - Fix broken behavior with regression tests

• Strategy: Reproduce with test → minimal fix → regression prevention

Selection Guide: Feature (new functionality), Refactor (quality), Migration (system change), Bug Fix (broken behavior).

---

Enforcement Rules

See: @.claude/skills/create-plan/references/enforcement-rules.md

Summary:

Rule 1: Minimum 2 ACs Per Task (Article III)

• Single AC often just tests "it compiles"
• Multiple ACs verify behavior from multiple angles

Rule 2: All Requirements → Tasks

• 100% coverage required
• Matrix format: REQ-001 → T1, T2 (coverage check)

Rule 3: No Vague Tasks

• ❌ "Fix the auth system" → ✓ "Add missing setState dependency to useEffect"
• ❌ "Improve performance" → ✓ "Replace N+1 query with single JOIN"

Common Pitfalls:

• Tasks too large (>8h) → Break into smaller chunks
• Missing dependencies → Use project-intel.mjs
• Layer-first organization → Use user-story-first (Article VII)
• No parallel work identified → Mark independent tasks [P]

---

Example: Feature Planning

See: @.claude/skills/create-plan/examples/feature-planning-example.md

Summary:

Input: feature-spec-oauth.md (3 requirements: OAuth login, session persistence, logout)

Process:

1. Load spec → REQ-001, REQ-002, REQ-003
2. Intel queries → found src/auth/session.ts:23 (JWT management, reusable)
3. Task breakdown → 6 tasks (T1-T6), each with 2-3 ACs
4. Dependencies → T1 → (T2, T4) → (T3, T5) → T6
5. Validate → 100% coverage, all tasks ≥2 ACs

Output: plan.md with 6 tasks, dependency graph, 24h estimate (19h with parallelization)

Success Metrics:

• Requirements coverage: 3/3 = 100% ✓
• Tasks with ≥2 ACs: 6/6 = 100% ✓
• No circular dependencies ✓

---

Prerequisites

Before using this skill:

• ✅ spec.md OR bug report exists (input requirement)
• ✅ project-intel.mjs exists and is executable
• ✅ PROJECT_INDEX.json exists (run /index if missing)
• ⚠️ Optional: Feature directory structure specs/<feature>/
• ⚠️ Optional: MCP tools configured (Ref for library docs)

---

Dependencies

Depends On:

• specify-feature skill - Provides spec.md (for feature planning)
• debug-issues skill - Provides bug diagnosis (for bug fix planning)
• project-intel.mjs - Codebase intelligence queries

Integrates With:

• generate-tasks skill - Uses plan.md to create tasks.md
• implement-and-verify skill - Uses plan.md for implementation
• /audit command - Validates plan against spec

Modern Alternative:

• create-implementation-plan skill - Preferred for SDD workflow (more comprehensive)

Tool Dependencies:

• project-intel.mjs (codebase intelligence)
• Read tool (load spec.md or bug-report.md)
• Write tool (create plan.md)

---

Next Steps

After plan creation:

Simple Workflow (using this skill):

create-plan (creates plan.md)
    ↓ (manual)
/tasks plan.md
    ↓ (automatic)
/audit
    ↓ (if PASS)
/implement plan.md

Recommended SDD Workflow (using create-implementation-plan):

specify-feature (creates spec.md)
    ↓ (auto-invokes /plan)
create-implementation-plan (creates plan.md, research.md, data-model.md)
    ↓ (auto-invokes generate-tasks)
generate-tasks (creates tasks.md)
    ↓ (auto-invokes /audit)
/audit
    ↓ (if PASS)
/implement plan.md

User Action Required:

• Review plan.md for completeness
• Run /tasks plan.md (if using simple workflow)
• Resolve [NEEDS CLARIFICATION] markers

Commands:

• /tasks plan.md - Generate user-story-organized tasks
• /implement plan.md - Begin implementation after tasks and audit
• /audit [feature-id] - Validate cross-artifact consistency

---

Failure Modes

See: @.claude/skills/create-plan/references/enforcement-rules.md for complete list.

Top Failures:

1. No input specification → Create spec.md with specify-feature skill first
2. <2 ACs per task (Article III violation) → Add more ACs or reject plan
3. No intelligence queries (Article I violation) → Query project-intel.mjs before assumptions
4. Missing CoD^Σ traces → Add file:line evidence with saved intel outputs
5. Layer-first organization (Article VII violation) → Restructure by user story priority
6. Plan doesn't map to spec → Ensure every requirement has corresponding tasks

---

Related Skills & Commands

Direct Integration:

• specify-feature skill - Creates spec.md (feature planning input)
• debug-issues skill - Creates bug diagnosis (bug fix planning input)
• generate-tasks skill - Uses plan.md to create tasks.md
• /plan command - Invokes create-implementation-plan (NOT this skill)

Modern Replacement:

• create-implementation-plan skill - Enhanced SDD version with constitutional gates

Workflow Context:

• Position: Phase 2 of SDD workflow (after specification, before tasks)
• Triggers: User mentions "plan" or "how to implement"
• Output: plan.md with implementation strategy and ACs

Quality Gates:

• Article III: ≥2 testable ACs per task
• Article IV: Specification must exist before plan
• Article V: Must follow plan.md template

Workflow Comparison:

Legacy/Simple:
specify-feature → create-plan → manual /tasks → /implement

Current SDD:
specify-feature → create-implementation-plan → generate-tasks (auto) → /audit (auto) → /implement

Recommendation: For new development, prefer create-implementation-plan skill for comprehensive planning with automatic workflow progression.

---

Skill Version: 1.1.0 Last Updated: 2025-10-23 Change Log:

• v1.1.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
• v1.0.0 (2025-10-22): Initial version