# 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](./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

```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, 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](./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:

```text
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 notification path.
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
- Notification failures are non-blocking, but they must be surfaced to the user.
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.

## 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.