1 files changed, 122 insertions, 47 deletions
diff --git a/pi/agent/extensions/taskwarrior-plan-mode/README.md b/pi/agent/extensions/taskwarrior-plan-mode/README.md
index 2613b12..92de7e6 100644
--- a/pi/agent/extensions/taskwarrior-plan-mode/README.md
+++ b/pi/agent/extensions/taskwarrior-plan-mode/README.md
@@ -1,82 +1,157 @@
 # Taskwarrior Plan Mode
 
-Custom Pi plan mode built on the official `plan-mode` example, but using
-Taskwarrior as the actual task source of truth through the
-`taskwarrior-task-management` workflow.
-
-## What it changes
-
-- `/plan` enters read-only planning mode
-- `/plan-exit` leaves planning mode and restores normal tools
-- blocks raw `task` and requires `ask ...`
-- injects current project Taskwarrior context into planning turns
-- extracts `Plan:` sections into actionable steps
-- `/plan-create-tasks [sequential|independent]` turns the last extracted plan
-  into real Taskwarrior tasks
-- `/task-sync [sequential|independent]` remains as a legacy alias
-- `/task-update <selector> :: <new description>` replaces a task description
-- `/task-modify <selector> :: <mods>` runs raw `ask ... modify ...` arguments
-- `/task-next [run]` focuses the started task, or starts the next `+READY` task
-- `/tasks` shows the current started and READY tasks for the repo
-- `/work-on-tasks [strategy] [max]` kicks off the project task loop using the
-  Taskwarrior skill semantics
-
-## Task semantics
-
-This extension is aligned to the `taskwarrior-task-management` skill:
-
-- `ask ...` only, never raw `task`
-- project-scoped by current git repo
-- continue started task first
+Taskwarrior-backed planning for Pi.
+
+This extension keeps planning and execution separate:
+
+- use `/plan` to enter read-only planning mode
+- ask Pi to produce a numbered `Plan:`
+- convert the extracted plan into Taskwarrior tasks explicitly
+- leave planning mode and continue execution against real tasks
+
+Taskwarrior remains the source of truth. This extension does not keep a private
+todo list.
+
+## Commands
+
+- `/plan`
+  Enter read-only planning mode. The active tool set is reduced to safe
+  exploration tools.
+- `/plan-exit`
+  Leave planning mode and restore the previous tool set.
+- `/plan-create-tasks [sequential|independent]`
+  Create Taskwarrior tasks from the last extracted `Plan:`.
+- `/task-sync [sequential|independent]`
+  Legacy alias for `/plan-create-tasks`.
+- `/task-update <selector> :: <new description>`
+  Replace a task description.
+- `/task-modify <selector> :: <mods>`
+  Apply raw `ask ... modify ...` arguments to a task.
+- `/tasks`
+  Show started and `+READY` tasks for the current repo.
+- `/task-next [run]`
+  Focus the started task, or start the next `+READY` task.
+- `/work-on-tasks [strategy] [max]`
+  Kick off the Taskwarrior execution loop aligned to the
+  `taskwarrior-task-management` workflow.
+
+## Rules
+
+- all Taskwarrior operations go through `ask`, never raw `task`
+- tasks are scoped to the current git repo through your `ask` wrapper
 - use UUIDs for stable references
-- do not mark a task done until implementation, tests, and commit are complete
-- self-review first, then run an independent fresh-context subagent review if
-  the `subagent` tool is available
+- planning mode is read-only by design
+- the extracted plan is session-local, so `/plan`, the planning prompt,
+  `/plan-create-tasks`, and `/plan-exit` should happen in the same interactive
+  or continued Pi session
 
-## Core workflow
+## Usage Flows
 
-1. Run `/plan`
-2. Ask Pi to analyze the repo and produce a numbered `Plan:`
-3. After the plan is extracted, run `/plan-create-tasks sequential`
-4. If needed, adjust tasks with `/task-update` or `/task-modify`
-5. Run `/plan-exit`
+### Flow 1: Turn a plan into Taskwarrior tasks
 
-Planning mode is intentionally read-only. The extension no longer auto-prompts
-you to create tasks after planning; task creation is explicit.
+1. Start Pi in the project.
+2. Run:
 
-The extracted plan is session-local. Use `/plan`, your planning prompt,
-`/plan-create-tasks`, and `/plan-exit` within the same interactive or continued
-Pi session.
+```text
+/plan
+```
+
+3. Ask for analysis and a numbered `Plan:`. Example:
 
-## Examples
+```text
+Analyze the current repo and propose a concise Plan: for fixing the SSH bootstrap trust model.
+```
 
-Create tasks from the last plan:
+4. After Pi replies with a `Plan:`, create tasks:
 
 ```text
 /plan-create-tasks sequential
 ```
 
+5. Leave planning mode:
+
+```text
+/plan-exit
+```
+
+Use `sequential` when each step should depend on the previous one. Use
+`independent` when the planned tasks can be worked separately.
+
+### Flow 2: Adjust a task after planning
+
 Rewrite a task description:
 
 ```text
 /task-update uuid:12345678-1234-1234-1234-123456789abc :: Restore SSH host verification during bootstrap
 ```
 
-Apply raw Taskwarrior modify arguments:
+Apply standard modify arguments:
 
 ```text
 /task-modify uuid:12345678-1234-1234-1234-123456789abc :: priority:H +security
 ```
 
-In-place description replacement with Taskwarrior syntax:
+Use Taskwarrior replacement syntax:
 
 ```text
 /task-modify uuid:12345678-1234-1234-1234-123456789abc :: /bootstrap/provisioning/
 ```
 
-## Notes
+### Flow 3: Start executing the real tasks
+
+See what is active:
+
+```text
+/tasks
+```
+
+Focus the current task:
+
+```text
+/task-next
+```
+
+Focus and immediately start execution:
+
+```text
+/task-next run
+```
+
+Run the full repo task loop:
+
+```text
+/work-on-tasks highest-impact
+```
+
+### Flow 4: Planning session pattern
+
+This is the cleanest end-to-end interactive pattern:
+
+```text
+/plan
+```
+
+```text
+Analyze the repo and give me a Plan: for the next implementation slice.
+```
+
+```text
+/plan-create-tasks sequential
+```
+
+```text
+/plan-exit
+```
+
+```text
+/work-on-tasks
+```
+
+## Notes And Limits
 
 - Planning mode is read-only by design.
 - All Taskwarrior operations still go through `ask`, never raw `task`.
 - Execution mode injects the current Taskwarrior task back into the agent prompt
   so the model works against the real task rather than an in-memory checklist.
+- Full `/plan` state is not meant to be passed across unrelated one-shot `pi -p`
+  invocations. Use a real interactive or continued session for planning.