212 lines
8.8 KiB
Markdown
212 lines
8.8 KiB
Markdown
# CREATE-PLAN
|
|
|
|
## Purpose
|
|
|
|
Create structured implementation plans with milestone and story tracking, and optionally review them iteratively with a second model/provider before finalizing.
|
|
|
|
## Requirements
|
|
|
|
- Superpowers skills installed from: https://github.com/obra/superpowers
|
|
- Required dependencies:
|
|
- `superpowers:brainstorming`
|
|
- `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/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
|
- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
|
|
- Codex: `~/.codex/skills/reviewer-runtime/run-review.sh`
|
|
- Claude Code: `~/.claude/skills/reviewer-runtime/run-review.sh`
|
|
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/run-review.sh`
|
|
- Cursor: `.cursor/skills/reviewer-runtime/run-review.sh` or `~/.cursor/skills/reviewer-runtime/run-review.sh`
|
|
|
|
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
|
|
|
|
```bash
|
|
mkdir -p ~/.codex/skills/create-plan
|
|
cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
|
|
mkdir -p ~/.codex/skills/reviewer-runtime
|
|
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
|
```
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
mkdir -p ~/.claude/skills/create-plan
|
|
cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
|
|
mkdir -p ~/.claude/skills/reviewer-runtime
|
|
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
|
```
|
|
|
|
### OpenCode
|
|
|
|
```bash
|
|
mkdir -p ~/.config/opencode/skills/create-plan
|
|
cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/
|
|
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
|
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
|
```
|
|
|
|
### Cursor
|
|
|
|
Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI discovers skills):
|
|
|
|
```bash
|
|
mkdir -p .cursor/skills/create-plan
|
|
cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/
|
|
mkdir -p .cursor/skills/reviewer-runtime
|
|
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
|
```
|
|
|
|
Or install globally (loaded via `~/.cursor/skills/`):
|
|
|
|
```bash
|
|
mkdir -p ~/.cursor/skills/create-plan
|
|
cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/
|
|
mkdir -p ~/.cursor/skills/reviewer-runtime
|
|
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
|
```
|
|
|
|
## 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/skills/create-plan/SKILL.md || test -f ~/.cursor/skills/create-plan/SKILL.md || true
|
|
test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
|
|
test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
|
|
test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
|
|
test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || true
|
|
```
|
|
|
|
Verify Superpowers dependencies exist in your agent skills root:
|
|
|
|
- Codex: `~/.agents/skills/superpowers/brainstorming/SKILL.md`
|
|
- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
|
|
- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
|
|
- 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/skills/superpowers/skills/brainstorming/SKILL.md` or `~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md`
|
|
- Cursor: `.cursor/skills/superpowers/skills/writing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/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`
|
|
- `milestone-plan.md` — includes Planning Guardrails section
|
|
- `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:
|
|
|
|
**Planning Guardrails** (`milestone-plan.md`):
|
|
- Design validation before implementation planning
|
|
- Native skill discovery (no deprecated CLI wrappers)
|
|
- Milestone verification + local commits + explicit approval
|
|
|
|
**Tracking Guardrails** (`story-tracker.md`):
|
|
- Immediate status updates when work starts/completes
|
|
- Explicit user approval at each milestone boundary
|
|
- No pushes until all milestones approved
|
|
- Synchronization between tracker and plan files
|
|
|
|
**Skill Workflow Guardrails** (`continuation-runbook.md`):
|
|
- Native skill invocation before action
|
|
- Explicit skill announcements
|
|
- Checklist tracking for driven skills
|
|
- No deprecated CLI wrappers
|
|
|
|
## Variant Hardening Notes
|
|
|
|
### Claude Code
|
|
|
|
- Must invoke explicit required sub-skills:
|
|
- `superpowers:brainstorming`
|
|
- `superpowers:writing-plans`
|
|
- Must enforce plan-mode file-write guard:
|
|
- if in plan mode, instruct user to exit plan mode before generating files
|
|
- Must copy `original-plan.md` from `~/.claude/plans/` when available.
|
|
|
|
### Codex
|
|
|
|
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
|
|
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
|
- Must invoke required sub-skills with explicit announcements:
|
|
- `superpowers:brainstorming` — for design exploration and approach validation
|
|
- `superpowers:writing-plans` — for milestone and story breakdown
|
|
- Must track checklist-driven skills with `update_plan` todos.
|
|
- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
|
|
|
|
### OpenCode
|
|
|
|
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
|
|
- Must verify Superpowers skill discovery under:
|
|
- `~/.config/opencode/skills/superpowers`
|
|
- Must explicitly load:
|
|
- `superpowers/brainstorming`
|
|
- `superpowers/writing-plans`
|
|
|
|
### Cursor
|
|
|
|
- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` 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.
|
|
- Complete one milestone at a time.
|
|
- Lint/typecheck/test (changed files first).
|
|
- Commit (do not push), ask for feedback, apply feedback, commit again.
|
|
- Move to next milestone only after approval.
|
|
- Ask permission before final push.
|