refactor pi resource wiring by directory

pi/extensions/subagent/README.md

@@ -0,0 +1,131 @@
+# pi subagent scaffold
+
+Foundation for a global pi subagent extension with parallel and chained delegation.
+
+## What this includes
+
+- `index.ts` — main `subagent` tool and `/subagents` command
+- `agents.ts` — agent discovery and manifest parsing
+- `agents/` — starter bundled agents:
+  - `scout` → `zai/glm-5.1`
+  - `planner` → `openai-codex/gpt-5.4:xhigh`
+  - `implementer` → `openai-codex/gpt-5.3-codex`
+  - `reviewer` → `openai-codex/gpt-5.4:xhigh`
+  - `librarian` → `zai/glm-5.1` + `exa_search` / `exa_code`
+- `prompts/` — starter prompt templates:
+  - `/implement`
+  - `/scout-and-plan`
+  - `/implement-and-review`
+  - `/parallel-scout`
+  - `/research`
+
+## Discovery model
+
+This extension supports three agent sources:
+
+- **bundled** — agents shipped in this directory (`./agents`)
+- **user** — `~/.pi/agent/agents`
+- **project** — nearest `.pi/agents` from the current working directory upward
+
+Scope values:
+
+- `global` — bundled + user
+- `project` — project only
+- `both` — bundled + user + project
+
+Precedence when names collide:
+
+1. bundled
+2. user
+3. project
+
+So project-local agents override user/global ones, and user/global agents override bundled defaults.
+
+## Parallel safety
+
+Parallel mode is intentionally conservative.
+
+- agents with `parallelSafe: true` can run in parallel
+- agents with `parallelSafe: false` are blocked in parallel mode
+
+The bundled `implementer` is marked serial-only.
+
+## Agent manifest format
+
+Each agent is a markdown file with YAML frontmatter:
+
+```md
+---
+name: planner
+description: Creates implementation plans
+model: anthropic/claude-sonnet-4-5
+tools: read, grep, find, ls
+parallelSafe: true
+role: planner
+tags: planning, design
+---
+
+System prompt goes here.
+```
+
+Notes:
+
+- `model` accepts normal pi `--model` values, including `provider/id` and optional `:thinking`
+- the current scaffold intentionally uses built-in pi providers (`openai-codex`, `zai`), so no custom provider extension is required yet
+- `tools` should usually be explicit to avoid recursive delegation
+- `parallelSafe` defaults to `false` if omitted
+
+## Install globally from this repo
+
+Recommended runtime target:
+
+```bash
+mkdir -p ~/.pi/agent/extensions
+ln -sfn /Users/rasyidanakbar/Development/dotfiles/pi/extensions/subagent ~/.pi/agent/extensions/subagent
+```
+
+Then start pi and run:
+
+```text
+/reload
+```
+
+Because prompts and bundled agents live inside the extension directory, a single directory symlink is enough.
+
+## Usage examples
+
+Single agent:
+
+```text
+Use subagent planner to propose a plan for refactoring auth
+```
+
+Parallel:
+
+```text
+Use subagent with two tasks in parallel: scout auth flow, librarian find similar patterns
+```
+
+Chain:
+
+```text
+Use subagent chain: scout -> planner -> implementer
+```
+
+Prompt templates:
+
+```text
+/implement add request validation to the API
+/scout-and-plan refactor auth to support oauth
+/implement-and-review add pagination to the endpoint
+/parallel-scout investigate session handling
+/research evaluate the best pattern for background job retries in this codebase
+```
+
+## Good next steps
+
+1. add `parallel_then_reduce`
+2. add budget / timeout controls
+3. add a custom `index_search` tool for librarian workflows
+4. wire the whole `pi/extensions/` directory into Home Manager so `~/.pi/agent/extensions/` is managed automatically
+5. pair librarian with the separate `pi/extensions/exa-tools` extension for web/docs/code retrieval