dot/modules/pi/agent/extensions-common/plan-mode/README.md

Plan Mode

Minimal read-only mode. Built iteratively — v1 does one thing only.

v1: no writing

Trigger	Effect
/plan	Toggle plan mode
Ctrl+Alt+P	Toggle plan mode
pi --plan	Start in plan mode

While active:

• Built-in write and edit tools are removed from the active tool set
• A plan marker appears in the footer status
• The system prompt tells the model it cannot modify files
• State is persisted, so /resume keeps plan mode on

Toggling off restores the exact tool set captured when plan mode was enabled.

v2: /handover

/handover [focus] distils the session into a standalone plan document.

• Runs a side LLM call over the current branch — no extra turn is added to the conversation, and the transcript is not polluted
• Compaction-aware: uses the summary plus surviving entries if the branch was compacted
• Opens the result in the editor for review; saving writes the file, an empty buffer cancels
• Written to .pi/plans/<YYYYMMDD-HHMM>-<slug>.md, slug derived from the # heading
• Optional focus argument steers what the document centres on

Document structure: Goal, Findings, Plan (numbered, file-scoped steps), Risks & open questions, Files.

Works whether or not plan mode is active.

Not implemented (yet)

• Guarding bash against writes — bash is still fully available
• Reading a handover back in / resuming from one
• Approval and step-by-step execution flow