ai-coding-skills/pi-package/skills/implement-plan/SKILL.md

name, description

name	description
implement-plan	Use when a plan folder created by create-plan must be executed in pi with milestone verification, reviewer gates, local commits, and resumable tracker updates.

Implement Plan (Pi)

Execute an existing plan under ai_plan/ milestone by milestone, using verification gates, reviewer approval, and local commits after each approved milestone.

Shared Setup

Before using this skill, read:

• docs/PI-SUPERPOWERS.md
• docs/PI-COMMON-REVIEWER.md

This workflow depends on:

• Superpowers execution skills being visible to pi
• the pi reviewer-runtime helper being installed in a supported location

Prerequisite Check (MANDATORY)

Required:

• pi --version
• a plan folder under ai_plan/
• continuation-runbook.md
• milestone-plan.md
• story-tracker.md
• git worktree support
• Superpowers executing-plans
• Superpowers using-git-worktrees
• Superpowers verification-before-completion
• Superpowers finishing-a-development-branch
• pi reviewer runtime helper
• pi Telegram notifier helper

Quick checks for common installs:

pi --version
git worktree list
test -f ~/.agents/skills/superpowers/executing-plans/SKILL.md || test -f ~/.pi/agent/skills/superpowers/executing-plans/SKILL.md
test -f ~/.agents/skills/superpowers/using-git-worktrees/SKILL.md || test -f ~/.pi/agent/skills/superpowers/using-git-worktrees/SKILL.md
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md || test -f ~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md
test -x .pi/skills/reviewer-runtime/pi/run-review.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh

If you use a settings-defined skill path for Superpowers, confirm it matches docs/PI-SUPERPOWERS.md before continuing.

If you install the reviewer helper in a nonstandard location, confirm it matches docs/PI-COMMON-REVIEWER.md before continuing.

If any dependency is missing, stop and return:

Missing dependency: pi implement-plan requires the execution skills and reviewer setup documented in docs/PI-SUPERPOWERS.md and docs/PI-COMMON-REVIEWER.md.

Required Workflow Rules

• Load the relevant workflow skill before entering its phase. If pi did not auto-load it, use /skill:<name>.
• Announce skill usage explicitly:
  • I've read the [Skill Name] skill and I'm using it to [purpose].
• Update story-tracker.md before starting and after completing every story.
• Do not use deprecated wrapper CLIs.

Process

Phase 1: Locate Plan

1. Scan ai_plan/ and identify the target plan folder
2. Read continuation-runbook.md first
3. Read story-tracker.md to identify resume state
4. Read milestone-plan.md for the implementation spec

Phase 2: Configure Reviewer

If the user already provided reviewer settings, use them. Otherwise ask:

Reviewer CLI: codex, claude, cursor, opencode, pi, or skip

1. Which CLI should review milestone implementations?
2. Reviewer model
3. Max rounds, default 10

Store REVIEWER_CLI, REVIEWER_MODEL, and MAX_ROUNDS.

If REVIEWER_CLI=pi, verify the Pi reviewer binary before entering the review loop:

pi --version

For shorthand pi/<pi-model-name>, split only on the first slash when the prefix is exactly pi; store the complete remainder in REVIEWER_MODEL. Examples: pi/claude-opus-4-7 -> claude-opus-4-7, pi/anthropic/claude-opus-4-7 -> anthropic/claude-opus-4-7, and pi/openrouter/anthropic/claude-opus-4-7 -> openrouter/anthropic/claude-opus-4-7.

When REVIEWER_CLI=pi, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use pi --list-models [search] to inspect configured models.

The pi reviewer command rendered into /tmp/milestone-review-${REVIEW_ID}.sh must be isolated and read-only:

pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/milestone-${REVIEW_ID}.md and review."

The pi reviewer invocation must not load workflow skills and must not include write, edit, or bash tools.

Phase 3: Set Up Workspace

1. Load using-git-worktrees
2. Create or resume the implementation branch/worktree described by the plan
3. Verify baseline setup and tests before changing code

Phase 4: Execute Milestones

For each milestone:

1. Mark the next story in-dev in story-tracker.md
2. Implement the story
3. Mark the story completed
4. Continue until the milestone stories are done
5. Load verification-before-completion
6. Run lint, typecheck, and tests for the changed scope
7. Send the milestone diff and verification output to the reviewer before committing
8. Commit only after approval

Phase 5: Milestone Review Loop

Skip this phase if REVIEWER_CLI=skip.

Step 1: Generate Session ID

REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)

Use these temp artifacts:

• /tmp/milestone-${REVIEW_ID}.md
• /tmp/milestone-review-${REVIEW_ID}.md
• /tmp/milestone-review-${REVIEW_ID}.json
• /tmp/milestone-review-${REVIEW_ID}.stderr
• /tmp/milestone-review-${REVIEW_ID}.status
• /tmp/milestone-review-${REVIEW_ID}.runner.out
• /tmp/milestone-review-${REVIEW_ID}.sh

Resolve the pi reviewer runtime helper in this order:

REVIEWER_RUNTIME=""
for candidate in ".pi/skills/reviewer-runtime/pi/run-review.sh" "$HOME/.pi/agent/skills/reviewer-runtime/pi/run-review.sh"; do
  if [ -x "$candidate" ]; then
    REVIEWER_RUNTIME="$candidate"
    break
  fi
done

Step 2: Build Review Payload

Write the milestone spec, acceptance criteria, diff, and verification output to /tmp/milestone-${REVIEW_ID}.md.

Reviewer responses must use this structure:

## Summary
...

## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...

## Verdict
VERDICT: APPROVED

Rules:

• Order findings from P0 to P3
• Use - None. when a severity has no findings
• VERDICT: APPROVED is valid only when no P0, P1, or P2 findings remain

Step 3: Run Review

Execute the reviewer command script through the helper when available:

"$REVIEWER_RUNTIME" \
  --command-file /tmp/milestone-review-${REVIEW_ID}.sh \
  --stdout-file /tmp/milestone-review-${REVIEW_ID}.runner.out \
  --stderr-file /tmp/milestone-review-${REVIEW_ID}.stderr \
  --status-file /tmp/milestone-review-${REVIEW_ID}.status

Fallback to direct execution only if the helper is missing.

Step 4: Handle Findings

• Keep waiting while fresh state=in-progress note="In progress N" heartbeats continue
• Fix P0, P1, and P2 findings before approval
• Fix cheap P3 findings when safe
• Re-run verification after each revision

Phase 6: Commit And Track Approval

After milestone approval:

1. Commit the milestone locally
2. Backfill the commit hash into that milestone's story notes
3. Mark the milestone approved in story-tracker.md
4. Move to the next milestone

Phase 7: Finalization

After all milestones are approved:

1. Load finishing-a-development-branch
2. Run the full verification suite
3. Ask whether to push or keep the work local
4. Mark the plan completed in story-tracker.md

Phase 8: Telegram Completion Notification

Resolve the helper in this order:

TELEGRAM_NOTIFY_RUNTIME=""
for candidate in ".pi/skills/reviewer-runtime/pi/notify-telegram.sh" "$HOME/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh"; do
  if [ -x "$candidate" ]; then
    TELEGRAM_NOTIFY_RUNTIME="$candidate"
    break
  fi
done

If the helper exists and both TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are configured, send a short completion summary. Otherwise state that no Telegram completion notification was sent.