ai-coding-skills/docs/IMPLEMENT-PLAN.md

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/skills/ (repo-local) or ~/.cursor/skills/ (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

mkdir -p ~/.codex/skills/implement-plan
cp -R skills/implement-plan/codex/* ~/.codex/skills/implement-plan/

Claude Code

mkdir -p ~/.claude/skills/implement-plan
cp -R skills/implement-plan/claude-code/* ~/.claude/skills/implement-plan/

OpenCode

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/skills/ directory (where the Cursor Agent CLI discovers skills):

mkdir -p .cursor/skills/implement-plan
cp -R skills/implement-plan/cursor/* .cursor/skills/implement-plan/

Or install globally (loaded via ~/.cursor/skills/):

mkdir -p ~/.cursor/skills/implement-plan
cp -R skills/implement-plan/cursor/* ~/.cursor/skills/implement-plan/

Verify Installation

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/skills/implement-plan/SKILL.md || test -f ~/.cursor/skills/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/skills/superpowers/skills/executing-plans/SKILL.md or ~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md
• Cursor: .cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md or ~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md
• Cursor: .cursor/skills/superpowers/skills/verification-before-completion/SKILL.md or ~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md
• Cursor: .cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md or ~/.cursor/skills/superpowers/skills/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/skills/ (repo-local or ~/.cursor/skills/ 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.