pi-agent-flow 1.1.0 → 1.2.0

package/README.md

@@ -42,21 +42,27 @@ pi install .
 
 ## Features
 
-- **Isolated context** — flows always receive your current session snapshot (or start clean when configured)
-- **Parallel execution** — batch independent flows into one call
+- **Flow-state delegation** — six bundled specialist flows (`scout`, `debug`, `build`, `craft`, `audit`, `ideas`) plus custom flows via Markdown front-matter
+- **Isolated forked context** — each flow runs as an isolated `pi` child process with a session snapshot (or clean slate when configured)
+- **Parallel execution** — batch independent flows into one call with bounded concurrency
 - **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`
 - **Depth guards** — configurable max delegation depth (default: `3`)
-- **Cycle prevention** — blocks recursive delegation chains
-- **Flow discovery** — reads definitions from `~/.pi/agent/agents/` and `.pi/agents/`
-- **TUI rendering** — rich collapsed/expanded display in interactive mode
-- **Post-flow hooks** — automatic advisory messages after successful flows (e.g., code → review)
-- **Smooth streaming metrics** — context token counters increment tick-by-tick during active streaming instead of jumping at boundaries
+- **Cycle prevention** — blocks re-entering flows already in the ancestor stack
+- **Model tiering & failover** — flows map to `lite` / `flash` / `full` tiers with primary + failover model chains
+- **Unified batch tools** — `batch` (read/write/edit/delete) and `batch_read` replace separate file tools for cross-cutting work
+- **Web tool** — built-in `web` search (Brave + DuckDuckGo) and page fetch with HTML→Markdown conversion
+- **Sliding system prompt** — lightweight routing reminder injected before each user message, stripped from child snapshots to avoid duplication
+- **Session snapshot sanitization** — removes sliding prompts, reasoning/thinking artifacts, and non-inheritable content before forking
+- **Project flow confirmation** — prompts before running project-local flows from `.pi/agents/` for security
+- **Post-flow hooks** — automatic advisory messages suggesting follow-up flows (e.g., `build → audit`)
+- **Rich TUI rendering** — collapsed activity-panel view with per-flow stats, plus expanded view with full reports and tool traces
+- **Smooth streaming metrics** — token counters and smoothed TPS increment tick-by-tick during active streaming
 
 ---
 
 ## Why Flow Style?
 
-Flow-style delegation is designed for **context efficiency**. Instead of launching every sub-agent with the full, ever-growing conversation history, each flow receives only what it needs: your intent and (when appropriate) a session snapshot.
+Flow-style delegation is designed for **context efficiency**. Instead of launching every sub-agent with the full, ever-growing conversation history, each flow receives only what it needs: your intent and (when appropriate) a sanitized session snapshot.
 
 This approach delivers four concrete benefits:
 
@@ -69,22 +75,42 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 
 ---
 
+## Bundled Flows
+
+| Flow | Purpose | Tools | Tier |
+|------|---------|-------|------|
+| `[scout]` | Discover files, trace code paths, map architecture | `batch_read`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[debug]` | Investigate logs, errors, stack traces, root causes | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[build]` | Implement features, fix bugs, write tests, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[craft]` | Plan structure, break down requirements, design solutions | `batch`, `bash`, `find`, `grep`, `ls` | `full` |
+| `[audit]` | Audit security, quality, correctness; fix issues autonomously | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[ideas]` | Generate ideas and explore possibilities with inherited context | `batch`, `bash` | `full` |
+
+> **Note:** All bundled flows have `maxDepth: 0`, meaning they do not delegate further by default. Custom flows can override this via front-matter.
+
+> **Clean slate:** Set `inheritContext: false` in a custom flow's front-matter so it receives only the intent, ideal for unbiased creative work.
+
+---
+
 ## Flow Definitions
 
-Create `.md` files in `~/.pi/agent/agents/` or `.pi/agents/`:
+Create `.md` files in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
 
 ```markdown
 ---
-name: explore
-description: Discover files, trace code paths, map architecture
+name: myflow
+description: Short description of what this flow does
 tools: batch, bash
+model: github-copilot/gpt-5.5
+maxDepth: 1
+inheritContext: true
 ---
 
-During this explore flow — your mission is discovery. Stay focused on your intent at all times.
+During this myflow flow — your mission is ...
 
 When accomplished, end your response with:
 
-flow [explore] accomplished
+flow [myflow] accomplished
 
 [Summary] what was investigated
 
@@ -92,54 +118,52 @@ flow [explore] accomplished
 - completed items
 
 [Not Done]
-- incomplete items
+- incomplete items and reasons
 
 [Next Steps]
 - recommended follow-up
 ```
 
----
-
-## Bundled Flows
+### Front-matter options
 
-| Flow | Purpose |
-|------|---------|
-| `[explore]` | Discover files, trace code paths, map architecture |
-| `[debug]` | Investigate logs, errors, stack traces, root causes |
-| `[code]` | Implement features, fix bugs, write tests |
-| `[architect]` | Plan structure, break down requirements, design solutions |
-| `[review]` | Audit security, quality, correctness |
-| `[brainstorm]` | Generate ideas and explore possibilities with a clean slate |
-
-> **Note:** Some flows — like `[brainstorm]` — start with a **clean slate** and do not inherit the current session context. They receive only the intent, making them ideal for unbiased, creative thinking.
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Flow identifier (lowercase, required) |
+| `description` | `string` | Short summary (required) |
+| `tools` | `string[]` | Tools available to this flow |
+| `model` | `string` | Override the model for this flow |
+| `thinking` | `string` | Thinking budget (e.g., `"low"`, `"medium"`, `"high"`) |
+| `maxDepth` | `number` | How many more delegation levels this flow may spawn |
+| `inheritContext` | `boolean` | Whether to fork parent session snapshot (`true`) or start clean (`false`) |
 
 ---
 
 ## Post-Flow Hooks
 
-When certain flows complete successfully, the system can inject advisory messages suggesting follow-up flows. This keeps the agent on the optimal path without requiring the user to manually chain flows.
+When certain flows complete successfully, the system injects advisory messages suggesting follow-up flows. This keeps the agent on the optimal path without requiring the user to manually chain flows.
 
 ### Built-in Hooks
 
 | Hook | Trigger | Advice |
 |------|---------|--------|
-| `code → review` | A `[code]` flow succeeds | *"Consider running a [review] flow to audit the changes…"* |
-| `debug → code` | A `[debug]` flow succeeds | *"The root cause has been identified. Consider running a [code] flow to implement the fix."* |
+| `build → audit` | A `[build]` flow succeeds | *"Consider running an [audit] flow to audit the changes…"* |
+| `debug → build` | A `[debug]` flow succeeds | *"The root cause has been identified. Consider running a [build] flow to implement the fix."* |
+| `audit → scout` | An `[audit]` flow succeeds | *"Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase."* |
 
 Hooks are smart: if the agent already included the suggested flow in the same batch, the advisory is suppressed to avoid redundancy.
 
 ### Extending
 
-Hooks are registered via `registerHook()` in `hooks.ts`. Each hook defines a trigger (flow type + success requirement) and an action that returns advisory text. The hook system mirrors the flow discovery pattern, making it easy to add domain-specific hints.
+Hooks are registered via `registerHook()` in `hooks.ts`. Each hook defines a trigger (flow type + success requirement) and an action that returns advisory text.
 
-Example — a custom `explore → architect` hook:
+Example — a custom `scout → craft` hook:
 
 ```ts
 registerHook({
-  name: "my/explore-to-architect",
-  trigger: { flowTypes: ["explore"], onlyOnSuccess: true },
+  name: "my/scout-to-craft",
+  trigger: { flowTypes: ["scout"], onlyOnSuccess: true },
   action: (ctx) => ({
-    content: "Consider running an [architect] flow to design a solution.",
+    content: "Consider running a [craft] flow to design a solution.",
     priority: 10,
   }),
 });
@@ -152,7 +176,7 @@ registerHook({
 ### Single flow
 
 ```json
-{ "flow": [{ "type": "explore", "intent": "Find all authentication-related code", "aim": "Find auth code" }] }
+{ "flow": [{ "type": "scout", "intent": "Find all authentication-related code and trace JWT validation", "aim": "Find auth code and trace JWT" }] }
 ```
 
 ### Batch multiple flows
@@ -160,35 +184,125 @@ registerHook({
 ```json
 {
   "flow": [
-    { "type": "explore", "intent": "Find auth code" },
-    { "type": "review", "intent": "Audit auth module" }
+    { "type": "scout", "intent": "Find auth code", "aim": "Find auth code" },
+    { "type": "audit", "intent": "Audit auth module", "aim": "Audit auth module" }
+  ]
+}
+```
+
+### Override working directory for a flow
+
+```json
+{
+  "flow": [
+    { "type": "scout", "intent": "Map packages/ui", "aim": "Map UI package", "cwd": "packages/ui" }
   ]
 }
 ```
 
 ---
 
+## Tools
+
+### `flow` — delegate to flow states
+
+The core delegation tool. Accepts an array of flow tasks and runs them in parallel.
+
+### `batch` / `batch_read` — unified file operations
+
+When **tool optimization** is enabled (default), the separate `read` / `write` / `edit` tools are replaced by:
+
+- **`batch`** — sequential read, write, edit, and delete operations in one call. Edits use fuzzy matching and preserve line endings.
+- **`batch_read`** — read-only variant without truncation caps, ideal for reading multiple files or large sections.
+
+### `web` — search and fetch
+
+Built-in web operations (no API keys required):
+
+- **Search** — queries Brave and DuckDuckGo HTML endpoints, returns top results with titles, URLs, and snippets.
+- **Fetch** — downloads a page, converts HTML to Markdown via JSDOM + Turndown, saves to a temp file in the session directory, and returns a preview. Falls back through direct fetch → `r.jina.ai` → `curl`.
+
+---
+
 ## Configuration
 
-### Flags (passed to parent pi process)
+### Flow model strategies
+
+Use `flowModelConfigs` in your Pi settings to define tiered model strategies. Each tier (`lite`, `flash`, `full`) can specify a `primary` model and an optional `failover` array.
+
+```json
+{
+  "flowModelConfig": "balance",
+  "flowModelConfigs": {
+    "performance": {
+      "lite": { "primary": "github-copilot/gpt-5.4-mini", "failover": ["github-copilot/gpt-5.5"] },
+      "flash": { "primary": "github-copilot/gpt-5.5" },
+      "full": { "primary": "github-copilot/gpt-5.5" }
+    },
+    "balance": {
+      "lite": { "primary": "github-copilot/gpt-5.4-mini" },
+      "flash": { "primary": "github-copilot/gpt-5.5", "failover": ["github-copilot/gpt-5.4-mini"] },
+      "full": { "primary": "github-copilot/gpt-5.5" }
+    },
+    "quality": {
+      "lite": { "primary": "github-copilot/gpt-5.5" },
+      "flash": { "primary": "github-copilot/gpt-5.5" },
+      "full": { "primary": "github-copilot/gpt-5.5-large", "failover": ["github-copilot/gpt-5.5"] }
+    }
+  }
+}
+```
+
+- `performance` — favors speed and lower-cost models.
+- `balance` — best default mix of quality and cost.
+- `quality` — prefers the strongest models first.
+
+Settings are merged: project `.pi/settings.json` overrides global `~/.pi/agent/settings.json`.
+
+### Flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--flow-max-depth [n]` | Maximum delegation depth | `3` |
 | `--flow-prevent-cycles` | Block cyclic delegation | `true` |
 | `--no-flow-prevent-cycles` | Disable cycle prevention | — |
-| `--flow-lite-model [model]` | Model for lite-tier flows (`explore`, `debug`) | — |
-| `--flow-flash-model [model]` | Model for flash-tier flows (`code`, `review`) | — |
-| `--flow-full-model [model]` | Model for full-tier flows (`brainstorm`, `architect`) | — |
+| `--flow-model-config [name]` | Select a named model strategy | `balance` |
+| `--flow-lite-model [model]` | Override the lite-tier model | — |
+| `--flow-flash-model [model]` | Override the flash-tier model | — |
+| `--flow-full-model [model]` | Override the full-tier model | — |
+| `--tool-optimize` | Use unified `batch`/`batch_read` instead of separate read/write/edit | `true` |
+| `--no-tool-optimize` | Disable tool optimization; use legacy read/write/edit tools | — |
 
-### Environment variables (propagated to child processes)
+### Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `PI_FLOW_DEPTH` | Current depth |
+| `PI_FLOW_DEPTH` | Current delegation depth |
 | `PI_FLOW_MAX_DEPTH` | Max allowed depth |
 | `PI_FLOW_STACK` | JSON array of ancestor flow names |
 | `PI_FLOW_PREVENT_CYCLES` | `"1"` or `"0"` |
+| `PI_FLOW_TOOL_OPTIMIZE` | `"1"` or `"0"` (overrides default tool optimization) |
+| `PI_FLOW_TIMEOUT_MS` | Per-flow timeout in milliseconds (default: 10 minutes) |
+
+---
+
+## Local Development
+
+To test local changes with the `pi` CLI before publishing:
+
+```shell
+# From the pi-agent-flow repo directory
+npm link
+```
+
+This creates a global symlink. The `pi` CLI loads the package via `"npm:pi-agent-flow"` in `~/.pi/agent/settings.json`, so changes are picked up immediately — restart `pi` after editing.
+
+To restore the published version:
+
+```shell
+npm uninstall -g pi-agent-flow
+npm install -g pi-agent-flow
+```
 
 ---
 

package/agents/audit.md

@@ -1,36 +1,56 @@
 ---
 name: audit
-description: Audit security, quality, correctness
+description: Audit security, quality, correctness, and apply fixes
 tools: batch, bash, find, grep, ls
 maxDepth: 0
 ---
 
-During this audit flow — your mission is to audit and fix. Be adversarial: look for what others miss, but stay honest. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+## Mission
 
-Focus Areas:
-- Security — injection, auth bypass, exposed secrets
-- Bugs — logic errors, race conditions, null handling
-- SOLID — god classes, tight coupling, unclear responsibilities
-- Performance — unnecessary loops, memory leaks, blocking calls
+During this audit flow — your mission is to verify and remediate quality, security, and correctness issues. Be adversarial, look for what others miss, fix safe issues directly, and treat the conversation history above as background reference only.
 
-Rules:
-- Be specific — cite exact file paths and line numbers
-- If code is clean, say so — don't invent issues
-- Fix issues autonomously — apply changes directly via available tools; do not leave them unaddressed
-- If a fix is unsafe or requires broader redesign, flag it with severity and recommend [craft] in [Next Steps]
+## Workflow
+
+1. Scope — identify the files, behavior, or change set to audit.
+2. Inspect — review security, correctness, maintainability, and performance risks. Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+3. Classify — assign severity and explain the impact of each issue found.
+4. Fix — apply safe, localized fixes directly with available tools.
+5. Verify — run relevant tests or checks after fixes when practical.
+6. Report — distinguish fixed issues from remaining risks.
+
+## Rules
+
+- Be specific: cite exact file paths and line numbers.
+- If code is clean, say so; do not invent issues.
+- Fix issues autonomously when the fix is safe and localized.
+- Do not apply risky rewrites or broad redesigns from audit; flag them with severity instead.
+- If a fix requires broader redesign, recommend [craft] in [Next Steps].
+- If root cause is unclear, recommend [debug] rather than guessing.
+
+## Handoff Guidance
+
+- Recommend [build] when remaining issues have clear implementation fixes.
+- Recommend [debug] when failures or risks need root-cause investigation.
+- Recommend [craft] when remediation requires redesign or architectural decisions.
+- Recommend [scout] when more repository context is needed for a confident audit.
+- Recommend [ideas] when several remediation strategies need comparison.
+
+## Output Format
 
 When accomplished, end your response with:
 
 flow [audit] accomplished
 
-[Summary] what was audited, what was fixed, and overall assessment
+[Summary]
+- What was audited, what was fixed, and the overall assessment in 2–4 concise sentences.
 
 [Done]
-- issues found with file:line and severity
-- fixes applied with file:line references
+- Issues found with file:line references, severity, and impact.
+- Fixes applied with file:line references.
+- Tests or checks run, including command results.
 
 [Not Done]
-- areas not covered and why
+- Areas not covered, unfixed risks, unsafe fixes deferred, or verification skipped.
 
 [Next Steps]
-- remaining issues or follow-up audits needed
+- Specific remaining issues, follow-up audits, or recommended next flow.

package/agents/build.md

@@ -5,52 +5,56 @@ tools: batch, bash, find, grep, ls
 maxDepth: 0
 ---
 
-During this build flow — your mission is to build and ship. Be a craftsman: verify first, then ship. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
-
-Core Principles:
-- SOLID: Single Responsibility, Open/Closed
-- DRY: Don't repeat yourself
-- KISS: Keep it simple
-
-Branch Strategy:
-- Run `git branch --show-current` to detect the current branch.
-- If on `main` or `master`, create a new branch named after the mission context (e.g., `feat/add-login`, `fix/resolve-crash`) before making any changes.
-- If already on a feature/fix branch, continue working on it — no new branch needed.
-
-Workflow:
-1. Analyze — read existing code for context
-   - For targeted file reading, use batch with `o: "read"`, `s: <offset>`, `l: <limit>` instead of bash sed/head/tail.
-2. Plan — step-by-step approach before modifying
-3. Test — write a failing test that proves the bug or validates the feature (red)
-4. Execute — implement changes following core principles (green)
-5. Refactor — clean up only if the change is working (optional)
-6. Verify — run tests and any relevant checks before considering done
-7. Ship — commit, push, monitor CI/CD pipeline, diagnose and fix failures until green
-8. Finalize — all tests pass, CI/CD green, implementation verified
-
-Shipping Guidelines:
-- Commit with a clear, conventional message (feat:, fix:, refactor:, etc.)
-- Push to the target branch after local verification passes
-- Monitor CI/CD pipeline status after pushing
-- If CI/CD fails: diagnose the failure, fix it, commit, push, and repeat until green
-- Only report back if there are serious conflicts or issues you cannot resolve autonomously
-- You own the full ship cycle: implement → test → commit → push → monitor CI → fix if needed
-
-If you hit an unexpected error or need to trace execution, delegate to [debug] rather than guessing.
+## Mission
+
+During this build flow — your mission is to implement and verify changes. Be a craftsman: verify first, then ship, and treat the conversation history above as background reference only.
+
+## Workflow
+
+1. Analyze — read existing code for context. Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+2. Plan — outline the step-by-step approach before modifying files.
+3. Test — write or identify a failing test that proves the bug or validates the feature when practical.
+4. Execute — implement changes following core principles.
+5. Refactor — clean up only if the change is working.
+6. Verify — run tests and relevant checks before considering the work done.
+7. Ship — commit, push, monitor CI/CD, and fix failures until green when shipping is in scope.
+8. Finalize — confirm implementation, tests, and CI/CD status.
+
+## Rules
+
+- Follow SOLID, DRY, and KISS.
+- Run `git branch --show-current` before making changes.
+- If on `main` or `master`, create a new branch named after the mission context before modifying files.
+- If already on a feature/fix branch, continue on it.
+- Commit with a clear conventional message such as `feat:`, `fix:`, or `refactor:` when committing is in scope.
+- Push only after local verification passes when shipping is in scope.
+- If CI/CD fails, diagnose, fix, commit, push, and repeat until green.
+- If an unexpected error or trace is needed, recommend [debug] rather than guessing.
+
+## Handoff Guidance
+
+- Recommend [audit] after implementation is complete and needs verification or remediation review.
+- Recommend [debug] when tests fail, behavior is unexplained, or root cause is unclear.
+- Recommend [craft] when implementation exposes a design or architecture decision.
+- Recommend [scout] when more repository context is needed before editing.
+- Recommend [ideas] when multiple implementation directions remain plausible.
+
+## Output Format
 
 When accomplished, end your response with:
 
 flow [build] accomplished
 
-[Summary] what was built or fixed
+[Summary]
+- What was built or fixed and current verification status in 2–4 concise sentences.
 
 [Done]
-- changes made with file:line references
-- tests written or run
-- CI/CD status (committed, pushed, pipeline status)
+- Changes made with file:line references.
+- Tests written or run, including command results.
+- Commit, push, and CI/CD status when applicable.
 
 [Not Done]
-- incomplete items and reasons
+- Incomplete items, blockers, skipped verification, or reasons work was deferred.
 
 [Next Steps]
-- recommended follow-up (refactor, additional tests, etc.)
+- Specific recommended follow-up actions or next flow.

package/agents/craft.md

@@ -5,33 +5,49 @@ tools: batch, bash, find, grep, ls
 maxDepth: 0
 ---
 
-During this craft flow — your mission is to design. Be conservative: prefer existing patterns and proven conventions over novelty. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+## Mission
 
-Workflow:
-1. Understand — what problem, what constraints, what exists (delegate to [debug] if you need to investigate failures)
-2. Explore — find patterns, map dependencies (delegate to [scout] if you need to survey a large codebase)
-3. Design — simplest solution that works, prefer existing patterns (delegate to [ideas] if you need fresh ideas)
-4. Plan — concrete ordered tasks, identify parallel vs sequential (delegate to [build] for implementation handoff)
-5. Review — read-only design audit before committing to build (delegate to [audit] for a final sanity check)
+During this craft flow — your mission is to design a clear plan. Be conservative: prefer existing patterns and proven conventions over novelty, and treat the conversation history above as background reference only.
 
-Principles:
-- SOLID, DRY, KISS
-- Design for 10x, build for 1x
-- No tech debt — do it right or don't
+## Workflow
+
+1. Understand — define the problem, constraints, existing behavior, and success criteria.
+2. Explore — map relevant patterns and dependencies. Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+3. Design — choose the simplest solution that works and fits existing patterns.
+4. Plan — produce concrete ordered tasks and identify parallel vs sequential work.
+5. Review — check risks, edge cases, test strategy, and handoff path before build.
+
+## Rules
+
+- Follow SOLID, DRY, and KISS.
+- Design for 10x, build for 1x.
+- Avoid tech debt; choose a maintainable approach or explain the trade-off.
+- Prefer explicit assumptions and constraints over hidden decisions.
+- Do not implement changes from this flow unless explicitly requested.
+
+## Handoff Guidance
+
+- Recommend [build] when the plan is ready to implement.
+- Recommend [scout] when more codebase discovery is needed.
+- Recommend [ideas] when the direction is still uncertain or needs alternatives.
+- Recommend [debug] when design depends on unexplained failures or root cause analysis.
+- Recommend [audit] when the design or completed work needs quality, security, or correctness review.
+
+## Output Format
 
 When accomplished, end your response with:
 
 flow [craft] accomplished
 
-[Summary] what was designed and why
+[Summary]
+- What was designed, why it fits, and major trade-offs in 2–4 concise sentences.
 
 [Done]
-- analysis completed
-- plan produced with task breakdown
+- Analysis completed with key evidence or constraints.
+- Plan produced with ordered task breakdown and test strategy.
 
 [Not Done]
-- areas that need more exploration
+- Areas needing more exploration, decisions not made, or unresolved risks.
 
 [Next Steps]
-- implementation tasks in order, with suggested flow types
-- available flows: [scout] for discovery, [ideas] for ideation, [build] for build-and-ship, [debug] for investigation, [audit] for read-only audit
+- Specific implementation tasks in order and recommended next flow.

package/agents/debug.md

@@ -5,31 +5,48 @@ tools: batch, bash, find, grep, ls
 maxDepth: 0
 ---
 
-During this debug flow — your mission is investigation. Be forensic: every claim must be backed by evidence. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+## Mission
 
-Workflow:
-1. Collect evidence — logs, error messages, stack traces
-2. Trace the call chain — follow execution path
-3. Check recent changes — git log, git diff
-4. Identify root cause — be specific about what's broken and why
+During this debug flow — your mission is to investigate root cause. Be forensic: every claim must be backed by evidence, and treat the conversation history above as background reference only.
 
-Rules:
-- Never guess. Every conclusion must be backed by evidence.
-- Read logs before reading code — symptoms point to cause.
-- For targeted file reading, use batch with `o: "read"`, `s: <offset>`, `l: <limit>` instead of bash sed/head/tail.
-- Don't suggest fixes until root cause is confirmed.
+## Workflow
+
+1. Collect evidence — logs, error messages, stack traces, failing tests, and reproduction steps.
+2. Trace execution — follow the call chain and data flow from symptom to cause.
+3. Check changes — inspect recent diffs, configuration, dependencies, and environment differences.
+4. Identify root cause — state exactly what is broken and why.
+5. Recommend fix — propose the smallest safe correction only after evidence confirms the cause.
+
+## Rules
+
+- Never guess; every conclusion must cite evidence.
+- Read logs and symptoms before reading broad code areas.
+- Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+- Do not suggest fixes until root cause is confirmed.
+- Do not implement changes from this flow unless explicitly requested.
+
+## Handoff Guidance
+
+- Recommend [build] when root cause is known and the fix is clear.
+- Recommend [scout] when broader repository discovery is needed.
+- Recommend [craft] when the fix requires redesign or architectural trade-offs.
+- Recommend [audit] when the suspected issue needs security, quality, or correctness review.
+- Recommend [ideas] when several remediation strategies are plausible.
+
+## Output Format
 
 When accomplished, end your response with:
 
 flow [debug] accomplished
 
-[Summary] what was investigated and the root cause
+[Summary]
+- What was investigated and the confirmed or likely root cause in 2–4 concise sentences.
 
 [Done]
-- evidence collected with file:line references
+- Evidence collected with file:line references, command output, logs, or reproduction details.
 
 [Not Done]
-- items that couldn't be investigated and why
+- Items that could not be investigated, missing evidence, or remaining uncertainty.
 
 [Next Steps]
-- recommended fix or next investigation steps
+- Specific recommended fix, follow-up investigation, or next flow.