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

---
name: create-plan
description: 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-SUPERPOWERS.md)
- [docs/PI-COMMON-REVIEWER.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:

```bash
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](../../../docs/PI-SUPERPOWERS.md) before continuing.

If you install the reviewer helper in a nonstandard location, verify it matches [docs/PI-COMMON-REVIEWER.md](../../../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.

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:

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

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

```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: Write The Plan Payload

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

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

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

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