@bastani/atomic 0.8.14 → 0.8.15

package/docs/subagents.md

@@ -0,0 +1,157 @@
+---
+title: "Subagents"
+description: "Run focused Atomic child agents"
+---
+
+# Subagents
+
+Atomic bundles `@bastani/subagents`, an extension for running focused child agents with their own context. Use it when a task benefits from isolation, parallel investigation, background execution, or a specialist pass for locating code, analyzing behavior, researching references, debugging, or simplifying code.
+
+You do not need to install anything separately when you use `@bastani/atomic`.
+
+## Start with natural language
+
+Ask Atomic to coordinate subagents in plain language:
+
+```text
+Map the authentication flow with focused subagents before we change it.
+```
+
+```text
+Run a parallel review composition: one pass for current behavior, one for failure modes, and one for existing patterns.
+```
+
+```text
+Research the upstream library behavior online, then compare it with our local implementation.
+```
+
+Atomic decides whether to call the bundled `subagent` tool, which specialist fits each part, and whether the work should run as a single child, parallel group, chain, foreground run, or background run.
+
+## Bundled agents
+
+Atomic currently bundles these agents from `@bastani/subagents`:
+
+| Agent | Use it for | Edit files? |
+|---|---|---|
+| `codebase-locator` | Find relevant files, directories, tests, configs, and docs for a topic. | No |
+| `codebase-analyzer` | Explain how specific code works and trace data flow with file references. | No |
+| `codebase-pattern-finder` | Find similar implementations, conventions, and test examples to model after. | No |
+| `codebase-research-locator` | Locate prior `research/` and `specs/` documents related to the task. | No |
+| `codebase-research-analyzer` | Extract decisions, constraints, and still-relevant conclusions from prior local docs. | No |
+| `codebase-online-researcher` | Research official docs, ecosystem behavior, and open-source source references online. | Can write research notes |
+| `debugger` | Reproduce, diagnose, and fix failures or unexpected behavior. | Yes |
+| `code-simplifier` | Clean up recently changed code while preserving behavior. | Yes |
+
+Read-oriented agents should inspect and report. `debugger` and `code-simplifier` can edit files, so run them with an explicit scope and validation target.
+
+## Review compositions
+
+Atomic does not bundle a single generic review agent. Instead, compose specialists with distinct angles and let the parent session synthesize their findings before applying any fix.
+
+Common review angles:
+
+| Angle | Specialist pattern |
+|---|---|
+| Current behavior and regressions | `codebase-analyzer` inspects the changed flow and cites file/line evidence. |
+| Failure modes | `debugger` runs in inspect-only mode to reproduce or reason about likely failures without editing. |
+| Fit with project conventions | `codebase-pattern-finder` compares the patch with existing local examples. |
+| Prior decisions | `codebase-research-locator` finds relevant docs, then `codebase-research-analyzer` extracts applicable constraints. |
+| External API or library conformance | `codebase-online-researcher` checks authoritative sources and version-specific behavior. |
+
+Example request:
+
+```text
+Review the current diff with fresh-context specialists: analyze correctness, inspect failure modes without editing, and compare the implementation to existing patterns. Synthesize only issues worth fixing now.
+```
+
+Useful prompt templates include `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`, and `/parallel-cleanup`. Treat them as reusable compositions, not as separate bundled agent names.
+
+## Background work and control
+
+Foreground subagents stream progress in the conversation. Background subagents keep working after control returns to you and report completion later.
+
+Natural-language examples:
+
+```text
+Run the local research scan in the background.
+```
+
+```text
+Show me the current async subagent runs.
+```
+
+Tool examples:
+
+```ts
+subagent({ agent: "codebase-analyzer", task: "Trace the auth flow with file references.", async: true })
+subagent({ action: "status" })
+subagent({ action: "status", id: "<run-id>" })
+subagent({ action: "interrupt", id: "<run-id>" })
+subagent({ action: "resume", id: "<run-id>", message: "continue with the test failures" })
+subagent({ action: "doctor" })
+```
+
+Use `interrupt` when you want a resumable stop. Use `resume` to send a follow-up to a reachable async child, or to revive a completed child from its saved session when the run has enough metadata. Use `doctor` for read-only setup diagnostics.
+
+Background runs are detached. If Atomic has no useful independent work while a background subagent runs, it should end the turn instead of polling in a loop; the run will notify the originating session when it completes.
+
+## Context and execution modes
+
+Subagents can run with fresh or forked context:
+
+- `context: "fresh"` starts a separate child with only the task and selected agent context.
+- `context: "fork"` creates a real branched child session from the parent session leaf. It fails fast if the parent session cannot be forked; it does not silently downgrade to fresh context.
+
+For adversarial review or research, prefer fresh context so the specialist inspects the repository directly. Use forked context when a writer needs the parent conversation history in a separate branch.
+
+For parallel implementation work, `worktree: true` can give each child an isolated git worktree so concurrent edits do not clobber each other.
+
+## Nested and fanout boundaries
+
+Child-safety boundaries are enforced by the bundled subagent extension:
+
+- Normal child sessions do not receive the `subagent` tool or the parent-only subagents skill.
+- Child context is filtered to remove parent orchestration artifacts, old control/status messages, and prior parent `subagent` tool calls/results.
+- Non-fanout children are instructed that they are not the parent orchestrator and must not propose or run subagents.
+- Nested fanout is available only for explicitly authorized agents whose resolved tools include `subagent`. Authorized fanout children receive narrower instructions that limit delegation to the assigned fanout.
+
+This keeps the parent session responsible for orchestration unless you deliberately choose a fanout-capable custom agent.
+
+## Custom agents
+
+Custom agents are Markdown files with YAML frontmatter and a system prompt body. Common locations are:
+
+| Scope | Path |
+|---|---|
+| User | `~/.atomic/agent/agents/**/*.md` |
+| Project | `.atomic/agents/**/*.md` |
+
+A small custom read-only inspection agent:
+
+```markdown
+---
+name: strict-inspector
+description: Inspect code for correctness and regressions
+tools: read, grep, bash
+model: anthropic/claude-sonnet-4
+fallbackModels: openai/gpt-5-mini
+inheritProjectContext: true
+completionGuard: false
+---
+
+You are a read-only inspector. Inspect the current diff, cite evidence with file paths, and return only issues worth fixing now. Do not edit files.
+```
+
+Use `completionGuard: false` sparingly. It opts a user-authored agent out of automatic completion-guard reminders and is intended for read-only agents whose prompt already prevents premature completion. Do not use it to bypass required implementation or validation work.
+
+## Fallback models
+
+Agents can define ordered `fallbackModels` for retryable provider or model failures such as rate limits, quota/auth problems, unavailable models, network timeouts, or 5xx errors. Atomic tries the requested primary model first, then configured fallbacks, and finally appends the current user-selected model as the last fallback candidate when available.
+
+Fallbacks do not retry ordinary task failures, validation failures, tool failures, cancellations, or workflow-code errors. Because a fallback may send the same prompt and context to a different provider, choose models that match your cost, privacy, and data-handling requirements.
+
+## Related docs
+
+- [Workflows](/workflows) for multi-stage reusable automation.
+- [Skills](/skills) for reusable instructions invoked with `/skill:<name>`.
+- [Settings](/settings) for user and project configuration.

package/docs/usage.md

@@ -27,7 +27,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 | Hidden shell command | `!!command` runs without sending output to the model |
 | External editor | CTRL+G opens `$VISUAL` or `$EDITOR` |
 
-See [Keybindings](keybindings.md) for all shortcuts and customization.
+See [Keybindings](/keybindings) for all shortcuts and customization.
 
 ## Slash Commands
 
@@ -64,9 +64,9 @@ You can submit messages while the agent is still working:
 - **Escape** aborts and restores queued messages to the editor.
 - **ALT+Up** retrieves queued messages back to the editor.
 
-On Windows Terminal, ALT+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want Atomic to receive the shortcut.
+On Windows Terminal, ALT+Enter is fullscreen by default. Remap it as described in [Terminal setup](/terminal-setup) if you want Atomic to receive the shortcut.
 
-Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+Configure delivery in [Settings](/settings) with `steeringMode` and `followUpMode`.
 
 ## Sessions
 
@@ -88,7 +88,7 @@ Useful session commands:
 - `/clone` duplicates the current active branch into a new session file.
 - `/compact` summarizes older messages to free context.
 
-See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+See [Sessions](/sessions) and [Compaction](/compaction) for details.
 
 ## Context Files
 
@@ -137,7 +137,7 @@ atomic list                      # List installed packages
 atomic config                    # Enable/disable package resources
 ```
 
-See [Atomic Packages](packages.md) for package sources and security notes.
+See [Atomic Packages](/packages) for package sources and security notes.
 
 ### Modes
 
@@ -145,8 +145,8 @@ See [Atomic Packages](packages.md) for package sources and security notes.
 |------|-------------|
 | default | Interactive mode |
 | `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
-| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](/json) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](/rpc) |
 | `--export <in> [out]` | Export a session to HTML |
 
 In print mode, Atomic also reads piped stdin and merges it into the initial prompt:

package/docs/windows.md

@@ -15,3 +15,11 @@ For most users, [Git for Windows](https://git-scm.com/download/win) is sufficien
   "shellPath": "C:\\cygwin64\\bin\\bash.exe"
 }
 ```
+
+## Self-Update Behavior
+
+`atomic update --self` can update Windows installations that Atomic can identify as writable global package-manager installs. `atomic update` includes the same self-update step before updating packages unless you pass `--extensions`.
+
+When self-update starts on Windows, Atomic first cleans any previous `.atomic-native-quarantine` directory under the global package root. If native add-ons from the current install are loaded by the running process, Atomic moves those files into a per-run quarantine directory and copies them back into place before invoking the package manager. This lets the package manager replace native dependency files that Windows would otherwise keep locked.
+
+If Atomic cannot safely self-update the current installation, it exits with a clear message instead of guessing. The message explains that the install is unsupported, unmanaged, or not writable; prints the detected executable path when available; and tells you to update Atomic with the package manager, wrapper, source checkout, or release artifact that originally installed it.

package/docs/workflows.md

@@ -139,7 +139,7 @@ Atomic bundles three workflows that cover the most common multi-stage jobs. They
 | Workflow | What it does | When to use |
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
-| `ralph` | Bounded plan → orchestrate → simplify → parallel review loop. Reviewer findings feed back into the next planner. | Larger implementation loops where you want implementation, review, and validation built in. |
+| `ralph` | Goal contract → orchestrate → simplify → parallel review/audit loop → PR preparation. Reviewer findings feed back into the next planner and completion is judged against an inferred verification oracle. | Larger autonomous implementation loops where you want implementation, receipts, review, validation, audit, and conditional PR creation built in. |
 | `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `playwright-cli` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
@@ -169,6 +169,22 @@ workflow({
 })
 ```
 
+Output locations and result fields:
+
+| Field | Meaning |
+|---|---|
+| `findings` | Final Markdown research report text. |
+| `research_doc_path` | Public report path under `research/<date>-<topic>.md`. If a file already exists, the workflow writes a suffixed filename. |
+| `artifact_dir` | Hidden per-run handoff directory under `research/.deep-research-<run-id>/`. |
+| `manifest_path` | Manifest JSON path inside the hidden artifact directory. |
+| `partitions` | Codebase partitions the specialists explored. |
+| `explorer_count` | Number of partition explorer groups used. |
+| `specialist_count` | Number of specialist stages run across the research waves. |
+| `max_concurrency` | Concurrency limit used for the run. |
+| `history` | Prior-research/history overview included in the final synthesis. |
+
+The dated Markdown report is intended for people to read and commit or share. The hidden artifact directory keeps large scout, history, and specialist handoff files available for audit without cluttering the visible research index.
+
 ### `ralph`
 
 Inputs:
@@ -186,9 +202,24 @@ Run examples:
 /workflow ralph prompt="Migrate the database layer to Drizzle" max_loops=5 base_branch=develop
 ```
 
-Ralph writes each planner RFC to `specs/<date>-<topic>.md` in the current workspace, returns the path as `plan_path`, then instructs the orchestrator to read that spec path instead of inlining the full plan. The orchestrator also maintains OS-temp implementation notes, returned as `implementation_notes_path`, for decisions, spec deviations, tradeoffs, blockers, and validation outcomes. After the review loop, Ralph runs a final PR-preparation phase that reviews changes against `base_branch` and creates a pull request when repository state and GitHub credentials allow it; when multiple GitHub accounts are logged in, it uses `git config` identity as a hint and tries available credentials until one works. If it creates a PR, the final phase posts the implementation notes contents as a PR comment.
+Ralph writes each planner goal contract to an OS-temp workflow artifact, returns the path as `plan_path`, then instructs the orchestrator to read that path instead of inlining the full plan. The goal contract captures owner intent, verification oracle, work surface, execution loop, and proof requirements; any user-supplied spec remains supporting input rather than the primary success criterion. The orchestrator also maintains OS-temp implementation notes, returned as `implementation_notes_path`, for the active work surface, receipts, decisions, goal-contract deviations, tradeoffs, blockers, and validation outcomes.
+
+The review loop also performs the completion audit: reviewers map receipts and verification results back to the original owner outcome and inferred oracle before approving. After approval or loop exhaustion, Ralph runs PR preparation: reviewing changes against `base_branch`, checking the current diff and untracked files, checking local git identity (`git config user.name` and `git config user.email`), and looking for GitHub credentials. It creates a pull request only when there are meaningful changes, a usable remote/branch target, suitable repository state, and credentials that can access the repository. When multiple GitHub accounts are logged in, it uses local git identity as a hint and tries available credentials until one works. If PR creation succeeds, the final phase posts the implementation notes and reviewer approval summary as a PR comment. If not, `pr_report` explains what blocked creation and the commands or steps to run later.
+
+Result fields:
+
+| Field | Meaning |
+|---|---|
+| `result` | Final orchestrator summary. |
+| `plan` | Last planner output text. |
+| `plan_path` | OS-temp path to the latest planner goal contract. |
+| `implementation_notes_path` | OS-temp Markdown notes maintained during orchestration. |
+| `pr_report` | Final PR-preparation report, including created PR URL or why no PR was created. |
+| `approved` | Whether the review loop approved the patch. |
+| `iterations_completed` | Number of plan/orchestrate/review loops run. |
+| `review_report` | Last structured review report used to decide whether to stop, including oracle satisfaction and remaining verification. |
 
-A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow ralph prompt="Implement specs/<date>-<topic>.md"`.
+A typical end-to-end flow is `/skill:research-codebase` → `/workflow ralph prompt="Implement the researched rate-limit behavior and validate it"`. If you already have a spec, pass it in the prompt as supporting input.
 
 ### `open-claude-design`
 
@@ -241,7 +272,9 @@ Named runs go to the background. Common controls:
 /workflow kill <run-id>                # destructive abort
 ```
 
-Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear in the workflow graph viewer, not as chat modals — use `/workflow connect <run-id>` (or F2) to answer them.
+Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear as awaiting-input nodes in the workflow graph viewer, not as chat modals — use `/workflow connect <run-id>` (or F2), focus the node, and press Enter to answer them locally.
+
+Prompt answers are replayable only while the source run remains in the live in-memory store. `StageSnapshot.promptAnswerState` is snapshot-safe metadata for continuation: `available` means a matching live answer can be replayed, `unavailable` means the matching prompt node exists but its private answer was purged, and `ambiguous` means multiple matching prompt nodes exist so Atomic asks again. The raw answer lives in a private `PromptAnswerRecord` ledger, is never written to snapshots or persistence, and remains resident in memory until the answer is cleared, the run is removed, or the store is cleared. Prompt replay keys include the prompt kind, message text, select choices, input/editor initial value, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. An empty `ctx.ui.select(..., [])` has no answerable choices and throws before creating a prompt node.
 
 ## When to Use Workflows
 
@@ -459,13 +492,14 @@ In the TUI, `/workflow <name>` opens an input picker when the workflow declares
 /workflow interrupt <run-id|--all>
 /workflow kill <run-id|--all>
 /workflow resume <run-id> [stage-id-or-name] [message]
+/workflow reload
 ```
 
-Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated and removed from live history/status. `/workflow status` lists in-flight runs by default; `/workflow status --all` includes retained ended runs.
+Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated and removed from live history/status. Use `/workflow reload` after adding, editing, installing, or removing workflow resources and you want Atomic to rediscover them in-process. `/workflow status` lists in-flight runs by default; `/workflow status --all` includes retained ended runs.
 
 <p align="center"><img src="images/workflow-graph.png" alt="Workflow Graph Viewer" width="600" /></p>
 
-Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear in the workflow UI/graph viewer, not as ordinary chat modals.
+Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear as awaiting-input nodes in the workflow UI/graph viewer, not as ordinary chat modals.
 
 ## Monitor and Control Runs
 
@@ -475,6 +509,17 @@ The workflow tool exposes lifecycle controls for non-interactive use:
 workflow({ action: "status" })
 workflow({ action: "status", runId: "<id-or-prefix>" })
 
+workflow({ action: "stages", runId: "<id-or-prefix>", statusFilter: "all" })
+workflow({ action: "stage", runId: "<id-or-prefix>", stageId: "review" })
+workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review", tail: 40 })
+workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review", includeToolOutput: true })
+
+workflow({ action: "send", runId: "<id-or-prefix>", stageId: "review", text: "please focus on tests" })
+workflow({ action: "send", runId: "<id-or-prefix>", stageId: "approval", response: true, delivery: "answer" })
+
+workflow({ action: "pause", runId: "<id-or-prefix>" })
+workflow({ action: "pause", runId: "<id-or-prefix>", stageId: "review" })
+
 workflow({ action: "interrupt", runId: "<id-or-prefix>" })
 workflow({ action: "interrupt", all: true })
 
@@ -483,15 +528,23 @@ workflow({ action: "resume", runId: "<id-or-prefix>", stageId: "review", message
 
 workflow({ action: "kill", runId: "<id-or-prefix>" })
 workflow({ action: "kill", all: true })
+
+workflow({ action: "reload", reason: "added team workflow" })
 ```
 
 Control behavior:
 
-- `runId` accepts full run ids or unique prefixes for `status`, `interrupt`, `resume`, and `kill`.
-- `interrupt` and `kill` default to the active run when `runId` is omitted.
+- `runId` accepts full run ids or unique prefixes for lifecycle and inspection actions.
+- `stages` lists stage summaries. Use `statusFilter: "all"` to include completed, failed, skipped, and pending stages.
+- `stage` returns details for one stage by stage id, unique prefix, or stage name.
+- `transcript` reads recent messages for a stage. `tail` overrides `limit`; `includeToolOutput` includes captured snapshot tool output when available.
+- `send` can answer pending prompts, steer streaming stages, queue follow-ups, or resume paused work. `delivery: "auto"` chooses in that order; use `delivery: "answer"` with `promptId` or `response` for explicit prompt answers.
+- `pause`, `interrupt`, and `kill` can target one run or `all: true`; `stageId` cannot be combined with `all: true`.
 - `interrupt` is resumable: it pauses live work when pausable stages exist and keeps the run in live history/status.
+- `pause` is useful for pausing a live run or a single live stage without treating it as a destructive abort.
 - `resume` can target a stage with `stageId`; the target may be a stage id, unique prefix, or stage name. `message` is forwarded to paused work.
 - `kill` is destructive: it aborts in-flight work and removes the run from live history/status.
+- `reload` refreshes discovered workflow resources in-process; the optional `reason` is echoed in the result.
 
 Use slash commands for graph connect and stage attach because those are interactive TUI surfaces. When a run needs user input or attention, surface that to the user instead of polling silently.
 
@@ -682,7 +735,7 @@ Common task/stage options include:
 `@bastani/workflows` is an Atomic package extension. It registers:
 
 - `/workflow <name> key=value ...` for interactive named runs
-- `/workflow connect|attach|pause|interrupt|resume|status|inputs` for live control and inspection
+- `/workflow connect|attach|pause|interrupt|resume|status|inputs|reload` for live control, inspection, and rediscovery
 - the `workflow` tool for agent-initiated orchestration and direct one-off runs
 - `runWorkflow(definition)` for explicit library or script usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.8.14",
+  "version": "0.8.15",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -43,6 +43,7 @@
     "copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/ && bun run copy-builtin-packages",
     "copy-builtin-packages": "bun run scripts/copy-builtin-packages.ts",
     "copy-builtin-workflows": "bun run copy-builtin-packages",
+    "docs:check": "bun run scripts/validate-docs-links.ts",
     "test": "vitest --run",
     "prepublishOnly": "bun run clean && bun run build"
   },

package/docs/images/exy.png

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:a8f253347440aed01ff659f41f573d340bcfd6010d829726ae92fe18abf601de
-size 1510779