@bastani/atomic 0.9.10 → 0.9.11-alpha.10

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.

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -159,7 +159,7 @@ Builtin agents load at the lowest priority. Project agents override user agents,
 | `codebase-research-analyzer` | Extract decisions and constraints from prior docs                 | `openai/gpt-5.5`      | low      | read, search, find, ls, bash                                                             | Read-only. Filters aggressively for what still applies today.                                              |
 | `codebase-online-researcher` | Web research with authoritative sources                           | `openai/gpt-5.5`      | low      | read, search, find, ls, bash, write, web_search, fetch_content, get_search_content       | Has the `browser` skill. Persists keepers to `research/web/`.                                       |
 | `code-simplifier`            | Clean up recently changed code without changing behavior          | `openai/gpt-5.5`      | low      | read, edit, write, search, find, ls, bash                                                | **Writer.** Scopes to recently modified code by default; preserves all observable behavior.                |
-| `debugger`                   | Reproduce, diagnose, and fix failing behavior                     | `openai/gpt-5.5`      | high     | read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content | **Writer.** Has the `tdd` and `browser` skills. Inspect-only mode requires an explicit instruction. |
+| `debugger`                   | Reproduce, diagnose, and fix failing behavior                     | `openai-codex/gpt-5.6-sol:xhigh` | xhigh | read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo | **Writer.** Has the `tdd`, `playwright-cli`, and `tmux` skills. Can coordinate with the parent; inspect-only mode requires an explicit instruction. |
 
 Each builtin declares an explicit `model` and `fallbackModels` chain (typically `github-copilot/<same>`, then `anthropic/claude-opus-4-8`, then `github-copilot/claude-opus-4.7`). The current user-selected model is automatically appended as the last fallback and de-duplicated. Override per run with inline config:
 
@@ -169,7 +169,7 @@ Each builtin declares an explicit `model` and `fallbackModels` chain (typically
 
 For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
-None of the builtin specialists carry the `intercom` tool. They cannot call `contact_supervisor` to coordinate back to the parent mid-run — they finish their pass and return. Custom agents that declare `intercom` (or that the runtime bridge injects `contact_supervisor` into) can still coordinate; see [Subagent + Intercom Coordination](#subagent--intercom-coordination).
+The builtin `debugger` and `worker` agents declare both `intercom` and `contact_supervisor`, so they can send progress or ask the parent for a decision when the bridge is active. Other builtin specialists finish their pass and return without live coordination. Custom agents can coordinate when they declare `intercom` or when the runtime bridge injects `contact_supervisor`; see [Subagent + Intercom Coordination](#subagent--intercom-coordination).
 
 ## Prompting specialist subagents
 
@@ -397,7 +397,7 @@ subagent({
 })
 ```
 
-If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists. The builtin specialists do not carry `intercom`, so they will not produce coordination pings; the parent must check status explicitly.
+If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists. Coordination depends on the resolved agent's tools and an active bridge route: the builtin `debugger` and `worker` declare `intercom` and `contact_supervisor`, while the other builtin specialists rely on the parent checking status.
 
 ## Non-Interactive Execution
 
@@ -425,7 +425,7 @@ subagent({
 
 Atomic subagents work without intercom. When Atomic's bundled intercom companion or upstream `pi-intercom` is installed and enabled, the bridge can give eligible child agents a private coordination tool back to the parent session without connecting either session automatically. If a child may need live coordination, invoke `intercom({ action: "status" })` in the parent before launching it; the child connects when it first invokes `contact_supervisor` or `intercom`.
 
-The builtin specialists in this skill do not declare the `intercom` tool, so they finish their pass and return without coordinating. They cannot pause to ask the parent for a decision mid-run; if you need that, write a custom agent that lists `intercom` (or that the runtime bridge can inject `contact_supervisor` into).
+The builtin `debugger` and `worker` agents declare `intercom` and `contact_supervisor`. With an active bridge route, they can send progress or pause to ask the parent for a decision. Other builtin specialists finish their pass and return without live coordination; use a custom agent with bridge tools when another role needs that ability.
 
 Custom agents that do have the bridge tool can ask the parent for a decision:
 
@@ -551,7 +551,7 @@ If a prompt-template extension is installed, additional user prompt templates ca
 - **Forked runs inherit parent history.** They are branched threads, not fresh filtered contexts. Use fresh context for adversarial review unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 5.** Deeper recursive delegation is blocked, and configured values above 5 are clamped to the hard ceiling.
 - **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
-- **Builtin specialists do not have `intercom`.** They cannot escalate decisions mid-run. Decide what the child should do up front, or use a custom agent with bridge tools when mid-run coordination is required.
+- **Builtin coordination varies by agent.** `debugger` and `worker` declare `intercom` and `contact_supervisor`; the other builtin specialists do not. For agents without bridge tools, decide the task up front or use a custom agent when mid-run coordination is required.
 - **Intercom asks are blocking.** A session can only maintain one pending outbound ask wait state at a time.
 - **Keep conversational authority clear.** Advisory specialists should not silently become second decision-makers.
 
@@ -586,7 +586,7 @@ Give subagents specific tasks rather than vague mandates.
 
 ### Escalate decisions upward
 
-The builtin specialists return on completion rather than pausing for parent decisions, so resolve scope/product/architecture questions before launching a writer. If the parent realizes mid-run that the scope is wrong, soft-interrupt rather than waiting for the writer to finish.
+Most builtin specialists return on completion rather than pausing for parent decisions. The builtin `debugger` and `worker` can use `contact_supervisor` when an active bridge route exists, but resolve known scope, product, and architecture questions before launching any writer. If the parent realizes mid-run that the scope is wrong, steer a reachable writer or soft-interrupt it.
 
 ### Intervene only on clear control signals
 

package/dist/builtin/subagents/src/agents/agent-discovery.ts

@@ -2,9 +2,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getEnvValue } from "@bastani/atomic";
-import { mergeAgentsForScope } from "./agent-selection.ts";
-import { applyBuiltinOverrides, readMergedSubagentSettings } from "./agent-overrides.ts";
 import { loadAgentsFromDir, loadChainsFromDir } from "./agent-loaders.ts";
+import { applyBuiltinOverrides, readMergedSubagentSettings } from "./agent-overrides.ts";
 import {
 	BUILTIN_AGENTS_DIR,
 	getProjectAgentSettingsPath,
@@ -17,13 +16,14 @@ import {
 	resolveNearestProjectAgentDirs,
 	resolveNearestProjectChainDirs,
 } from "./agent-paths.ts";
+import { mergeAgentsForScope } from "./agent-selection.ts";
 import {
-	EMPTY_SUBAGENT_SETTINGS,
 	type AgentConfig,
 	type AgentDiscoveryResult,
 	type AgentScope,
 	type ChainConfig,
 	type ChainDiscoveryDiagnostic,
+	EMPTY_SUBAGENT_SETTINGS,
 } from "./agent-types.ts";
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
@@ -50,8 +50,9 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userAgents = [...userAgentsOld, ...userAgentsNew];
 
 	const projectAgents = scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project"));
-	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents)
-		.filter((agent) => agent.disabled !== true);
+	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents).filter(
+		(agent) => agent.disabled !== true,
+	);
 
 	return { agents, projectAgentsDir };
 }
@@ -110,18 +111,28 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const userChainLoads = getUserChainDirs().map((dir) => loadChainsFromDir(dir, "user"));
-	const chains = [
-		...userChainLoads.flatMap((loaded) => loaded.chains),
-		...Array.from(chainMap.values()),
-	];
-	const chainDiagnostics = [
-		...userChainLoads.flatMap((loaded) => loaded.diagnostics),
-		...projectChainDiagnostics,
-	];
+	const chains = [...userChainLoads.flatMap((loaded) => loaded.chains), ...Array.from(chainMap.values())];
+	const chainDiagnostics = [...userChainLoads.flatMap((loaded) => loaded.diagnostics), ...projectChainDiagnostics];
 
 	const legacyUserAgentDir = userDirOld[0]!;
 	// ATOMIC_CODING_AGENT_DIR is already applied by getUserAgentDirs(); prefer that resolved path over ~/.agents.
-	const userDir = getEnvValue("ATOMIC_CODING_AGENT_DIR") ? legacyUserAgentDir : fs.existsSync(userDirNew) ? userDirNew : legacyUserAgentDir;
+	const userDir = getEnvValue("ATOMIC_CODING_AGENT_DIR")
+		? legacyUserAgentDir
+		: fs.existsSync(userDirNew)
+			? userDirNew
+			: legacyUserAgentDir;
 
-	return { builtin, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+	return {
+		builtin,
+		user,
+		project,
+		chains,
+		chainDiagnostics,
+		userDir,
+		projectDir,
+		userChainDir,
+		projectChainDir,
+		userSettingsPath,
+		projectSettingsPath,
+	};
 }

package/dist/builtin/subagents/src/agents/agent-loaders.ts

@@ -1,20 +1,20 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { shouldPreserveAgentExtraField } from "./agent-serializer.ts";
-import { parseChain, parseJsonChain } from "./chain-serializer.ts";
-import { parseFrontmatter } from "./frontmatter.ts";
-import { buildRuntimeName, parsePackageName } from "./identity.ts";
+import { normalizeMaxSubagentDepth } from "../shared/types.ts";
 import { splitToolList } from "./agent-overrides.ts";
+import { shouldPreserveAgentExtraField } from "./agent-serializer.ts";
 import {
-	defaultInheritProjectContext,
-	defaultInheritSkills,
-	defaultSystemPromptMode,
 	type AgentConfig,
 	type AgentSource,
 	type ChainConfig,
 	type ChainDiscoveryDiagnostic,
+	defaultInheritProjectContext,
+	defaultInheritSkills,
+	defaultSystemPromptMode,
 } from "./agent-types.ts";
-import { normalizeMaxSubagentDepth } from "../shared/types.ts";
+import { parseChain, parseJsonChain } from "./chain-serializer.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { buildRuntimeName, parsePackageName } from "./identity.ts";
 
 function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
 	const files: string[] = [];
@@ -51,7 +51,10 @@ function parseCommaSeparatedList(value: string | undefined): string[] | undefine
 export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
-	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
+	for (const filePath of listFilesRecursive(
+		dir,
+		(fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"),
+	)) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -78,26 +81,30 @@ export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig
 		const skills = parseCommaSeparatedList(skillStr);
 		const fallbackModels = parseCommaSeparatedList(frontmatter.fallbackModels);
 		const fallbackThinkingLevels = parseCommaSeparatedList(frontmatter.fallbackThinkingLevels);
-		const systemPromptMode = frontmatter.systemPromptMode === "replace"
-			? "replace"
-			: frontmatter.systemPromptMode === "append"
-				? "append"
-				: defaultSystemPromptMode(localName);
-		const inheritProjectContext = frontmatter.inheritProjectContext === "true"
-			? true
-			: frontmatter.inheritProjectContext === "false"
-				? false
-				: defaultInheritProjectContext(localName);
-		const inheritSkills = frontmatter.inheritSkills === "true"
-			? true
-			: frontmatter.inheritSkills === "false"
-				? false
-				: defaultInheritSkills();
-		const defaultContext = frontmatter.defaultContext === "fork"
-			? "fork" as const
-			: frontmatter.defaultContext === "fresh"
-				? "fresh" as const
-				: undefined;
+		const systemPromptMode =
+			frontmatter.systemPromptMode === "replace"
+				? "replace"
+				: frontmatter.systemPromptMode === "append"
+					? "append"
+					: defaultSystemPromptMode(localName);
+		const inheritProjectContext =
+			frontmatter.inheritProjectContext === "true"
+				? true
+				: frontmatter.inheritProjectContext === "false"
+					? false
+					: defaultInheritProjectContext(localName);
+		const inheritSkills =
+			frontmatter.inheritSkills === "true"
+				? true
+				: frontmatter.inheritSkills === "false"
+					? false
+					: defaultInheritSkills();
+		const defaultContext =
+			frontmatter.defaultContext === "fork"
+				? ("fork" as const)
+				: frontmatter.defaultContext === "fresh"
+					? ("fresh" as const)
+					: undefined;
 
 		let extensions: string[] | undefined;
 		if (frontmatter.extensions !== undefined) {
@@ -146,11 +153,17 @@ export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig
 	return agents;
 }
 
-export function loadChainsFromDir(dir: string, source: "user" | "project"): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
+export function loadChainsFromDir(
+	dir: string,
+	source: "user" | "project",
+): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
 	const chains = new Map<string, ChainConfig>();
 	const diagnostics: ChainDiscoveryDiagnostic[] = [];
 
-	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md") || fileName.endsWith(".chain.json"))) {
+	for (const filePath of listFilesRecursive(
+		dir,
+		(fileName) => fileName.endsWith(".chain.md") || fileName.endsWith(".chain.json"),
+	)) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -159,13 +172,14 @@ export function loadChainsFromDir(dir: string, source: "user" | "project"): { ch
 		}
 
 		try {
-			const chain = filePath.endsWith(".chain.json") ? parseJsonChain(content, source, filePath) : parseChain(content, source, filePath);
+			const chain = filePath.endsWith(".chain.json")
+				? parseJsonChain(content, source, filePath)
+				: parseChain(content, source, filePath);
 			const existing = chains.get(chain.name);
-			if (existing && existing.filePath.endsWith(".chain.json") && filePath.endsWith(".chain.md")) continue;
+			if (existing?.filePath.endsWith(".chain.json") && filePath.endsWith(".chain.md")) continue;
 			chains.set(chain.name, chain);
 		} catch (error) {
 			diagnostics.push({ source, filePath, error: error instanceof Error ? error.message : String(error) });
-			continue;
 		}
 	}