Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4d37674626156bfcd4c55cd6fb3363a183a02bed
ai-coding-skills/docs/IMPLEMENT-PLAN.md
Stefano Fiorini 4d37674626 fix: isolate claude reviewer templates
2026-03-08 18:04:07 -05:00

12 KiB
Raw Blame History

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)
  • Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
    • Codex: ~/.codex/skills/reviewer-runtime/run-review.sh
    • Claude Code: ~/.claude/skills/reviewer-runtime/run-review.sh
    • OpenCode: ~/.config/opencode/skills/reviewer-runtime/run-review.sh
    • Cursor: .cursor/skills/reviewer-runtime/run-review.sh or ~/.cursor/skills/reviewer-runtime/run-review.sh

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/
mkdir -p ~/.codex/skills/reviewer-runtime
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/

Claude Code

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

OpenCode

mkdir -p ~/.config/opencode/skills/implement-plan
cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/
mkdir -p ~/.config/opencode/skills/reviewer-runtime
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/

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/
mkdir -p .cursor/skills/reviewer-runtime
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/

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

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

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
test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || 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).
  • Runs reviewer commands through reviewer-runtime/run-review.sh when available, with fallback to direct synchronous execution only if the helper is missing.
  • Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
  • 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. Prepare — milestone payload and a bash reviewer command script are written to temp files
  3. Run — the command script is executed through reviewer-runtime/run-review.sh when installed
  4. Feedback — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security
  5. Revise — the implementing agent addresses each issue, re-verifies, and re-submits
  6. Repeat — up to max rounds (default 10) until the reviewer returns VERDICT: APPROVED
  7. Approve — milestone is marked approved in story-tracker.md

Runtime Artifacts

The milestone review flow may create these temp artifacts:

  • /tmp/milestone-<id>.md — milestone review payload
  • /tmp/milestone-review-<id>.md — normalized review text
  • /tmp/milestone-review-<id>.json — raw Cursor JSON output
  • /tmp/milestone-review-<id>.stderr — reviewer stderr
  • /tmp/milestone-review-<id>.status — helper heartbeat/status log
  • /tmp/milestone-review-<id>.runner.out — helper-managed stdout from the reviewer command process
  • /tmp/milestone-review-<id>.sh — reviewer command script

Status log lines use this format:

ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"

stall-warning is a heartbeat/status-log state only. It is not a terminal review result.

Failure Handling

  • completed-empty-output means the reviewer exited without producing review text; surface .stderr and .status, then retry only after diagnosing the cause.
  • needs-operator-decision means the helper reached hard-timeout escalation; surface .status and decide whether to keep waiting, abort, or retry with different parameters.
  • Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain .stderr, .status, and .runner.out until diagnosed.

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> --strict-mcp-config --setting-sources user No (fresh call each round) --strict-mcp-config --setting-sources user
cursor cursor-agent -p --mode=ask --model <model> --trust --output-format json Yes (--resume <id>) --mode=ask

For all three CLIs, the preferred execution path is:

  1. write the reviewer command to a bash script
  2. run that script through reviewer-runtime/run-review.sh
  3. fall back to direct synchronous execution only if the helper is missing or not executable

The helper also supports manual override flags for diagnostics:

run-review.sh \
  --command-file <path> \
  --stdout-file <path> \
  --stderr-file <path> \
  --status-file <path> \
  --poll-seconds 10 \
  --soft-timeout-seconds 600 \
  --stall-warning-seconds 300 \
  --hard-timeout-seconds 1800

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.
Reference in New Issue View Git Blame Copy Permalink