@dreki-gg/pi-plan-mode

Two-phase planning workflow for pi.

Plan with claude-opus-4-6:medium, execute with gpt-5.5:low. Plans are persisted as files in .plans/ for clean context handoff between models.

Install

pi install npm:@dreki-gg/pi-plan-mode

Recommended companions:

pi install npm:@dreki-gg/pi-questionnaire

What it provides

Feature	Name	Notes
Flag	--plan	Start pi in plan mode
Command	/plan [prompt]	Enter plan mode, optionally with a starting prompt
Command	/todos	Show current plan progress
Shortcut	Ctrl+Alt+P	Toggle plan mode

Workflow

1. Plan (claude-opus-4-6:medium)

/plan add authentication middleware with JWT support

The planner has access to read-only tools plus edit/write restricted to .plans/ files. Bash is locked to a strict allowlist of safe commands.

The planner:

• Inspects the codebase using read-only tools
• Uses questionnaire when requirements are underspecified
• Creates .plans/<kebab-name>/PLAN.md with the full numbered plan
• Creates .plans/<kebab-name>/START-PROMPT.md — a self-contained handoff prompt with all context needed to execute without the planning conversation
• Can add supporting files in the same directory for extra context

2. Choose next step

When the planner finishes, a menu appears:

Option	Description
Execute Plan	Extract todos from PLAN.md, switch to gpt-5.5:low, start with START-PROMPT.md
Refine Plan	Adversarial review — planner critiques its own plan and updates files
Follow up	Open an editor for additional instructions to the planner
Exit plan mode	Disable plan mode and restore original model

3. Execute (gpt-5.5:low)

When Execute Plan is selected:

1. Todos are extracted from PLAN.md
2. Model switches to gpt-5.5:low with full tool access
3. The executor starts with a clean context window using START-PROMPT.md
4. Each step must be marked with [DONE:n] before moving to the next
5. Progress is tracked in a widget in the status bar
6. When all steps complete, the original model and thinking level are restored

Plan directory structure

.plans/
├── plans.json                # Tracking manifest — plan status lifecycle
└── add-auth-middleware/
    ├── PLAN.md               # Numbered plan with context
    ├── START-PROMPT.md       # Self-contained executor handoff prompt
    └── ...                   # Optional supporting files

plans.json

The extension automatically maintains .plans/plans.json to track plan lifecycle:

{
  "add-auth-middleware": {
    "status": "in-progress",
    "title": "Add Authentication Middleware with JWT Support",
    "created": "2026-05-08T12:00:00.000Z",
    "completed": null
  },
  "fix-ci-flakes": {
    "status": "done",
    "title": "Fix CI Flaky Tests",
    "created": "2026-05-07T10:00:00.000Z",
    "completed": "2026-05-07T14:30:00.000Z"
  }
}

Plans start as "in-progress" when created and are marked "done" when all execution steps complete. This prevents accidental deletion of in-flight plans.

Cleaning completed plans

Use the CLI to remove completed plan directories:

# Preview what would be deleted
npx @dreki-gg/pi-plan-mode clean --dry-run

# Delete completed plans and update plans.json
npx @dreki-gg/pi-plan-mode clean

In-flight plans ("status": "in-progress") are never touched.

GitHub Actions

Clean done plans automatically after merge — similar to changesets:

name: Clean Plans

on:
  push:
    branches: [main]
    paths: ['.plans/**']

jobs:
  clean:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
      - run: npx @dreki-gg/pi-plan-mode clean
      - name: Commit cleanup
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .plans/
          git diff --cached --quiet || git commit -m "chore: clean completed plans"
          git push

Should you gitignore .plans/?

No. Commit your plans — they provide decision history and execution context. Use the clean CLI to remove done plans after merge, keeping the directory lean. Plans are execution blueprints, not permanent documentation; for lasting decisions, use ADRs.

Footer indicators

• 📝 plan — plan mode active (opus-4-6:medium, strict bash)
• 📋 exec 2/5 — executing plan with gpt-5.5:low, 2 of 5 steps done

Bash safety

In plan mode, bash is restricted to read-only commands (ls, grep, git status, cat, rg, etc.). Destructive commands (rm, mv, git commit, etc.) are blocked.

CLI reference

pi-plan-mode clean [--dry-run]

Option	Description
clean	Remove completed plan directories, update manifest
--dry-run	Show what would be deleted without deleting