---
name: create-plan
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
---

# Create Plan (Claude Code)

Create and maintain a local plan folder under `ai_plan/` at project root.

## Prerequisite Check (MANDATORY)

This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.

Required:
- Superpowers repo: `https://github.com/obra/superpowers`
- `brainstorming` skill
- `writing-plans` skill

If any dependency is missing, stop immediately and return:

"Missing dependency: Superpowers planning skills are required (`brainstorming`, `writing-plans`). Install from https://github.com/obra/superpowers, then retry."

## Process

### Phase 1: Analyze
- Explore the codebase with exploration agents.
- Understand existing patterns and context.

### Phase 2: Gather Requirements
- Ask questions ONE AT A TIME until user says ready.
- Cover scope, constraints, success criteria, dependencies.
- Summarize before proceeding.

### Phase 3: Design (REQUIRED SUB-SKILL)
- Invoke `superpowers:brainstorming` explicitly.
- Present 2-3 approaches and recommend one.
- Validate design in sections.

### Phase 4: Plan (REQUIRED SUB-SKILL)
- Invoke `superpowers:writing-plans` explicitly.
- Break into milestones and bite-sized stories (2-5 min each).
- Story IDs: `S-{milestone}{sequence}`.

### Phase 5: Initialize Local Plan Workspace (MANDATORY)

At project root:
1. Ensure `ai_plan/` exists. Create it if missing.
2. Ensure `.gitignore` contains `/ai_plan/`.
3. If `.gitignore` was changed, commit that change immediately (local commit only).

Recommended commit message:
- `chore(gitignore): ignore ai_plan local planning artifacts`

### Phase 6: Generate Plan Files (MANDATORY - DO NOT SKIP)

⚠️ **PLAN MODE CHECK:** If currently in plan mode:
1. Inform user that plan files cannot be written while in plan mode.
2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
3. Proceed with file generation only after exiting plan mode.

Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
2. `final-transcript.md` - Copy of final planning transcript for reference.
3. `milestone-plan.md` - Full specification (template-based).
4. `story-tracker.md` - Status tracking (template-based, all stories start as `pending`).
5. `continuation-runbook.md` - Resume context and execution protocol (template-based).

Use templates from this skill's `templates/` folder (or `~/.claude/skills/create-plan/templates/` when installed directly in Claude Code).

### Phase 7: Handoff Instructions

When handing off to execution, instruct:
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from `ai_plan` files only.

Private plan files under `~/.claude/plans/` are planning artifacts and must not be used as execution source of truth.

## Tracker Discipline (MANDATORY)

**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**

Before starting any story:
1. Open `story-tracker.md`
2. Mark story `in-dev`
3. Add notes if relevant
4. Then begin implementation

After completing any story:
1. Mark story `completed`
2. Add commit hash in Notes
3. Review pending stories
4. Update Last Updated and Stories Complete counts

## Execution Rules to Include in Plan (MANDATORY)

- Run lint/typecheck/tests after each milestone.
- Prefer linting changed files only for speed.
- Commit locally after each completed milestone (**do not push**).
- Stop and ask user for feedback.
- Apply feedback, rerun checks, and commit again.
- Move to next milestone only after user approval.
- After all milestones are completed and approved, ask permission to push.
- Only after approved push: mark plan as completed.

## Gitignore Note

`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.

## Verification Checklist

- [ ] `ai_plan/` exists at project root
- [ ] `.gitignore` includes `/ai_plan/`
- [ ] `.gitignore` ignore-rule commit was created if needed
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
- [ ] `original-plan.md` copied from `~/.claude/plans/` plan file
- [ ] `final-transcript.md` present
- [ ] `milestone-plan.md` present
- [ ] `story-tracker.md` created with all stories as `pending`
- [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder

## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions"