ai-coding-skills/skills/implement-plan/cursor/SKILL.md

name, description

name	description
implement-plan	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:

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.

# 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):

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

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:

# 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:

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:

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:

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:

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:

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):

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:

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

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:

# From the main repo (not the worktree)
git merge implement/<plan-folder-name>

4. Delete the worktree and its branch:

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