From d2970b06bd1fcd15f9dd843429605dac02669e72 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Wed, 4 Mar 2026 13:58:11 -0600 Subject: [PATCH] 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 --- README.md | 12 +- docs/CREATE-PLAN.md | 64 ++- skills/create-plan/claude-code/SKILL.md | 235 +++++++++- skills/create-plan/codex/SKILL.md | 252 ++++++++++- skills/create-plan/cursor/SKILL.md | 401 ++++++++++++++++++ .../cursor/templates/continuation-runbook.md | 134 ++++++ .../cursor/templates/milestone-plan.md | 106 +++++ .../cursor/templates/story-tracker.md | 72 ++++ skills/create-plan/opencode/SKILL.md | 233 +++++++++- 9 files changed, 1481 insertions(+), 28 deletions(-) create mode 100644 skills/create-plan/cursor/SKILL.md create mode 100644 skills/create-plan/cursor/templates/continuation-runbook.md create mode 100644 skills/create-plan/cursor/templates/milestone-plan.md create mode 100644 skills/create-plan/cursor/templates/story-tracker.md diff --git a/README.md b/README.md index 0b6ae6e..56e1a12 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # ai-coding-skills -Cross-agent skill collection for **Codex**, **Claude Code**, and **OpenCode**. +Cross-agent skill collection for **Codex**, **Claude Code**, **OpenCode**, and **Cursor**. This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time. @@ -24,7 +24,8 @@ ai-coding-skills/ │ ├── create-plan/ │ │ ├── codex/ │ │ ├── claude-code/ -│ │ └── opencode/ +│ │ ├── opencode/ +│ │ └── cursor/ │ └── web-automation/ │ ├── codex/ │ ├── claude-code/ @@ -42,9 +43,10 @@ ai-coding-skills/ | Skill | Agent Variant | Purpose | Status | Docs | |---|---|---|---|---| -| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | -| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | -| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | +| create-plan | codex | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | +| create-plan | claude-code | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | +| create-plan | opencode | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | +| create-plan | cursor | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | | web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | | web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | | web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md index 88ccddd..2d6442c 100644 --- a/docs/CREATE-PLAN.md +++ b/docs/CREATE-PLAN.md @@ -2,7 +2,7 @@ ## Purpose -Create structured implementation plans with milestone and story tracking. +Create structured implementation plans with milestone and story tracking, and optionally review them iteratively with a second model/provider before finalizing. ## Requirements @@ -12,11 +12,26 @@ Create structured implementation plans with milestone and story tracking. - `superpowers:writing-plans` - For Codex, native skill discovery must be configured: - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` +- For Cursor, skills must be installed under `.cursor/rules/` (repo-local) or `~/.cursor/rules/` (global) If dependencies are missing, stop and return: "Missing dependency: native Superpowers skills are required (`superpowers:brainstorming`, `superpowers:writing-plans`). Install from https://github.com/obra/superpowers, then retry." +### Reviewer CLI Requirements (Optional) + +To use the iterative plan review feature, one of these CLIs must be installed: + +| Reviewer CLI | Install | Verify | +|---|---|---| +| `codex` | `npm install -g @openai/codex` | `codex --version` | +| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` | +| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) | + +The reviewer CLI is independent of which agent is running the planning — e.g., Claude Code can send plans to Codex for review, and vice versa. + +**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`. + ## Install ### Codex @@ -40,12 +55,29 @@ mkdir -p ~/.config/opencode/skills/create-plan cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/ ``` +### Cursor + +Copy into the repo-local `.cursor/rules/` directory (where the Cursor Agent CLI discovers skills): + +```bash +mkdir -p .cursor/rules/create-plan +cp -R skills/create-plan/cursor/* .cursor/rules/create-plan/ +``` + +Or install globally (loaded via `~/.cursor/rules/`): + +```bash +mkdir -p ~/.cursor/rules/create-plan +cp -R skills/create-plan/cursor/* ~/.cursor/rules/create-plan/ +``` + ## Verify Installation ```bash test -f ~/.codex/skills/create-plan/SKILL.md || true test -f ~/.claude/skills/create-plan/SKILL.md || true test -f ~/.config/opencode/skills/create-plan/SKILL.md || true +test -f .cursor/rules/create-plan/SKILL.md || test -f ~/.cursor/rules/create-plan/SKILL.md || true ``` Verify Superpowers dependencies exist in your agent skills root: @@ -56,12 +88,16 @@ Verify Superpowers dependencies exist in your agent skills root: - Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md` - OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md` - OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md` +- Cursor: `.cursor/rules/superpowers/brainstorming/SKILL.md` or `~/.cursor/rules/superpowers/brainstorming/SKILL.md` +- Cursor: `.cursor/rules/superpowers/writing-plans/SKILL.md` or `~/.cursor/rules/superpowers/writing-plans/SKILL.md` ## Key Behavior - Creates plans under `ai_plan/YYYY-MM-DD-/`. - Ensures `/ai_plan/` is in `.gitignore`. - Commits `.gitignore` update locally when added. +- Asks which reviewer CLI and model to use (or accepts `skip` for no review). +- Iteratively reviews the plan with the chosen reviewer (max 5 rounds) before generating files. - Produces: - `original-plan.md` - `final-transcript.md` @@ -69,6 +105,25 @@ Verify Superpowers dependencies exist in your agent skills root: - `story-tracker.md` — includes Tracking Guardrails section - `continuation-runbook.md` — includes Skill Workflow Guardrails section +## Iterative Plan Review + +After the plan is created (design + milestones + stories), the skill sends it to a second model for review: + +1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`) and model, or skips +2. **Submit** — plan is written to a temp file and sent to the reviewer in read-only/ask mode +3. **Feedback** — reviewer evaluates correctness, risks, missing steps, alternatives, security +4. **Revise** — the planning agent addresses each issue and re-submits +5. **Repeat** — up to 5 rounds until the reviewer returns `VERDICT: APPROVED` +6. **Finalize** — approved plan is used to generate the plan file package + +### Supported Reviewer CLIs + +| CLI | Command | Session Resume | Read-Only Mode | +|---|---|---|---| +| `codex` | `codex exec -m -s read-only` | Yes (`codex exec resume `) | `-s read-only` | +| `claude` | `claude -p --model --allowedTools Read` | No (fresh call each round) | `--allowedTools Read` | +| `cursor` | `cursor-agent -p --mode=ask --model --trust --output-format json` | Yes (`--resume `) | `--mode=ask` | + ## Template Guardrails All plan templates now include guardrail sections that enforce: @@ -120,6 +175,13 @@ All plan templates now include guardrail sections that enforce: - `superpowers/brainstorming` - `superpowers/writing-plans` +### Cursor + +- Must use workspace discovery from `.cursor/rules/` (repo-local or `~/.cursor/rules/` global). +- Must announce skill usage explicitly before invocation. +- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively. +- Must not use `--force` or `--mode=agent` for review (reviewer should never write files). + ## Execution Workflow Rules - Read runbook first. diff --git a/skills/create-plan/claude-code/SKILL.md b/skills/create-plan/claude-code/SKILL.md index a2e9298..70eaa72 100644 --- a/skills/create-plan/claude-code/SKILL.md +++ b/skills/create-plan/claude-code/SKILL.md @@ -31,17 +31,238 @@ If any dependency is missing, stop immediately and return: - Cover scope, constraints, success criteria, dependencies. - Summarize before proceeding. -### Phase 3: Design (REQUIRED SUB-SKILL) +### 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 4: Plan (REQUIRED SUB-SKILL) +### 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 5: Initialize Local Plan Workspace (MANDATORY) +### 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: `). 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 (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. + +#### 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. @@ -51,9 +272,9 @@ At project root: Recommended commit message: - `chore(gitignore): ignore ai_plan local planning artifacts` -### Phase 6: Generate Plan Files (MANDATORY - DO NOT SKIP) +### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP) -⚠️ **PLAN MODE CHECK:** If currently in plan mode: +**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. @@ -67,7 +288,7 @@ Create `ai_plan/YYYY-MM-DD-/` with ALL files: Use templates from this skill's `templates/` folder (or `~/.claude/skills/create-plan/templates/` when installed directly in Claude Code). -### Phase 7: Handoff Instructions +### Phase 9: Handoff Instructions When handing off to execution, instruct: > Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from `ai_plan` files only. @@ -111,6 +332,8 @@ After completing any story: - [ ] `.gitignore` includes `/ai_plan/` - [ ] `.gitignore` ignore-rule commit was created if needed - [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` +- [ ] 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 diff --git a/skills/create-plan/codex/SKILL.md b/skills/create-plan/codex/SKILL.md index eec49c2..cbeac38 100644 --- a/skills/create-plan/codex/SKILL.md +++ b/skills/create-plan/codex/SKILL.md @@ -12,7 +12,8 @@ Create and maintain a local plan workspace under `ai_plan/` at project root. This skill wraps the current Superpowers flow for Codex: 1. Design first with `superpowers:brainstorming` 2. Then build an implementation plan with `superpowers:writing-plans` -3. Persist a local execution package in `ai_plan/YYYY-MM-DD-/` +3. Review the plan iteratively with a second model/provider +4. Persist a local execution package in `ai_plan/YYYY-MM-DD-/` **Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands. @@ -55,15 +56,236 @@ If any dependency is missing, stop and return: - Ask questions one at a time until user says ready. - Confirm scope, constraints, success criteria, dependencies. -### Phase 3: Design (REQUIRED SUB-SKILL) +### Phase 3: Configure Reviewer + +If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), 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 4: Plan (REQUIRED SUB-SKILL) +### Phase 5: Plan (REQUIRED SUB-SKILL) Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories. -### Phase 5: Initialize Local Plan Workspace (MANDATORY) +### 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: `). 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 (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. + +#### 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. @@ -73,7 +295,7 @@ At project root: Recommended commit message: - `chore(gitignore): ignore ai_plan local planning artifacts` -### Phase 6: Generate Plan Files (MANDATORY) +### Phase 8: Generate Plan Files (MANDATORY) Create `ai_plan/YYYY-MM-DD-/` with all files below: 1. `original-plan.md` - copy of original planner-generated plan. @@ -84,7 +306,7 @@ Create `ai_plan/YYYY-MM-DD-/` with all files below: Use templates from this skill's `templates/` folder. -### Phase 7: Handoff +### Phase 9: Handoff Always instruct the executing agent: > Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. @@ -97,11 +319,13 @@ Do not rely on planner-private files during implementation. |---|---|---| | 1 | Analyze codebase/context | Constraints and known patterns | | 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria | -| 3 | Invoke `superpowers:brainstorming` | Chosen design approach | -| 4 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories | -| 5 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | -| 6 | Build plan package from templates | Full plan folder with required files | -| 7 | Handoff with runbook-first instruction | Resumable execution context | +| 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 | ## Execution Rules to Include in Plan (MANDATORY) @@ -126,6 +350,8 @@ Do not rely on planner-private files during implementation. - 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. +- Not capturing the Codex session ID for resume in subsequent review rounds. ## Rationalizations and Counters @@ -135,6 +361,7 @@ Do not rely on planner-private files during implementation. | "I can skip brainstorming for small tasks" | Creative/planning work still requires design validation first. | | "I don't need `update_plan` for checklist skills" | Checklist tracking is mandatory for execution reliability. | | "I can keep plan files outside `ai_plan/`" | This skill standardizes local resumable planning under `ai_plan/`. | +| "The reviewer approved, I can skip my own validation" | Reviewer feedback supplements but does not replace your own verification. | ## Red Flags - Stop and Correct @@ -143,6 +370,7 @@ Do not rely on planner-private files during implementation. - 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. ## Verification Checklist @@ -150,6 +378,8 @@ Do not rely on planner-private files during implementation. - [ ] `.gitignore` includes `/ai_plan/` - [ ] `.gitignore` ignore-rule commit was created if needed - [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` +- [ ] 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 diff --git a/skills/create-plan/cursor/SKILL.md b/skills/create-plan/cursor/SKILL.md new file mode 100644 index 0000000..cf80eb6 --- /dev/null +++ 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-/` + +**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: `). 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-/` 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-/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-/` +- [ ] 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" diff --git a/skills/create-plan/cursor/templates/continuation-runbook.md b/skills/create-plan/cursor/templates/continuation-runbook.md new file mode 100644 index 0000000..a34dffd --- /dev/null +++ b/skills/create-plan/cursor/templates/continuation-runbook.md @@ -0,0 +1,134 @@ +# Continuation Runbook: [Plan Title] + +## Reference Files (START HERE) + +Upon resumption, these files in this folder are the ONLY source of truth: + +| File | Purpose | When to Use | +|------|---------|-------------| +| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST | +| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story | +| `milestone-plan.md` | Complete plan with specifications | Reference implementation details | +| `original-plan.md` | Original approved plan | Reference original intent | +| `final-transcript.md` | Final planning transcript | Reference reasoning/context | + +Do NOT reference planner-private files during implementation. + +## Skill Workflow Guardrails + +- Invoke relevant skills before action using workspace discovery (`.cursor/rules/`). +- Announce which skill is being used and why. +- If a checklist-driven skill applies, track checklist execution explicitly. + +--- + +## Quick Resume Instructions + +1. Read this runbook completely. +2. Check `story-tracker.md`. +3. Find next `pending` story and mark as `in-dev` before starting. +4. Implement the story. +5. Update tracker immediately after each change. + +--- + +## Mandatory Execution Workflow + +Work from this folder (`ai_plan/YYYY-MM-DD-/`) and always follow this order: + +1. Read `continuation-runbook.md` first. +2. Execute stories milestone by milestone. +3. After completing a milestone: + - Run lint/typecheck/tests, prioritizing changed files for speed. + - Commit locally (**DO NOT PUSH**). + - Stop and ask user for feedback. +4. If feedback is provided: + - Apply feedback changes. + - Re-run checks for changed files. + - Commit locally again. + - Ask for milestone approval. +5. Only move to next milestone after explicit approval. +6. After all milestones are completed and approved: + - Ask permission to push. + - If approved, push. + - Mark plan status as `completed`. + +--- + +## Git Note + +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error. + +--- + +## Full Context Reproduction + +### Project Overview +[What this project/feature is about] + +### User Requirements +[All gathered requirements] + +### Scope +[In scope / out of scope] + +### Dependencies +[External dependencies, prerequisites, related systems] + +--- + +## Key Specifications + +### Type Definitions +```typescript +// Copy-paste ready type definitions +``` + +### Enums & Constants +```typescript +// All enums/constants needed +``` + +### API Endpoints +```typescript +// Request/response shapes +``` + +--- + +## Critical Design Decisions + +| Decision | Chosen Approach | Alternatives Rejected | Rationale | +|----------|-----------------|----------------------|-----------| +| [Topic] | [What we chose] | [Other options] | [Why] | + +--- + +## Verification Commands + +### Lint (changed files first) +```bash +# example: +``` + +### Typecheck +```bash +# example: +``` + +### Tests (target changed scope first) +```bash +# example: +``` + +--- + +## File Quick Reference + +| File | Purpose | +|------|---------| +| `original-plan.md` | Original approved plan | +| `final-transcript.md` | Final planning transcript | +| `milestone-plan.md` | Full specification | +| `story-tracker.md` | Current progress tracker | +| `continuation-runbook.md` | This runbook | diff --git a/skills/create-plan/cursor/templates/milestone-plan.md b/skills/create-plan/cursor/templates/milestone-plan.md new file mode 100644 index 0000000..5ab6619 --- /dev/null +++ b/skills/create-plan/cursor/templates/milestone-plan.md @@ -0,0 +1,106 @@ +# [Plan Title] + +## Overview +- **Goal:** [One sentence describing the end state] +- **Created:** YYYY-MM-DD +- **Status:** In Progress | Complete + +## Planning Guardrails +- This plan assumes design was validated before implementation planning. +- Skills are invoked via workspace discovery (`.cursor/rules/`). +- Milestones require verification + local commits + explicit approval before proceeding. + +## Context + +### Requirements +[Gathered requirements from user questions] + +### Constraints +[Technical, business, or timeline constraints] + +### Success Criteria +[How we know this is complete] + +## Architecture + +### Design Decisions +[Key architectural choices and rationale] + +### Component Relationships +[How pieces fit together] + +### Data Flow +[How data moves through the system] + +## Milestones + +### M1: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-101, S-102, S-103... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +### M2: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-201, S-202, S-203... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +## Technical Specifications + +### Types & Interfaces +```typescript +// Key type definitions (or equivalent language constructs) +``` + +### API Contracts +```typescript +// Endpoint signatures, request/response shapes (if applicable) +``` + +### Constants & Enums +```typescript +// Shared constants (if applicable) +``` + +## Files Inventory + +| File | Purpose | Milestone | +|------|---------|-----------| +| `path/to/file.ts` | [What it does] | M1 | +| `path/to/other.ts` | [What it does] | M2 | + +--- + +## Related Plan Files + +This file is part of the plan folder under `ai_plan/`: +- `original-plan.md` - Original approved plan (reference for original intent) +- `final-transcript.md` - Final planning transcript (reference for rationale/context) +- `milestone-plan.md` - This file (full specification) +- `story-tracker.md` - Status tracking (must be kept up to date) +- `continuation-runbook.md` - Resume/execution context (read first) diff --git a/skills/create-plan/cursor/templates/story-tracker.md b/skills/create-plan/cursor/templates/story-tracker.md new file mode 100644 index 0000000..0da4ccd --- /dev/null +++ b/skills/create-plan/cursor/templates/story-tracker.md @@ -0,0 +1,72 @@ +# Story Tracker: [Plan Title] + +## Progress Summary +- **Current Milestone:** M1 +- **Stories Complete:** 0/N +- **Milestones Approved:** 0/M +- **Last Updated:** YYYY-MM-DD + +## Tracking Guardrails +- Update status immediately when work starts (`in-dev`) and when work completes (`completed`). +- Require explicit user approval at each milestone boundary before continuing. +- Do not push until all milestones are approved and permission is explicitly granted. +- Keep this file and `milestone-plan.md` synchronized. + +--- + +## Milestones + +### M1: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-101 | [Brief description] | pending | | +| S-102 | [Brief description] | pending | | +| S-103 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +### M2: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-201 | [Brief description] | pending | | +| S-202 | [Brief description] | pending | | +| S-203 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +## Status Legend + +| Status | Meaning | +|--------|---------| +| `pending` | Not started | +| `in-dev` | Currently being worked on | +| `completed` | Done - include commit hash in Notes | +| `deferred` | Postponed - include reason in Notes | + +## Update Instructions (MANDATORY) + +Before starting any story: +1. Mark story as `in-dev` +2. Update "Last Updated" + +After completing any story: +1. Mark story as `completed` +2. Add local commit hash to Notes +3. Update "Stories Complete" and "Last Updated" + +At milestone boundary: +1. Run lint/typecheck/tests for changed files +2. Commit (no push) +3. Request feedback +4. Apply feedback, re-check changed files, commit again +5. Mark milestone **Approval Status: approved** only after user confirms +6. Continue only after approval + +After all milestones approved: +- Ask permission to push and then mark plan completed. diff --git a/skills/create-plan/opencode/SKILL.md b/skills/create-plan/opencode/SKILL.md index 988a44e..a3d4cf5 100644 --- a/skills/create-plan/opencode/SKILL.md +++ b/skills/create-plan/opencode/SKILL.md @@ -43,14 +43,32 @@ Use OpenCode's native skill tool: - Cover scope, constraints, success criteria, dependencies. - Summarize before proceeding. -### Phase 4: Design (REQUIRED SUB-SKILL) +### Phase 4: 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 7 (Iterative Plan Review). + +### Phase 5: Design (REQUIRED SUB-SKILL) Use OpenCode's native skill tool to load: - `superpowers/brainstorming` Then present 2-3 approaches and recommend one. -### Phase 5: Plan (REQUIRED SUB-SKILL) +### Phase 6: Plan (REQUIRED SUB-SKILL) Use OpenCode's native skill tool to load: - `superpowers/writing-plans` @@ -58,7 +76,210 @@ Use OpenCode's native skill tool to load: Then break into milestones and bite-sized stories (2-5 min each). Story IDs: `S-{milestone}{sequence}`. -### Phase 6: Initialize Local Plan Workspace (MANDATORY) +### Phase 7: 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: `). 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 (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. + +#### 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 8 (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 8: Initialize Local Plan Workspace (MANDATORY) At project root: 1. Ensure `ai_plan/` exists. Create it if missing. @@ -68,7 +289,7 @@ At project root: Recommended commit message: - `chore(gitignore): ignore ai_plan local planning artifacts` -### Phase 7: Generate Plan Files (MANDATORY) +### Phase 9: Generate Plan Files (MANDATORY) Create `ai_plan/YYYY-MM-DD-/` with ALL files: 1. `original-plan.md` - copy of original planner-generated plan. @@ -79,7 +300,7 @@ Create `ai_plan/YYYY-MM-DD-/` with ALL files: Use templates from this skill's `templates/` folder. -### Phase 8: Handoff +### Phase 10: Handoff Always instruct the executing agent: > Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from `ai_plan` files only. @@ -119,6 +340,8 @@ After completing any story: - [ ] `.gitignore` includes `/ai_plan/` - [ ] `.gitignore` ignore-rule commit was created if needed - [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` +- [ ] 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