ai-coding-skills/skills/create-plan/opencode/SKILL.md

---
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 Opencode workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
---

# Create Plan (OpenCode)

Create and maintain a local plan folder under `ai_plan/` at project root.

## Prerequisite Check (MANDATORY)

This OpenCode variant depends on Superpowers skills being installed via OpenCode's native skill system.

Required:
- Superpowers repo: `https://github.com/obra/superpowers`
- OpenCode Superpowers skills symlink: `~/.config/opencode/skills/superpowers`
- `superpowers/brainstorming`
- `superpowers/writing-plans`

Verify before proceeding:

```bash
ls -l ~/.config/opencode/skills/superpowers
```

If dependencies are missing, stop immediately and return:

"Missing dependency: OpenCode Superpowers skills are required (`superpowers/brainstorming`, `superpowers/writing-plans`). Install from https://github.com/obra/superpowers (OpenCode setup), then retry."

## Process

### Phase 1: Bootstrap Superpowers Context (REQUIRED)

Use OpenCode's native skill tool:
- list skills
- verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable

### Phase 2: Analyze
- Explore the codebase and existing patterns.

### Phase 3: Gather Requirements
- Ask questions ONE AT A TIME until user says ready.
- Cover scope, constraints, success criteria, dependencies.
- Summarize before proceeding.

### 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 6: Plan (REQUIRED SUB-SKILL)

Use OpenCode's native skill tool to load:
- `superpowers/writing-plans`

Then break into milestones and bite-sized stories (2-5 min each).
Story IDs: `S-{milestone}{sequence}`.

### 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 temp artifacts:
- `/tmp/plan-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
- `/tmp/plan-review-${REVIEW_ID}.stderr`
- `/tmp/plan-review-${REVIEW_ID}.status`
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
- `/tmp/plan-review-${REVIEW_ID}.sh`

Resolve the shared reviewer helper from the installed OpenCode skills directory:

```bash
REVIEWER_RUNTIME=~/.config/opencode/skills/reviewer-runtime/run-review.sh
```

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

Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:

```bash
#!/usr/bin/env bash
set -euo pipefail
```

**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"
```

Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for 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
```

**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
```

For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.

Run the command script through the shared helper when available:

```bash
if [ -x "$REVIEWER_RUNTIME" ]; then
  "$REVIEWER_RUNTIME" \
    --command-file /tmp/plan-review-${REVIEW_ID}.sh \
    --stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
    --stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
    --status-file /tmp/plan-review-${REVIEW_ID}.status
else
  echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
  bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
fi
```

After the command completes:
- If `REVIEWER_CLI=cursor`, extract the final 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
```

- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.

#### Step 4: Read Review & Check Verdict

1. Read `/tmp/plan-review-${REVIEW_ID}.md`
2. If the review failed, produced empty output, or reached helper timeout, also read:
   - `/tmp/plan-review-${REVIEW_ID}.stderr`
   - `/tmp/plan-review-${REVIEW_ID}.status`
   - `/tmp/plan-review-${REVIEW_ID}.runner.out`
3. 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
   - Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
   - Helper state `needs-operator-decision` → surface status log and decide whether to keep waiting, abort, or retry with different helper parameters
   - 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
```

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

After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.

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 \
  /tmp/plan-review-${REVIEW_ID}.stderr \
  /tmp/plan-review-${REVIEW_ID}.status \
  /tmp/plan-review-${REVIEW_ID}.runner.out \
  /tmp/plan-review-${REVIEW_ID}.sh
```

If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.

### Phase 8: 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 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.
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
3. `milestone-plan.md` - full implementation spec (template-based).
4. `story-tracker.md` - status tracking (template-based, all stories start as `pending`).
5. `continuation-runbook.md` - resume context and execution protocol (template-based).

Use templates from this skill's `templates/` folder.

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

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

## 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` created with all stories as `pending`
- [ ] `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"