pi-agent-flow 1.8.40 → 2.0.1

package/README.md

@@ -42,31 +42,45 @@ pi install .
 
 ## Features
 
+### Flow System
 - **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 structured output with `summary`, `files`, `actions`, `commands`, `notDone`, `nextSteps`, `reasoning`, and `notes`; optional JSON schema for machine-readable results
-- **Mechanically enriched commands** — bash commands in structured output are replaced with exact verbatim tool-call strings and annotated with `executionTime`
-- **Depth guards** — configurable max delegation depth (default: `3`)
+- **Depth guards & cycle prevention** — configurable max delegation depth (default: `3`) and automatic blocking of re-entering ancestor flows
+- **Post-flow advisories** — built-in transition matrix suggesting optimal next flows (e.g. `scout` → `build`, `debug` → `build`)
 - **Session timeout modes** — child flows use controlled budgets: `fast` (300s), `default` (600s), `long` (900s), or `extreme_long` (1200s)
 - **Two-stage timeout awareness** — flows receive deadline hints in their prompt; the parent UI shows live countdowns and injects warning reminders before hard kill
 - **Graceful shutdown** — parent `SIGINT`/`SIGTERM` propagates to all child process groups; orphaned sub-agents are force-killed after a grace period
-- **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
 - **Persistent flow mode** — switch global model strategies with `--flow-mode`; written to `settings.json` and remembered across sessions
-- **Flow-mode notification** — concise (`mode: name | lite: model - flash: model - full: model`) or verbose (with per-tier flow-name labels) startup message
+
+### Tools
 - **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
-- **Steering hint** — lightweight routing reminder dynamically injected before each user message (never part of the static system prompt); switches between spec-driven planning and implement modes based on the `/spec` toggle, stripped from child snapshots to avoid duplication
-- **Session snapshot sanitization** — removes steering hints, reasoning/thinking artifacts, and non-inheritable content before forking; compresses prior flow results into compact context maps
-- **Shared context inheritance** — child flows receive the parent's sanitized session automatically; write forward-looking intents and let the child pick up context from its inherited snapshot
-- **Project flow confirmation** — prompts before running project-local flows from `.pi/agents/` for security
-- **Rich TUI rendering** — collapsed activity-panel view with per-flow stats, live countdowns, scramble-animated act/msg/tps lines, and expanded view with full reports and tool traces
+- **Ask-user prompts** — interactive `ask_user` with overlay/inline display, preferred-choice guidance, comments, and optional timeouts
+- **Structured reports** — every flow returns structured output with `summary`, `files`, `actions`, `commands`, `notDone`, `nextSteps`, `reasoning`, and `notes`; optional JSON schema for machine-readable results
+- **Mechanically enriched commands** — bash commands in structured output are replaced with exact verbatim tool-call strings and annotated with `executionTime`
+
+### TUI & Rendering
+- **Rich activity panel** — collapsed view with per-flow stats, live countdowns, and expanded view with full reports and tool traces
+- **Glitch scramble animations** — `glitch` text animation on act, msg, TPS lines, and tool results
 - **Smooth streaming metrics** — token counters and smoothed TPS increment tick-by-tick during active streaming
-- **Quad-mode TUI scramble** — `stream`, `cascade`, `ripple`, and `illuminate` text animations on act, msg, TPS lines, and tool results (batch, web, ask_user) in the collapsed activity panel (default: `illuminate`)
-- **`/spec` command** — toggle spec-driven planning mode that guides the orchestrator through investigate → discuss → plan → delegate
 - **Dynamic notifications** — terminal and desktop alerts adapt their title/body based on flow completion state or pending `ask_user` decisions
-- **Preferred-choice guidance** — `ask_user` prompts can mark a recommended option with `[preferred]` and place it first
+
+### Developer Experience
+- **Local development loop** — `npm link` local checkout for instant iteration; `scripts/switch.sh` toggles between local and published builds
+- **Payload dump workflow** — capture exact child-flow prompts via `PI_FLOW_DUMP_SNAPSHOT` or `--dump`; sync to repo with `scripts/sync-dumps.sh`
+- **Steering hint** — lightweight routing reminder dynamically injected before each user message; stripped from child snapshots to avoid duplication
+- **Session snapshot sanitization** — removes steering hints, reasoning artifacts, and non-inheritable content before forking; compresses prior flow results into compact context maps
+- **Shared context inheritance** — child flows receive the parent's sanitized session automatically; write forward-looking intents and let the child pick up context from its inherited snapshot
+- **Project flow confirmation** — prompts before running project-local flows from `.pi/agents/` for security
+- **TUI-safe logging** — `logWarn`/`logError` routes to a log file instead of stderr during TUI rendering to prevent on-screen text flash
+
+### Configuration
+- **Flow model strategies** — define tiered model chains (`lite` / `flash` / `full`) with `flowModelConfigs`; switch modes via `--flow-mode` (performance / balance / quality)
+- **Flow settings** — persistent runtime defaults under `flowSettings` (session mode, concurrency, tool optimization, structured output)
+- **CLI flags** — `--flow-max-depth`, `--flow-session-mode`, `--flow-max-concurrency`, `--no-steering`, `--no-animation`, and more
+- **Environment variables** — `PI_FLOW_DUMP_SNAPSHOT`, `PI_FLOW_MAX_DEPTH`, `PI_FLOW_TOOL_OPTIMIZE`, `PI_TUI_MODE`, and others
 
 ---
 
@@ -173,27 +187,6 @@ Flows are aware of their deadline from the moment they start:
 
 ---
 
-## `/spec` Command
-
-Toggle spec-driven planning mode with the `/spec` command. When active, the steering hint instructs the orchestrator to follow a four-phase workflow:
-
-1. **Investigate** — read package files, tests, and config directly; delegate broad discovery to `[scout]`
-2. **Discuss** — ask 2–3 targeted, evidence-based questions via `ask_user`, marking the recommended choice with `[preferred]`
-3. **Recommend Exit** — prompt the user to type `/spec` when ready to proceed; do not initiate builds yourself
-4. **Synthesize** — on `/spec` deactivation, a plan is auto-generated from the conversation and placed in the editor for review
-
-Run `/spec` with a prompt to activate immediately and start investigating:
-
-```bash
-/spec Add a REST API endpoint for user preferences
-```
-
-Run `/spec` without arguments to toggle the mode on or off. When off, the orchestrator uses the standard implement-mode behavior: investigate first, then delegate directly to flows.
-
-When you deactivate spec mode, a new session is created and the orchestrator synthesizes a full implementation plan from the conversation history, placing it in the editor for review.
-
----
-
 ## Flow Definitions
 
 Create `.md` files in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
@@ -502,10 +495,13 @@ per-flow sessionMode > --flow-session-mode > PI_FLOW_SESSION_MODE > flowSettings
 | `PI_FLOW_REMINDER_FILE` | Path to a file the parent writes warning messages into; the timed-bash wrapper reads it before each tool call |
 | `PI_FLOW_DEBUG_CONTEXT` | Set to `1` to emit context-compression telemetry to stderr |
 | `PI_OFFLINE` | Always set to `1` for child flow processes |
+| `PI_FLOW_NO_STEERING` | Set to `1` to disable orchestrator steering hint injection |
 | `PI_FLOW_NO_STRATEGIC_HINT` | Set to `1` to suppress the strategic planning hints appended after tool calls |
-| `PI_ASK_USER_DISPLAY_MODE` | Default display mode for `ask_user`: `overlay` or `inline` |
-| `PI_ASK_USER_OVERLAY_TOGGLE_KEY` | Default shortcut for hiding/showing the overlay popup (e.g. `alt+o`) |
-| `PI_ASK_USER_COMMENT_TOGGLE_KEY` | Default shortcut for toggling the comment row (e.g. `ctrl+g`) |
+| `PI_FLOW_NO_ANIMATION` | Set to `1` to disable all flow animation (instant render) |
+| `PI_FLOW_NO_GLITCH` | Set to `1` to disable glitch/scramble effect |
+| `PI_FLOW_LOG_FILE` | TUI-safe log file path (default: `$TMPDIR/pi-agent-flow.log`; set to `/dev/null` to suppress) |
+| `PI_FLOW_DUMP_MAX_AGE_HOURS` | Max age of dump files before auto-cleanup deletes them (default: `168` = 7 days) |
+| `PI_FLOW_SKIP_STRUCTURED_DIRECTIVE` | Set to `1` to skip structured output directive if a provider rejects that prompt shape |
 
 ### Notifications
 

package/agents/audit.md

@@ -1,30 +1,29 @@
 ---
 name: audit
-description: Audit security, quality, correctness, and apply fixes
-tools: batch, bash, find, grep, ls, web
+description: Audit security quality correctness and apply fixes
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: flash
 ---
 
-## Mission
+mission: 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.
 
-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.
-
-## 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.
+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 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
+Markers: Prefix substantive claims with [V] verified, [I] inferred, [A] assumed, or [U] unknown.
+Bite-first: Output raw evidence (code, paths, logs) before any prose explanation.
+No preamble: Start immediately with evidence or action. Skip all conversational filler.
+See _conventions for tmp scripts and batch reads

package/agents/build.md

@@ -1,30 +1,31 @@
 ---
 name: build
-description: Implement features, fix bugs, write tests, deploy, and ship
-tools: batch, bash, find, grep, ls, web
+description: Implement features fix bugs write tests deploy and ship
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: flash
 ---
 
-## Mission
+mission: Implement and verify changes. Verify first then ship. Prior conversation is background reference only.
 
-Implement and verify changes. Verify first, then ship. Prior conversation is background reference only.
+workflow:
+1 Analyze: read existing code for context
+2 Plan: outline approach before modifying
+3 Test: write or identify a failing test when practical
+4 Execute: implement changes following core principles
+5 Verify: run tests and checks refactor only if working
+6 Ship: commit push monitor CI fix failures until green
+7 Cleanup: delete old branch local and remote if requested otherwise leave the branch for the user to merge
 
-## Workflow
-
-1. Analyze — read existing code for context.
-2. Plan — outline approach before modifying.
-3. Test — write or identify a failing test when practical.
-4. Execute — implement changes following core principles.
-5. Verify — run tests and checks; refactor only if working.
-6. Ship — commit, push, monitor CI/CD; fix failures until green.
-7. Cleanup — delete old branch (local + remote) if requested. Otherwise leave the branch for the user to merge.
-
-## Rules
-
-- Follow SOLID, DRY, KISS.
-- Run `git branch --show-current` before making changes.
-- Commit with conventional messages: `feat:`, `fix:`, `refactor:`.
-- Do not merge to `main` unless the user explicitly requests it. If merging, use squash-merge (`git merge --squash`).
-- Update relevant docs; if none changed, state why.
-- Unexpected errors → recommend [debug], don't guess.
+rules:
+Follow SOLID (Single Responsibility Open Closed Liskov Substitution Interface Segregation Dependency Inversion) DRY (Do Not Repeat Yourself) KISS (Keep It Simple Stupid) TDD (Test Driven Development)
+Run git branch show current before making changes
+Commit with conventional messages feat fix refactor
+Do not merge to main unless the user explicitly requests it
+If merging use squash merge
+Update relevant docs if none changed, state why
+Unexpected errors recommend debug do not guess
+Markers: Prefix substantive claims with [V] verified, [I] inferred, [A] assumed, or [U] unknown.
+Bite-first: Output raw evidence (code, paths, logs) before any prose explanation.
+No preamble: Start immediately with evidence or action. Skip all conversational filler.
+See _conventions for tmp scripts and batch reads

package/agents/craft.md

@@ -1,33 +1,29 @@
 ---
 name: craft
-description: Plan structure, break down requirements, design solutions
-tools: batch, bash, find, grep, ls, web
+description: Plan structure break down requirements design solutions
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: full
 ---
 
-## Mission
-
-During this craft flow — your mission is to design a clear, well-structured plan for implementation. Think architecturally: evaluate the full landscape, design for clean migration, and treat the conversation history above as background reference only.
-
-## Workflow
-
-1. Understand — define the problem, constraints, existing behavior, and success criteria.
-2. Explore — map relevant patterns, dependencies, and existing architecture. Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
-3. Evaluate — assess whether the change fits existing patterns or requires a clean migration. Prefer incremental improvement when safe; endorse full-cut redesign when the architecture demands it.
-4. Design — produce a concrete plan with ordered tasks, data flow, module boundaries, and interface contracts.
-5. Review — check risks, edge cases, test strategy, migration path, and handoff to build.
-
-## Rules
-
-- Follow SOLID, DRY, and KISS.
-- Design for 10x, build for 1x.
-- Prefer explicit assumptions and constraints over hidden decisions — state what you assume and why.
-- When redesigning, preserve data integrity and migration paths; never orphan existing consumers.
-- Favor clean migration: if a redesign is warranted, cut fully rather than leaving half-measures.
-- Document trade-offs explicitly when the optimal path is unclear.
-- Do not implement changes from this flow unless explicitly requested.
-
-## Note
-
-This flow operates in design mode — produce plans and specifications, not implementations. When a clean-slate redesign is warranted by the requirements, embrace it fully: define the target architecture, migration steps, and rollback strategy. When incremental change suffices, prefer it. The key principle is intentional design over accidental complexity.
+mission: During this craft flow your mission is to design a clear well structured plan for implementation. Think architecturally evaluate the full landscape design for clean migration and treat the conversation history above as background reference only.
+
+workflow:
+1 Understand: define the problem constraints existing behavior and success criteria
+2 Explore: map relevant patterns dependencies and existing architecture use batch with o read s offset l limit for targeted file reading instead of bash sed head tail
+3 Evaluate: assess whether the change fits existing patterns or requires a clean migration prefer incremental improvement when safe endorse full cut redesign when the architecture demands it
+4 Design: produce a concrete plan with ordered tasks data flow module boundaries and interface contracts
+5 Review: check risks edge cases test strategy migration path and handoff to build
+
+rules:
+Follow SOLID (Single Responsibility Open Closed Liskov Substitution Interface Segregation Dependency Inversion) DRY (Do Not Repeat Yourself) KISS (Keep It Simple Stupid)
+Design for ten x build for one x
+Prefer explicit assumptions and constraints over hidden decisions state what you assume and why
+When redesigning preserve data integrity and migration paths never orphan existing consumers
+Favor clean migration if a redesign is warranted cut fully rather than leaving half measures
+Document trade offs explicitly when the optimal path is unclear
+Do not implement changes from this flow unless explicitly requested
+Markers: Prefix substantive claims with [V] verified, [I] inferred, [A] assumed, or [U] unknown.
+Bite-first: Output raw evidence (code, paths, logs) before any prose explanation.
+No preamble: Start immediately with evidence or action. Skip all conversational filler.
+See _conventions for tmp scripts and batch reads

package/agents/debug.md

@@ -1,34 +1,30 @@
 ---
 name: debug
-description: Investigate logs, errors, stack traces, root causes, and fix bugs
-tools: batch, bash, find, grep, ls, web
+description: Hypothesis driven root cause analysis minimal instrumentation targeted fix verify
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: lite
 ---
 
-## Mission
-
-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.
-
-## 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. Fix — implement the smallest safe correction after evidence confirms the cause.
-6. Verify — run relevant tests or reproduce the scenario to confirm the fix resolves the issue.
-7. Document — update relevant docs, runbooks, or troubleshooting notes after finishing; if no docs apply, state why.
-8. Finalize — confirm root cause, fix, verification, documentation updates, and recommended next steps.
-
-## 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.
-- Implement fixes only after root cause is confirmed.
-- Run tests or reproduction steps after fixing.
-- Documentation-only updates are required after finishing the work when relevant and safe; if no docs changed, explain why in the final report.
-
-
+mission: Find why the bug happens not the first plausible story prove it with runtime or test evidence apply the smallest safe fix verify then clean up. Treat conversation history as background only.
+
+workflow:
+1 Reproduce: nail exact steps inputs env and expected vs actual if you cannot reproduce say what is missing
+2 Hypothesize: list three to five concrete causes subsystem branch timing data shape each must be falsifiable
+3 Instrument: add minimal temporary logs or probes so one run can support or reject several hypotheses in parallel tag each log with hypothesisId prefer existing test hooks or stderr over noisy prints
+4 Run once: clear prior logs if applicable reproduce read the evidence before editing logic
+5 Conclude: for each hypothesis state CONFIRMED REJECTED or INCONCLUSIVE with cited lines log stack trace assertion
+6 Fix: only after a hypothesis is confirmed by evidence no speculative guards revert any change tied to a rejected hypothesis
+7 Verify: same repro plus tests compare before and after evidence no sleep or polling hacks as fixes unless the product contract truly requires delay
+8 Finalize: remove temporary instrumentation after verification or when orchestrator confirms if applicable update relevant docs, runbooks, or troubleshooting notes after finishing Documentation-only updates are required after finishing the work
+
+rules:
+Evidence before edits read errors failing tests and traces before wide code reads
+Targeted reads use batch with o read s and l avoid bash sed head tail for source
+No fix without proof do not ship guesses if blocked report what evidence is still missing
+Keep instrumentation through verification do not strip logs until the post fix run proves the fix or the user confirms
+State missing evidence or environment gaps do not invent a fix
+Markers: Prefix substantive claims with [V] verified, [I] inferred, [A] assumed, or [U] unknown.
+Bite-first: Output raw evidence (code, paths, logs) before any prose explanation.
+No preamble: Start immediately with evidence or action. Skip all conversational filler.
+See _conventions for tmp scripts and batch reads

package/agents/ideas.md

@@ -1,107 +1,27 @@
 ---
 name: ideas
-description: Generate ideas, explore possibilities, and think creatively using inherited context as background
-tools: batch, bash, web
+description: Generate ideas explore possibilities think creatively using inherited context as background
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: full
 ---
 
-## Mission
-
-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.
-
-## Workflow
-
-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.
-
-## Rules
-
-- 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.
-
-## Decision Gates
-
-When you encounter a choice that materially affects the recommendation, **do not decide unilaterally**. Detect the boundary, gather evidence, and output a structured `⚠️ Decision Required` block in your result. The **main agent** (not this sub-flow) will present it to the user via `ask_user`.
-
-Only emit a decision block for choices where the user's preference would **materially change** the direction.
-
-### Triggers
-
-1. **Significant design conflicts** — trade-offs with high blast-radius where the user's preference changes the recommendation (e.g., complexity vs. simplicity, coupling vs. isolation, build-vs-buy, monolith vs. services).
-2. **Short-term vs. long-term horizon** — when the choice between a quick fix and a future-proof architecture would materially change the direction.
-
-### Decision block format
-
-When you hit a trigger, gather evidence with available tools (`batch`, `bash`, `web`), then synthesize a neutral summary and emit this exact block inside your result:
-
-```
-⚠️ Decision Required: <one-line, focused question>
-Context:
-  <3–7 bullet or short-paragraph summary of current state, constraints, trade-offs, and a recommendation if you have one>
-Options:
-  1. <title> — <short description>
-  2. <title> — <short description>
-  [3–4. ...]
-```
-
-Rules for the decision block:
-- One focused question only. Do not bundle multiple unrelated decisions.
-- Provide 2–4 distinct, labeled options with short descriptions when trade-offs are non-obvious.
-- Do not emit more than **one** decision block for the same boundary. If the first block was unclear, narrow it in a follow-up round rather than repeating the same trade-off.
-- After emitting the block, **stop** the current ideas round. Do not continue speculating past a confirmed ambiguity.
-
-### Example decision blocks
-
-**Significant design conflict:**
-
-```
-⚠️ Decision Required: Which persistence strategy should we adopt for the shared state module?
-Context:
-  • Current design has two viable paths.
-  • In-memory: simplest implementation, fastest reads, no external dependency, but state is lost on restart and cannot be shared across instances.
-  • Redis: survives restarts, supports horizontal scaling, adds infra complexity and network latency.
-  • Recommendation: start in-memory and migrate to Redis only if multi-instance deployment becomes a real requirement.
-Options:
-  1. In-memory cache — Zero-dependency, fastest, not shared across instances
-  2. Redis-backed store — Scalable and durable, adds ops overhead
-```
-
-**Short-term vs. long-term horizon:**
-
-```
-⚠️ Decision Required: Should we ship a minimal regex-based parser now or build a proper AST parser first?
-Context:
-  • The user wants config-file validation.
-  • Regex parser: can be done in ~1 day, covers 90% of cases, brittle on nested structures.
-  • AST parser: takes ~3 days, handles all edge cases, enables future linting and auto-fix.
-  • The config format is still evolving; a brittle parser may need a full rewrite in two weeks.
-Options:
-  1. Ship regex parser now — Fastest path, accept rewrite risk if format changes
-  2. Build AST parser first — Future-proof, higher upfront cost
-```
-
-## Anti-overasking guardrails
-
-Apply a strict decision-block budget per boundary:
-
-- **Max 1** decision block per decision boundary in normal cases.
-- **Max 2** decision blocks for the same boundary when the first was unclear.
-- Never repeat the same trade-off without new evidence.
-
-Escalation ladder:
-
-1. **Attempt 1:** structured options + concise context (examples above).
-2. **Attempt 2 (only if needed):** narrower question with your explicit recommendation:
-   - `Proceed with recommended option`
-   - `Choose another option` (triggers freeform)
-   - `Stop for now`
-
-After attempt 2:
-- If the boundary is a **significant design conflict** or **horizon choice**: **stop and mark blocked**. Do not continue emitting decision blocks.
-- If the boundary is **ambiguity-only** and the user says "your call" or equivalent: proceed with the most reversible default, state assumptions explicitly, and continue.
+mission: 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.
+
+workflow:
+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
+
+rules:
+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 l limit for targeted reading instead of bash sed head tail
+Do not implement changes from this flow
+Markers: Prefix substantive claims with [V] verified, [I] inferred, [A] assumed, or [U] unknown.
+Bite-first: Output raw evidence (code, paths, logs) before any prose explanation.
+No preamble: Start immediately with evidence or action. Skip all conversational filler.
+See _conventions for batch reads and tmp scripts
+See decision gates for material choices that require user preference

package/agents/scout.md

@@ -1,27 +1,28 @@
 ---
 name: scout
-description: Discover files, trace code paths, map architecture
-tools: batch, bash, find, grep, ls, web
+description: Discover files trace code paths map architecture
+tools: batch bash find grep ls web
 maxDepth: 0
 tier: lite
 ---
 
-## Mission
+mission: 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. This is a read oriented flow do not modify files.
 
-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.
+workflow:
+1 Survey: use ls find and grep to locate relevant files and symbols before reading whole files
+2 Inspect: use batch with o read s offset l limit for targeted file reading instead of bash sed head tail
+3 Trace: if batch returns a context map for a large file use the reported line ranges for targeted follow up reads then follow code paths dependencies configuration and tests that explain the requested area
+4 Report: cite concrete evidence with precise file paths and line ranges stop when the requested context is mapped
+5 Validate: cross-check evidence, verify inferences against source, mark gaps with [U], and confirm sufficiency.
 
-## Workflow
-
-1. Survey — use `ls`, `find`, and `grep` to locate relevant files and symbols before reading whole files.
-2. Inspect — use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
-3. If `batch` 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.
-
-## Rules
-
-- 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.
+rules:
+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 or data not excessive summaries
+If something is not found say so directly do not guess
+Workflow: Scouts must complete 5 steps (Survey → Inspect → Trace → Report → Validate). Reject and resend if Validate is missing.
+Snap mode: when session mode is snap, prioritize Survey and Inspect. Skip deep Trace. Emit partial findings fast — incomplete maps are acceptable.
+Markers: Preserve exactly ([V] Verified, [I] Inferred, [A] Assumed, [U] Unknown). Never present [A] or [U] as facts to the user. Dispatch a validation scout if critical claims are [A]/[U].
+Output: Zero preamble or filler. Start immediately with the answer or tool call.
+See _conventions for batch reads and tmp scripts

package/dist/batch/batch-bash.d.ts

@@ -1,5 +1,5 @@
 import { type BashOpResult, type PendingBashResult } from "./constants.js";
-export interface TrackedBashResult {
+interface TrackedBashResult {
     id: string;
     command: string;
     status: "ok" | "error" | "aborted";
@@ -64,7 +64,6 @@ export declare function executeBatchBash(ops: Array<{
 }>, defaultCwd: string, tracker: BashProcessTracker, signal?: AbortSignal, softTimeoutMs?: number): Promise<BashOpResult[]>;
 /** Poll for completed bash results. */
 export declare function pollBatchBashResults(ids: string[], tracker: BashProcessTracker): PendingBashResult[];
-export declare const BatchBashPollParams: any;
 export declare function createBatchBashPollTool(tracker: BashProcessTracker): {
     name: string;
     label: string;
@@ -89,4 +88,5 @@ export declare function createBatchBashPollTool(tracker: BashProcessTracker): {
         isError: boolean;
     }>;
 };
+export {};
 //# sourceMappingURL=batch-bash.d.ts.map

package/dist/batch/batch-bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-bash.d.ts","sourceRoot":"","sources":["../../src/batch/batch-bash.ts"],"names":[],"mappings":"AAiBA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAKtB,MAAM,gBAAgB,CAAC;AAgBxB,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,SAAS,CAAwC;IAEzD,sFAAsF;IACtF,MAAM,CACL,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GAClB,IAAI;IAoFP,2CAA2C;IAC3C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B,0DAA0D;IAC1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAOlC,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,iFAAiF;IACjF,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,mFAAmF;IACnF,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAMvD,+CAA+C;IAC/C,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C,wCAAwC;IACxC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIjC,qCAAqC;IACrC,OAAO,CAAC,SAAS;IAWjB,6CAA6C;IAC7C,QAAQ,IAAI,IAAI;CAKhB;AAWD,sEAAsE;AACtE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA8B,EACxC,QAAQ,GAAE,MAA8B,GACtC,MAAM,CAiCR;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrF;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,KAAK,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC5D,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,CAAC,EAAE,WAAW,EACpB,aAAa,GAAE,MAA6B,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAqDzB;AAoCD,uCAAuC;AACvC,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EAAE,EACb,OAAO,EAAE,kBAAkB,GACzB,iBAAiB,EAAE,CAgCrB;AAMD,eAAO,MAAM,mBAAmB,KAK9B,CAAC;AAEH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB;;;;;;;4BAgBzC,OAAO,GAAG,OAAO;yBAS3B,MAAM,SACZ,OAAO,YACJ,WAAW,cACT,OAAO;;;;;;;;;;;;;;;EAqCrB"}
+{"version":3,"file":"batch-bash.d.ts","sourceRoot":"","sources":["../../src/batch/batch-bash.ts"],"names":[],"mappings":"AAkBA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAKtB,MAAM,gBAAgB,CAAC;AAgBxB,UAAU,iBAAiB;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,SAAS,CAAwC;IAEzD,sFAAsF;IACtF,MAAM,CACL,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GAClB,IAAI;IAwGP,2CAA2C;IAC3C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B,0DAA0D;IAC1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAOlC,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,iFAAiF;IACjF,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,mFAAmF;IACnF,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAMvD,+CAA+C;IAC/C,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C,wCAAwC;IACxC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIjC,qCAAqC;IACrC,OAAO,CAAC,SAAS;IAWjB,6CAA6C;IAC7C,QAAQ,IAAI,IAAI;CAKhB;AAWD,sEAAsE;AACtE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA8B,EACxC,QAAQ,GAAE,MAA8B,GACtC,MAAM,CAiCR;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrF;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,KAAK,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC5D,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,CAAC,EAAE,WAAW,EACpB,aAAa,GAAE,MAA6B,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAqDzB;AAoCD,uCAAuC;AACvC,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EAAE,EACb,OAAO,EAAE,kBAAkB,GACzB,iBAAiB,EAAE,CAgCrB;AAaD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB;;;;;;;4BAgBzC,OAAO,GAAG,OAAO;yBAS3B,MAAM,SACZ,OAAO,YACJ,WAAW,cACT,OAAO;;;;;;;;;;;;;;;EAqCrB"}