@bastani/atomic 0.6.3 → 0.6.4

package/dist/sdk/runtime/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EACV,kBAAkB,EAElB,aAAa,EAKb,SAAS,EAET,YAAY,EAEZ,kBAAkB,EAInB,MAAM,aAAa,CAAC;AAwErB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAa5C,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,iBAAiB;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAoDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,SAAS,CAgB1D;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,OAAO,CAKtD;AAyBD;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAuFD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAejC;AAMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmFf;AAoDD,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAOvE;AA2OD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CA0CrE;AAOD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAClC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAuB5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,CACA,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC3C,MAAM,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAChC,MAAM,IAAI,CA0BZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAChC,MAAM,IAAI,CAwBZ;AAsFD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,EAAE,CAMV;AAED,KAAK,4BAA4B,GAAG,IAAI,CACtC,kBAAkB,CAAC,SAAS,CAAC,EAC7B,aAAa,GAAG,iBAAiB,CAClC,CAAC;AAEF,UAAU,sBAAsB;IAC9B,aAAa,EAAE,4BAA4B,CAAC;IAC5C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAC5C,kBAAkB,CAAC,EAAE,MAAM,GAC1B,sBAAsB,CAsBxB;AAomBD;;;;;;;;;GASG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,kBAAkB,GAAG,SAAS,GAC1E,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgKf"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/executor.ts"],"names":[],"mappings":"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"}

package/dist/sdk/workflows/builtin/deep-research-codebase/claude/index.d.ts

@@ -2,33 +2,44 @@
  * deep-research-codebase / claude
  *
  * A deterministically-orchestrated, distributed codebase researcher built on
- * the Claude Agent SDK's native sub-agent dispatch. Specialist sub-agents
- * (codebase-locator / codebase-pattern-finder / codebase-analyzer /
- * codebase-online-researcher / codebase-research-locator /
- * codebase-research-analyzer) are spawned as separate headless `ctx.stage()`
- * calls — each binds the SDK's `agent` option to the desired specialist
- * instead of relying on a coordinator agent that dispatches them via the
- * `@"name (agent)"` prompt syntax.
+ * the Claude Agent SDK with **batched** Task-tool fan-out. Specialist
+ * sub-agents (codebase-locator / codebase-pattern-finder / codebase-analyzer
+ * / codebase-online-researcher) run inside batch sessions: each batch is a
+ * single `ctx.stage()` whose orchestrator turn dispatches up to
+ * MAX_TASKS_PER_BATCH (≈10) specialists in parallel via the Task tool.
+ * Research-history specialists (codebase-research-locator /
+ * codebase-research-analyzer) remain as their own small pipeline since they
+ * have a strict sequential dependency and run only twice per workflow.
  *
- * Why SDK primitives instead of in-prompt orchestration:
+ * Why batched Task-tool dispatch instead of one ctx.stage per specialist:
  *
- *   • Each specialist runs in an ISOLATED conversation. The locator's giant
- *     file index doesn't pollute the analyzer's context window, and the
- *     online-researcher doesn't see the analyzer's reasoning at all. This is
- *     `multi-agent-patterns` swarm-style isolation, not orchestrator-style.
+ *   • SDK-level fan-out scales by codebase size — at 5K LOC per partition
+ *     and 4 specialists per partition, a 750K-LOC codebase would otherwise
+ *     spawn 600 `claude` subprocesses. Batches of 10 cap that at ~60 SDK
+ *     sessions, with each session internally fanning out via Task tool.
  *
- *   • There is no orchestrator turn whose context grows linearly with the
- *     number of specialists. Token cost per partition is bounded by the four
- *     specialists' independent prompts — adding more partitions scales
- *     cleanly because every fan-out is a fresh session.
+ *   • ~10 parallel Task tool sub-agents per single message is the practical
+ *     ceiling before rate limits, context contention, and degraded
+ *     coordination kick in (no documented hard cap; tunable in
+ *     helpers/batching.ts).
  *
- *   • Failure of one specialist does not abort the partition mid-thought —
- *     the runtime fails the stage, but its siblings' outputs are still on
- *     disk and the aggregator can continue with whatever completed.
+ *   • Sub-agents still run in ISOLATED contexts — Task tool gives every
+ *     sub-agent its own conversation window, so the locator's file index
+ *     doesn't pollute the analyzer the way it would inside a shared
+ *     conversation. (multi-agent-patterns swarm isolation.)
  *
- *   • The synthesis step that combines specialist outputs is plain TypeScript
- *     (`renderExplorerMarkdown` in helpers/scratch.ts) — no extra LLM call
- *     just to concatenate four markdown sections.
+ *   • The orchestrator's turn does NOT grow linearly with sub-agent count:
+ *     each Task sub-agent writes its verbatim findings to a per-task scratch
+ *     file and returns just "DONE", so the orchestrator collects N short
+ *     confirmations rather than N transcripts (filesystem-context skill).
+ *
+ *   • Failure isolation is preserved at two levels: (1) Promise.allSettled
+ *     around the batches means one failed batch doesn't abort siblings;
+ *     (2) inside a batch, the orchestrator is instructed not to retry
+ *     failed Task sub-agents — the synthesis step tolerates missing files.
+ *
+ *   • Synthesis remains plain TypeScript (`renderExplorerMarkdown` in
+ *     helpers/scratch.ts) — no extra LLM call just to concatenate sections.
  *
  * Topology:
  *
@@ -38,23 +49,27 @@
  *                                       │
  *                                       ▼
  *   ┌──────────────────────────────────────────────────────────────────────┐
- *   │  Per-partition (Promise.all over partitions, all stages headless):    │
- *   │                                                                       │
- *   │     locator-i      ∥   pattern-finder-i        (Layer 1, parallel)    │
- *   │            │                                                          │
- *   │            ▼                                                          │
- *   │     analyzer-i     ∥   online-researcher-i     (Layer 2, parallel)    │
- *   │            │                                                          │
- *   │            ▼                                                          │
- *   │     deterministic write to scratch file (TS helper, no LLM)           │
+ *   │  Wave 1 (locator + pattern-finder, no inter-deps):                    │
+ *   │     wave1-batch-1  ∥  wave1-batch-2  ∥  ...  (Promise.allSettled)     │
+ *   │       └── each batch session: orchestrator dispatches ≤10 Task        │
+ *   │           sub-agents in one assistant message; each writes to disk    │
+ *   │                                       │                                │
+ *   │                                       ▼                                │
+ *   │  TS reads locator-i.md files from disk for Layer 2 prompts            │
+ *   │                                       │                                │
+ *   │                                       ▼                                │
+ *   │  Wave 2 (analyzer + online-researcher, embed locator output):         │
+ *   │     wave2-batch-1  ∥  wave2-batch-2  ∥  ...  (Promise.allSettled)     │
+ *   │                                       │                                │
+ *   │                                       ▼                                │
+ *   │  Per partition i: TS reads 4 specialist files + writes explorer-i.md  │
  *   └──────────────────────────────────────────────────────────────────────┘
  *                                       │
  *                                       ▼
  *                                  aggregator (visible)
  *
- * Specialist stages run headless (in-process via the Agent SDK's `query()`),
- * so they are transparent to the workflow graph. The visible nodes are just:
- *   parent → [codebase-scout] → aggregator
+ * Batch sessions are headless (transparent to the workflow graph). Visible
+ * nodes: parent → [codebase-scout] → aggregator.
  */
 declare const _default: import("../../../index.ts").WorkflowDefinition<"claude", readonly [{
     readonly name: "prompt";

package/dist/sdk/workflows/builtin/deep-research-codebase/claude/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;;;;;;;AAsCH,wBAwTa"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;;;;;;;AAuFH,wBAwZa"}

package/dist/sdk/workflows/builtin/deep-research-codebase/copilot/index.d.ts

@@ -1,29 +1,31 @@
 /**
  * deep-research-codebase / copilot
  *
- * Copilot replica of the Claude deep-research-codebase workflow. Specialist
- * sub-agents are dispatched as separate headless `ctx.stage()` calls — each
- * binds the SDK's session to a single named agent via `sessionOpts: { agent }`,
- * which is the SDK-native way to spawn a sub-agent on Copilot.
+ * Copilot replica of the Claude deep-research-codebase workflow with the
+ * same **batched** Task-tool fan-out. Specialist sub-agents run inside batch
+ * sessions: each batch is a single `ctx.stage()` whose orchestrator turn
+ * dispatches up to MAX_TASKS_PER_BATCH (≈10) specialists in parallel via
+ * Copilot's `agent` tool (alias `Task`, see Copilot subagents docs).
+ * Research-history specialists remain as their own sequential sub-pipeline.
  *
- * Copilot-specific concerns baked in (see references/failure-modes.md):
+ * See claude/index.ts for the full design rationale and topology diagram.
  *
- *   • F5 — every `ctx.stage()` is a FRESH session. Each specialist receives
- *     everything it needs (research question, scope, scout overview, and —
- *     for layer-2 specialists — verbatim locator output) in its first prompt.
+ * Copilot-specific concerns baked in (see references/failure-modes.md):
  *
  *   • F1 — Copilot's last assistant turn is often empty when the agent ends
- *     on a tool call. We use `getAssistantText()` (canonical concatenation
- *     of every top-level non-empty assistant turn, ignoring sub-agent
- *     `parentToolCallId` traffic) instead of `.at(-1).data.content`.
+ *     on a tool call. Batch sessions don't read `getAssistantText` for the
+ *     orchestrator output (sub-agents write to disk; the orchestrator's text
+ *     reply is just a short tally), so this is no longer load-bearing for
+ *     Stage 2 — but the history pipeline still depends on it.
  *
- *   • F6 — every prompt explicitly requires trailing prose AFTER any tool
- *     call so `getAssistantText()` and downstream `transcript()` reads are
- *     never empty.
+ *   • F5 — every `ctx.stage()` is a FRESH session. Batch session prompts
+ *     embed everything the orchestrator needs (per-task subagent_type,
+ *     output path, and verbatim specialist prompt) in the first turn.
  *
- *   • F9 — `s.save()` receives `SessionEvent[]` from `s.session.getMessages()`.
+ *   • F6 — orchestrator prompt requires a single-line tally as the trailing
+ *     turn so transcripts are never empty.
  *
- * See claude/index.ts for the full design rationale and topology diagram.
+ *   • F9 — `s.save()` receives `SessionEvent[]` from `s.session.getMessages()`.
  */
 declare const _default: import("../../../index.ts").WorkflowDefinition<"copilot", readonly [{
     readonly name: "prompt";

package/dist/sdk/workflows/builtin/deep-research-codebase/copilot/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/copilot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;;AA6CH,wBA4Ra"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/copilot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;;;;;AAiFH,wBAkXa"}

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/batching.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Batching primitives for the deep-research-codebase workflow.
+ *
+ * The workflow caps SDK-level fan-out by grouping specialist invocations into
+ * "batch sessions" — one `ctx.stage()` per batch. Inside each batch session,
+ * the default Claude Code agent dispatches up to MAX_TASKS_PER_BATCH
+ * sub-agents in parallel via the Task tool. This keeps the parallel SDK
+ * subprocess count proportional to (specialists / 10) rather than to
+ * specialists itself, which scales linearly with codebase size.
+ *
+ * The per-message Task fan-out cap is empirical: there's no documented hard
+ * limit, but ~10 parallel sub-agents per single message is the reliable
+ * ceiling before rate limits, context contention, and degraded coordination
+ * kick in. Lower this if you see batch sessions stalling or returning
+ * partial completions; raise it only after measuring.
+ */
+import type { PartitionUnit } from "./scout.ts";
+/** Maximum Task-tool sub-agent dispatches per single batch session. */
+export declare const MAX_TASKS_PER_BATCH = 10;
+/** Specialist kinds that share Layer 1 (no inter-task dependencies). */
+export type Layer1Kind = "locator" | "pattern-finder";
+/** Specialist kinds that share Layer 2 (depend on Layer 1 locator output). */
+export type Layer2Kind = "analyzer" | "online-researcher";
+/** Maps a specialist kind to the Claude agent name it dispatches as. */
+export declare const SUBAGENT_TYPE: Record<Layer1Kind | Layer2Kind, string>;
+export type Layer1Task = {
+    kind: Layer1Kind;
+    partitionIndex: number;
+    partition: PartitionUnit[];
+    /** Absolute path the sub-agent must write its verbatim findings to. */
+    outputPath: string;
+};
+export type Layer2Task = {
+    kind: Layer2Kind;
+    partitionIndex: number;
+    partition: PartitionUnit[];
+    outputPath: string;
+    /** Verbatim locator text for this partition, embedded into the prompt. */
+    locatorOutput: string;
+};
+/** Split a flat task list into fixed-size chunks (last chunk may be smaller). */
+export declare function chunkBatches<T>(items: T[], size?: number): T[][];
+//# sourceMappingURL=batching.d.ts.map

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/batching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/helpers/batching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,mBAAmB,CAAC;AAE1D,wEAAwE;AACxE,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,UAAU,GAAG,UAAU,EAAE,MAAM,CAKjE,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,GAAE,MAA4B,GACjC,CAAC,EAAE,EAAE,CAOP"}

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/prompts.d.ts

@@ -103,4 +103,34 @@ export declare function buildAggregatorPrompt(opts: {
     scoutOverview: string;
     historyOverview: string;
 }): string;
+/**
+ * Wrap a specialist prompt with the "write to file, reply with token only"
+ * envelope. The envelope is what the orchestrator hands to the Task tool's
+ * `prompt` parameter — the inner specialist prompt is built by the existing
+ * `buildLocatorPrompt` / `buildPatternFinderPrompt` / etc. and embedded
+ * verbatim so prompt semantics stay identical to the unbatched workflow.
+ */
+export declare function wrapPromptForTaskDispatch(opts: {
+    specialistPrompt: string;
+    outputPath: string;
+    agentLabel: string;
+}): string;
+/**
+ * Build the orchestrator prompt for a batch session. The orchestrator's job
+ * is purely deterministic dispatch — fire one Task tool call per task in
+ * **a single assistant message** so they execute in parallel, then report a
+ * one-line tally. It must NOT inline sub-agent findings, paraphrase the
+ * embedded prompts, or retry failures — siblings still run and synthesis
+ * tolerates missing files.
+ */
+export declare function buildBatchOrchestratorPrompt(opts: {
+    wave: 1 | 2;
+    batchIndex: number;
+    totalBatches: number;
+    tasks: Array<{
+        subagentType: string;
+        prompt: string;
+        outputPath: string;
+    }>;
+}): string;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/helpers/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUpD;AAqBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,aAAa,EAAE,EAAE,CAAC;CACrC,GAAG,MAAM,CAyDT;AAeD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAuET;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAwDT;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CA0FT;AAED,qFAAqF;AACrF,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CA2ET;AAMD,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAoDT;AAED,mFAAmF;AACnF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAuDT;AAMD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE;QACb,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,aAAa,EAAE,CAAC;KAC5B,EAAE,CAAC;IACJ,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAwIT"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/helpers/prompts.ts"],"names":[],"mappings":"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"}

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/scout.d.ts

@@ -3,7 +3,8 @@
  *
  * Responsibilities:
  *   1. Discover the codebase root (git toplevel, falling back to cwd).
- *   2. List all source files, respecting .gitignore when in a git repo.
+ *   2. List all source files, honoring `.gitignore` via git ls-files in repos
+ *      and via `rg --files` in non-repo directories that still have one.
  *   3. Count lines of code per file using batched `wc -l`.
  *   4. Render a compact directory tree (depth-bounded) for prompt context.
  *   5. Build "partition units" by aggregating LOC at depth-1, then drilling

package/dist/sdk/workflows/builtin/deep-research-codebase/helpers/scout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scout.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/helpers/scout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+BH,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,MAAM,CAUxC;AAmMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAiBzD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,MAAM,GACZ,aAAa,EAAE,EAAE,CAwBnB"}
+{"version":3,"file":"scout.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/helpers/scout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4JH,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,MAAM,CAexC;AA0OD;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAiBzD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,MAAM,GACZ,aAAa,EAAE,EAAE,CAwBnB"}

package/dist/sdk/workflows/builtin/deep-research-codebase/opencode/index.d.ts

@@ -1,29 +1,31 @@
 /**
  * deep-research-codebase / opencode
  *
- * OpenCode replica of the Claude deep-research-codebase workflow. Specialist
- * sub-agents are dispatched as separate headless `ctx.stage()` calls — each
- * call passes `agent: "<name>"` to `s.client.session.prompt()` directly,
- * which is OpenCode's SDK-native way to route a turn to a sub-agent.
+ * OpenCode replica of the Claude deep-research-codebase workflow with the
+ * same **batched** Task-tool fan-out. Specialist sub-agents run inside batch
+ * sessions: each batch is a single `ctx.stage()` whose orchestrator turn
+ * dispatches up to MAX_TASKS_PER_BATCH (≈10) specialists in parallel via
+ * OpenCode's `task` tool. The default agent must have `task: "allow"` in
+ * its permission ruleset (see `.opencode/agents/worker.md` for the
+ * canonical example).
+ *
+ * See claude/index.ts for the full design rationale and topology diagram.
  *
  * OpenCode-specific concerns baked in (see references/failure-modes.md):
  *
- *   • F5 — every `ctx.stage()` is a FRESH session. Each specialist receives
- *     everything it needs (research question, scope, scout overview, and —
- *     for layer-2 specialists — verbatim locator output) in its first prompt.
+ *   • F3 — `result.data!.parts` is heterogenous. Batch sessions don't read
+ *     `extractResponseText` for orchestrator output (sub-agents write to
+ *     disk; the orchestrator reply is just a short tally), but the history
+ *     pipeline still uses it.
  *
- *   • F3 — `result.data!.parts` is a heterogenous array (text/tool/reasoning/
- *     file parts). Use `extractResponseText()` to filter to text parts only;
- *     concatenating raw `parts` produces `[object Object]` strings.
+ *   • F5 — every `ctx.stage()` is a FRESH session. Batch session prompts
+ *     embed everything the orchestrator needs in the first turn.
  *
- *   • F6 — every prompt explicitly requires trailing prose so transcripts and
- *     `extractResponseText()` reads are never empty.
+ *   • F6 — orchestrator prompt requires a single-line tally as the trailing
+ *     turn so transcripts are never empty.
  *
  *   • F9 — `s.save()` receives the unwrapped `{ info, parts }` payload from
- *     `result.data!`; passing the full `result` or raw `result.data!.parts`
- *     breaks downstream `transcript()` reads.
- *
- * See claude/index.ts for the full design rationale and topology diagram.
+ *     `result.data!`.
  */
 declare const _default: import("../../../index.ts").WorkflowDefinition<"opencode", readonly [{
     readonly name: "prompt";

package/dist/sdk/workflows/builtin/deep-research-codebase/opencode/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/opencode/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;;AAsCH,wBA8Ua"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/sdk/workflows/builtin/deep-research-codebase/opencode/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;;;;;AAwEH,wBA0Za"}

package/dist/services/config/additional-instructions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Default seed contents for `~/.atomic/AGENTS.md`. Markdown-format because
+ * Copilot CLI / OpenCode read instruction files as Markdown; Claude's
+ * `--append-system-prompt-file` accepts arbitrary text and is happy with
+ * Markdown too.
+ */
+export declare const ADDITIONAL_INSTRUCTIONS = "This section provides you with **CRITICAL** instructions that will help you to maintain coherency in long-horizon context-heavy tasks and better support users:\n\n<user_experience>\n- Always ask clarifying questions if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants.\n- If you find yourself circling in thought and asking what the user \"really\" wants, stop and ask the user for clarification. It's better to ask than to guess.\n</user_experience>\n\n<tool_policies>\nFollow these tool selection and usage rules in order of priority:\n\n1. **Browser search and automation**:\n\nUse playwright-cli (refer to playwright-cli skill) for ALL browser automation tasks, including web research, form filling, and UI interaction:\n   - ALWAYS load the playwright-cli skill before usage with the Skill tool.\n   - ALWAYS ASSUME playwright-cli is installed. If the `playwright-cli` command fails, fall back to `bunx playwright-cli`.\n\n2. **Structural code search**:\n\nYou are operating in an environment where ast-grep is installed. For any code search that requires understanding of syntax or code structure, you should default to using `ast-grep --lang [language] -p '<pattern>'`. Rely on your ast-grep skill for best practices. Adjust the --lang flag as needed for the specific programming language. Avoid using text-only search tools unless a plain-text search is explicitly requested.\n\n3. **Testing**: ALWAYS invoke your test-driven-development skill BEFORE creating or modifying any tests.\n\n4. **Sub-agent Orchestration**: You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either `Agent` or `Task`.\n\nAll non-trivial operations should be delegated to sub-agents. You should delegate research and codebase understanding tasks to codebase-analyzer, codebase-locator and codebase-pattern-locator sub-agents.\n\nYou should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the `aws` CLI, using the `gh` CLI, digging through logs to `Bash` sub-agents.\n\nYou should use separate sub-agents for separate tasks, and you may launch them in parallel - but do not delegate multiple tasks that are likely to have significant overlap to separate sub-agents.\n\nIMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.\nIMPORTANT: sometimes sub-agents will take a long time. DO NOT attempt to do the job yourself while waiting for the sub-agent to respond. Instead, use the time to plan out your next steps, or ask the user follow-up questions to clarify the task requirements.\n\nIf you have not already been explicitly given a task, you should ask the user what task they would like for you to work on - do not assume or begin working on a ticket automatically.\n\n5. **Debugging**: When a user asks about debugging, ALWAYS spawn a debugger sub-agent first.\n   - Do not attempt to debug or analyze code yourself without first consulting the debugger sub-agent.\n   - Explain the debugger's insights to the user clearly and concisely.\n   - Once the user confirms, implement the necessary code changes based on those insights.\n   - If the user has follow-up questions, spawn additional debugger and research sub-agents as needed.\n</tool_policies>\n\n<engineering_principles>\nSoftware engineering is fundamentally about **managing complexity** to prevent technical debt. When implementing features, prioritize maintainability and testability over cleverness.\n\n**Core Principles:**\n- **Single Responsibility (SRP):** Every class and module must have exactly one reason to change. If a unit does more than one job, split it.\n- **Dependency Inversion (DIP):** Depend on abstractions (interfaces), never on concrete implementations. Inject dependencies; do not instantiate them internally.\n- **KISS:** Keep solutions as simple as possible. Reject unnecessary abstraction layers.\n- **YAGNI:** Do not build generic frameworks or add configurability for hypothetical future requirements. Solve the problem at hand.\n\n**Design Patterns** \u2014 Use Gang of Four patterns as a shared vocabulary for recurring problems:\n- **Creational:** Use _Factory_ or _Builder_ to abstract complex object creation and isolate construction logic.\n- **Structural:** Use _Adapter_ or _Facade_ to decouple core logic from external APIs or legacy code.\n- **Behavioral:** Use _Strategy_ to make algorithms interchangeable. Use _Observer_ for event-driven communication between decoupled components.\n\n**Architectural Hygiene:**\n- **Separation of Concerns:** Isolate business logic (Domain) from infrastructure (Database, UI, networking). Never let infrastructure details leak into domain code.\n- **Anti-Pattern Detection:** Watch for **God Objects** (classes with too many responsibilities) and **Spaghetti Code** (tightly coupled, hard-to-follow control flow). Refactor them using polymorphism and clear interfaces.\n\nCreate **seams** in your software using interfaces and abstractions. This ensures code remains flexible, testable, and capable of evolving independently.\n</engineering_principles>\n";
+/** Path to the global seed: `~/.atomic/AGENTS.md`. */
+export declare function getGlobalAdditionalInstructionsPath(): string;
+/** Path to the per-project override: `<projectRoot>/.atomic/AGENTS.md`. */
+export declare function getLocalAdditionalInstructionsPath(projectRoot: string): string;
+/**
+ * Resolve the effective additional-instructions file for a project.
+ *
+ * Returns the project-local override if it exists, otherwise the global
+ * seed. Returns `undefined` only if neither exists — which can happen on a
+ * fresh dev checkout that hasn't yet run `autoSyncIfStale` (the seed write).
+ *
+ * Sync `existsSync` is intentional: this is called on every spawn and we
+ * want the cost to be a single `stat` per provider, not an `await`.
+ */
+export declare function resolveAdditionalInstructionsPath(projectRoot: string): string | undefined;
+/**
+ * Read the resolved file's contents, or `undefined` if no file exists.
+ * Used by SDK paths that need the raw string (Claude `systemPrompt.append`,
+ * Copilot `systemMessage.content`).
+ */
+export declare function resolveAdditionalInstructionsContent(projectRoot: string): Promise<string | undefined>;
+/**
+ * Write `~/.atomic/AGENTS.md` with {@link ADDITIONAL_INSTRUCTIONS} if (and
+ * only if) the file is missing. Idempotent and safe to call on every CLI
+ * start; the user is free to edit the file afterward without atomic
+ * clobbering their changes on upgrade.
+ */
+export declare function seedGlobalAdditionalInstructions(): Promise<void>;
+/**
+ * Ensure the resolved `AGENTS.md` is wired into
+ * `<projectRoot>/.opencode/opencode.json`'s `instructions` array.
+ *
+ * OpenCode (CLI and SDK alike) consumes the `instructions` field from
+ * project config; there's no flag or env var that injects an instruction
+ * file. Strategy:
+ *   - Resolve the effective path via {@link resolveAdditionalInstructionsPath}.
+ *   - Strip any prior atomic-managed entries (matches `.atomic/AGENTS.md`).
+ *   - Append the absolute resolved path. Absolute is fine because OpenCode
+ *     happily takes them; we don't expect the user to commit this entry
+ *     across machines (and even if they do, the next run reconciles it).
+ *   - When nothing resolves (file truly missing on this machine), we still
+ *     run the cleanup pass so a previously-seeded entry doesn't leak.
+ *
+ * No-op on `.opencode/opencode.json` files we don't own (i.e. we never
+ * create the file ourselves; `applyManagedOnboardingFiles` is responsible
+ * for that). When the file is absent, this helper simply returns.
+ *
+ * Concurrency: this is a read-modify-write on `opencode.json` with no
+ * cross-process lock. Two concurrent `atomic` invocations (e.g. parallel
+ * `chat -a opencode` sessions, or a workflow racing the chat startup) can
+ * interleave reads and writes — A reads, B reads, A writes, B writes —
+ * and B's write loses any user-managed `instructions` entries A added in
+ * between. The window is tiny (a single `readFile` + `JSON.parse` +
+ * `writeFile`) and the damage is bounded: only concurrent edits to
+ * non-atomic entries are at risk, and the next reconcile pass restores
+ * the atomic entry. If this becomes a real problem in practice, wrap the
+ * read-modify-write in a file lock (`proper-lockfile` or similar).
+ */
+export declare function reconcileOpencodeInstructions(projectRoot: string): Promise<void>;
+//# sourceMappingURL=additional-instructions.d.ts.map

package/dist/services/config/additional-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"additional-instructions.d.ts","sourceRoot":"","sources":["../../../src/services/config/additional-instructions.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2nKA8DnC,CAAC;AAUF,sDAAsD;AACtD,wBAAgB,mCAAmC,IAAI,MAAM,CAE5D;AAED,2EAA2E;AAC3E,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;GAIG;AACH,wBAAsB,oCAAoC,CACxD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED;;;;;GAKG;AACH,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,IAAI,CAAC,CAKtE;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",
@@ -85,6 +85,8 @@
     "@opentui/react": "0.1.102",
     "commander": "^14.0.3",
     "ignore": "^7.0.5",
+    "ignore-by-default": "^2.1.0",
+    "linguist-languages": "^9.3.2",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },

package/src/cli.ts

@@ -297,6 +297,22 @@ Examples:
             process.exit(exitCode);
         });
 
+    // ── Internal: Claude Subagent / TeammateIdle lifecycle hook handler ───
+    program
+        .command("_claude-inflight-hook", { hidden: true })
+        .description("Internal: Claude Code Subagent/TeammateIdle lifecycle hook handler — touches/removes inflight markers, or waits for them to drain")
+        .argument("<mode>", "start (SubagentStart), stop (SubagentStop), or wait (TeammateIdle)")
+        .action(async (mode: string) => {
+            if (mode !== "start" && mode !== "stop" && mode !== "wait") {
+                // Silent exit-0 to match the handler's contract — never red
+                // hook errors in transcripts.
+                process.exit(0);
+            }
+            const { claudeInflightHookCommand } = await import("./commands/cli/claude-inflight-hook.ts");
+            const exitCode = await claudeInflightHookCommand(mode);
+            process.exit(exitCode);
+        });
+
     // ── Completions command ────────────────────────────────────────────────
     program
         .command("completions")
@@ -373,7 +389,8 @@ async function main(): Promise<void> {
                 argv[0] === "_footer" ||
                 argv[0] === "_claude-stop-hook" ||
                 argv[0] === "_claude-ask-hook" ||
-                argv[0] === "_claude-session-start-hook";
+                argv[0] === "_claude-session-start-hook" ||
+                argv[0] === "_claude-inflight-hook";
 
             if (!isInfoCommand) {
                 const { autoSyncIfStale } = await import(

package/src/commands/cli/chat/index.ts

@@ -16,6 +16,10 @@ import { mkdir, writeFile, rm } from "node:fs/promises";
 import { AGENT_CONFIG, type AgentKey } from "../../../services/config/index.ts";
 import { getProviderOverrides } from "../../../services/config/atomic-config.ts";
 import { getCopilotScmDisableFlags } from "../../../services/config/scm-sync.ts";
+import {
+  resolveAdditionalInstructionsPath,
+} from "../../../services/config/additional-instructions.ts";
+import { dirname } from "node:path";
 import { ensureProjectSetup } from "../init/index.ts";
 import { COLORS } from "../../../theme/colors.ts";
 import { isCommandInstalled } from "../../../services/system/detect.ts";
@@ -88,7 +92,32 @@ export async function buildAgentArgs(
   const scmFlags =
     agentType === "copilot" ? await getCopilotScmDisableFlags(projectRoot) : [];
 
-  return [...flags, ...scmFlags, ...passthroughArgs];
+  // Claude Code is the only one with a flag that takes an instructions file.
+  // OpenCode and Copilot CLI consume the file via config (.opencode/opencode.json
+  // `instructions` array) and env var (`COPILOT_CUSTOM_INSTRUCTIONS_DIRS`)
+  // respectively — see `applyManagedOnboardingFiles` and `chatCommand`'s env
+  // build. Skipped silently when no file resolves so the CLI still spawns
+  // even on a fresh checkout that hasn't run `autoSyncIfStale` yet.
+  const instructionsFlags: string[] = [];
+  if (agentType === "claude") {
+    const path = resolveAdditionalInstructionsPath(projectRoot);
+    if (path) instructionsFlags.push("--append-system-prompt-file", path);
+  }
+
+  return [...flags, ...scmFlags, ...instructionsFlags, ...passthroughArgs];
+}
+
+/**
+ * Directory containing the resolved additional-instructions `AGENTS.md`,
+ * or `undefined` if no file resolves. Used to set
+ * `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` on Copilot spawns — Copilot loads
+ * `AGENTS.md` from each dir on that list.
+ */
+export function getAdditionalInstructionsDir(
+  projectRoot: string,
+): string | undefined {
+  const path = resolveAdditionalInstructionsPath(projectRoot);
+  return path ? dirname(path) : undefined;
 }
 
 function generateChatId(): string {
@@ -213,12 +242,33 @@ export async function chatCommand(options: ChatCommandOptions = {}): Promise<num
   const overrides = await getProviderOverrides(agentType, projectRoot);
   // ATOMIC_AGENT must be baked into the launcher env so the agent CLI
   // and anything it spawns can read it from process start.
-  const envVars = {
+  const envVars: Record<string, string> = {
     ...config.env_vars,
     ...overrides.envVars,
     ATOMIC_AGENT: agentType,
   };
 
+  // Copilot CLI loads `AGENTS.md` from any directory listed in
+  // `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` (comma-separated). Point it at the
+  // resolved AGENTS.md's parent dir so our additional instructions get
+  // appended to the persona without touching the project's `AGENTS.md`.
+  // Skip dirs containing a comma — Copilot CLI has no documented escape
+  // syntax for the list separator, so a comma in the path (rare on POSIX,
+  // possible in Windows usernames) would be misparsed as a list boundary.
+  if (agentType === "copilot") {
+    const dir = getAdditionalInstructionsDir(projectRoot);
+    if (dir && dir.includes(",")) {
+      console.error(
+        `${COLORS.yellow}Warning: skipping COPILOT_CUSTOM_INSTRUCTIONS_DIRS entry because the path contains a comma, which Copilot CLI cannot escape: ${dir}${COLORS.reset}`,
+      );
+    } else if (dir) {
+      const existing = envVars.COPILOT_CUSTOM_INSTRUCTIONS_DIRS;
+      envVars.COPILOT_CUSTOM_INSTRUCTIONS_DIRS = existing
+        ? `${existing},${dir}`
+        : dir;
+    }
+  }
+
   // ── No TTY: tmux attach requires a real terminal ──
   if (!process.stdin.isTTY) {
     return spawnDirect(cmd, projectRoot, envVars);