--- 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 all temp file paths: `/tmp/plan-${REVIEW_ID}.md` and `/tmp/plan-review-${REVIEW_ID}.md`. #### 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) **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" ``` Capture the Codex session ID from output (line `session id: `). Store as `CODEX_SESSION_ID` for session 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 \ > /tmp/plan-review-${REVIEW_ID}.md ``` **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 ``` Extract session ID and review text (requires `jq`): ```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 `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent. #### Step 4: Read Review & Check Verdict 1. Read `/tmp/plan-review-${REVIEW_ID}.md` 2. 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 - 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 \ > /tmp/plan-review-${REVIEW_ID}.md ``` **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. 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 ``` ### 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-/` 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-/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-/` - [ ] 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"