From 262aed29507d9a85ad77f9cc5428efcd91af0319 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Wed, 4 Mar 2026 18:02:41 -0600 Subject: [PATCH] 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. --- README.md | 11 + docs/IMPLEMENT-PLAN.md | 183 ++++++++ docs/README.md | 1 + skills/implement-plan/claude-code/SKILL.md | 415 +++++++++++++++++ skills/implement-plan/codex/SKILL.md | 489 +++++++++++++++++++++ skills/implement-plan/cursor/SKILL.md | 482 ++++++++++++++++++++ skills/implement-plan/opencode/SKILL.md | 431 ++++++++++++++++++ 7 files changed, 2012 insertions(+) create mode 100644 docs/IMPLEMENT-PLAN.md create mode 100644 skills/implement-plan/claude-code/SKILL.md create mode 100644 skills/implement-plan/codex/SKILL.md create mode 100644 skills/implement-plan/cursor/SKILL.md create mode 100644 skills/implement-plan/opencode/SKILL.md diff --git a/README.md b/README.md index 56e1a12..76246c1 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ ai-coding-skills/ ├── docs/ │ ├── README.md │ ├── CREATE-PLAN.md +│ ├── IMPLEMENT-PLAN.md │ └── WEB-AUTOMATION.md ├── skills/ │ ├── _template/ @@ -26,6 +27,11 @@ ai-coding-skills/ │ │ ├── claude-code/ │ │ ├── opencode/ │ │ └── cursor/ +│ ├── implement-plan/ +│ │ ├── codex/ +│ │ ├── claude-code/ +│ │ ├── opencode/ +│ │ └── cursor/ │ └── web-automation/ │ ├── codex/ │ ├── claude-code/ @@ -47,12 +53,17 @@ ai-coding-skills/ | create-plan | claude-code | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | | create-plan | opencode | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | | create-plan | cursor | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) | +| implement-plan | codex | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) | +| implement-plan | claude-code | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) | +| implement-plan | opencode | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) | +| implement-plan | cursor | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) | | web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | | web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | | web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) | - Docs index: `docs/README.md` - Create-plan guide: `docs/CREATE-PLAN.md` +- Implement-plan guide: `docs/IMPLEMENT-PLAN.md` - Web-automation guide: `docs/WEB-AUTOMATION.md` ## Compatibility Policy diff --git a/docs/IMPLEMENT-PLAN.md b/docs/IMPLEMENT-PLAN.md new file mode 100644 index 0000000..6d0c908 --- /dev/null +++ b/docs/IMPLEMENT-PLAN.md @@ -0,0 +1,183 @@ +# IMPLEMENT-PLAN + +## Purpose + +Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. Milestones are implemented one-by-one with lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all are approved. + +## Requirements + +- Plan folder under `ai_plan/` (created by `create-plan`) with: + - `continuation-runbook.md` + - `milestone-plan.md` + - `story-tracker.md` +- Git repo with worktree support +- Superpowers execution skills installed from: https://github.com/obra/superpowers +- Required dependencies: + - `superpowers:executing-plans` + - `superpowers:using-git-worktrees` + - `superpowers:verification-before-completion` + - `superpowers:finishing-a-development-branch` +- For Codex, native skill discovery must be configured: + - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` +- For Cursor, skills must be installed under `.cursor/rules/` (repo-local) or `~/.cursor/rules/` (global) + +If dependencies are missing, stop and return: + +"Missing dependency: [specific missing item]. Ensure all prerequisites are met, then retry." + +### Reviewer CLI Requirements (Optional) + +To use the iterative milestone review feature, one of these CLIs must be installed: + +| Reviewer CLI | Install | Verify | +|---|---|---| +| `codex` | `npm install -g @openai/codex` | `codex --version` | +| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` | +| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) | + +The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code can send milestones to Codex for review, and vice versa. + +**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`. + +## Install + +### Codex + +```bash +mkdir -p ~/.codex/skills/implement-plan +cp -R skills/implement-plan/codex/* ~/.codex/skills/implement-plan/ +``` + +### Claude Code + +```bash +mkdir -p ~/.claude/skills/implement-plan +cp -R skills/implement-plan/claude-code/* ~/.claude/skills/implement-plan/ +``` + +### OpenCode + +```bash +mkdir -p ~/.config/opencode/skills/implement-plan +cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/ +``` + +### Cursor + +Copy into the repo-local `.cursor/rules/` directory (where the Cursor Agent CLI discovers skills): + +```bash +mkdir -p .cursor/rules/implement-plan +cp -R skills/implement-plan/cursor/* .cursor/rules/implement-plan/ +``` + +Or install globally (loaded via `~/.cursor/rules/`): + +```bash +mkdir -p ~/.cursor/rules/implement-plan +cp -R skills/implement-plan/cursor/* ~/.cursor/rules/implement-plan/ +``` + +## Verify Installation + +```bash +test -f ~/.codex/skills/implement-plan/SKILL.md || true +test -f ~/.claude/skills/implement-plan/SKILL.md || true +test -f ~/.config/opencode/skills/implement-plan/SKILL.md || true +test -f .cursor/rules/implement-plan/SKILL.md || test -f ~/.cursor/rules/implement-plan/SKILL.md || true +``` + +Verify Superpowers execution dependencies exist in your agent skills root: + +- Codex: `~/.agents/skills/superpowers/executing-plans/SKILL.md` +- Codex: `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md` +- Codex: `~/.agents/skills/superpowers/verification-before-completion/SKILL.md` +- Codex: `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md` +- Claude Code: `~/.claude/skills/superpowers/executing-plans/SKILL.md` +- Claude Code: `~/.claude/skills/superpowers/using-git-worktrees/SKILL.md` +- Claude Code: `~/.claude/skills/superpowers/verification-before-completion/SKILL.md` +- Claude Code: `~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md` +- OpenCode: `~/.config/opencode/skills/superpowers/executing-plans/SKILL.md` +- OpenCode: `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md` +- OpenCode: `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md` +- OpenCode: `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md` +- Cursor: `.cursor/rules/superpowers/executing-plans/SKILL.md` or `~/.cursor/rules/superpowers/executing-plans/SKILL.md` +- Cursor: `.cursor/rules/superpowers/using-git-worktrees/SKILL.md` or `~/.cursor/rules/superpowers/using-git-worktrees/SKILL.md` +- Cursor: `.cursor/rules/superpowers/verification-before-completion/SKILL.md` or `~/.cursor/rules/superpowers/verification-before-completion/SKILL.md` +- Cursor: `.cursor/rules/superpowers/finishing-a-development-branch/SKILL.md` or `~/.cursor/rules/superpowers/finishing-a-development-branch/SKILL.md` + +## Key Behavior + +- Reads existing plan from `ai_plan/YYYY-MM-DD-/`. +- Sets up an isolated git worktree with branch `implement/`. +- Executes milestones one-by-one, tracking stories in `story-tracker.md`. +- Runs lint/typecheck/tests as a gate before each milestone review. +- Sends each milestone to a reviewer CLI for approval (max rounds configurable, default 10). +- Commits each milestone locally only after reviewer approval (does not push). +- After all milestones approved, merges worktree branch to parent and deletes worktree. +- Supports resume: detects existing worktree and `in-dev`/`completed` stories. + +## Milestone Review Loop + +After each milestone is implemented and verified, the skill sends it to a second model for review: + +1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`) and model, or skips +2. **Submit** — milestone spec, acceptance criteria, git diff, and verification output are written to a temp file and sent to the reviewer in read-only/ask mode +3. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security +4. **Revise** — the implementing agent addresses each issue, re-verifies, and re-submits +5. **Repeat** — up to max rounds (default 10) until the reviewer returns `VERDICT: APPROVED` +6. **Approve** — milestone is marked approved in `story-tracker.md` + +### Supported Reviewer CLIs + +| CLI | Command | Session Resume | Read-Only Mode | +|---|---|---|---| +| `codex` | `codex exec -m -s read-only` | Yes (`codex exec resume `) | `-s read-only` | +| `claude` | `claude -p --model --allowedTools Read` | No (fresh call each round) | `--allowedTools Read` | +| `cursor` | `cursor-agent -p --mode=ask --model --trust --output-format json` | Yes (`--resume `) | `--mode=ask` | + +## Variant Hardening Notes + +### Claude Code + +- Must invoke explicit required sub-skills: + - `superpowers:executing-plans` + - `superpowers:using-git-worktrees` + - `superpowers:verification-before-completion` + - `superpowers:finishing-a-development-branch` + +### Codex + +- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers). +- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` +- Must invoke required sub-skills with explicit announcements. +- Must track checklist-driven skills with `update_plan` todos. +- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used. + +### OpenCode + +- Must use OpenCode native skill tool (not Claude/Codex invocation syntax). +- Must verify Superpowers skill discovery under: + - `~/.config/opencode/skills/superpowers` +- Must explicitly load all four execution sub-skills. + +### Cursor + +- Must use workspace discovery from `.cursor/rules/` (repo-local or `~/.cursor/rules/` global). +- Must announce skill usage explicitly before invocation. +- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively. +- Must not use `--force` or `--mode=agent` for review (reviewer should never write files). + +## Execution Workflow Rules + +- Read `continuation-runbook.md` first (source of truth). +- Set up worktree before any implementation work. +- Complete one milestone at a time. +- Update `story-tracker.md` before/after each story. +- Lint/typecheck/test after each milestone (all must pass). +- Send to reviewer for approval before committing. +- Address review feedback, re-verify, re-submit (do not commit between rounds). +- Commit locally (do not push) only after reviewer approves the milestone. +- Move to next milestone only after approval and commit. +- After all milestones: run full test suite, merge worktree branch to parent, delete worktree. +- Max review rounds default to 10 if user does not specify a value. diff --git a/docs/README.md b/docs/README.md index 1ee965c..6c6451a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ This directory contains user-facing docs for each skill. ## Index - [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan. +- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan. - [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation. ## Repo Setup diff --git a/skills/implement-plan/claude-code/SKILL.md b/skills/implement-plan/claude-code/SKILL.md new file mode 100644 index 0000000..e739dc8 --- /dev/null +++ b/skills/implement-plan/claude-code/SKILL.md @@ -0,0 +1,415 @@ +--- +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. ALWAYS invoke when user says "implement the plan", "execute the plan", "start implementation", "resume the plan", or similar execution requests. +--- + +# Implement Plan (Claude Code) + +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) + +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` +- Superpowers execution skills: + - `superpowers:executing-plans` + - `superpowers:using-git-worktrees` + - `superpowers:verification-before-completion` + - `superpowers:finishing-a-development-branch` + +If any dependency is missing, stop immediately and return: + +"Missing dependency: [specific missing item]. Ensure all prerequisites are met, then retry." + +If no plan folder exists: + +"No plan found under `ai_plan/`. Run `create-plan` first." + +## Process + +### Phase 1: 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 2: Configure Reviewer + +If the user has already specified a reviewer CLI and model (e.g., "implement the plan, review with claude sonnet"), 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 3: Set Up Worktree (REQUIRED SUB-SKILL) + +Invoke `superpowers:using-git-worktrees` explicitly. + +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 4: 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) + +Invoke `superpowers:verification-before-completion` explicitly. + +```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 5 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 5: 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 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) + +**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 4 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 6: Completion (REQUIRED SUB-SKILL) + +After all milestones are approved and committed: + +1. Invoke `superpowers:finishing-a-development-branch` explicitly. +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 7: 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) + +**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.** + +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 diff --git a/skills/implement-plan/codex/SKILL.md b/skills/implement-plan/codex/SKILL.md new file mode 100644 index 0000000..e16b3be --- /dev/null +++ b/skills/implement-plan/codex/SKILL.md @@ -0,0 +1,489 @@ +--- +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. ALWAYS invoke when user says "implement the plan", "execute the plan", "start implementation", "resume the plan", or similar execution requests. +--- + +# Implement Plan (Codex Native Superpowers) + +Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. + +## Overview + +This skill wraps the Superpowers execution flow for Codex: +1. Locate plan files under `ai_plan/` +2. Set up an isolated git worktree +3. Execute milestones one-by-one with lint/typecheck/test gates +4. Review each milestone with a second model/provider +5. Commit approved milestones, merge to parent branch, and delete worktree + +**Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands. + +## Prerequisite Check (MANDATORY) + +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` +- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` +- Superpowers execution skills: + - `superpowers:executing-plans` + - `superpowers:using-git-worktrees` + - `superpowers:verification-before-completion` + - `superpowers:finishing-a-development-branch` + +Verify before proceeding: + +```bash +test -L ~/.agents/skills/superpowers +test -f ~/.agents/skills/superpowers/executing-plans/SKILL.md +test -f ~/.agents/skills/superpowers/using-git-worktrees/SKILL.md +test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md +test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md +``` + +If any dependency is missing, stop and return: + +`Missing dependency: [specific missing item]. Ensure all prerequisites are met, then retry.` + +If no plan folder exists: + +`No plan found under ai_plan/. Run create-plan first.` + +## Required Skill Invocation Rules + +- Invoke relevant skills through native discovery (no CLI wrapper). +- Announce skill usage explicitly: + - `I've read the [Skill Name] skill and I'm using it to [purpose].` +- For skills with checklists, track checklist items with `update_plan` todos. +- Tool mapping for Codex: + - `TodoWrite` -> `update_plan` + - `Task` subagents -> unavailable in Codex; do the work directly and state the limitation + - `Skill` -> use native skill discovery from `~/.agents/skills/` + +## Process + +### Phase 1: 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 2: Configure Reviewer + +If the user has already specified a reviewer CLI and model (e.g., "implement the plan, review with claude sonnet"), 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 3: Set Up Worktree (REQUIRED SUB-SKILL) + +Invoke `superpowers:using-git-worktrees`. + +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 4: 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) + +Invoke `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 5 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 5: 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 4 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 6: Completion (REQUIRED SUB-SKILL) + +After all milestones are approved and committed: + +1. Invoke `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 7: 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) +``` + +## Quick Reference + +| Phase | Action | Required Output | +|---|---|---| +| 1 | Locate plan in `ai_plan/` | Plan folder identified, files read | +| 2 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` | +| 3 | Invoke `superpowers:using-git-worktrees` | Worktree created, baseline passing | +| 4 | Execute milestones (loop) | Stories tracked, verified, committed, reviewed | +| 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | +| 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted | +| 7 | Final report | Summary presented | + +## Tracker Discipline (MANDATORY) + +**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.** + +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. + +## Common Mistakes + +- Using deprecated commands like `superpowers-codex bootstrap` or `superpowers-codex use-skill`. +- Proceeding to milestone review with failing tests. +- Pushing commits before milestone approval. +- Skipping worktree setup and working directly on the main branch. +- Not capturing the Codex session ID for resume in subsequent review rounds. +- Forgetting to update `story-tracker.md` between stories. +- Creating a new worktree when one already exists for a resumed plan. + +## Rationalizations and Counters + +| Rationalization | Counter | +|---|---| +| "Bootstrap CLI is faster" | Deprecated for Codex; native discovery is the supported path. | +| "I can skip the worktree for small plans" | Worktree isolation is mandatory — it protects the main branch. | +| "Tests passed earlier, I can skip re-verification" | Each milestone must be independently verified before review. | +| "The reviewer approved, I can skip my own validation" | Reviewer feedback supplements but does not replace your own verification. | +| "I can commit before the reviewer approves" | Code must only be committed after milestone approval — reviewers evaluate uncommitted diffs. | + +## Red Flags - Stop and Correct + +- You are about to run any `superpowers-codex` command. +- You are pushing commits without user approval. +- You did not announce which skill you invoked and why. +- You are proceeding to review with failing lint/typecheck/tests. +- You are skipping the worktree and working on the main branch. +- You are applying a reviewer suggestion that contradicts user requirements. + +## 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 diff --git a/skills/implement-plan/cursor/SKILL.md b/skills/implement-plan/cursor/SKILL.md new file mode 100644 index 0000000..410c49a --- /dev/null +++ b/skills/implement-plan/cursor/SKILL.md @@ -0,0 +1,482 @@ +--- +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 Cursor Agent CLI workflows. ALWAYS invoke when user says "implement the plan", "execute the plan", "start implementation", "resume the plan", or similar execution requests. +--- + +# Implement Plan (Cursor Agent CLI) + +Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. + +## Overview + +This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`cursor-agent`): +1. Locate plan files under `ai_plan/` +2. Set up an isolated git worktree +3. Execute milestones one-by-one with lint/typecheck/test gates +4. Review each milestone with a second model/provider +5. Commit approved milestones, merge to parent branch, and delete worktree + +**Core principle:** Cursor Agent CLI discovers skills from `.cursor/rules/` (repo-local or `~/.cursor/rules/` global). It also reads `AGENTS.md` at the repo root for additional instructions. + +## Prerequisite Check (MANDATORY) + +Required: +- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout. +- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager) +- 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` +- Superpowers skills installed under `.cursor/rules/` (repo-local) or `~/.cursor/rules/` (global) +- Superpowers execution skills: + - `superpowers:executing-plans` + - `superpowers:using-git-worktrees` + - `superpowers:verification-before-completion` + - `superpowers:finishing-a-development-branch` + +Verify before proceeding: + +```bash +cursor-agent --version +test -f .cursor/rules/superpowers/executing-plans/SKILL.md || test -f ~/.cursor/rules/superpowers/executing-plans/SKILL.md +test -f .cursor/rules/superpowers/using-git-worktrees/SKILL.md || test -f ~/.cursor/rules/superpowers/using-git-worktrees/SKILL.md +test -f .cursor/rules/superpowers/verification-before-completion/SKILL.md || test -f ~/.cursor/rules/superpowers/verification-before-completion/SKILL.md +test -f .cursor/rules/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.cursor/rules/superpowers/finishing-a-development-branch/SKILL.md +# Only if using cursor as reviewer CLI: +# jq --version +``` + +If any dependency is missing, stop and return: + +`Missing dependency: [specific missing item]. Install from https://github.com/obra/superpowers and copy into .cursor/rules/ or ~/.cursor/rules/, then retry.` + +If no plan folder exists: + +`No plan found under ai_plan/. Run create-plan first.` + +## Required Skill Invocation Rules + +- Invoke relevant skills through workspace discovery (`.cursor/rules/`). +- Announce skill usage explicitly: + - `I've read the [Skill Name] skill and I'm using it to [purpose].` +- For skills with checklists, track checklist items explicitly in conversation. + +## Process + +### Phase 1: 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 2: 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 3: Set Up Worktree (REQUIRED SUB-SKILL) + +Invoke `superpowers:using-git-worktrees`. + +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 4: 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) + +Invoke `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 5 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 5: 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: + +```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 +``` + +Notes on Cursor flags: +- `--mode=ask` — read-only mode, no file modifications +- `--trust` — trust workspace without prompting (required for non-interactive use) +- `-p` / `--print` — non-interactive mode, output to stdout +- `--output-format json` — structured output with `session_id` and `result` fields + +#### 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 4 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 6: Completion (REQUIRED SUB-SKILL) + +After all milestones are approved and committed: + +1. Invoke `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 7: 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) +``` + +## Quick Reference + +| Phase | Action | Required Output | +|---|---|---| +| 1 | Locate plan in `ai_plan/` | Plan folder identified, files read | +| 2 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` | +| 3 | Invoke `superpowers:using-git-worktrees` | Worktree created, baseline passing | +| 4 | Execute milestones (loop) | Stories tracked, verified, committed, reviewed | +| 5 | Milestone review loop (per milestone) | Reviewer approval or max rounds + user override | +| 6 | Invoke `superpowers:finishing-a-development-branch` | Branch merged to parent, worktree deleted | +| 7 | Final report | Summary presented | + +## 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. + +## Common Mistakes + +- Forgetting `--trust` flag when running `cursor-agent` non-interactively (causes interactive prompt). +- Using `--mode=agent` or `--force` for reviews (reviewer should be read-only, use `--mode=ask`). +- Proceeding to milestone review with failing tests. +- Pushing commits before milestone approval. +- Skipping worktree setup and working directly on the main branch. +- Forgetting to update `story-tracker.md` between stories. +- Creating a new worktree when one already exists for a resumed plan. + +## Red Flags - Stop and Correct + +- You started implementing without reading `continuation-runbook.md` first. +- You are pushing commits without user approval. +- You did not announce which skill you invoked and why. +- You are proceeding to review with failing lint/typecheck/tests. +- You are skipping the worktree and working on the main branch. +- You are applying a reviewer suggestion that contradicts user requirements. +- Reviewer CLI is running with write permissions (must be read-only). + +## 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 diff --git a/skills/implement-plan/opencode/SKILL.md b/skills/implement-plan/opencode/SKILL.md new file mode 100644 index 0000000..13d1a43 --- /dev/null +++ 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