--- name: implement-plan description: Use when a plan folder (from create-plan) exists and needs to be executed in an isolated git worktree with iterative cross-model milestone review in OpenCode workflows. ALWAYS invoke when user says "implement the plan", "execute the plan", "start implementation", "resume the plan", or similar execution requests. --- # Implement Plan (OpenCode) Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. ## Prerequisite Check (MANDATORY) This OpenCode variant depends on Superpowers execution skills being installed via OpenCode's native skill system. Required: - Plan folder exists under `ai_plan/` at project root - `continuation-runbook.md` exists in plan folder - `milestone-plan.md` exists in plan folder - `story-tracker.md` exists in plan folder - Git repo with worktree support: `git worktree list` - OpenCode Superpowers skills symlink: `~/.config/opencode/skills/superpowers` - Superpowers execution skills: - `superpowers/executing-plans` - `superpowers/using-git-worktrees` - `superpowers/verification-before-completion` - `superpowers/finishing-a-development-branch` Verify before proceeding: ```bash ls -l ~/.config/opencode/skills/superpowers ``` If dependencies are missing, stop immediately and return: "Missing dependency: OpenCode Superpowers execution skills are required (`superpowers/executing-plans`, `superpowers/using-git-worktrees`, `superpowers/verification-before-completion`, `superpowers/finishing-a-development-branch`). Install from https://github.com/obra/superpowers (OpenCode setup), then retry." If no plan folder exists: "No plan found under `ai_plan/`. Run `create-plan` first." ## Process ### Phase 1: Bootstrap Superpowers Context (REQUIRED) Use OpenCode's native skill tool: - list skills - verify `superpowers/executing-plans`, `superpowers/using-git-worktrees`, `superpowers/verification-before-completion`, and `superpowers/finishing-a-development-branch` are discoverable ### Phase 2: Locate Plan 1. Scan `ai_plan/` for plan directories (most recent first by date prefix). 2. If multiple plans exist, ask user which one to implement. 3. If no plan exists, stop: "No plan found. Run create-plan first." 4. Read `continuation-runbook.md` first (source of truth). 5. Read `story-tracker.md` to detect resume state (`in-dev` or `completed` stories). 6. Read `milestone-plan.md` for implementation details. ### Phase 3: Configure Reviewer If the user has already specified a reviewer CLI and model (e.g., "implement the plan, review with codex o4-mini"), use those values. Otherwise, ask: 1. **Which CLI should review each milestone?** - `codex` — OpenAI Codex CLI (`codex exec`) - `claude` — Claude Code CLI (`claude -p`) - `cursor` — Cursor Agent CLI (`cursor-agent -p`) - `skip` — No external review, proceed with user approval only 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 available models - Accept any model string the user provides 3. **Max review rounds per milestone?** (default: 10) - If the user does not provide a value, set `MAX_ROUNDS=10`. Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed for the entire run. ### Phase 4: Set Up Worktree (REQUIRED SUB-SKILL) Use OpenCode's native skill tool to load: - `superpowers/using-git-worktrees` Then: 1. Branch naming: `implement/` (e.g., `implement/2026-03-04-auth-system`). 2. Follow worktree skill's directory priority: `.worktrees/` > `worktrees/` > CLAUDE.md > ask user. 3. Verify `.gitignore` covers worktree directory. 4. Run project setup (auto-detect: `npm install`, `cargo build`, `pip install`, etc.). 5. Verify clean baseline (run tests). **Resume detection:** If `story-tracker.md` shows `in-dev` or `completed` stories, check if worktree branch already exists (`git worktree list`). If so, `cd` into existing worktree instead of creating a new one. ### Phase 5: Execute Milestones (Loop) For each milestone (M1, M2, ...): #### Step 1: Read Milestone Spec Read the milestone section from `milestone-plan.md`. #### Step 2: Update Tracker Mark first story `in-dev` in `story-tracker.md`. #### Step 3: Implement Stories Execute each story in order. After completing each story: 1. Mark `in-dev` -> `completed` in `story-tracker.md` 2. Update counts 3. Mark next story `in-dev` Commit hashes are not available yet — they are backfilled in Step 6 after the milestone is approved and committed. #### Step 4: Verify Milestone (REQUIRED SUB-SKILL) Use OpenCode's native skill tool to load: - `superpowers/verification-before-completion` ```bash # Lint changed files # Typecheck # Run tests (targeted first, then full suite) ``` All must pass before proceeding. If failures: fix, re-verify. Do NOT proceed to review with failures. #### Step 5: Milestone Review Loop Send to reviewer for approval **before committing**. See Phase 6 for details. The review payload uses working-tree diffs (`git diff` for unstaged, `git diff --staged` for staged changes). **Skip this step if reviewer was set to `skip`.** When skipped, present the milestone summary to the user and ask for approval directly. #### Step 6: Commit & Approve Only after the reviewer approves (or user overrides at max rounds): ```bash git add git commit -m "feat(): implement milestone M - " ``` Do NOT push. After committing: 1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`. 2. Mark milestone as `approved` in `story-tracker.md`. 3. Move to next milestone. ### Phase 6: Milestone Review Loop (Detail) **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 `REVIEW_ID` for all milestone review temp file paths: - `/tmp/milestone-${REVIEW_ID}.md` - `/tmp/milestone-review-${REVIEW_ID}.md` - `/tmp/milestone-review-${REVIEW_ID}.json` - `/tmp/milestone-review-${REVIEW_ID}.stderr` - `/tmp/milestone-review-${REVIEW_ID}.status` - `/tmp/milestone-review-${REVIEW_ID}.runner.out` - `/tmp/milestone-review-${REVIEW_ID}.sh` Resolve the shared runtime helper path before writing the command script: ```bash REVIEWER_RUNTIME=~/.config/opencode/skills/reviewer-runtime/run-review.sh ``` #### Step 2: Write Review Payload Write to `/tmp/milestone-${REVIEW_ID}.md`: ```markdown # Milestone M Review: ## Milestone Spec (from plan) [Copy milestone section from milestone-plan.md] ## Acceptance Criteria [Copy acceptance criteria checkboxes] ## Changes Made (git diff) [Output of: git diff -- for unstaged changes, or git diff --staged for staged changes] ## Verification Output ### Lint [lint output] ### Typecheck [typecheck output] ### Tests [test output with pass/fail counts] ``` #### Step 3: Submit to Reviewer (Round 1) Write the reviewer invocation to `/tmp/milestone-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/milestone-review-${REVIEW_ID}.md \ "Review this milestone implementation. The spec, acceptance criteria, git diff, and verification output are in /tmp/milestone-${REVIEW_ID}.md. Evaluate: 1. Correctness — Does the implementation match the milestone spec? 2. Acceptance criteria — Are all criteria met? 3. Code quality — Clean, maintainable, no obvious issues? 4. Test coverage — Are changes adequately tested? 5. Security — Any security concerns introduced? Be specific and actionable. If 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/milestone-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/milestone-${REVIEW_ID}.md and review this milestone implementation. Evaluate: 1. Correctness — Does the implementation match the milestone spec? 2. Acceptance criteria — Are all criteria met? 3. Code quality — Clean, maintainable, no obvious issues? 4. Test coverage — Are changes adequately tested? 5. Security — Any security concerns introduced? Be specific and actionable. If 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/milestone-${REVIEW_ID}.md and review this milestone implementation. Evaluate: 1. Correctness — Does the implementation match the milestone spec? 2. Acceptance criteria — Are all criteria met? 3. Code quality — Clean, maintainable, no obvious issues? 4. Test coverage — Are changes adequately tested? 5. Security — Any security concerns introduced? Be specific and actionable. If solid, end with exactly: VERDICT: APPROVED If changes are needed, end with exactly: VERDICT: REVISE" \ > /tmp/milestone-review-${REVIEW_ID}.json ``` For `cursor`, the command script writes raw JSON to `/tmp/milestone-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/milestone-review-${REVIEW_ID}.sh \ --stdout-file /tmp/milestone-review-${REVIEW_ID}.runner.out \ --stderr-file /tmp/milestone-review-${REVIEW_ID}.stderr \ --status-file /tmp/milestone-review-${REVIEW_ID}.status else echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2 bash /tmp/milestone-review-${REVIEW_ID}.sh >/tmp/milestone-review-${REVIEW_ID}.runner.out 2>/tmp/milestone-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/milestone-review-${REVIEW_ID}.json) jq -r '.result' /tmp/milestone-review-${REVIEW_ID}.json > /tmp/milestone-review-${REVIEW_ID}.md ``` - If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/milestone-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/milestone-review-${REVIEW_ID}.md` before verdict parsing. Fallback is allowed only when the helper is missing or not executable. #### Step 4: Read Review & Check Verdict 1. Read `/tmp/milestone-review-${REVIEW_ID}.md` 2. If the review failed, produced empty output, or reached helper timeout, also read: - `/tmp/milestone-review-${REVIEW_ID}.stderr` - `/tmp/milestone-review-${REVIEW_ID}.status` - `/tmp/milestone-review-${REVIEW_ID}.runner.out` 3. Present review to the user: ``` ## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL}) [Reviewer feedback] ``` 4. Check verdict: - **VERDICT: APPROVED** -> proceed to Phase 5 Step 6 (commit & approve) - **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, note any `stall-warning` heartbeat lines as non-terminal operator hints, and decide whether to keep waiting, abort, or retry with different helper parameters - Max rounds (`MAX_ROUNDS`) reached -> present to user for manual decision (proceed or stop) #### Step 5: Address Feedback & Re-verify 1. Address each issue the reviewer raised (do NOT commit yet). 2. Re-run verification (lint/typecheck/tests) — all must pass. 3. Update `/tmp/milestone-${REVIEW_ID}.md` with new diff and verification output. 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-N) Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly. **If `REVIEWER_CLI` is `codex`:** Resume the existing session: ```bash codex exec resume ${CODEX_SESSION_ID} \ -o /tmp/milestone-review-${REVIEW_ID}.md \ "I've addressed your feedback. Updated diff and verification output are in /tmp/milestone-${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 milestone M<N> and requested revisions. Previous feedback summary: [key points from last review] I've addressed your feedback. Updated diff and verification output are in /tmp/milestone-${REVIEW_ID}.md. Changes made: [List specific changes] Re-review. If solid, end with: VERDICT: APPROVED If more changes needed, end with: VERDICT: REVISE" \ --model ${REVIEWER_MODEL} \ --allowedTools Read \ > /tmp/milestone-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 addressed your feedback. Updated diff and verification output are in /tmp/milestone-${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/milestone-review-${REVIEW_ID}.json ``` If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds. Do not run `jq` extraction until after the helper or fallback execution completes, then extract `/tmp/milestone-review-${REVIEW_ID}.md` from the JSON response. After updating `/tmp/milestone-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1. Return to Step 4. #### Step 7: Cleanup Per Milestone ```bash rm -f \ /tmp/milestone-${REVIEW_ID}.md \ /tmp/milestone-review-${REVIEW_ID}.md \ /tmp/milestone-review-${REVIEW_ID}.json \ /tmp/milestone-review-${REVIEW_ID}.stderr \ /tmp/milestone-review-${REVIEW_ID}.status \ /tmp/milestone-review-${REVIEW_ID}.runner.out \ /tmp/milestone-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 7: Completion (REQUIRED SUB-SKILL) After all milestones are approved and committed: 1. Use OpenCode's native skill tool to load: `superpowers/finishing-a-development-branch` 2. Run full test suite one final time — all must pass. 3. Merge the worktree branch into the parent branch: ```bash # From the main repo (not the worktree) git merge implement/<plan-folder-name> ``` 4. Delete the worktree and its branch: ```bash git worktree remove <worktree-path> git branch -d implement/<plan-folder-name> ``` 5. Mark plan status as `completed` in `story-tracker.md`. ### Phase 8: Final Report Present summary: ``` ## Implementation Complete **Plan:** <plan-folder-name> **Milestones:** <N> completed, <N> approved **Review rounds:** <total across all milestones> **Branch:** implement/<plan-folder-name> (merged and deleted) ``` ## 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. Review pending stories 3. Update Last Updated and Stories Complete counts Note: Commit hashes are backfilled into story Notes after the milestone commit (Step 6), not per-story. ## Verification Checklist - [ ] Plan folder located and all required files present - [ ] Reviewer configured or explicitly skipped - [ ] Max review rounds confirmed (default: 10) - [ ] Worktree created with branch `implement/<plan-folder-name>` - [ ] Worktree directory verified in .gitignore - [ ] Baseline tests pass in worktree - [ ] Each milestone: stories tracked (in-dev -> completed) - [ ] Each milestone: lint/typecheck/tests pass before review - [ ] Each milestone: reviewer approved (or max rounds + user override) - [ ] Each milestone: committed locally only after approval - [ ] Each milestone: marked approved in story-tracker.md - [ ] All milestones completed, approved, and committed - [ ] Final test suite passes - [ ] Worktree branch merged to parent and worktree deleted - [ ] Story tracker updated with final status