Add Pi extensions and usage docs

1 files changed, 72 insertions, 27 deletions

diff --git a/pi/agent/extensions/fresh-subagent/README.md b/pi/agent/extensions/fresh-subagent/README.md
index c74dd78..8758bc9 100644
--- a/pi/agent/extensions/fresh-subagent/README.md
+++ b/pi/agent/extensions/fresh-subagent/README.md
@@ -1,29 +1,30 @@
 # Fresh Subagent
 
-Minimal fresh-context subagent support for Pi.
+Generic fresh-context delegation for Pi.
 
-## What it does
+This extension gives Pi a simple subagent primitive:
 
-- registers a `subagent` tool the main agent can call
-- registers a `/subagent <prompt>` command for direct use
-- runs the delegated work in a new `pi --mode json -p --no-session` process
-- defaults to the current session model when one is active
-- returns only the final answer or review result
+- the main agent can call the `subagent` tool
+- you can call `/subagent <prompt>` directly
+- the delegated work runs in a new `pi --mode json -p --no-session` process
+- the child starts with a fresh context
+- the result comes back as one final answer
 
 This is intentionally small. It does not manage agent catalogs, chains, or
 parallel workers. It is meant for one-off delegation with a clean context.
 
-## What it is for
+## What It Is For
 
 Subagents are generic. The main agent can hand them any focused prompt that
 benefits from a clean context, for example:
 
-- independent code review
-- fresh-context debugging
-- focused codebase research
+- code review
+- debugging
+- focused research
 - second-opinion architecture checks
-- summarizing a noisy command output or diff
-- validating whether a completed task is actually done
+- summarizing noisy output
+- validating whether a task is really complete
+- any other self-contained side task
 
 One common use is the `taskwarrior-task-management` review loop:
 
@@ -33,51 +34,95 @@ One common use is the `taskwarrior-task-management` review loop:
 4. The main agent fixes findings
 5. Only then does the task move toward completion
 
-## Direct usage
+## Usage Flows
 
-Run a manual fresh-context review:
+### Flow 1: Use it directly inside Pi
+
+Run a direct delegation:
 
 ```text
-/subagent Independently review the recent changes for bugs, regressions, and missing tests. Only report concrete findings.
+/subagent Compare the current plan-mode extension behavior against the requested workflow and list only the mismatches.
 ```
 
-Run a focused side investigation:
+Run a focused investigation:
 
 ```text
 /subagent Find all code paths that write to the SSH known_hosts file and summarize the risk.
 ```
 
-Run a generic delegation:
+Run a review:
 
 ```text
-/subagent Compare the current plan-mode extension behavior against the requested workflow and list only the mismatches.
+/subagent Independently review the recent changes for bugs, regressions, and missing tests. Only report concrete findings.
 ```
 
-One-shot CLI usage also works now:
+### Flow 2: Use it from the main agent
+
+Because this is registered as a tool, the main agent can call it itself.
+
+Generic handoff pattern:
+
+```text
+Use the subagent tool for a fresh-context pass on this side task, then return only the useful result.
+```
+
+Review handoff pattern:
+
+```text
+First review your own changes. Afterwards, use the subagent tool to perform an independent fresh-context review and then address any findings.
+```
+
+Research handoff pattern:
+
+```text
+Use the subagent tool to inspect only the WireGuard setup path in a fresh context and summarize the concrete risks.
+```
+
+### Flow 3: Use it in one-shot CLI mode
+
+This works outside the full TUI as well:
 
 ```bash
 pi --model openai/gpt-4.1 --no-session -p '/subagent Say only SUBAGENT_COMMAND_OK'
 ```
 
-## Agent usage
+### Flow 4: Use it in the Taskwarrior review loop
 
-Because this is registered as a tool, the main agent can call it itself. A good
-generic pattern is:
+The intended task workflow is:
+
+1. main agent implements
+2. main agent self-reviews
+3. main agent calls `subagent` for independent review
+4. main agent fixes findings
+5. only then complete the task
+
+## What To Put In The Prompt
+
+Subagents start fresh, so include enough context in the prompt:
+
+- what to inspect or do
+- the scope or files to focus on
+- the expected output shape
+- any constraints such as “report only concrete findings”
+
+Good:
 
 ```text
-Use the subagent tool for a fresh-context pass on this side task, then return only the useful result.
+/subagent Review the recent SSH bootstrap changes in hyperstack.rb. Report only concrete bugs, regressions, or missing tests.
 ```
 
-For review-specific flows:
+Weak:
 
 ```text
-First review your own changes. Afterwards, use the subagent tool to perform an independent fresh-context review and then address any findings.
+/subagent Review this
 ```
 
-## Notes
+## Notes And Limits
 
 - The subagent uses a fresh session via `--no-session`.
 - The subprocess still runs in the same working directory unless you override
   `cwd`.
 - The extension disables itself inside child subagent processes to avoid
   accidental recursive registration.
+- This is deliberately minimal. There is no built-in multi-agent orchestration,
+  planner chain, or background pool here.