feat(implement-plan): add worktree-isolated plan execution skill (4 variants)

New skill that executes create-plan artifacts in an isolated git worktree with iterative cross-model milestone review. Supports codex, claude-code, opencode, and cursor agent variants.
2026-03-04 18:02:41 -06:00
parent d2970b06bd
commit 262aed2950
7 changed files with 2012 additions and 0 deletions
--- a/skills/implement-plan/opencode/SKILL.md
+++ b/skills/implement-plan/opencode/SKILL.md
@@ -0,0 +1,431 @@
+---
+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/<plan-folder-name>` (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 <changed-files>
+git commit -m "feat(<scope>): implement milestone M<N> - <description>"
+```
+
+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 for all temp file paths: `/tmp/milestone-${REVIEW_ID}.md` and `/tmp/milestone-review-${REVIEW_ID}.md`.
+
+#### Step 2: Write Review Payload
+
+Write to `/tmp/milestone-${REVIEW_ID}.md`:
+
+```markdown
+# Milestone M<N> Review: <title>
+
+## 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)
+
+**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"
+```
+
+Capture the Codex session ID from output (line `session id: <uuid>`). Store as `CODEX_SESSION_ID`.
+
+**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 \
+  > /tmp/milestone-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/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
+```
+
+Extract session ID and review text (requires `jq`):
+
+```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 `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
+
+#### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/milestone-review-${REVIEW_ID}.md`
+2. Present review to the user:
+
+```
+## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
+
+[Reviewer feedback]
+```
+
+3. 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
+   - 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)
+
+**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
+
+jq -r '.result' /tmp/milestone-review-${REVIEW_ID}.json > /tmp/milestone-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: Cleanup Per Milestone
+
+```bash
+rm -f /tmp/milestone-${REVIEW_ID}.md /tmp/milestone-review-${REVIEW_ID}.md /tmp/milestone-review-${REVIEW_ID}.json
+```
+
+### 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