@bastani/atomic 0.8.24-alpha.2 → 0.8.24-alpha.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.8.24-alpha.3] - 2026-06-03
+
+### Added
+
+- Added `/exit` as a built-in interactive slash command alias for graceful app shutdown from the main chat.
+
 ## [0.8.24-alpha.2] - 2026-06-03
 
 ### Added

package/README.md

@@ -186,7 +186,8 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files (themes hot-reload automatically) |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
-| `/quit` | Quit pi |
+| `/exit` | Exit Atomic |
+| `/quit` | Quit Atomic |
 
 ### Keyboard Shortcuts
 

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.8.24-alpha.3] - 2026-06-03
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.24-alpha.3 prerelease.
+
 ## [0.8.24-alpha.2] - 2026-06-03
 
 ### Changed

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.24-alpha.2",
+  "version": "0.8.24-alpha.3",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.24-alpha.3] - 2026-06-03
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.24-alpha.3 prerelease.
+
 ## [0.8.24-alpha.2] - 2026-06-03
 
 ### Changed

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.24-alpha.2",
+  "version": "0.8.24-alpha.3",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.8.24-alpha.3] - 2026-06-03
+
+### Added
+
+- Synced upstream dynamic fanout and acceptance-gate support for subagent chains, including `.chain.json` discovery, named chain outputs, structured subagent output capture, workflow graph status rendering, and explicit acceptance contracts.
+
+### Fixed
+
+- Synced the upstream final-output fix so multi-part assistant responses use the last non-empty text part as the subagent's final output.
+
 ## [0.8.24-alpha.2] - 2026-06-03
 
 ### Changed

package/dist/builtin/subagents/README.md

@@ -250,7 +250,7 @@ Skip this section until you want exact syntax.
 | `/run <agent> [task]` | Run one agent; omit the task for self-contained agents |
 | `/chain agent1 "task1" -> agent2 "task2"` | Run agents in sequence |
 | `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel |
-| `/run-chain <chainName> -- <task>` | Launch a saved `.chain.md` workflow |
+| `/run-chain <chainName> -- <task>` | Launch a saved `.chain.md` or `.chain.json` workflow |
 | `/subagents-doctor` | Show read-only setup diagnostics |
 
 Commands validate agent names locally, support tab completion, and send results back into the conversation.
@@ -494,14 +494,14 @@ When `extensions` is present, it takes precedence over extension paths implied b
 
 ## Chain files
 
-Chains are reusable `.chain.md` workflows stored separately from agent files.
+Chains are reusable workflows stored separately from agent files. Use `.chain.md` for simple sequential saved chains. Use `.chain.json` when a chain needs dynamic fanout.
 
 | Scope | Path |
 |-------|------|
-| User | `~/.atomic/agent/chains/**/*.chain.md` |
-| Project | `.atomic/chains/**/*.chain.md` |
+| User | `~/.atomic/agent/chains/**/*.chain.md`, `~/.atomic/agent/chains/**/*.chain.json` |
+| Project | `.atomic/chains/**/*.chain.md`, `.atomic/chains/**/*.chain.json` |
 
-Nested subdirectories are discovered recursively. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
+Nested subdirectories are discovered recursively. If both `.chain.md` and `.chain.json` define the same parsed runtime chain name in the same scope, `.chain.json` wins. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
 Example:
 
@@ -512,23 +512,67 @@ description: Gather context then plan implementation
 ---
 
 ## scout
+phase: Context
+label: Map auth flow
+as: context
 output: context.md
 
 Analyze the codebase for {task}
 
 ## planner
+phase: Planning
+label: Implementation plan
 reads: context.md
 model: anthropic/claude-sonnet-4-5:high
 progress: true
 
-Create an implementation plan based on {previous}
+Create an implementation plan based on {outputs.context}
 ```
 
-Each `## agent-name` section is a step. Config lines such as `output`, `outputMode`, `reads`, `model`, `skills`, and `progress` go immediately after the header. A blank line separates config from task text.
+Each `.chain.md` `## agent-name` section is a step. Config lines such as `phase`, `label`, `as`, `outputSchema`, `output`, `outputMode`, `reads`, `model`, `skills`, and `progress` go immediately after the header. A blank line separates config from task text. In saved `.chain.md` files, `outputSchema` is a path to a JSON Schema file; direct tool calls and `.chain.json` files can pass the schema object inline.
 
 For `output`, `reads`, `skills`, and `progress`, chain behavior is three-state: omitted inherits from the agent, a value overrides, and `false` disables.
 
-Create chains by writing `.chain.md` files directly or with the `subagent({ action: "create", config: ... })` management action. Run them with natural language or:
+Use `phase` to group related work in status output, `label` for a readable step name, and `as` to store a successful step or parallel task result for later `{outputs.name}` references. Duplicate `as` names, invalid identifiers, and unknown output references fail before child execution.
+
+Dynamic fanout is available only through direct `subagent({ chain: [...] })` JSON or saved `.chain.json` files. It expands an array from a prior structured named output, runs one child template per item, and stores the ordered collection under `collect.as`. The source must be structured output; prose is never parsed. `expand.maxItems` is required, over-limit arrays fail, nested fanout and arbitrary expressions are not supported, and `.chain.md` has no dynamic syntax in this release.
+
+```json
+{
+  "name": "dynamic-review",
+  "description": "Find review targets, fan out reviewers, then synthesize.",
+  "chain": [
+    {
+      "agent": "scout",
+      "task": "Return {\"items\":[{\"path\":\"...\",\"reason\":\"...\"}]} via structured_output.",
+      "as": "targets",
+      "outputSchema": { "type": "object" }
+    },
+    {
+      "expand": {
+        "from": { "output": "targets", "path": "/items" },
+        "item": "target",
+        "key": "/path",
+        "maxItems": 12
+      },
+      "parallel": {
+        "agent": "reviewer",
+        "label": "Review {target.path}",
+        "task": "Review {target.path}. Reason: {target.reason}",
+        "outputSchema": { "type": "object" }
+      },
+      "collect": { "as": "reviews" },
+      "concurrency": 4
+    },
+    {
+      "agent": "worker",
+      "task": "Synthesize fixes from {outputs.reviews}"
+    }
+  ]
+}
+```
+
+Create simple `.chain.md` chains by writing files directly or with the `subagent({ action: "create", config: ... })` management action. Create dynamic `.chain.json` chains by writing the JSON file directly. Run saved chains with natural language or:
 
 ```text
 /run-chain scout-planner -- refactor authentication
@@ -543,6 +587,7 @@ Task templates support:
 | `{task}` | Original task from the first step. |
 | `{previous}` | Output from the prior step, or aggregated output from a parallel step. |
 | `{chain_dir}` | Path to the chain artifact directory. |
+| `{outputs.name}` | Text value from a prior step or completed parallel task with `as: "name"`. |
 
 Parallel outputs are aggregated with clear separators before being passed to the next step:
 
@@ -638,14 +683,49 @@ These are the parameters the LLM passes when it calls the `subagent` tool. Most
 
 // Chain with fan-out/fan-in
 { chain: [
-  { agent: "scout", task: "Gather context" },
+  { agent: "scout", task: "Gather context", phase: "Context", label: "Map code", as: "context" },
   { parallel: [
-    { agent: "worker", task: "Implement feature A from {previous}" },
-    { agent: "worker", task: "Implement feature B from {previous}" }
+    { agent: "worker", task: "Implement feature A from {outputs.context}", label: "Feature A", as: "featureA" },
+    { agent: "worker", task: "Implement feature B from {outputs.context}", label: "Feature B", as: "featureB" }
   ], concurrency: 2, failFast: true },
-  { agent: "reviewer", task: "Review all changes from {previous}" }
+  { agent: "reviewer", task: "Review {outputs.featureA} and {outputs.featureB}" }
 ]}
 
+// Dynamic fanout from structured output
+{ chain: [
+  {
+    agent: "scout",
+    task: "Return review targets as structured_output: { items: [{ path, reason }] }",
+    as: "targets",
+    outputSchema: { type: "object" }
+  },
+  {
+    expand: { from: { output: "targets", path: "/items" }, item: "target", key: "/path", maxItems: 12 },
+    parallel: { agent: "reviewer", task: "Review {target.path}. Reason: {target.reason}", outputSchema: { type: "object" } },
+    collect: { as: "reviews" },
+    concurrency: 4
+  },
+  { agent: "worker", task: "Synthesize fixes from {outputs.reviews}" }
+] }
+
+// Strict structured output for reliable handoff data
+{ chain: [
+  {
+    agent: "scout",
+    task: "Return the key files and risks for {task}",
+    as: "scan",
+    outputSchema: {
+      type: "object",
+      required: ["files", "risks"],
+      properties: {
+        files: { type: "array", items: { type: "string" } },
+        risks: { type: "array", items: { type: "string" } }
+      }
+    }
+  },
+  { agent: "planner", task: "Plan from this scan: {outputs.scan}" }
+] }
+
 // Worktree isolation
 { tasks: [
   { agent: "worker", task: "Implement auth" },
@@ -715,10 +795,10 @@ Agent definitions are not loaded into context by default. Management actions let
 | `outputMode` | `"inline" \| "file-only"` | `inline` | Return saved output inline or as a concise saved-file reference. `file-only` requires an `output` path. |
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all. |
 | `model` | string | agent default | Override model. |
-| `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. |
+| `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `outputMode`, `reads`, `progress`, `skill`, `model`, and `acceptance`. |
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
-| `chain` | array | - | Sequential and parallel chain steps. |
+| `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Steps and chain parallel tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`. |
 | `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
 | `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
 | `clarify` | boolean | true for chains | Show TUI preview/edit flow. |
@@ -730,12 +810,13 @@ Agent definitions are not loaded into context by default. Management actions let
 | `includeProgress` | boolean | false | Include full progress in result. |
 | `share` | boolean | false | Upload session export to GitHub Gist. |
 | `sessionDir` | string | derived | Override session log directory. |
+| `acceptance` | string/object/false | inferred | Override the run's inferred acceptance gates. Use `"auto"`, `"attested"`, `"checked"`, `"verified"`, `"reviewed"`, or `{ level: "none", reason: "..." }`. |
 
 `context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`. In multi-agent runs, if any requested agent has `defaultContext: fork` and the launch omits `context`, the whole invocation uses forked context; pass `context: "fresh"` when you intentionally want a fresh run.
 
 Use `outputMode: "file-only"` when a saved output may be large and the parent only needs a pointer. The returned text is a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Failed runs and save errors still return normal inline output for debugging. In chains, later `{previous}` steps receive the same compact reference when the prior step used file-only mode.
 
-Sequential and parallel chain tasks accept `agent`, `task`, `cwd`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`.
+Sequential and parallel chain tasks accept `agent`, `task`, `phase`, `label`, `as`, `outputSchema`, `cwd`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`. If `outputSchema` is present, the child must call `structured_output` with schema-valid JSON; prose-only completion or invalid JSON fails the step. Validated structured values are preserved on the step result, and `as` also exposes a compact text representation through `{outputs.name}`.
 
 Status and control actions:
 
@@ -905,13 +986,43 @@ Async runs write:
 
 `status.json` powers the widget and `subagent({ action: "status" })` output. `events.jsonl` contains wrapper events plus child Pi JSON events annotated with run and step metadata. `output-<n>.log` is a live human-readable tail. Fallback information is persisted so background runs are debuggable after completion.
 
+## Acceptance Gates
+
+Every run resolves an effective acceptance policy. Callers may omit `acceptance` for the inferred default, or set it on single runs, top-level parallel task items, chain steps, static parallel tasks, and dynamic fanout templates.
+
+```ts
+{
+  agent: "worker",
+  task: "Implement the fix",
+  acceptance: {
+    level: "verified",
+    criteria: ["Patch the bug without widening scope"],
+    evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"],
+    verify: [{ id: "focused", command: "npm test", timeoutMs: 120000 }]
+  }
+}
+```
+
+Accepted levels are `auto`, `none`, `attested`, `checked`, `verified`, and `reviewed`. `acceptance: "auto"` is the default. Read-only reviewer/scout tasks infer lightweight attestation, normal writer tasks infer checked evidence, and async/risky/dynamic writer contexts infer a reviewed gate. To disable gates, prefer `{ level: "none", reason: "..." }`.
+
+Acceptance provenance is stored separately from child prose:
+
+- `claimed`: child finished but did not provide structured evidence.
+- `attested`: child returned a structured acceptance report.
+- `checked`: runtime structural checks passed, such as required evidence and no staged files.
+- `verified`: configured runtime verification commands passed. Child-reported command success does not count.
+- `reviewed`: an independent reviewer result is present.
+- `rejected`: attestation, structural checks, verification, or review failed.
+
+For `attested` or stricter levels, the child prompt includes a standardized acceptance section and asks for a fenced `acceptance-report` JSON block. Explicit failed gates fail the run. Inferred gates are persisted for observability without breaking older calls that omit `acceptance`.
+
 ## Live progress
 
-Foreground runs show compact live progress for single, chain, and parallel modes: current tool, recent output, token counts, duration, activity freshness, and current-tool duration.
+Foreground runs show compact live progress for single, chain, and parallel modes: current tool, recent output, token counts, duration, activity freshness, current-tool duration, and chain graph metadata when available.
 
 Press `CTRL+O` to expand the full streaming view with complete output per step.
 
-Sequential chains show a flow line like `done scout → running planner`. Chains with parallel steps show per-step cards instead.
+Sequential chains show a flow line like `done scout → running planner`. Chains with parallel steps show per-step cards instead. Chain status uses `label` and `phase` metadata when present, while falling back to agent names for older chains.
 
 ## Session sharing
 
@@ -936,12 +1047,12 @@ Configure the limit with:
 3. `maxSubagentDepth` in agent frontmatter, which can only tighten the inherited limit
 
 ```bash
-export PI_SUBAGENT_MAX_DEPTH=3
-export PI_SUBAGENT_MAX_DEPTH=1
-export PI_SUBAGENT_MAX_DEPTH=0
+export ATOMIC_SUBAGENT_MAX_DEPTH=3
+export ATOMIC_SUBAGENT_MAX_DEPTH=1
+export ATOMIC_SUBAGENT_MAX_DEPTH=0
 ```
 
-`PI_SUBAGENT_DEPTH` is internal and propagated automatically. Do not set it manually.
+`ATOMIC_SUBAGENT_DEPTH` is internal and propagated automatically. Do not set it manually. Legacy `PI_SUBAGENT_MAX_DEPTH` and `PI_SUBAGENT_DEPTH` are still read for compatibility.
 
 ## Events
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.24-alpha.2",
+  "version": "0.8.24-alpha.3",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

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

@@ -4,14 +4,16 @@ 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.
 
-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, for example:
+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:
 
 - `context-build/where-it-lives.md`
 - `context-build/how-it-works.md`
 - `context-build/existing-patterns.md`
 - `context-build/prior-research.md`
 
-Do not write these artifacts into the repository unless I explicitly ask for persistent files.
+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:
 

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

@@ -20,7 +20,7 @@ Parallel discovery step. Choose the specialists that apply:
 - `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 distinct output paths under the chain directory. Example outputs:
+Use distinct output paths, `label` values, and `as` names under the chain directory. Example outputs:
 
 - `handoff/external-reference.md`
 - `handoff/local-files.md`
@@ -28,6 +28,8 @@ Use distinct output paths under the chain directory. Example outputs:
 - `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:

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

@@ -35,7 +35,7 @@ Humans often use the slash-command layer instead:
 - `/run` — launch a single agent
 - `/chain` — launch a chain of steps
 - `/parallel` — launch top-level parallel tasks
-- `/run-chain` — launch a saved `.chain.md` workflow
+- `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow
 - `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
 
 Prefer the tool when you are writing agent logic. Prefer the slash commands when you are guiding a human through an interactive flow.
@@ -112,7 +112,40 @@ Use this at the start of non-trivial work. Launch `codebase-locator` and `codeba
 
 ### Parallel cleanup technique
 
-Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `codebase-analyzer` scouts with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that scout; otherwise inline the criteria. Both scouts are read-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. The parent decides what to apply and asks before making changes unless cleanup was already authorized. When the user opts to autofix, the parent launches one async `code-simplifier` writer with the synthesized fixes as its explicit scope.
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `codebase-analyzer` scouts with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that scout; otherwise inline the criteria. Both scouts are read-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized. When the user opts to autofix, the parent launches one async `code-simplifier` writer with the synthesized fixes as its explicit scope.
+
+### Staged fix orchestration technique
+
+Use this when a broad diff has known reviewer findings across several items and the user wants the parent to coordinate a safe multi-stage fix. Keep the active worktree safe with a three-stage chain:
+
+1. A parallel read-only planning fanout, one specialist per issue cluster. Use `codebase-analyzer`, `debugger` in inspect-only mode, or `codebase-pattern-finder` based on the angle. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
+2. One writer worker (`debugger` for correctness fixes or `code-simplifier` for cleanup fixes). It receives the planner summaries through `{previous}` or named `{outputs.name}` values, the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
+3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
+
+Prefer `async: true`, `context: "fresh"` for planners/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
+
+When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
+
+Example shape:
+
+```typescript
+subagent({
+  async: true,
+  context: "fresh",
+  chain: [
+    { parallel: [
+      { agent: "codebase-analyzer", phase: "Planning", label: "Deploy docs", as: "deployPlan", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" },
+      { agent: "debugger", phase: "Planning", label: "Scheduler contract", as: "schedulerPlan", task: "Inspect-only plan for scheduler contract fixes. Do not edit. Return exact fixes and focused validation.", output: "plans/scheduler.md", outputMode: "file-only" },
+      { agent: "codebase-pattern-finder", phase: "Planning", label: "Sandbox patterns", as: "sandboxPlan", task: "Find existing patterns relevant to sandbox/security fixes. Do not edit.", output: "plans/sandbox.md", outputMode: "file-only" }
+    ], concurrency: 3 },
+    { agent: "debugger", phase: "Implementation", label: "Apply accepted fixes", as: "workerResult", task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\n\nDeploy plan:\n{outputs.deployPlan}\n\nScheduler plan:\n{outputs.schedulerPlan}\n\nSandbox plan:\n{outputs.sandboxPlan}", output: "worker/fixes.md", outputMode: "file-only", progress: true },
+    { parallel: [
+      { agent: "codebase-analyzer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
+      { agent: "debugger", phase: "Validation", label: "Failure-mode validation", task: "Inspect-only failure-mode hunt on the post-worker diff. Start from the worker result: {outputs.workerResult}. Do not edit.", output: "validation/failure-modes.md", outputMode: "file-only" }
+    ], concurrency: 2 }
+  ]
+})
+```
 
 ## Builtin Agents
 
@@ -189,11 +222,10 @@ Agent files can live in:
 - legacy `.agents/**/*.md` and `.pi/agents/**/*.md` — still read for compatibility, but `.atomic/agents/` wins on conflicts
 
 Chains live in:
+- `~/.atomic/agent/chains/**/*.chain.md` and `~/.atomic/agent/chains/**/*.chain.json` — user scope
+- `.atomic/chains/**/*.chain.md` and `.atomic/chains/**/*.chain.json` — project scope
 
-- `~/.atomic/agent/chains/**/*.chain.md` — user scope
-- `.atomic/chains/**/*.chain.md` — project scope
-
-Discovery is recursive. `.chain.md` files do not define agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: codebase-analyzer` plus `package: code-analysis` registers as runtime name `code-analysis.codebase-analyzer` while serialization keeps `name` and `package` separate.
+Discovery is recursive. `.chain.md` files do not define agents. Use `.chain.md` for simple saved chains and `.chain.json` for dynamic fanout or inline schema objects. Agents and chains can set optional frontmatter/package metadata; `name: codebase-analyzer` plus `package: code-analysis` registers as runtime name `code-analysis.codebase-analyzer` while serialization keeps `name` and `package` separate.
 
 Precedence is by parsed runtime name:
 
@@ -264,7 +296,7 @@ subagent({
 })
 ```
 
-Chain steps can use templated variables such as `{task}`, `{previous}`, and `{chain_dir}`. This is the main way to pass structured summaries between steps without forcing each step to rediscover everything.
+Chain steps can use templated variables such as `{task}`, `{previous}`, `{chain_dir}`, and `{outputs.name}`. Use `as: "name"` on a successful step or parallel task to make that output available to later steps. Prefer named outputs when a later step needs one specific result; keep `{previous}` for simple linear handoffs or full fan-in summaries. Use `phase` and `label` for status readability. Use `outputSchema` when later steps need reliable structured data; the child must call `structured_output` with schema-valid JSON, or the step fails.
 
 ### Async/background
 
@@ -599,7 +631,9 @@ For feature work, use this sequence as scaffolding for parent-agent behavior:
 clarify → validation contract → parallel discovery → async writer (debugger or code-simplifier) → parallel async fresh-context specialist reviewers → async fix writer → follow-up review when warranted → parent review
 ```
 
-The validation contract defines what done means before code is written: expected behavior, acceptance checks, commands or user flows to exercise, and evidence the writer should return. Keep it lightweight for small tasks, but make it explicit enough that reviewers are checking the intended outcome rather than the writer's own assumptions.
+The validation contract defines acceptance before code is written: expected behavior, acceptance checks, commands or user flows to exercise, and evidence the writer should return. Keep it lightweight for small tasks, but make it explicit enough that reviewers and validators are checking the intended outcome rather than the writer’s own assumptions.
+
+Use the structured `acceptance` field when the run should carry an explicit acceptance contract. If omitted, subagents infer an effective acceptance policy from role, mode, and risk. Use `level: "checked"` for ordinary writer evidence gates, `level: "verified"` when the runtime should run explicit validation commands, and `level: "reviewed"` only when an independent reviewer result is expected. Do not call a run reviewed just because the writer says it is done; reviewed means a reviewer gate returned a result. Child-reported command success is evidence, not runtime verification.
 
 The first writer implements the approved change. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async writer completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for writer-only work, review-only output, or to stop after implementation. Parallel specialist reviewers inspect the resulting diff from fresh context. The final fix writer applies synthesized review fixes, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async chain when the workflow is already clear, or as follow-up subagent runs after each async completion. Initial chains should pass `async: true` so the main chat is unblocked; avoid `clarify: true` unless the user asked for foreground clarification. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
 
@@ -609,8 +643,8 @@ For very large work, split into serial milestones instead of launching a swarm o
 
 Keep orchestration authority in the parent session. Child subagents should not launch more subagents, read this skill, or run their own orchestration loops unless the parent intentionally selected an explicit fanout agent whose resolved builtin `tools` includes `subagent` for that assigned fanout. Spawned non-fanout subagents do not receive the `subagent` skill, parent-only status/control/slash messages, prior parent `subagent` tool-call/tool-result artifacts, or the `subagent` extension tool. Child context filtering also strips old hidden orchestration-instruction messages when they appear in inherited history. Every child also receives a boundary instruction that says the parent owns orchestration, the child must not propose or run subagents unless explicitly authorized for fanout, and writer children must call real edit/write tools instead of printing pseudo tool calls. Pass children concrete role-specific work instead.
 
-1. Clarify first. Gather code context with `codebase-locator`, `codebase-analyzer`, `codebase-pattern-finder`, and prior research specialists; add `codebase-online-researcher` only when external evidence matters; then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
-2. Define the validation contract. State what done means before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the writer handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
+1. Clarify first. This is mandatory. Gather code context with `codebase-locator`, `codebase-analyzer`, `codebase-pattern-finder`, and prior research specialists; add `codebase-online-researcher` only when external evidence matters; then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
+2. Define the validation contract. State acceptance before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the writer handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
 3. Plan when useful. For complex work, write a plan doc yourself and get approval before implementation. For simple work, confirm shared understanding and explicitly note why planning is skipped.
 4. Implement with one writer. After approval, launch `debugger` (for correctness-shaped work) or `code-simplifier` (for refinement-shaped work) asynchronously with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
 5. Require a useful writer handoff. Ask the writer to report changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises or new risks, decisions made inside approved scope, and decisions needing parent approval.
@@ -625,6 +659,10 @@ Example writer handoff after clarification and optional planning:
 subagent({
   agent: "debugger",
   task: "Implement the approved fix.\n\nClarified requirements:\n- ...\n\nPlan: see ~/Documents/docs/...-plan.md\n\nValidation contract:\n- ...\n\nReturn a handoff with changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises/new risks, and decisions needing parent approval.",
+  acceptance: {
+    level: "checked",
+    evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"]
+  },
   async: true
 })
 ```
@@ -679,7 +717,7 @@ subagent({
 /run-chain review-chain -- review this branch
 ```
 
-Use saved `.chain.md` workflows when the user wants a repeatable multi-agent flow without rewriting the chain each time.
+Use saved `.chain.md` or `.chain.json` workflows when the user wants a repeatable multi-agent flow without rewriting the chain each time. Prefer `.chain.json` for dynamic fanout or inline `outputSchema` objects; `.chain.md` remains the simple sequential/static authoring format.
 
 ## Error Handling