feat(create-plan): add iterative cross-model plan review and Cursor variant

Add a configurable reviewer phase to all create-plan variants (claude-code, codex, opencode) that sends the plan to a second CLI/model for iterative feedback (max 5 rounds). Supported reviewer CLIs: codex, claude, cursor. Add new Cursor Agent CLI variant with full skill, templates, and workspace-discovery-based prerequisites (.cursor/rules/). Update README and docs/CREATE-PLAN.md with Cursor install/verify, reviewer CLI requirements, and supported reviewer CLIs table. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 13:58:11 -06:00
parent 76fd7f374f
commit d2970b06bd
9 changed files with 1481 additions and 28 deletions
--- a/skills/create-plan/cursor/SKILL.md
+++ b/skills/create-plan/cursor/SKILL.md
@@ -0,0 +1,401 @@
+---
+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 in Cursor Agent CLI workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
+---
+
+# Create Plan (Cursor Agent CLI)
+
+Create and maintain a local plan folder under `ai_plan/` at project root.
+
+## Overview
+
+This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
+1. Design first with `superpowers:brainstorming`
+2. Then build an implementation plan with `superpowers:writing-plans`
+3. Review the plan iteratively with a second model/provider
+4. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`
+
+**Core principle:** Cursor Agent CLI discovers skills from `.cursor/rules/` (repo-local or `~/.cursor/rules/` global). It also reads `AGENTS.md` at the repo root for additional instructions.
+
+## Prerequisite Check (MANDATORY)
+
+Required:
+- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
+- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
+- Superpowers repo: `https://github.com/obra/superpowers`
+- Superpowers skills installed under `.cursor/rules/` (repo-local) or `~/.cursor/rules/` (global)
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
+
+Verify before proceeding:
+
+```bash
+cursor-agent --version
+test -f .cursor/rules/superpowers/brainstorming/SKILL.md || test -f ~/.cursor/rules/superpowers/brainstorming/SKILL.md
+test -f .cursor/rules/superpowers/writing-plans/SKILL.md || test -f ~/.cursor/rules/superpowers/writing-plans/SKILL.md
+# Only if using cursor as reviewer CLI:
+# jq --version
+```
+
+If any dependency is missing, stop and return:
+
+`Missing dependency: Superpowers planning skills are required (superpowers:brainstorming, superpowers:writing-plans). Install from https://github.com/obra/superpowers and copy into .cursor/rules/ or ~/.cursor/rules/, then retry.`
+
+## Required Skill Invocation Rules
+
+- Invoke relevant skills through workspace discovery (`.cursor/rules/`).
+- Announce skill usage explicitly:
+  - `I've read the [Skill Name] skill and I'm using it to [purpose].`
+- For skills with checklists, track checklist items explicitly in conversation.
+
+## Process
+
+### Phase 1: Analyze
+- Explore the codebase and existing patterns.
+
+### Phase 2: Gather Requirements
+- Ask questions one at a time until user says ready.
+- Confirm scope, constraints, success criteria, dependencies.
+
+### 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`, then propose 2-3 approaches and recommend one.
+
+### Phase 5: Plan (REQUIRED SUB-SKILL)
+
+Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.
+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 all temp file paths: `/tmp/plan-${REVIEW_ID}.md` and `/tmp/plan-review-${REVIEW_ID}.md`.
+
+#### 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)
+
+**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 \
+  > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+**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:
+
+```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
+```
+
+Notes on Cursor flags:
+- `--mode=ask` — read-only mode, no file modifications
+- `--trust` — trust workspace without prompting (required for non-interactive use)
+- `-p` / `--print` — non-interactive mode, output to stdout
+- `--output-format json` — structured output with `session_id` and `result` fields
+
+#### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/plan-review-${REVIEW_ID}.md`
+2. 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
+   - 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 \
+  > /tmp/plan-review-${REVIEW_ID}.md
+```
+
+**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.
+
+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
+```
+
+### 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)
+
+Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
+1. `original-plan.md` - copy of original planner-generated plan.
+2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
+3. `milestone-plan.md` - full implementation spec (from template).
+4. `story-tracker.md` - story/milestone status tracker (from template).
+5. `continuation-runbook.md` - execution instructions and context (from template).
+
+Use templates from this skill's `templates/` folder.
+
+### Phase 9: Handoff
+
+Always instruct the executing agent:
+> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
+
+Do not rely on planner-private files during implementation.
+
+## Quick Reference
+
+| Phase | Action | Required Output |
+|---|---|---|
+| 1 | Analyze codebase/context | Constraints and known patterns |
+| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
+| 3 | Configure reviewer CLI and model | `REVIEWER_CLI` and `REVIEWER_MODEL` (or `skip`) |
+| 4 | Invoke `superpowers:brainstorming` | Chosen design approach |
+| 5 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
+| 6 | Iterative plan review (max 5 rounds) | Reviewer approval or max-rounds warning |
+| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
+| 8 | Build plan package from templates | Full plan folder with required files |
+| 9 | Handoff with runbook-first instruction | Resumable execution context |
+
+## Tracker Discipline (MANDATORY)
+
+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.
+
+## Common Mistakes
+
+- Forgetting `--trust` flag when running `cursor-agent` non-interactively (causes interactive prompt).
+- Using `--mode=agent` or `--force` for reviews (reviewer should be read-only, use `--mode=ask`).
+- Jumping to implementation planning without running `superpowers:brainstorming` first.
+- Asking multiple requirement questions in one message.
+- Forgetting to create/update `.gitignore` for `/ai_plan/`.
+- Omitting one or more required files in the plan package.
+- Handoff without explicit "read runbook first" direction.
+- Skipping the reviewer phase without explicit user opt-out.
+
+## Red Flags - Stop and Correct
+
+- You started writing milestones before design validation.
+- You did not announce which skill you invoked and why.
+- You are marking planning complete without all required files.
+- Handoff does not explicitly point to `continuation-runbook.md`.
+- You are applying a reviewer suggestion that contradicts user requirements.
+- Reviewer CLI is running with write permissions (must be read-only).
+
+## 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` present
+- [ ] `final-transcript.md` present
+- [ ] `milestone-plan.md` present
+- [ ] `story-tracker.md` present
+- [ ] `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"