ai-coding-skills/skills/create-plan/claude-code/SKILL.md

---
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: Configure Reviewer

If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:

1. **Which CLI should review the plan?**
   - `codex` — OpenAI Codex CLI (`codex exec`)
   - `claude` — Claude Code CLI (`claude -p`)
   - `cursor` — Cursor Agent CLI (`cursor-agent -p`)
   - `skip` — No external review, proceed directly to file generation

2. **Which model?** (only if a CLI was chosen)
   - For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
   - For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
   - For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
   - Accept any model string the user provides

Store the chosen `REVIEWER_CLI` and `REVIEWER_MODEL` for Phase 6 (Iterative Plan Review).

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

### Phase 5: 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 6: Iterative Plan Review

Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (max 5 rounds).

**Skip this phase entirely if reviewer was set to `skip`.**

#### Step 1: Generate Session ID

```bash
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
```

Use for temp artifacts:
- `/tmp/plan-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
- `/tmp/plan-review-${REVIEW_ID}.stderr`
- `/tmp/plan-review-${REVIEW_ID}.status`
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
- `/tmp/plan-review-${REVIEW_ID}.sh`

Resolve the shared reviewer helper from the installed Claude Code skills directory:

```bash
REVIEWER_RUNTIME=~/.claude/skills/reviewer-runtime/run-review.sh
```

#### Step 2: Write Plan to Temp File

Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.

#### Step 3: Submit to Reviewer (Round 1)

Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:

```bash
#!/usr/bin/env bash
set -euo pipefail
```

**If `REVIEWER_CLI` is `codex`:**

```bash
codex exec \
  -m ${REVIEWER_MODEL} \
  -s read-only \
  -o /tmp/plan-review-${REVIEW_ID}.md \
  "Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?

Be specific and actionable. If the plan is solid, end with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE"
```

Capture the Codex session ID from output (line `session id: <uuid>`). Store as `CODEX_SESSION_ID` for session resume in subsequent rounds.

**If `REVIEWER_CLI` is `claude`:**

```bash
claude -p \
  "Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?

Be specific and actionable. If the plan is solid, end with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE" \
  --model ${REVIEWER_MODEL} \
  --allowedTools Read
```

**If `REVIEWER_CLI` is `cursor`:**

```bash
cursor-agent -p \
  --mode=ask \
  --model ${REVIEWER_MODEL} \
  --trust \
  --output-format json \
  "Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?

Be specific and actionable. If the plan is solid, end with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE" \
  > /tmp/plan-review-${REVIEW_ID}.json
```

Extract session ID and review text (requires `jq`):

```bash
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
```

If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.

Run the command script through the shared helper when available:

```bash
if [ -x "$REVIEWER_RUNTIME" ]; then
  "$REVIEWER_RUNTIME" \
    --command-file /tmp/plan-review-${REVIEW_ID}.sh \
    --stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
    --stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
    --status-file /tmp/plan-review-${REVIEW_ID}.status
else
  echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
  bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
fi
```

After the command completes:
- If `REVIEWER_CLI=cursor`, extract the final review text:

```bash
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
```

- If `REVIEWER_CLI=codex` and the review text is only in `/tmp/plan-review-${REVIEW_ID}.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.

#### Step 4: Read Review & Check Verdict

1. Read `/tmp/plan-review-${REVIEW_ID}.md`
2. If the review failed, produced empty output, or reached helper timeout, also read:
   - `/tmp/plan-review-${REVIEW_ID}.stderr`
   - `/tmp/plan-review-${REVIEW_ID}.status`
   - `/tmp/plan-review-${REVIEW_ID}.runner.out`
3. Present review to the user:

```
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})

[Reviewer feedback]
```

3. Check verdict:
   - **VERDICT: APPROVED** → proceed to Phase 7 (Initialize workspace)
   - **VERDICT: REVISE** → go to Step 5
   - No clear verdict but positive / no actionable items → treat as approved
   - Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
   - Helper state `needs-operator-decision` → surface status log and decide whether to keep waiting, abort, or retry with different helper parameters
   - Max rounds (5) reached → proceed with warning

#### Step 5: Revise the Plan

Address each issue the reviewer raised. Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.

Summarize revisions for the user:

```
### Revisions (Round N)
- [Change and reason, one bullet per issue addressed]
```

If a revision contradicts the user's explicit requirements, skip it and note it for the user.

#### Step 6: Re-submit to Reviewer (Rounds 2-5)

**If `REVIEWER_CLI` is `codex`:**

Resume the existing session:

```bash
codex exec resume ${CODEX_SESSION_ID} \
  -o /tmp/plan-review-${REVIEW_ID}.md \
  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.

Changes made:
[List specific changes]

Re-review. If solid, end with: VERDICT: APPROVED
If more changes needed, end with: VERDICT: REVISE"
```

If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.

**If `REVIEWER_CLI` is `claude`:**

Fresh call with accumulated context (Claude CLI has no session resume):

```bash
claude -p \
  "You previously reviewed an implementation plan and requested revisions.

Previous feedback summary: [key points from last review]

I've revised the plan. Updated version is in /tmp/plan-${REVIEW_ID}.md.

Changes made:
[List specific changes]

Re-review the full plan. If solid, end with: VERDICT: APPROVED
If more changes needed, end with: VERDICT: REVISE" \
  --model ${REVIEWER_MODEL} \
  --allowedTools Read
```

**If `REVIEWER_CLI` is `cursor`:**

Resume the existing session:

```bash
cursor-agent --resume ${CURSOR_SESSION_ID} -p \
  --mode=ask \
  --model ${REVIEWER_MODEL} \
  --trust \
  --output-format json \
  "I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.

Changes made:
[List specific changes]

Re-review. If solid, end with: VERDICT: APPROVED
If more changes needed, end with: VERDICT: REVISE" \
  > /tmp/plan-review-${REVIEW_ID}.json

jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
```

If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.

After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.

Return to Step 4.

#### Step 7: Present Final Result

```
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})

**Status:** Approved after N round(s)
[or]
**Status:** Max rounds (5) reached — not fully approved

[Final feedback / remaining concerns]
```

#### Step 8: Cleanup

```bash
rm -f /tmp/plan-${REVIEW_ID}.md \
  /tmp/plan-review-${REVIEW_ID}.md \
  /tmp/plan-review-${REVIEW_ID}.json \
  /tmp/plan-review-${REVIEW_ID}.stderr \
  /tmp/plan-review-${REVIEW_ID}.status \
  /tmp/plan-review-${REVIEW_ID}.runner.out \
  /tmp/plan-review-${REVIEW_ID}.sh
```

If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.

### Phase 7: 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 8: 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 9: 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>/`
- [ ] Reviewer configured or explicitly skipped
- [ ] Plan review completed (approved or max rounds) — or skipped
- [ ] `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"