ai-coding-skills/skills/create-plan/_source/pi/SKILL.md

name, description

name	description
create-plan	Use when a user asks to create or maintain a structured implementation plan in pi, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.

Create Plan (Pi)

Create and maintain a local plan workspace under ai_plan/ at project root.

Shared Setup

Before using this skill, read:

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

The workflow depends on:

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

Prerequisite Check (MANDATORY)

Required:

• pi --version
• Superpowers brainstorming
• Superpowers writing-plans
• pi reviewer runtime helper:
  • .pi/skills/reviewer-runtime/pi/run-review.sh, or
  • ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh

Quick checks for common installs:

pi --version
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md || test -f ~/.pi/agent/skills/superpowers/writing-plans/SKILL.md
test -x .pi/skills/reviewer-runtime/pi/run-review.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh

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

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

If any dependency is missing, stop and return:

Missing dependency: pi planning requires Superpowers brainstorming/writing-plans skills plus the 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:brainstorming or /skill:writing-plans.
• Announce skill usage explicitly:
  • I've read the [Skill Name] skill and I'm using it to [purpose].
• Track checklist-style progress inside the plan artifacts that this skill generates.
• Do not use deprecated wrapper CLIs.

Process

Phase 1: Analyze

• Explore the codebase and existing patterns.
• Review any current docs, scripts, or variant layouts that affect the plan.

Phase 2: Gather Requirements

• Ask questions one at a time until the scope is clear.
• Confirm constraints, success criteria, dependencies, and what is out of scope.

Phase 3: Configure Reviewer

If the user already specified a reviewer CLI and model, use those values. Otherwise ask:

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

1. Which CLI should review the plan?
   • codex
   • claude
   • cursor
   • opencode
   • pi
   • skip
2. Which model?
3. Max review rounds? Default: 10

Store REVIEWER_CLI, REVIEWER_MODEL, and MAX_ROUNDS for the review loop.

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/plan-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/plan-${REVIEW_ID}.md and review."

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

Phase 4: Design

• Load brainstorming.
• Present 2-3 approaches and recommend one.
• Resolve open design questions before the milestone breakdown.

Phase 5: Plan

• Load writing-plans.
• Break the work into milestones and bite-sized stories.
• Story IDs should use the S-101, S-102 style.

Phase 6: Iterative Plan Review

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/plan-${REVIEW_ID}.md
• /tmp/plan-review-${REVIEW_ID}.md
• /tmp/plan-review-${REVIEW_ID}.json
• /tmp/plan-review-${REVIEW_ID}.stderr
• /tmp/plan-review-${REVIEW_ID}.status
• /tmp/plan-review-${REVIEW_ID}.runner.out
• /tmp/plan-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: Write The Plan Payload

Write the full plan to /tmp/plan-${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: Submit To Reviewer

Build a bash command script in /tmp/plan-review-${REVIEW_ID}.sh and execute it through the shared helper when present:

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

Fallback to direct execution only if the helper is missing.

Step 4: Wait And Parse Verdict

• Keep waiting while fresh state=in-progress note="In progress N" heartbeats continue to appear.
• Treat P0, P1, or P2 as must-fix findings.
• P3 findings are non-blocking, but fix them when cheap and safe.

Step 5: Revise And Re-Submit

• Address findings in priority order.
• Rebuild the plan payload.
• Re-submit until approved or MAX_ROUNDS is reached.

Phase 7: Generate Plan Files

Once the plan is approved:

1. Ensure /ai_plan/ exists in .gitignore
2. Create ai_plan/YYYY-MM-DD-<slug>/
3. Write:
   • original-plan.md
   • final-transcript.md
   • milestone-plan.md
   • story-tracker.md
   • continuation-runbook.md
4. Use the template files from this skill's templates/ directory

Phase 8: Telegram Completion Notification

Resolve the notification 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. If not, state that no Telegram completion notification was sent.