subagent wokflows

pi/.pi/agent/skills/subagent-plan/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: subagent-plan
+description: "Plan-only pipeline: scout → plan → review. Produces a reviewed implementation plan without coding. Use when the user invokes /plan."
+---
+
+# /plan — Plan Only (No Implementation)
+
+## Agent Roster
+
+| Agent | Role |
+|-------|------|
+| scout | Fast codebase recon |
+| planner | Detailed implementation plans |
+| plan-reviewer | Reviews plans for correctness and risk |
+
+## Workflow (single chain)
+
+```js
+await subagent({ chain: [
+  { agent: "scout",         task: "Explore the codebase for: {task}" },
+  { agent: "planner",       task: "Create a detailed implementation plan for: {task}" },
+  { agent: "plan-reviewer", task: "Review the plan for correctness, completeness, and risk." }
+]})
+```
+
+The chain creates `scout.md`, `plan.md`, `plan-review.md` in the chain artifact dir (`/tmp/pi-chain-runs/<id>/`).
+
+## Handling the Verdict
+
+Read `plan-review.md` from the artifact dir. If **NEEDS_REVISION** or **REJECTED**, loop: tell the planner what to fix, re-run the reviewer. If **APPROVED**, present the plan path to the user.
+
+Show the user the path to `plan.md`.
+
+## Workflow Summary
+
+After the chain completes, give the user a brief honest summary:
+
+- **What happened**: did the plan pass review on the first try, or did it need revision loops?
+- **Issues**: any agent silent failures, fallbacks used, or unexpected behavior
+- **Agent quality**: did any agent misinterpret the task, produce poor output, or need hand-holding? Name the agent and the problem
+- **Skill improvements**: did this workflow reveal gaps in the skill instructions or agent prompts? Note what should change
+
+Be concise — a few lines is enough when things went well. Only expand on problems.
+
+## Chain Mechanics
+
+Chain mode (`subagent({ chain: [...] })`) runs agents sequentially in a shared temp directory (`{chain_dir}`). Each step:
+1. The framework injects `[Read from:]` and `[Write to:]` directives from the agent's `defaultReads` and `output` frontmatter
+2. The agent reads upstream files, does its work, and writes its deliverable to the `[Write to:]` path using the `write` tool
+3. The agent returns a brief text summary; `{previous}` carries this summary to the next step
+4. Variable substitution: `{task}` = original task, `{previous}` = prior step's brief ack, `{chain_dir}` = artifact dir path
+
+Key behaviors:
+- Data flows through FILES (`scout.md` → `plan.md` → `plan-review.md`), not through `{previous}`
+- `{previous}` contains only a brief summary from the prior step — do NOT rely on it for full context
+- The framework validates that the expected output file was created
+- The chain result includes `📁 Artifacts: /tmp/pi-chain-runs/<id>/` — use this path to read files for branching decisions
+
+## Fallback Strategy
+
+When a subagent call returns no output (silent failure), apply cross-family model fallback. **Do not fall back to doing the work yourself** — always retry with the fallback model first.
+
+1. **First attempt**: Use the agent's default model
+2. **If silent failure or error**: Retry with the fallback model using `model` override
+3. **If the fallback also fails**: Report the double-failure to the user. Still do not do the work yourself.
+
+```js
+// Example: scout fails silently, retry with fallback
+subagent({ agent: "scout", task: "...", model: "anthropic/claude-haiku-4-5" })
+```
+
+| Agent | Primary | Fallback |
+|-------|---------|----------|
+| scout | zai/glm-4.7-flash | anthropic/claude-haiku-4-5 |
+| planner | zai/glm-5.1 | anthropic/claude-opus-4-6 |
+| plan-reviewer | anthropic/claude-opus-4-6 | zai/glm-5.1 |