@taylorsatula/pi-prepare

Read-only prepare mode for Pi with clarifying questions, structured plan approval, tracked execution, and clean-workspace orientation recaps.

Overview

A three-phase linear workflow extension for Pi:

1. Preparing — Read-only exploration phase. The agent reads code, asks clarifying questions via an interactive TUI questionnaire, writes a structured plan, and submits it via propose_completed_plan.
2. Executing — Full editing tools restored. The agent executes the approved plan step-by-step, tracking progress with plan_todo.
3. Idle — Default state when prepare mode is off.

Installation

# Via pi packages
pi add github.com/taylorsatula/pi-prepare

Or install locally by placing this directory under ~/.pi/packages/prepare/.

Usage

Start Prepare Mode

• Run /prepare or press Ctrl+Alt+P to toggle prepare mode on/off.
• Pass --prepare flag to start directly in preparing phase:

  pi --prepare "implement feature X"
  

Preparing Phase

During preparation, the agent operates in read-only mode:

• Allowed tools: read, bash (allowlist-gated), grep, find, ls, questionnaire, propose_completed_plan
• Blocked: edit, write, mutating bash commands (git mutations, npm install, sed -i, find -exec, curl -o, etc.)
• Bash safety gate: Commands are validated against an allowlist with per-command subcommand checks for git, npm/pnpm/yarn, sed/awk, find/fd, and curl/wget. Unquoted command substitution ($(), `) and output redirection to real files are also rejected.

The agent should:

1. Explore the codebase using read/grep/find/ls
2. Ask clarifying questions via questionnaire when requirements are ambiguous
3. Write a complete plan following the prescribed format (Decisions → Types → Architecture → Implementation Steps)
4. Submit the plan by calling propose_completed_plan() as the final action

Plan Review Dialog

After submission, the user sees four options:

Choice	Behavior
Clean Workspace & Implement	Asks the model to PAUSE and recap what it knows so far as if briefing a newcomer, captures that full recap as the orientation document, then starts execution with a clean context window
Implement	Starts execution without compaction — full planning history remains in context
Keep Refining	Returns to chat for further discussion before resubmitting
Cancel	Exits prepare mode entirely

Executing Phase

During execution, the agent has full editing capabilities:

• Allowed tools: read, bash, edit, write, plan_todo, questionnaire
• Progress is tracked via plan_todo: use action: "list" to review steps, action: "complete" with stepId: "step-N" to mark done, or action: "cancel" to abandon the plan
• A HUD section displays the current step being executed
• Status bar shows completion progress (e.g., prepare 2/5)

Commands

Command	Description
/prepare	Toggle prepare mode on/off
/todos	Show current plan progress
/recap	Generate an orientation recap of the conversation so far (optionally focused with an argument)

Architecture

File Structure

extensions/prepare/
├── index.ts          # Main extension entry point — flags, commands, shortcuts, event hooks, phase transitions
├── types.ts           # Core type definitions (PreparePhase, PlanStep, PreparedPlan, QuestionnaireResult)
├── identity.ts        # Constants — custom type strings for context messages and compaction markers
├── prompts.ts         # Prompt builders for planning/execution instructions + step formatters
├── bash-safety.ts     # Read-only bash command validation gate with per-command allowlists
├── dossier.ts         # Clean-workspace compaction — asks the model to recap what it knows so far; the full recap becomes the orientation document. Also powers the on-demand `/recap` command.
├── plan-todo.ts       # plan_todo tool — tracks step completion during execution
├── questionnaire.ts   # Interactive TUI widget for multi-question surveys with radio + free-text input
└── submit-plan.ts     # propose_completed_plan tool — signals plan readiness for user review

Key Design Decisions

• Tool swapping over blocking: Instead of intercepting every tool call, the extension swaps active tools at phase boundaries — edit/write are removed during preparing, and propose_completed_plan/questionnaire are added back during executing.
• Structured plan parsing: Plans are parsed from markdown using ### Step N — Title headers with bullet fields (What, Files, Details, Acceptance Criteria, Dependencies). Falls back to a single catch-all step if no numbered steps are found.
• Clean workspace compaction: When selected, the entire planning conversation is serialized and sent to the active model with a single instruction — pause and recap what it knows so far as if bringing a third party up to speed. The model's full recap output, following a standardized section rubric (The system, The problem, What's there today, What's good and should survive, The journey of our discussion, The ideal scenario, Decisions locked, The delineation, What I verified in code, Open before plan-writing), becomes the orientation document that replaces all previous entries in the context window.
• Bash safety gate: Allowlist-based command checking with granular subcommand rules for git (blocks mutating operations like commit/push/rebase), package managers (blocks install/add/remove), sed/awk (blocks -i), find/fd (blocks -exec/-delete), and curl/wget (blocks writes). Unquoted command substitution and output redirection to real files are also rejected.

Development

# Type-check
npm run check

License

MIT