subagent wokflows

pi/.pi/agent/prompts/implement-critical.md

@@ -7,33 +7,38 @@ Use the subagent tool to implement with maximum quality. This is for high-risk o
 ## Step 1: Deep scout + Plan + Plan review
 ```
 { chain: [
-  { agent: "deep-scout", task: "Thoroughly investigate all code relevant to: $@" },
-  { agent: "planner", task: "Create a detailed implementation plan for: $@\n\nDeep context:\n\n{previous}" },
+  { agent: "deep-scout", task: "Deep architectural investigation for: $@\n\nTrace all dependency chains, read tests, check types, understand WHY things are structured the way they are. Map subsystems and their boundaries. Your output enables a complex high-risk change." },
+  { agent: "planner", task: "Create a detailed implementation plan for: $@\n\nDeep scout context:\n\n{previous}\n\nBe precise: every step must name exact files, functions, and line ranges. Address edge cases and error handling explicitly. Specify which steps can run in parallel. This is a high-risk change — be thorough." },
   { 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}" }
 ]}
 ```
 
 ## Step 2: APPROVAL GATE
 
-**STOP. Present the plan and the Opus review to the user.**
+**STOP. Present the plan and the plan-reviewer verdict to the user.**
 
 Show clearly:
 - The implementation plan (steps, files, risks)
-- Opus's verdict and any issues found
+- Plan-reviewer's verdict (APPROVED / NEEDS_REVISION / REJECTED) and any issues found
 - Ask: "Approve this plan, or want changes?"
 
 Do NOT proceed until the user explicitly approves.
-If the user requests changes, revise the plan and present again.
+If the user requests changes, revise the plan (re-run planner with the feedback) and present again.
 
 ## Step 3: Implement (only after approval)
-- Use "coder-claude" (Sonnet 4.6) for the implementation steps
-- For multiple independent steps, run them in parallel using separate coder-claude tasks
+- Use "coder-claude" for the implementation steps
+- For each coder run, include the approved plan verbatim: "Implement the following plan step(s). Do NOT deviate.\n\n<plan>\n{the approved plan steps}\n</plan>"
+- For multiple independent steps, run them in parallel using separate coder-claude tasks, each assigned to specific files/plan steps to avoid conflicts
 
 ## Step 4: Opus review
-Run the "reviewer" agent on all changes.
+Run the "reviewer" agent on all changes with this task: "Review all changes made for: $@\n\nCheck for correctness, edge cases, error handling, type safety, and consistency with the approved plan."
 
 ## Step 5: Fix
 If the reviewer says NEEDS_FIXES, run the "fixer" agent with the review output.
 
 ## Step 6: Report
 Summarize everything: what was planned, what was implemented, what was reviewed, what was fixed, and any remaining concerns.
+
+## Failure handling
+
+- **If any subagent fails, retry it once.** If it fails again, stop and inform the user which agent failed, what the error was, and what had been completed so far. Do NOT continue with remaining steps after a second failure.

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.

pi/.pi/agent/prompts/plan.md

@@ -13,3 +13,14 @@ Use the subagent tool with a chain to plan (but NOT implement) the following:
 ```
 
 Present the plan and the review to me. Do NOT proceed to implementation.
+
+## Agent Failure and Fallback
+
+If any agent returns empty output or an error (rate limit, credit exhaustion, connection failure):
+
+1. Retry once with the same agent.
+2. If still failing, retry with the cross-family fallback using the `model` override:
+   - scout (zai/glm-4.7-flash fails) → `model: "anthropic/claude-haiku-4-5"`
+   - planner (zai/glm-5.1 fails) → `model: "anthropic/claude-opus-4-6"`
+   - plan-reviewer (anthropic/claude-opus-4-6 fails) → `model: "zai/glm-5.1"`
+3. If the fallback also fails, do the work yourself and tell me which agent failed and why.