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/docs/IMPLEMENT-PLAN.md
+++ 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-<short-title>/`.
+- Sets up an isolated git worktree with branch `implement/<plan-folder-name>`.
+- 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 <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
+| `claude` | `claude -p --model <model> --allowedTools Read` | No (fresh call each round) | `--allowedTools Read` |
+| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--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.
--- 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