413 lines
14 KiB
Markdown
413 lines
14 KiB
Markdown
---
|
|
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 \
|
|
"Review the implementation plan below. Focus on:
|
|
|
|
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
|
|
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} \
|
|
--strict-mcp-config \
|
|
--setting-sources user
|
|
```
|
|
|
|
**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 below.
|
|
|
|
$(cat /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} \
|
|
--strict-mcp-config \
|
|
--setting-sources user
|
|
```
|
|
|
|
**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"
|