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

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

```bash
# Type-check
npm run check
```

## License

MIT