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

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

```bash
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 settings-defined paths instead of the common locations above, confirm they match [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md) before continuing.

If any dependency is missing, stop and return:

`Missing dependency: pi implement-plan requires the execution skills and reviewer-runtime setup documented in docs/PI-SUPERPOWERS.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:

1. Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, or `skip`
2. Reviewer model
3. Max rounds, default `10`

Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`.

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

```bash
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:

```bash
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:

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

```bash
"$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:

```bash
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.