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>
This commit is contained in:
Stefano Fiorini
12
README.md
12
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) |
|
||||
|
||||
@@ -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-<short-title>/`.
|
||||
- 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 <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
|
||||
| `claude` | `claude -p --model <model> --allowedTools Read` | No (fresh call each round) | `--allowedTools Read` |
|
||||
| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--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.
|
||||
|
||||
@@ -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: <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 (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-<short-title>/` 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-<short-title>/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-<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
|
||||
|
||||
@@ -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-<short-title>/`
|
||||
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:** 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: <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 (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-<short-title>/` with all files below:
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
@@ -84,7 +306,7 @@ Create `ai_plan/YYYY-MM-DD-<short-title>/` 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-<short-title>/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-<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
|
||||
|
||||
401
skills/create-plan/cursor/SKILL.md
Normal file
401
skills/create-plan/cursor/SKILL.md
Normal file
@@ -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"
|
||||
134
skills/create-plan/cursor/templates/continuation-runbook.md
Normal file
134
skills/create-plan/cursor/templates/continuation-runbook.md
Normal file
@@ -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-<short-title>/`) 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: <lint-command> <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
```bash
|
||||
# example: <typecheck-command>
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
```bash
|
||||
# example: <test-command> <related spec/file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
106
skills/create-plan/cursor/templates/milestone-plan.md
Normal file
106
skills/create-plan/cursor/templates/milestone-plan.md
Normal file
@@ -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)
|
||||
72
skills/create-plan/cursor/templates/story-tracker.md
Normal file
72
skills/create-plan/cursor/templates/story-tracker.md
Normal file
@@ -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.
|
||||
@@ -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: <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 (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-<short-title>/` with ALL files:
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
@@ -79,7 +300,7 @@ Create `ai_plan/YYYY-MM-DD-<short-title>/` 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-<short-title>/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-<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
|
||||
|
||||
Reference in New Issue
Block a user