@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/dist/builtin/subagents/prompts/gather-context-and-clarify.md

@@ -2,19 +2,26 @@
 description: Use subagents to gather codebase context, then ask clarifying questions
 ---
 
-Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing. Aim for a small parallel fan-out — typically two or three — and let each one inspect the codebase from a different angle.
+## Goal
 
-Pick from these specialists depending on what we already know:
+Build enough grounded codebase context to ask only the unresolved questions needed before planning or implementation. Use a small parallel fan-out, typically two or three specialists with distinct angles.
 
-- `codebase-locator` — find the files, directories, tests, and configs that touch this work.
-- `codebase-analyzer` — explain how a specific feature, flow, or component currently works, with `file:line` references.
-- `codebase-pattern-finder` — surface existing implementations or patterns we can model after.
-- `codebase-research-locator` — discover prior research docs, tickets, notes, or specs in `research/` and `specs/` that are relevant.
-- `codebase-research-analyzer` — extract decisions, constraints, and trade-offs from those prior docs when the topic has history.
-- `codebase-online-researcher` — pull authoritative external docs, release notes, specs, or ecosystem context. Use only when external evidence would materially change the answer.
+Additional request context:
 
-Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence. None of these specialists should edit files — they are read-only context gatherers.
+$@
 
-After they return, synthesize what we know and use the `interview` tool to ask me the unresolved questions needed to reach shared understanding.
+## Constraints and tools
 
-$@
+Choose specialists according to what is unknown: `codebase-locator` for relevant files, directories, tests, and configs; `codebase-analyzer` for current behavior with `file:line` references; `codebase-pattern-finder` for implementations or patterns to model; `codebase-research-locator` for relevant prior docs, tickets, notes, or specs in `research/` and `specs/`; `codebase-research-analyzer` for applicable historical decisions, constraints, and trade-offs; and `codebase-online-researcher` for authoritative external evidence only when it could materially change the answer.
+
+Give each specialist a specific meta-prompt and keep every specialist read-only. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
+
+## Output
+
+Synthesize a concise, user-facing brief of roughly 300–600 words: established facts with evidence, remaining implementation-relevant uncertainties, and focused questions. Then use the `interview` tool to ask those unresolved questions so we reach shared understanding. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
+
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
+
+## Stop rule
+
+Done means the specialists have returned concise findings and remaining clarification questions, their evidence has been synthesized, and the unresolved questions have been sent through `interview`. Do not plan or implement in this step.

package/dist/builtin/subagents/prompts/parallel-cleanup.md

@@ -2,52 +2,47 @@
 description: Parallel cleanup review and refinement of recent changes
 ---
 
-Run a fresh-context parallel cleanup pass over the current work. Read-only specialists scout the diff for slop and verbosity, then a single writer applies the synthesized fixes.
+## Goal
 
-Use the `subagent` tool. Launch the read-only scouts in parallel with `context: "fresh"`. Do not use forked context unless I explicitly ask for it. Each scout inspects the repository and current diff directly through `git diff`, `git status`, and targeted reads. Do not write artifacts into the repository unless I explicitly ask for them — prefer `output: false`.
+Run a fresh-context cleanup pass over the current work: two scouts identify concrete slop and verbosity issues, then synthesize which fixes are worth doing now. In authorized autofix mode, one writer applies that list.
 
-Scout 1: deslop pass — `codebase-analyzer`.
+Additional scope or focus from the slash command invocation:
 
-If the `deslop` skill is available, pass it to this scout. If not, inline the guidance below. Ask this scout to scan the changed scope for AI-slop patterns:
+$@
 
-- comments that restate code, placeholder text, stale rationale, or debug leftovers;
-- defensive checks that hide useful errors, return vague defaults, or validate trusted internal data after a real boundary was already crossed;
-- type escapes, broad casts, duplicated type definitions, or object-bag typing where a local source-of-truth type exists;
-- style drift from nearby non-slop code and project instructions;
-- generated-sounding docs, changelog text, UI copy, status text, or test names;
-- pass-through wrappers, dead helpers, duplicate helper signatures, duplicated test harness setup, or abstractions that do not enforce an invariant;
-- UI or CLI copy that is noisy, vague, brittle, or makes the user do extra interpretation.
+## Constraints and tools
 
-Tell this scout to treat tool output and slop-scan-style findings as leads, not verdicts. It should return only concrete issues in the requested scope with evidence, severity, file/line references, and the smallest safe fix.
+Use the `subagent` tool with `context: "fresh"` unless I explicitly request forked context. Launch both scouts in parallel. Each must inspect the repository and current diff through `git diff`, `git status`, and targeted reads. Keep artifacts outside the repository unless I explicitly request them; prefer `output: false`.
 
-Scout 2: verbosity pass — `codebase-analyzer`.
+**Deslop scout — `codebase-analyzer`.** Pass the `deslop` skill when available; otherwise ask it to inspect the changed scope for:
 
-If the `verbosity-cleaner` skill is available, pass it to this scout. If not, inline the guidance below. Ask this scout to scan the changed scope for needless verbosity in code, tests, docs, status text, grouped messages, receipts, and changelog wording:
+- comments that restate code, placeholders, stale rationale, or debug leftovers;
+- defensive checks that hide useful errors, return vague defaults, or validate trusted data past the real boundary;
+- type escapes, broad casts, duplicated types, or object-bag typing despite a source-of-truth type;
+- drift from nearby code or project instructions, including generated-sounding docs, changelogs, UI/CLI copy, status text, or test names;
+- pass-through wrappers, dead helpers, duplicate signatures or test setup, and abstractions without an invariant;
+- noisy, vague, brittle UI/CLI copy that requires extra interpretation.
 
-- single-use helpers that merely paraphrase an expression;
-- temporary variables that only name obvious expressions;
-- nested returns or branches that can become direct returns without hiding intent;
-- multi-line cleanup scaffolding that can use a local direct pattern while preserving cleanup semantics;
-- repeated boilerplate that can use an existing local fixture or a small local helper;
-- tests that restate formatter details already covered at a cheaper layer;
-- regression tests where one focused assertion would cover the bug but wrapper/API-adjacent tests only repeat the same claim;
-- prose that says the same thing twice, sounds generic, or buries the important rule.
+Treat tool output and scan findings as leads, not verdicts. Return only concrete in-scope issues with evidence, severity, `file:line`, and the smallest safe fix.
 
-Shorter is only better when it is clearer and preserves behavior, error signals, cleanup semantics, useful invariants, and local style.
+**Verbosity scout — `codebase-analyzer`.** Pass the `verbosity-cleaner` skill when available; otherwise ask it to inspect code, tests, docs, status text, grouped messages, receipts, and changelog wording for:
 
-Both scouts are read-only. `codebase-analyzer` cannot edit; do not ask it to. Their response should be evidence-backed findings with file/line references and suggested fixes, not a context summary.
+- single-use helpers or variables that merely name an obvious expression;
+- nested branches replaceable by direct returns without hiding intent;
+- multi-line cleanup scaffolding replaceable by a direct local pattern without changing cleanup semantics;
+- boilerplate replaceable by an existing fixture or small local helper;
+- formatter-detail tests already covered more cheaply, or wrapper/API-adjacent assertions that repeat one regression claim;
+- prose that repeats itself, sounds generic, or buries the important rule.
 
-While the scouts run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+Shorter is better only when clearer and when behavior, error signals, cleanup semantics, useful invariants, and local style remain intact.
 
-- fixes worth doing now;
-- optional improvements;
-- feedback to ignore or defer, with a short reason.
+Both scouts are read-only; `codebase-analyzer` cannot edit. Their reports are review findings, not context summaries. While they run, perform a narrow inspection if useful. Synthesize fixes worth doing now, optional improvements, and feedback to ignore or defer with a short reason; assess findings rather than applying them blindly.
 
-Do not blindly apply every finding.
+Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not cleanup scope. Remove it before deciding the cleanup target. After synthesis, launch a single async `code-simplifier` writer with the synthesized fixes-worth-doing-now as its explicit scope. Validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not cleanup scope; remove it before identifying the target. After synthesis, launch one async `code-simplifier` writer with only the fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
 
-Without autofix mode, ask before applying fixes unless I already told you to address the cleanup feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+Without autofix mode, ask before applying fixes unless I already authorized addressing the cleanup feedback. End that request with a compact numbered menu, including when applicable:
 
 ```text
 Reply with [1], [2], or further instructions:
@@ -55,6 +50,12 @@ Reply with [1], [2], or further instructions:
 [2] Apply the fixes worth doing now plus optional improvements via `code-simplifier`.
 ```
 
-Additional scope or focus from the slash command invocation:
+## Output
 
-$@
+Return a concise, user-facing cleanup report of roughly 300–700 words: fixes worth doing now, optional improvements, ignored or deferred feedback with reasons, edits made when authorized, and validation. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
+
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
+
+## Stop rule
+
+Done means both scouts' evidence has been assessed and synthesized, then either the authorized writer's focused changes have been validated, no worthwhile fixes exist, or the numbered approval menu has been presented. Stop without editing when authorization is absent.

package/dist/builtin/subagents/prompts/parallel-context-build.md

@@ -2,56 +2,42 @@
 description: Parallel codebase specialists building handoff context for planning
 ---
 
-Launch fresh-context codebase specialists in parallel to build grounded handoff context for planning or implementation.
+## Goal
 
-Use the `subagent` tool in chain mode with a single parallel step, not top-level parallel tasks, so relative output files live under the temporary chain directory. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, `label`, and `as` name, for example:
+Build grounded, implementation-ready handoff context for the next planner or writer without starting implementation.
 
-- `context-build/where-it-lives.md`
-- `context-build/how-it-works.md`
-- `context-build/existing-patterns.md`
-- `context-build/prior-research.md`
-
-Use one phase such as `phase: "Context build"` for the parallel tasks so async status is readable. A later synthesis step can reference specific outputs with `{outputs.requestScope}`, `{outputs.codebasePatterns}`, and `{outputs.validationRisks}` instead of relying only on `{previous}`.
-
-Do not write these context artifacts into the repository unless I explicitly ask for persistent files.
-
-Treat the slash command arguments as the primary request, target, or focus:
+Primary request, target, or focus:
 
 $@
 
-If the invocation provides a URL, issue link, file path, plan path, or freeform request, read or fetch that target before assigning angles, then pass the target explicitly into every subagent task.
+## Constraints and tools
 
-Choose two to four specialists based on the request. These are examples, not fixed defaults:
+Use the `subagent` tool in chain mode with one parallel step so relative outputs stay under the temporary chain directory. Use `context: "fresh"` unless I explicitly request forked context. Give every task a distinct `output` path, `label`, and `as` name, such as:
 
-1. Locate — `codebase-locator`
-   Find every file, directory, test, fixture, config, and doc that touches the change. Group by purpose and return full paths from repo root.
+- `context-build/where-it-lives.md`
+- `context-build/how-it-works.md`
+- `context-build/existing-patterns.md`
+- `context-build/prior-research.md`
 
-2. Analyze — `codebase-analyzer`
-   Explain how the relevant feature or flow currently works. Trace entry points, control flow, data transformations, side effects, and error handling with `file:line` citations.
+Use one phase such as `phase: "Context build"` so async status is readable. A synthesis step can cite `{outputs.requestScope}`, `{outputs.codebasePatterns}`, and `{outputs.validationRisks}` when available, using `{previous}` only for the whole fan-in. Do not persist context artifacts in the repository unless I explicitly request it.
 
-3. Pattern-find — `codebase-pattern-finder`
-   Surface comparable implementations, test patterns, and conventions already in the codebase that the next agent should model after.
+Read or fetch any supplied URL, issue link, file path, plan path, or freeform request before assigning angles, and pass that target into every specialist task. Choose two to four specialists according to the request:
 
-4. Prior research — `codebase-research-locator` followed by `codebase-research-analyzer`
-   When the topic has history in `research/` or `specs/`, locate relevant prior docs and then extract the decisions, constraints, and rationale that still apply.
+- **Locate — `codebase-locator`:** map every relevant file, directory, test, fixture, config, and doc by purpose, using full repo-root paths.
+- **Analyze — `codebase-analyzer`:** trace entry points, control flow, data transformations, side effects, and error handling with `file:line` citations.
+- **Pattern-find — `codebase-pattern-finder`:** provide comparable implementations, test patterns, conventions, and useful code snippets.
+- **Prior research — `codebase-research-locator` then `codebase-research-analyzer`:** when `research/` or `specs/` history applies, locate it before extracting current decisions, constraints, and rationale.
 
-Adapt the specialists when the request calls for it:
+For an issue or PR URL, include locator and analyzer coverage of mentioned files. For a plan, cover its files and their current behavior. For external API/library work, add `codebase-online-researcher` for current primary sources. For a large refactor, emphasize module-boundary and dependency-direction patterns. For UI/product work, cover analogous components and the surrounding render path.
 
-- Issue or PR URL: include locator and analyzer for files mentioned in the linked discussion.
-- Plan file: include locator (files mentioned by the plan) and analyzer (current behavior of those files).
-- External API/library work: add `codebase-online-researcher` for current docs or primary sources.
-- Large refactor: lean on `codebase-pattern-finder` for module-boundary and dependency-direction examples.
-- UI/product work: add `codebase-pattern-finder` for analogous components and `codebase-analyzer` for the surrounding render path.
+Every specialist is read-only and produces a compact handoff file containing only its unique contribution, ending with `## Open Questions`. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-Ask each specialist to produce a compact handoff file with the information their role uniquely provides — locator returns file maps, analyzer returns flow narratives with `file:line` refs, pattern-finder returns code snippets, research agents return decision histories. Each file should end with a short `## Open Questions` section.
+## Output
 
-None of these specialists should edit files. This is a read-only context-build pass.
+Synthesize the artifacts for the downstream planner or writer into roughly 500–900 words: the most important context, a compact implementation-ready meta-prompt, open questions or assumptions, and artifact paths. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
 
-After the specialists return, synthesize their outputs yourself into:
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
 
-- the most important context the next agent needs;
-- a compact implementation-ready meta-prompt for the next planner or writer;
-- open questions or assumptions;
-- the output artifact paths.
+## Stop rule
 
-Do not start implementation from this command unless I explicitly ask for it.
+Done means the selected specialists have returned their distinct handoff files and the downstream synthesis names its evidence and artifact paths. Do not implement unless I explicitly ask.

package/dist/builtin/subagents/prompts/parallel-handoff-plan.md

@@ -2,25 +2,27 @@
 description: Parallel external + local research builders into an implementation handoff plan
 ---
 
-Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
+## Goal
+
+Produce a grounded implementation handoff plan and implementation-ready meta-prompt by comparing applicable external evidence, local behavior, established patterns, and prior decisions.
 
 Primary request, target, or focus:
 
 $@
 
-Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
+## Constraints and tools
 
-Use the `subagent` tool in chain mode. The chain has one parallel discovery step followed by a parent-side synthesis pass (there is no dedicated synthesizer subagent in this skill):
+First read or fetch every URL, issue, PR, screenshot, plan, doc, or local file named in the request; these define primary scope. Use the `subagent` tool in chain mode with `context: "fresh"` unless I explicitly request forked context. Run one parallel discovery step, then synthesize parent-side rather than launching a synthesizer subagent.
 
-Parallel discovery step. Choose the specialists that apply:
+Choose specialists by evidence need:
 
-- `codebase-online-researcher` — required whenever the request mentions external projects, libraries, docs, APIs, recent changes, or best-practice guidance. It web-searches, fetches authoritative sources, and persists keepers under `research/web/`.
-- `codebase-locator` — required for any non-trivial code change. Find the local files, tests, fixtures, and configs the change would touch.
-- `codebase-analyzer` — required when the local behavior matters. Trace the relevant flow with `file:line` references.
-- `codebase-pattern-finder` — add when transferable conventions or analogous implementations would shape the plan.
-- `codebase-research-locator` and `codebase-research-analyzer` — add when prior `research/` or `specs/` docs likely apply. Run them sequentially (locator first, then analyzer) or pair them inside the parallel step with distinct output paths.
+- Use `codebase-online-researcher` when external projects, libraries, docs, APIs, recent changes, or best practices could shape the plan. It should inspect linked projects, docs, issues, examples, source, or prompt guidance; identify behavior, APIs, implementation files, constraints, and transferable ideas; use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and fall back to `browser` only for required JS or auth; persist high-value sources to `research/web/<YYYY-MM-DD>-<topic>.md`; and return links, repo paths, evidence, risks, and implementation implications.
+- Use `codebase-locator` for non-trivial code changes to map relevant local files, tests, fixtures, and configs by purpose.
+- Use `codebase-analyzer` when local behavior matters to trace the located implementation, control flow, transformations, and constraints with `file:line` citations. Locator and analyzer cover where the work lives and how it works without overlap.
+- Add `codebase-pattern-finder` when analogous implementations or conventions could shape the plan; include useful snippets with `file:line` references.
+- Add `codebase-research-locator` then `codebase-research-analyzer` when prior `research/` or `specs/` may apply. The locator finds relevant dated docs; the analyzer extracts current decisions, constraints, and lessons while flagging superseded guidance. Run them sequentially, or pair them in the parallel step with distinct outputs when the dependency is already resolved.
 
-Use distinct output paths, `label` values, and `as` names under the chain directory. Example outputs:
+Give tasks distinct `output` paths, `label` values, and `as` names under the chain directory, for example:
 
 - `handoff/external-reference.md`
 - `handoff/local-files.md`
@@ -28,52 +30,18 @@ Use distinct output paths, `label` values, and `as` names under the chain direct
 - `handoff/local-patterns.md`
 - `handoff/prior-research.md`
 
-Use phases such as `Research`, `Local context`, and `Synthesis` so async status is readable. Prefer `{outputs.externalReference}`, `{outputs.localContext}`, and `{outputs.implementationStrategy}` in the synthesis task when those specific inputs are available; keep `{previous}` only when the whole parallel fan-in summary is the desired input.
-
-Do not write these artifacts into the repository unless I explicitly ask for persistent files.
-
-Role guidance:
-
-External researcher (`codebase-online-researcher`):
-
-- Study linked projects, docs, issues, examples, source code, or prompt guidance.
-- Identify the behavior, API, implementation files, constraints, and transferable ideas.
-- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `browser` when JS execution or auth is required.
-- Persist any high-value fetch to `research/web/<YYYY-MM-DD>-<topic>.md`.
-- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
-
-Local locator + analyzer (`codebase-locator`, `codebase-analyzer`):
-
-- Locator returns the full file map grouped by purpose.
-- Analyzer reads the located files and traces the current implementation, control flow, transformations, and constraints with `file:line` citations.
-- Together they cover "where it lives" and "how it works today" without overlap.
-
-Local pattern-finder (`codebase-pattern-finder`), when used:
-
-- Find similar implementations or conventions worth modeling after. Include working snippets with `file:line` references.
-
-Prior research (`codebase-research-locator` → `codebase-research-analyzer`), when used:
+Use phases such as `Research`, `Local context`, and `Synthesis` for readable async status. In synthesis, prefer `{outputs.externalReference}`, `{outputs.localContext}`, and `{outputs.implementationStrategy}` when available; use `{previous}` only for the whole parallel fan-in. Do not persist these artifacts in the repository unless I explicitly request it.
 
-- Locator surfaces the relevant dated docs from `research/` and `specs/`.
-- Analyzer extracts the decisions, constraints, and lessons that are still applicable, flagging anything superseded by newer docs.
+Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-Parent-side synthesis after the discovery step returns:
+## Output
 
-- Compare external evidence against the local architecture.
-- Propose the safest implementation shape, the likely files to change, edge cases, validation commands, and decisions that need approval.
-- Write `handoff/final-handoff-plan.md` yourself, or summarize inline if I didn't ask for a persisted artifact.
+Compare external evidence with local architecture and write `handoff/final-handoff-plan.md` yourself, or summarize inline when no persisted artifact was requested. The downstream writer needs roughly 700–1,200 words covering: intended behavior; lessons from external references; local implications; recommended approach; likely files; constraints and non-goals; edge cases, validation commands, risks, and approval decisions; unresolved questions; and a compact implementation-ready meta-prompt.
 
-Include in the final handoff:
+Then give the user a concise summary with the recommendation, artifact paths, final meta-prompt, and remaining questions or assumptions. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
 
-- what the feature or change should do;
-- what the external reference teaches;
-- what the local codebase implies;
-- the recommended approach;
-- likely files to change;
-- constraints, non-goals, validation, risks;
-- unresolved questions;
-- a compact implementation-ready meta-prompt for the next writer.
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
 
-After the chain returns, summarize the result for me with the recommended approach, artifact paths, the final meta-prompt, and any questions or assumptions that remain.
+## Stop rule
 
-Do not start implementation from this command unless I explicitly ask for it.
+Done means discovery evidence has been compared, the final handoff exists at the requested destination or inline, and the user has the recommendation, paths, meta-prompt, and unresolved decisions. Do not start implementation unless I explicitly ask.

package/dist/builtin/subagents/prompts/parallel-research.md

@@ -2,57 +2,33 @@
 description: Parallel research specialists for grounded answers
 ---
 
-Launch parallel research specialists to build a grounded answer to the current question or decision.
+## Goal
 
-Use fresh context, not forked context, unless I explicitly ask for forked context. Specialists should inspect sources directly instead of relying on the main conversation history.
+Build a grounded answer to the current question or decision from distinct external, local, convention, or prior-decision evidence.
 
-Choose specialists based on the question:
+Primary question or focus:
 
-- `codebase-online-researcher` — web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
-- `codebase-locator` — repository files that touch the question.
-- `codebase-analyzer` — how the relevant code currently works, with `file:line` references.
-- `codebase-pattern-finder` — comparable implementations or conventions already in the codebase.
-- `codebase-research-locator` and `codebase-research-analyzer` — prior `research/` or `specs/` docs that bear on the question (run locator first, then analyzer).
-
-Give each specialist a distinct angle. Unless I specify angles, use three of these (skip the ones that don't apply):
-
-1. External evidence — `codebase-online-researcher`
-   Find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
-
-2. Local code context — `codebase-locator` and/or `codebase-analyzer`
-   Locate the relevant files and trace how they work today.
-
-3. Local conventions — `codebase-pattern-finder`
-   Surface analogous implementations or patterns the answer should respect.
+$@
 
-4. Prior decisions — `codebase-research-locator` followed by `codebase-research-analyzer`
-   When the topic has history in `research/` or `specs/`, extract the decisions and constraints that still apply.
+## Constraints and tools
 
-Adapt the angles when the question calls for it:
+Use fresh context unless I explicitly request forked context; specialists inspect sources directly rather than relying on the main conversation. Choose two or three strong specialists with distinct applicable angles, using my specified angles when provided:
 
-- Library/API questions: include `codebase-online-researcher` for official docs and recent examples.
-- Architecture decisions: include `codebase-locator` and `codebase-pattern-finder` for module boundaries and dependency direction.
-- Debugging questions: include `codebase-analyzer` for call paths and `codebase-online-researcher` for the error message.
-- UI/product questions: include `codebase-pattern-finder` for analogous components and `codebase-online-researcher` for design precedent.
-- Time-sensitive topics: have the online researcher prefer 2026/2025 sources and persist findings to `research/web/`.
+- **External evidence — `codebase-online-researcher`:** current authoritative sources such as official docs, standards, release notes, benchmarks, issue threads, and primary explanations.
+- **Local context — `codebase-locator` and/or `codebase-analyzer`:** relevant repository files and how they work, with `file:line` references.
+- **Local conventions — `codebase-pattern-finder`:** analogous implementations and patterns the answer should respect.
+- **Prior decisions — `codebase-research-locator` then `codebase-research-analyzer`:** applicable decisions and constraints from `research/` or `specs/`, with locator preceding analyzer.
 
-Prefer two or three strong specialists over many vague ones. None of these agents should edit files — this is a research pass only unless I explicitly ask for implementation.
+For library/API questions, include official docs and recent examples. For architecture decisions, cover module boundaries and dependency direction. For debugging, cover call paths and authoritative information about the error. For UI/product questions, cover analogous components and design precedent. For time-sensitive topics, have the online researcher prefer 2026/2025 sources and persist findings to `research/web/`.
 
-Ask each specialist to return concise findings with evidence:
+This is read-only research unless I explicitly request implementation. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-- file paths and line ranges for local findings;
-- source links for external findings;
-- confidence level and gaps;
-- recommended next step or decision implication.
+## Output
 
-After the specialists return, synthesize the answer into:
+Each specialist returns concise evidence: local paths and line ranges or external links, confidence and gaps, and the decision implication or next step. Synthesize a user-facing answer of roughly 400–800 words covering what is known, local implications, tradeoffs and risks, gaps or assumptions, and the recommended move. Name disagreements rather than smoothing them over. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
 
-- what we know;
-- what the local codebase implies;
-- tradeoffs and risks;
-- gaps or assumptions;
-- the recommended next move.
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
 
-If findings disagree, call out the disagreement instead of smoothing it over.
+## Stop rule
 
-$@
+Done means applicable specialists have returned direct evidence and the synthesis answers the question, identifies material uncertainty or disagreement, and recommends the next move. Do not edit files unless implementation was explicitly requested.

package/dist/builtin/subagents/prompts/parallel-review.md

@@ -2,42 +2,33 @@
 description: Parallel specialist review of the current work
 ---
 
-Launch parallel specialists for an adversarial review of the current work.
+## Goal
 
-Use fresh context, not forked context, unless I explicitly ask for forked context. Specialists should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+Produce an adversarial, evidence-backed review of the current work, separating fixes worth doing now from optional or inapplicable feedback. Apply fixes only when authorized.
 
-There is no generic `reviewer` agent — assemble the review from read-only specialists with distinct angles. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise pick three of the following:
-
-1. Correctness and regressions — `codebase-analyzer`
-   Trace the current diff and the surrounding flow to check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures. Cite `file:line` for every claim.
-
-2. Bug and failure-mode hunt — `debugger`
-   Treat the diff as a suspect change. Reproduce the relevant behavior when possible, hypothesize how it could break, and report findings with evidence. The `debugger` agent can write fixes — for this pass, explicitly instruct it to inspect and report only, not edit.
-
-3. Pattern fit and consistency — `codebase-pattern-finder`
-   Compare the implementation against existing analogous patterns and conventions in the codebase. Flag drift, divergence from established structure, or missed reuse opportunities with `file:line` snippets.
+Additional review target or focus from the slash command invocation:
 
-4. Prior decisions and constraints — `codebase-research-locator` then `codebase-research-analyzer`
-   When prior research or specs likely constrain the change, surface the relevant docs and extract the decisions the new code must honor.
+$@
 
-5. External-spec or API conformance — `codebase-online-researcher`
-   When the change implements an external contract (API, RFC, library behavior), verify the implementation against the authoritative source.
+If this supplies a URL, issue, file, plan, or freeform focus, treat it as primary scope: read or fetch it before assigning angles and pass it into every specialist task.
 
-Cleanup-style angles (simplicity, slop, verbosity) belong in `/parallel-cleanup`; use that instead of overloading this pass.
+## Constraints and tools
 
-Give every specialist a specific task prompt naming its angle. Ask them to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Specialists must not edit files in this pass, even when the agent type can — say so explicitly in the prompt.
+Use fresh context unless I explicitly request forked context. Specialists inspect repository instructions, relevant files, and the current diff through direct reads and commands, not main-conversation history. There is no generic `reviewer`; choose read-only specialists with distinct angles derived from user intent, the plan, implementation, and diff. Use my angles when supplied; otherwise select three applicable angles:
 
-While they run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- **Correctness and regressions — `codebase-analyzer`:** trace the diff and surrounding flow against the request, preserved behavior, edge cases, and hidden runtime failures; cite `file:line` for every claim.
+- **Bug and failure modes — `debugger`:** reproduce relevant behavior where possible, assess how the suspect diff could break, and report evidence.
+- **Pattern fit — `codebase-pattern-finder`:** compare analogous code and conventions, identifying structural drift or missed reuse with `file:line` snippets.
+- **Prior constraints — `codebase-research-locator` then `codebase-research-analyzer`:** surface applicable research or specs and the decisions the change must honor.
+- **External conformance — `codebase-online-researcher`:** compare an external API, RFC, or library contract with its authoritative source.
 
-- fixes worth doing now;
-- optional improvements;
-- feedback to ignore or defer, with a short reason.
+Use `/parallel-cleanup` instead for simplicity, slop, or verbosity angles. Every specialist gets a task naming its angle and returns concise review findings with evidence, `file:line`, and suggested fixes—not a context summary. Every specialist is read-only, including agent types that can edit. While they run, perform a narrow inspection if useful.
 
-Do not blindly apply every finding.
+Synthesize fixes worth doing now, optional improvements, and ignored or deferred feedback with a short reason; assess findings rather than applying them blindly. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, launch a single async writer (`debugger` for correctness or regression fixes, `code-simplifier` for cleanup-shaped feedback) with the explicit fix list as scope. Validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not review scope; remove it before identifying the target. After synthesis, launch one async writer—`debugger` for correctness/regression fixes or `code-simplifier` for cleanup-shaped feedback—with only the explicit fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
 
-Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+Without autofix mode, ask before applying fixes unless I already authorized addressing review feedback. End that request with a compact numbered menu, including when applicable:
 
 ```text
 Reply with [1], [2], or further instructions:
@@ -45,8 +36,12 @@ Reply with [1], [2], or further instructions:
 [2] Apply the fixes worth doing now plus optional improvements.
 ```
 
-Additional review target or focus from the slash command invocation:
+## Output
 
-$@
+Return a concise, user-facing review of roughly 400–800 words: outcome, evidence-backed fixes worth doing now, optional improvements, ignored or deferred feedback with reasons, and any authorized edits and validation. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
+
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
+
+## Stop rule
 
-If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each specialist task.
+Done means the specialist evidence has been assessed and synthesized, then either authorized fixes were validated, no worthwhile fixes exist, or the numbered approval menu was presented. Stop without editing when authorization is absent.

package/dist/builtin/subagents/prompts/review-loop.md

@@ -2,47 +2,38 @@
 description: Specialist review/fix loop until clean
 ---
 
-Run a parent-orchestrated review-and-fix loop for the requested work.
+## Goal
 
-Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks; they must not run subagents or manage the loop themselves.
+Run a parent-orchestrated review-and-fix loop for the requested work until the current scope is clean, blocked on an unapproved decision, or capped. The parent controls the loop and makes final decisions; children receive concrete role-specific tasks and must not launch subagents or manage the loop.
 
-There is no generic worker or reviewer in this skill — the loop composes specialist agents:
+Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
 
-- Writers (one per pass): `debugger` for bug fixes, correctness/regression fixes, or behavior changes; `code-simplifier` for cleanup, refinement, or simplification.
-- Read-only reviewers (parallel each round): `codebase-analyzer` for correctness and flow; `debugger` in inspect-only mode for failure-mode hunts; `codebase-pattern-finder` for consistency; `codebase-online-researcher` for external-spec conformance; `codebase-research-locator` + `codebase-research-analyzer` for prior decisions.
+$@
 
-Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a writer pass. Stop early when reviewers find no blockers or fixes worth doing now.
+## Constraints and tools
 
-If the invocation includes an implementation request, first launch one async writer for the approved scope — `debugger` when the work is correctness-shaped, `code-simplifier` when it is refinement-shaped. If the current diff is already the target, start with review. The sequence can be launched up front as an async/background chain when the workflow is clear, or continued as follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; subagent launches are non-interactive, so resolve any questions with me before launching. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
+Use the `subagent` tool and specialist roles rather than a generic worker or reviewer. Use one writer per pass: `debugger` for bugs, correctness/regression fixes, or behavior changes; `code-simplifier` for cleanup, refinement, or simplification. Reviewer options are `codebase-analyzer` for correctness and flow, `debugger` in inspect-only mode for failure modes, `codebase-pattern-finder` for consistency, `codebase-online-researcher` for external conformance, and `codebase-research-locator` then `codebase-research-analyzer` for prior decisions.
 
-For each review round, launch fresh-context read-only reviewer specialists in parallel. They must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files — when using `debugger` for this pass, explicitly tell it to inspect and report only.
+Default to at most 3 review rounds unless I set another cap. A round is a fresh-context inspection of the current diff after a writer pass.
 
-Choose review angles from the actual change. Common angles are correctness/regressions (`codebase-analyzer`), failure-mode hunt (`debugger` inspect-only), and pattern fit (`codebase-pattern-finder`). Add external-spec (`codebase-online-researcher`) or prior-decision (`codebase-research-*`) angles when the work calls for it. Prefer three strong reviewers over many vague reviewers.
+If the invocation requests implementation, first launch one async writer for the approved scope: `debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work. If the current diff is already the target, begin with review. Launch a clear sequence up front as an async/background chain or continue with follow-up runs after each completion. For an initial chain, pass `async: true`; because launches are non-interactive, resolve questions with me first. Use one writer against the active worktree at a time unless I explicitly request isolated worktrees.
 
-After reviewers return, synthesize their feedback into:
+Each review round uses fresh context. Reviewers inspect repository instructions, relevant files, and the current diff directly, without main-conversation history, and cannot edit; explicitly put `debugger` in inspect-only mode. Choose angles from the change. Common angles are correctness/regressions, failure modes, and pattern fit; add external-spec or prior-decision coverage when applicable. Prefer three strong reviewers over many vague ones.
 
-- blockers or scope/product/architecture decisions that need user approval;
-- fixes worth doing now;
-- optional improvements;
-- feedback to ignore or defer, with a short reason.
+Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-Do not blindly apply every finding. If reviewers surface an unapproved product, scope, or architecture decision, pause and ask me before launching a fix writer.
+After each round, synthesize blockers or scope/product/architecture decisions needing approval, fixes worth doing now, optional improvements, and feedback to ignore or defer with a short reason. Assess findings rather than applying them blindly. Pause for my approval before a writer acts on any unapproved product, scope, or architecture decision.
 
-When an async implementation writer completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for writer-only work, review-only output, or to stop after implementation.
+An async implementation writer's handoff transitions into review; it is not final completion unless I requested writer-only work, review-only output, or a stop after implementation. When implementation is authorized and fixes are worth doing now, launch one async writer to apply only the synthesized fixes—`debugger` for correctness or `code-simplifier` for cleanup. Require it to preserve approved scope, run focused validation, and report changed files, commands with exit codes, validation evidence, surprises, and unfinished work.
 
-When there are fixes worth doing now and the workflow is implementation-authorized, launch one async writer to apply only those synthesized fixes — `debugger` for correctness fixes, `code-simplifier` for cleanup fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
+Run another review round after a fix only when it made material changes or addressed non-trivial findings. Do not loop for optional polish, speculative improvements, or already deferred findings.
 
-After a fix writer returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
+## Output
 
-Stop and summarize when one of these is true:
+On completion, inspect the final diff and run or confirm appropriate focused validation. Return a concise, user-facing summary of roughly 300–700 words: why the loop stopped, rounds run, fixes applied, validation, remaining blockers or deferred items, and next steps. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
 
-- reviewers find no blockers or fixes worth doing now;
-- remaining feedback is optional, speculative, or intentionally deferred;
-- reviewers surface an unapproved decision that needs me;
-- the max review-round cap is reached.
+Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
 
-On completion, inspect the final diff yourself, run or confirm focused validation where appropriate, and summarize the loop: rounds run, fixes applied, validation, remaining deferred items, and why the loop stopped.
+## Stop rule
 
-Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
-
-$@
+Stop and summarize when reviewers find no blockers or fixes worth doing now; remaining feedback is optional, speculative, or intentionally deferred; an unapproved decision needs me; or the review-round cap is reached. The loop is done only after the final diff and focused validation have been inspected or explicitly reported as unverified.