Update pi

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

@@ -1,66 +1,42 @@
-# Plan Mode Extension
+# Plan Mode
 
-Read-only exploration mode for safe code analysis.
+Minimal read-only mode. Built iteratively — v1 does one thing only.
 
-## Features
+## v1: no writing
 
-- **Built-in write tools disabled**: Disables edit/write while preserving other active tools
-- **Bash allowlist**: Only read-only bash commands are allowed
-- **Plan extraction**: Extracts numbered steps from `Plan:` sections
-- **Progress tracking**: Widget shows completion status during execution
-- **[DONE:n] markers**: Explicit step completion tracking
-- **Session persistence**: State survives session resume
+| Trigger | Effect |
+| --- | --- |
+| `/plan` | Toggle plan mode |
+| `Ctrl+Alt+P` | Toggle plan mode |
+| `pi --plan` | Start in plan mode |
 
-## Commands
+While active:
 
-- `/plan` - Toggle plan mode
-- `/todos` - Show current plan progress
-- `Ctrl+Alt+P` - Toggle plan mode (shortcut)
+- 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
 
-## Usage
+Toggling off restores the exact tool set captured when plan mode was enabled.
 
-1. Enable plan mode with `/plan` or `--plan` flag
-2. Ask the agent to analyze code and create a plan
-3. The agent should output a numbered plan under a `Plan:` header:
+## v2: `/handover`
 
-```
-Plan:
-1. First step description
-2. Second step description
-3. Third step description
-```
+`/handover [focus]` distils the session into a standalone plan document.
 
-4. Choose "Execute the plan" when prompted
-5. During execution, the agent marks steps complete with `[DONE:n]` tags
-6. Progress widget shows completion status
+- 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
 
-## How It Works
+Document structure: `Goal`, `Findings`, `Plan` (numbered, file-scoped steps),
+`Risks & open questions`, `Files`.
 
-### Plan Mode (Read-Only)
-- Built-in edit/write tools disabled
-- Other active tools remain available
-- Bash commands filtered through allowlist
-- Agent creates a plan without making changes
+Works whether or not plan mode is active.
 
-### Execution Mode
-- Full tool access restored
-- Agent executes steps in order
-- `[DONE:n]` markers track completion
-- Widget shows progress
+## Not implemented (yet)
 
-### Command Allowlist
-
-Safe commands (allowed):
-- File inspection: `cat`, `head`, `tail`, `less`, `more`
-- Search: `grep`, `find`, `rg`, `fd`
-- Directory: `ls`, `pwd`, `tree`
-- Git read: `git status`, `git log`, `git diff`, `git branch`
-- Package info: `npm list`, `npm outdated`, `yarn info`
-- System info: `uname`, `whoami`, `date`, `uptime`
-
-Blocked commands:
-- File modification: `rm`, `mv`, `cp`, `mkdir`, `touch`
-- Git write: `git add`, `git commit`, `git push`
-- Package install: `npm install`, `yarn add`, `pip install`
-- System: `sudo`, `kill`, `reboot`
-- Editors: `vim`, `nano`, `code`
+- Guarding `bash` against writes — `bash` is still fully available
+- Reading a handover back in / resuming from one
+- Approval and step-by-step execution flow