ai-coding-skills/docs/CREATE-PLAN.md

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
• Telegram notification setup is documented in TELEGRAM-NOTIFICATIONS.md

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

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

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

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):

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/):

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

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, model, and max rounds to use (or accepts skip for no review).
• Iteratively reviews the plan with the chosen reviewer (default max 10 rounds) before generating files.
• Runs reviewer commands through reviewer-runtime/run-review.sh when available, with fallback to direct synchronous execution only if the helper is missing.
• Waits as long as the reviewer runtime keeps emitting per-minute In progress N heartbeats.
• Requires reviewer findings to be ordered P0 through P3, with P3 explicitly non-blocking.
• Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
• Sends completion notifications through Telegram only when the shared setup in TELEGRAM-NOTIFICATIONS.md is installed and configured.
• 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), a model, and optional max rounds (default 10), or skips
2. Prepare — plan payload and a bash reviewer command script are written to temp files
3. Run — the command script is executed through reviewer-runtime/run-review.sh when installed
4. Feedback — reviewer evaluates correctness, risks, missing steps, alternatives, security, and returns ## Summary, ## Findings, and ## Verdict
5. Prioritize — findings are ordered P0, P1, P2, P3
6. Revise — the planning agent addresses findings in priority order and re-submits
7. Repeat — up to max rounds until the reviewer returns VERDICT: APPROVED
8. Finalize — approved plan is used to generate the plan file package

Reviewer Output Contract

• P0 = total blocker
• P1 = major risk
• P2 = must-fix before approval
• P3 = cosmetic / nice to have
• Each severity section should use - None. when empty
• VERDICT: APPROVED is valid only when no P0, P1, or P2 findings remain
• P3 findings are non-blocking, but the caller should still try to fix them when cheap and safe

Runtime Artifacts

The review flow may create these temp artifacts:

• /tmp/plan-<id>.md — plan payload
• /tmp/plan-review-<id>.md — normalized review text
• /tmp/plan-review-<id>.json — raw Cursor JSON output
• /tmp/plan-review-<id>.stderr — reviewer stderr
• /tmp/plan-review-<id>.status — helper heartbeat/status log
• /tmp/plan-review-<id>.runner.out — helper-managed stdout from the reviewer command process
• /tmp/plan-review-<id>.sh — reviewer command script

Status log lines use this format:

ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-progress|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"

in-progress is the liveness heartbeat emitted roughly once per minute with note="In progress N". stall-warning is a non-terminal status-log state only. It does not mean the caller should stop waiting if in-progress heartbeats continue.

Failure Handling

• completed-empty-output means the reviewer exited without producing review text; surface .stderr and .status, then retry only after diagnosing the cause.
• needs-operator-decision means the helper reached hard-timeout escalation; surface .status and decide whether to extend the timeout, abort, or retry with different parameters.
• Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain .stderr, .status, and .runner.out until diagnosed.
• As long as fresh in-progress heartbeats continue to arrive roughly once per minute, the caller should keep waiting.

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> --strict-mcp-config --setting-sources user	No (fresh call each round)	--strict-mcp-config --setting-sources user
cursor	cursor-agent -p --mode=ask --model <model> --trust --output-format json	Yes (--resume <id>)	--mode=ask

For all three CLIs, the preferred execution path is:

1. write the reviewer command to a bash script
2. run that script through reviewer-runtime/run-review.sh
3. fall back to direct synchronous execution only if the helper is missing or not executable

Notifications

• Telegram is the only supported completion notification path.
• Shared setup: TELEGRAM-NOTIFICATIONS.md
• Notification failures are non-blocking, but they must be surfaced to the user.

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.