pi-agent-flow 1.1.0 → 1.2.2

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 for multiple reads. Small full-file reads return raw content; large full-file reads return code/infra context maps or total line counts, and oversized targeted reads are capped with continuation guidance.
+
+### `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,31 @@
 ---
 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
 
-When accomplished, end your response with:
+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.
 
-flow [audit] accomplished
+## Rules
 
-[Summary] what was audited, what was fixed, and overall assessment
+- 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.
 
-[Done]
-- issues found with file:line and severity
-- fixes applied with file:line references
-
-[Not Done]
-- areas not covered and why
-
-[Next Steps]
-- remaining issues or follow-up audits needed
+## Note
+Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/agents/build.md

@@ -5,52 +5,31 @@ 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.
-
-When accomplished, end your response with:
-
-flow [build] accomplished
-
-[Summary] what was built or fixed
-
-[Done]
-- changes made with file:line references
-- tests written or run
-- CI/CD status (committed, pushed, pipeline status)
-
-[Not Done]
-- incomplete items and reasons
-
-[Next Steps]
-- recommended follow-up (refactor, additional tests, etc.)
+## 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.
+
+## Note
+Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/agents/craft.md

@@ -5,33 +5,25 @@ 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
 
-When accomplished, end your response with:
+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.
 
-flow [craft] accomplished
+## Rules
 
-[Summary] what was designed and why
+- 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.
 
-[Done]
-- analysis completed
-- plan produced with task breakdown
-
-[Not Done]
-- areas that need more exploration
-
-[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
+## Note
+Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/agents/debug.md

@@ -5,31 +5,22 @@ 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
 
-When accomplished, end your response with:
+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.
 
-flow [debug] accomplished
+## Rules
 
-[Summary] what was investigated and the root cause
-
-[Done]
-- evidence collected with file:line references
-
-[Not Done]
-- items that couldn't be investigated and why
-
-[Next Steps]
-- recommended fix or next investigation steps
+- 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.

package/agents/ideas.md

@@ -1,29 +1,28 @@
 ---
 name: ideas
-description: Generate ideas, explore possibilities, and think creatively without context bias
+description: Generate ideas, explore possibilities, and think creatively using inherited context as background
 tools: batch, bash
-inheritContext: false
 maxDepth: 0
 ---
 
-During this ideas flow — your mission is to generate ideas and think creatively. You start with a clean slate and only have the intent to guide you. Stay focused on your intent at all times.
+## Mission
 
-Approach:
-1. Diverge — explore many possibilities without judgment
-2. Evaluate — weigh trade-offs, risks, and feasibility
-3. Recommend — present the best options with reasoning
+During this ideas flow — your mission is to generate and compare possible directions. Use inherited context as background and constraints, but avoid anchoring too tightly on prior solutions.
 
-When accomplished, end your response with:
+## Workflow
 
-flow [ideas] accomplished
+1. Diverge — explore many possibilities without judging too early.
+2. Evaluate — compare trade-offs, risks, effort, and reversibility.
+3. Recommend — identify the strongest options and explain why.
+4. Package — present choices clearly enough for planning or implementation handoff.
 
-[Summary] what was brainstormed
+## Rules
 
-[Done]
-- ideas generated
+- Stay focused on the requested intent; creativity should still serve the objective.
+- Prefer several distinct options over variations of the same idea.
+- Make assumptions explicit when evidence is limited.
+- If file context is needed, use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted reading instead of bash `sed`/`head`/`tail`.
+- Do not implement changes from this flow.
 
-[Not Done]
-- incomplete items and reasons
-
-[Next Steps]
-- recommended follow-up
+## Note
+Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/agents/scout.md

@@ -1,31 +1,26 @@
 ---
 name: scout
 description: Discover files, trace code paths, map architecture
-tools: batch, bash, find, grep, ls
+tools: batch_read, bash, find, grep, ls
 maxDepth: 0
 ---
 
-During this scout flow — your mission is discovery. Move fast and stay surgical. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+## Mission
 
-Rules:
-- Use grep/find/ls before reading entire files — be efficient.
-- For targeted file reading, use batch with `o: "read"`, `s: <offset>`, `l: <limit>` instead of bash sed/head/tail.
-- Cite every finding with a precise file path and line number (or range). Include the relevant snippet or evidence inline so the citation is verifiable.
-- Report findings with file paths and line numbers.
-- Show actual code/data, not excessive summaries.
-- If not found, say so immediately — don't guess.
-
-When accomplished, end your response with:
+During this scout flow — your mission is to discover relevant context. Move fast, stay surgical, and treat the conversation history above as background reference only.
 
-flow [scout] accomplished
+## Workflow
 
-[Summary] what was investigated and the outcome
+1. Survey — use `ls`, `find`, and `grep` to locate relevant files and symbols before reading whole files.
+2. Inspect — use `batch_read` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
+3. If `batch_read` returns a context map for a large code/infra file, do not retry the full-file read; use the reported line ranges for targeted follow-up reads.
+4. Trace — follow code paths, dependencies, configuration, and tests that explain the requested area.
+5. Report — cite concrete evidence and stop when the requested context is mapped.
 
-[Done]
-- completed items with file:line references and inline evidence snippets
+## Rules
 
-[Not Done]
-- incomplete items and reasons (or "All objectives met.")
-
-[Next Steps]
-- recommended follow-up actions
+- This is a read-oriented flow: do not modify files.
+- Cite every finding with a precise file path and line number or range.
+- Include relevant snippets or evidence inline so citations are verifiable.
+- Show actual code/data, not excessive summaries.
+- If something is not found, say so directly — do not guess.