subagent wokflows

pi/.pi/agent/prompts/implement.md

@@ -1,54 +1,68 @@
 ---
-description: "Adaptive implementation workflow — routes, plans, waits for approval, then implements"
+description: "Implementation workflow — scouts, plans, waits for approval, then implements"
 ---
 
-Use the subagent tool to implement the following task. The workflow is ADAPTIVE — first evaluate, then plan, get user approval, then execute.
+# Task: $@
 
-## Step 1: Route
+Use the subagent tool to implement the task.
 
-Run the "router" agent with this task: $@
+## Step 1: Scout and Plan
 
-The router will return a classification (SMALL, MEDIUM, LARGE, or HUGE).
+Run this chain:
 
-## Step 2: Execute based on classification
+```
+{ chain: [
+  { agent: "scout", task: "Thoroughly investigate the codebase for: $@\n\nFind all relevant files, types, functions, dependencies, and tests. Report file paths with line ranges. Trace how the pieces connect. Flag anything surprising or risky that an implementer needs to know." },
+  { agent: "planner", task: "Create a detailed implementation plan for: $@\n\nScout context:\n\n{previous}\n\nBe precise: every step must name exact files, functions, and line ranges. Address edge cases and error handling. Specify which steps can run in parallel." },
+  { agent: "plan-reviewer", task: "Review this plan critically. Verify all file paths, line numbers, and assumptions against the codebase. Check for missing steps, edge cases, and risks.\n\n{previous}" }
+]}
+```
 
-### If SMALL:
-Run a single "coder" agent. No planning or review needed.
-After implementation, present what was done. Done.
+## Step 2: Approval gate
 
-### If MEDIUM:
-Run the "scout" agent, then the "planner" agent as a chain.
+**STOP. Present the plan AND the plan-reviewer verdict to the user. Ask for approval before continuing.**
 
-**STOP. Present the plan to the user and ask for approval before continuing.**
-
-Once approved (user says ok, go, approved, looks good, etc):
-- Run the "coder" agent to implement the plan
-- Run "reviewer-quick" on the result
-- If NEEDS_FIXES, run the "fixer" agent
-
-### If LARGE:
-Run a chain: "scout" → "planner" → "plan-reviewer"
-
-**STOP. Present the plan AND the Opus review to the user. Ask for approval before continuing.**
-
-Once approved:
-- Execute the plan steps using "coder" for sequential steps, or "coder-parallel" with parallel tasks if the plan identified parallelizable steps
-- Run the "reviewer" agent on all changes
-- If NEEDS_FIXES, run the "fixer" agent
+When presenting, highlight: what will change, which files, risks, and the plan-reviewer verdict.
 
 If the user requests changes to the plan, revise and present again before implementing.
 
-### If HUGE:
-Same as LARGE but use "deep-scout" instead of "scout", and prefer parallel execution with "coder-parallel" for independent steps.
+## Step 3: Implement
 
-**STOP after planning. Same approval gate as LARGE.**
+Once approved:
+- Execute the plan steps using "coder" for sequential steps, or "coder-parallel" with parallel tasks if the plan identified parallelizable steps
+- When running coder, always wrap the plan step(s) in the task: "Implement the following plan step(s). Do NOT deviate.\n\n<plan>\n{the approved plan steps}\n</plan>"
+- Run the "reviewer" agent on all changes
+- If NEEDS_FIXES, run the "fixer" agent with the review output
+
+## Step 4: Summary
+
+After the final step, summarize: what was done, what files changed, what was reviewed, and any remaining concerns.
 
 ## Important
 
-- **NEVER skip the approval gate** for MEDIUM, LARGE, or HUGE tasks. Always present the plan and wait.
-- When presenting the plan, format it clearly. Highlight: what will change, which files, risks, and the Opus review verdict (if applicable).
-- If the user says "with changes" or gives feedback, revise the plan and present again.
-- Always pass scout/planner context forward using {previous} in chain mode.
-- For parallel coder tasks, clearly assign each coder to specific files to avoid conflicts.
-- If any step fails, report what happened and stop.
-- After the final step, summarize: what was done, what files changed, what was reviewed, and any remaining concerns.
+- **NEVER skip the approval gate**. Always present the plan and wait.
+- Always pass scout context forward using {previous} in chain mode — this is how the planner and plan-reviewer receive the scout's findings.
+- When running the coder, always include the approved plan verbatim in the task so the coder has full context.
+- For parallel coder tasks, clearly assign each coder to specific files/plan steps to avoid conflicts.
+
+## Agent Failure and Fallback
+
+When a subagent returns empty output or an error (rate limit, credit exhaustion, connection failure):
+
+1. **Retry once** with the same agent and model — transient failures are common.
+2. **If still failing, retry with the cross-family fallback model** using the `model` override parameter:
+
+| Agent | Primary model | Fallback model |
+|-------|--------------|----------------|
+| scout | zai/glm-4.7-flash | anthropic/claude-haiku-4-5 |
+| deep-scout, coder-parallel | zai/glm-4.7 | anthropic/claude-sonnet-4-6 |
+| planner, coder | zai/glm-5.1 | anthropic/claude-opus-4-6 |
+| reviewer-quick, explorer | anthropic/claude-haiku-4-5 | zai/glm-4.7-flash |
+| coder-claude, fixer | anthropic/claude-sonnet-4-6 | zai/glm-5.1 |
+| plan-reviewer, reviewer | anthropic/claude-opus-4-6 | zai/glm-5.1 |
+
+Example: `subagent({ agent: "scout", task: "...", model: "anthropic/claude-haiku-4-5" })`
+
+3. **If the fallback also fails**, do the work yourself (read the relevant files directly and produce the scout/plan/review output inline). Inform the user which agent failed, what error was returned, and what you did instead.
+
+Do NOT silently absorb failures. Always surface them to the user even when working around them.