From a6e36b2b5c745358705b196b6081ae954442c1b0 Mon Sep 17 00:00:00 2001 From: Aaron Ogle Date: Mon, 27 Jul 2026 11:52:42 -0500 Subject: [PATCH 1/3] Add New agent guide --- docs/adding-agents.md | 417 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 417 insertions(+) create mode 100644 docs/adding-agents.md diff --git a/docs/adding-agents.md b/docs/adding-agents.md new file mode 100644 index 00000000..91b60c46 --- /dev/null +++ b/docs/adding-agents.md @@ -0,0 +1,417 @@ +# Adding a New AI Agent to Atomic + +This document explains how to add support for a new AI coding agent (e.g. +Claude Code, OpenCode, Codex, Gemini CLI) to the Atomic ecosystem: how the +pieces fit together, what you have to build, and how to verify it. + +It is written for someone who has never touched this part of the codebase. + +## The three repositories + +Agent support spans **three** repositories. Know which one owns which concern. + +| Repo | Role | What lives here | +|------|------|-----------------| +| **`atomic`** (this repo) | The engine + CLI | The `atomic-agent` crate: per-agent *hook adapters*, the `AgentRegistry`, the verb→event map, and the `atomic agent …` CLI. This is where you write Rust to make Atomic *understand* an agent. | +| **`atomic-`** (e.g. `atomic-opencode`, `atomic-claude`) | The integration package | The agent-facing glue: the system prompt (`agents/*.md`, `CLAUDE.md`, …), the skills (`skills/*/SKILL.md`), the wiring that makes the agent call back into `atomic agent hooks …` (a plugin, or a hooks manifest), and an installer. Published to npm / installed via `install.sh`. | +| **`atomic-agents`** | The test harness | An ACP-based harness (`atomic-agent-harness`) that spawns each agent, sends real prompts, and asserts on the ACP stream and repository side effects. Also a native pure-Rust ACP agent (`atomic-agent`). This is where you register an agent so it gets *tested*. | + +The mental model: + +``` + atomic- package atomic (this repo) + ───────────────────── ────────────────── + agent runs, fires lifecycle ──► atomic agent hooks + events → calls the CLI │ + (plugin or native hooks) ▼ + AgentRegistry.require() + adapter.parse_event(verb, stdin-json) + │ + ▼ + TurnEvent → TurnOrchestrator + │ + ▼ + change recorded with AI provenance + + + atomic-agents (harness) ──► spawns the agent over ACP, prompts it, + verifies it can search / status / record +``` + +Two integration *styles* exist. **Which one(s) you can use is dictated by the +agent, not by preference** — it depends entirely on what extension mechanism +the target agent exposes: + +1. **Native-hooks style** (Claude Code, Codex, Gemini, Cursor, …). The agent + has its own hook system in a settings file. The integration package ships a + **hooks manifest** JSON; `atomic agent enable --hooks ` merges it + into the agent's settings file. See `atomic-claude`. +2. **Plugin style** (OpenCode, …). The agent exposes a plugin/extension API. + The integration package ships a plugin that subscribes to lifecycle events + and shells out to `atomic agent hooks `. See `atomic-opencode` + (`plugins/atomic-hooks.ts`). + +You do not freely pick between these — the agent constrains you: + +- Some agents **only** support a plugin (no user-editable hooks config), so the + plugin style is your only option — this is why OpenCode ships a plugin. +- Some agents **only** expose a settings/hooks file (no plugin API), so the + native-hooks manifest is the only option — this is why Claude Code ships a + manifest. +- Some agents support **both**, in which case pick whichever gives you richer + lifecycle data (a plugin can usually report model/tokens/cost/timing that a + shell hook cannot) and the simpler install. +- Some agents support **neither** cleanly. Then you're limited to whatever + coarse signal is available (e.g. detecting a config directory and recording + on a file-watch / session boundary) — and the adapter's `supported_hooks()` + should advertise only the events you can actually observe. + +Before writing anything, **investigate the target agent's extension model +first** and let that decide the style. Whichever style you land on, the payload +that reaches Atomic is identical: JSON on stdin to +`atomic agent hooks `. + +--- + +## Part 1 — The hook adapter in `atomic` (required) + +Everything in the `atomic agent hooks ` pipeline is keyed off a +**string agent name**, dispatched through the `AgentRegistry`. To make Atomic +understand a new agent you implement one trait and register it. + +### 1.1 Create the adapter file + +Create `atomic-agent/src/hooks/.rs`. Use +`atomic-agent/src/hooks/opencode.rs` as the reference implementation — it is +the cleanest example and covers all six hook types. + +Implement the `AgentHook` trait (`atomic-agent/src/hooks/mod.rs:131`): + +```rust +pub trait AgentHook: Send + Sync + fmt::Debug { + fn name(&self) -> &str; // registry key, e.g. "myagent" + fn display_name(&self) -> &str; // "My Agent" + fn parse_event(&self, hook_type: HookType, input: &[u8]) -> AgentResult; + fn install(&self, repo_root: &Path) -> AgentResult; + fn uninstall(&self, repo_root: &Path) -> AgentResult<()>; + fn is_installed(&self, repo_root: &Path) -> bool; + fn supported_hooks(&self) -> Vec; + fn hook_verbs(&self) -> Vec<&str>; + + // Optional (have defaults): + fn detect_presence(&self, repo_root: &Path) -> bool { false } + fn stdout_response(&self, hook_type: HookType) -> Option<&'static str> { None } + fn repo_root_hints(&self, event: &TurnEvent) -> Option> { None } +} +``` + +Key responsibilities of `parse_event`: + +- Deserialize the agent's stdin JSON (each agent sends a different shape — model + one struct per verb, as `opencode.rs` does). +- Build a `TurnEvent` (`atomic-agent/src/event.rs`) with `session_id`, and + attach `prompt`, `tool_name`, `tool_use_id` where relevant. +- Stash anything else the orchestrator/provenance wants (model, provider, + tokens, cost, finish reason) into `raw_json` — see how `opencode.rs` + re-inserts `model`/`provider` into the raw JSON object. + +The six canonical hook types (`atomic-agent/src/event.rs:67`) are: +`SessionStart`, `SessionEnd`, `TurnStart`, `TurnEnd`, `PreToolUse`, +`PostToolUse`. An agent need not support all of them — return only what it +emits from `supported_hooks()` and `hook_verbs()`. + +Regarding `install`/`uninstall`/`is_installed`: if the integration package +handles installation itself (plugin style, or manifest style), these can be +near no-ops. OpenCode's adapter returns `Ok(1)`/`Ok(0)` from `install` by +checking whether the plugin file exists, and `uninstall` is a no-op — because +the `atomic-opencode` npm package owns installation. Only implement real +config-file writing here if you want `atomic agent enable --agent ` to be +the installer (the older per-repo path). + +### 1.2 Register the adapter + +Add the module and register it in the default registry +(`atomic-agent/src/hooks/mod.rs`): + +```rust +// near line 59, with the other `pub mod` declarations +pub mod myagent; + +// in AgentRegistry::with_defaults() near line 319 +registry.register(Box::new(myagent::MyAgentHook::new())); +``` + +That is the *only* place that decides which agents exist. `atomic agent hooks`, +`enable`, `status`, and auto-detection all read from this registry. + +### 1.3 Map the agent's verbs to hook types + +`atomic agent hooks ` turns `` into a `HookType` via +`HookType::from_verb` (`atomic-agent/src/event.rs:166`). This one function is +the union of *all* agents' verb strings. If your agent introduces a verb string +that is not already mapped, add an arm: + +```rust +// in HookType::from_verb +"my-turn-begin" => Some(HookType::TurnStart), +"my-turn-done" => Some(HookType::TurnEnd), +``` + +Many common verbs (`session-start`, `session-end`, `user-prompt`, `stop`, +`before-tool`, `after-tool`, …) are already mapped — reuse them if your plugin +can emit them, and you may not need to touch this function at all. + +### 1.4 Wire correct provenance (strongly recommended) + +The agent name flows through end-to-end as a free-form string +(`AITool::Cli(String)`), so recording will *work* without these. But several +hardcoded per-agent maps make the output correct and pretty. Update them: + +| What | File:line | Why | +|------|-----------|-----| +| Vendor inference | `atomic-agent/src/record/provenance.rs:161` (`vendor_from_agent_name`) | Maps agent → `AIVendor`. Without an arm, vendor becomes `Other("")`. | +| Author-is-agent classification | `atomic-repository/src/repository/provenance_summary.rs:208` (`KNOWN_AGENT_PREFIXES`) and the fallback name list (~`:241`) | Otherwise the agent's changes are miscounted as human-authored in `atomic agent attest --summary`. | +| Display prettifier | `atomic-cli/src/commands/agent/attest.rs:607` (`pretty_tool`) | Nice name in attestation output. | + +Note: `AIVendor` itself is an enum (`atomic-core/src/change/provenance/types.rs:21`). +If your agent's provider isn't represented and you don't want `Other(...)`, add +a variant there and to its `parse()`. + +### 1.5 (Optional) global install support + +`atomic agent enable --global` uses a hardcoded `match agent_name` in +`atomic-cli/src/commands/agent/enable.rs` (~`:324`). Only add an arm if your +agent supports a single global settings file *and* you want `enable --global` +to be the installer. Plugin/manifest-style integrations don't need this — they +install themselves. + +--- + +## Part 2 — The integration package `atomic-` (required) + +This is a separate repo (published so users can install it). It contains no +Atomic Rust code — only the agent-facing assets and the wiring that makes the +agent call `atomic agent hooks …`. + +Standard layout (see `atomic-opencode` and `atomic-claude`): + +``` +atomic-/ +├── agents/.md or CLAUDE.md / AGENTS.md # system prompt +├── skills/ +│ ├── atomic-vault/SKILL.md +│ ├── atomic-vcs/SKILL.md +│ └── code-intelligence/SKILL.md +├── hooks/.atomic-hooks.json # manifest (native-hooks style) +│ —or— +├── plugins/atomic-hooks.ts # plugin (plugin style) +├── install.sh # dev install (symlinks) +├── install.js # npm postinstall +├── package.json +└── README.md +``` + +### 2.1 The system prompt + +Ship the agent's system prompt in whatever file the agent reads. The prompt +location convention per agent is recorded in the harness +(`atomic-agents/.../env.rs`, `PromptKind`): + +- `CLAUDE.md` at root — Claude Code +- `AGENTS.md` at root — Codex, Devin, Gemini +- `agents/*.md` — OpenCode, Pi +- `rules/*.md` — Cursor, Cline +- `steering/*.md` — Kiro +- `copilot-instructions.md` — Copilot + +The prompt should teach the intent-first Atomic workflow (create an intent, +define the problem, plan, execute, and *don't* run `atomic add`/`record` — +hooks do that). Copy `atomic-claude/CLAUDE.md` or `atomic-opencode/agents/atomic.md` +as a starting point. + +### 2.2 The skills + +Skills are on-demand reference docs the agent loads when relevant. The common +set is `atomic-vault`, `atomic-vcs`, and `code-intelligence`. Reuse the +existing skill content; the installer symlinks them into the agent's skills +directory. + +### 2.3 The lifecycle wiring — use the style the agent supports + +Use whichever style the target agent's extension model allows (see the +constraints in [The three repositories](#the-three-repositories) above): a +manifest if it has a user-configurable hooks file, a plugin if it exposes a +plugin API, both-then-prefer-plugin if it supports both. + +**A. Native-hooks style (manifest).** Write +`hooks/.atomic-hooks.json` describing where the agent's settings file is +and which commands to register. The manifest is merged idempotently by +`atomic agent enable --hooks ` — the merge engine is built into +`atomic` (no `jq`/Node needed), and it preserves the user's non-Atomic hooks. +See `atomic-claude/hooks/claude-code.atomic-hooks.json`. Format +(`atomic-agent/src/hooks/manifest.rs`): + +```json +{ + "target": "~/.claude/settings.json", + "hooks_key": "hooks", + "command_prefix": "atomic agent hooks claude-code", + "hooks": { + "SessionStart": [ { "matcher": "", "hooks": [ + { "type": "command", + "command": "test -d .atomic && atomic agent hooks claude-code session-start || true" } ] } ], + "Stop": [ { "matcher": "", "hooks": [ + { "type": "command", + "command": "test -d .atomic && atomic agent hooks claude-code stop || true" } ] } ] + }, + "merge": { "permissions": { "deny": [ "Read(./.atomic/metadata/**)" ] } } +} +``` + +- `target` — the agent's settings file (`~` expands to home). +- `command_prefix` — substring identifying *our* hooks so re-runs are + idempotent and uninstall removes only ours. +- `hooks` — `event → [entry]` in the agent's native shape (nested + `{matcher, hooks:[{command}]}` or flat `{command}` both supported). +- `merge` — extra non-hook settings deep-merged into the file. + +The big win: because the manifest lives in the integration repo, changing hook +wiring never requires rebuilding `atomic` — just re-publish the package. + +**B. Plugin style.** If the agent has a plugin API, write a plugin that +subscribes to lifecycle events and shells out to the CLI. See +`atomic-opencode/plugins/atomic-hooks.ts`. The essential shape: + +```ts +// on each lifecycle event, pipe JSON to the CLI +await $`echo ${JSON.stringify(payload)} | atomic agent hooks ${verb}`.nothrow(); +``` + +Map the agent's events to Atomic verbs, e.g. OpenCode: +`session.created→session-start`, `chat.message→user-prompt`, +`tool.execute.before→before-tool`, `tool.execute.after→after-tool`, +`session.idle→stop`, `session.deleted→session-end`. Send model, provider, +tokens, cost, and timing in the payload so provenance is rich. + +Guard every hook so it only fires inside an Atomic repo: +`test -d .atomic && … || true` (or the sandbox-aware form in +`guarded_hook_command`, `atomic-agent/src/hooks/mod.rs:103`). + +### 2.4 The installer + +`install.sh` (dev) symlinks prompt + skills into the agent's config dir and, for +native-hooks style, calls `atomic agent enable --hooks `. `install.js` +is the npm `postinstall` equivalent. Copy from whichever existing package +matches your style. + +--- + +## Part 3 — Register the agent in the test harness `atomic-agents` (required) + +The harness in `atomic-agents` auto-discovers and tests every agent that (a) +has an integration package present and (b) is spawnable per the live ACP +registry. To include your agent, add one entry to `AGENT_REGISTRY` in +`crates/atomic-agent-harness/src/env.rs` (~`:48`): + +```rust +AgentEntry { + registry_id: "myagent-acp", // ID in the canonical ACP registry + name: "myagent", // label in test output + package: "atomic-myagent", // dir name under AGENTS_DIR + prompt: PromptKind::AgentsDir, // where the prompt lives (see 2.1) + installed_skills_dir: "~/.config/myagent/skills", + skills: &["atomic-vault", "atomic-vcs", "code-intelligence"], +}, +``` + +Notes: + +- The **spawn command** is *not* hardcoded — it comes from the live ACP registry + (`registry.rs`, fetched from `cdn.agentclientprotocol.com`). `registry_id` + must match the agent's ID there. If the agent is stdio-only and needs a + local install hint, add it to `spawn.rs`'s `AGENTS` table. +- `available_agents()` only returns an agent when its package directory exists + in `AGENTS_DIR` (default `~/Projects/agents`) *and* the registry knows how to + spawn it on this platform. + +The harness then runs the shared `all_agents_*` integration tests against your +agent (`crates/atomic-agent-harness/tests/acp_integration.rs`): respond to a +prompt, use code search, check repo status, create an intent. These are +`#[ignore]` by default (they make real LLM calls); run explicitly. + +--- + +## Checklist + +**In `atomic` (this repo):** + +- [ ] `atomic-agent/src/hooks/.rs` implements `AgentHook`. +- [ ] Registered in `AgentRegistry::with_defaults()` (`hooks/mod.rs`), module declared. +- [ ] Any new verbs added to `HookType::from_verb` (`event.rs`). +- [ ] Vendor arm in `vendor_from_agent_name` (`record/provenance.rs`). +- [ ] Author classification in `provenance_summary.rs` (`KNOWN_AGENT_PREFIXES` + fallback list). +- [ ] Display name in `pretty_tool` (`agent/attest.rs`). +- [ ] (Optional) `enable --global` arm (`agent/enable.rs`). +- [ ] `cargo test -p atomic-agent` passes; adapter has unit tests (copy `opencode.rs`'s test module). + +**In `atomic-` (integration package):** + +- [ ] System prompt in the agent's convention (`CLAUDE.md` / `agents/*.md` / …). +- [ ] Skills (`atomic-vault`, `atomic-vcs`, `code-intelligence`). +- [ ] Lifecycle wiring: a hooks manifest **or** a plugin that calls `atomic agent hooks `. +- [ ] Every hook guarded with `test -d .atomic && … || true`. +- [ ] `install.sh` / `install.js` + `package.json` + `README.md`. + +**In `atomic-agents` (harness):** + +- [ ] `AgentEntry` added to `AGENT_REGISTRY` (`env.rs`). +- [ ] `registry_id` matches the canonical ACP registry (add spawn hint to `spawn.rs` if stdio-only). + +## Verifying end-to-end + +```bash +# 1. Build atomic with your adapter. +cargo build -p atomic +cargo test -p atomic-agent + +# 2. Install the integration package into your agent (dev mode). +cd ~/code/work/atomic- && ./install.sh + +# 3. Smoke-test the hook path by hand — this is exactly what the agent will do. +cd /some/atomic/repo +echo '{"session_id":"t1","cwd":"'"$PWD"'"}' | atomic agent hooks session-start +echo '{"session_id":"t1","prompt":"hi","model":"...","provider":"..."}' | atomic agent hooks user-prompt +echo '{"session_id":"t1","turn_number":1}' | atomic agent hooks stop +atomic agent attest # confirm a provenance/attestation record appeared + +# 4. Full ACP integration test via the harness (real LLM calls; needs API key + package in AGENTS_DIR). +cd ~/code/work/atomic-agents +cargo test -p atomic-agent-harness --test acp_integration -- --ignored --nocapture +``` + +## What is agent-agnostic vs. what you must touch + +Agent-agnostic (no change needed): the `atomic agent hooks ` +command itself, the `AgentRegistry` dispatch machinery, the `AITool::Cli(String)` +provenance carrier, the manifest merge engine, and the W3C PROV projection +(the agent slug is free-form). + +Must touch to add a *fully supported* agent: the adapter file, its registry +registration, and (if it uses new verb strings) the verb map — plus the +provenance/display maps for correct attribution. + +## Reference: key files + +- Trait + registry: `atomic-agent/src/hooks/mod.rs` +- Example adapter (plugin style): `atomic-agent/src/hooks/opencode.rs` +- Example adapter set: `atomic-agent/src/hooks/{claude_code,codex,gemini_cli,cursor,…}.rs` +- Verb → hook-type map: `atomic-agent/src/event.rs` (`HookType::from_verb`) +- Manifest install engine: `atomic-agent/src/hooks/manifest.rs` +- Hooks CLI entry: `atomic-cli/src/commands/agent/hooks.rs` +- Enable/attest CLI: `atomic-cli/src/commands/agent/{enable,attest}.rs` +- Provenance mapping: `atomic-agent/src/record/provenance.rs`, + `atomic-repository/src/repository/provenance_summary.rs` +- Integration packages: `atomic-opencode/` (plugin), `atomic-claude/` (manifest) +- Test harness registry: `atomic-agents/crates/atomic-agent-harness/src/env.rs` + + From 2444d44c2c34989192fd6041866aab0a7c870bd7 Mon Sep 17 00:00:00 2001 From: Aaron Ogle Date: Mon, 27 Jul 2026 12:44:54 -0500 Subject: [PATCH 2/3] Updated doc with hopefully a better flow --- docs/adding-agents.md | 803 +++++++++++++++++++++++++++++------------- 1 file changed, 549 insertions(+), 254 deletions(-) diff --git a/docs/adding-agents.md b/docs/adding-agents.md index 91b60c46..0fad20a6 100644 --- a/docs/adding-agents.md +++ b/docs/adding-agents.md @@ -1,89 +1,459 @@ # Adding a New AI Agent to Atomic -This document explains how to add support for a new AI coding agent (e.g. -Claude Code, OpenCode, Codex, Gemini CLI) to the Atomic ecosystem: how the -pieces fit together, what you have to build, and how to verify it. +This document teaches you how to add support for a new AI coding agent +(Claude Code, OpenCode, Codex, Gemini CLI, Cursor, …) to the Atomic ecosystem. -It is written for someone who has never touched this part of the codebase. +It is written to be read top to bottom. The first half explains *what an agent +integration is* and *why it is built the way it is*. The second half walks you +through building one. By the end you should understand the system well enough +to add your own agent — and know exactly where to look for working examples. -## The three repositories +--- + +## What "adding an agent" actually means + +Every version control system records **what changed**: these lines were added, +those were removed, this file was renamed. Atomic does that too — but it also +records **how and why the change came to be**. + +When an AI agent works in an Atomic repository, Atomic captures the full +provenance of the session alongside the code: + +- **The prompt** — the human's actual request that kicked off the work. +- **The model and vendor** — which AI did the work (e.g. `claude-sonnet-4`, + `gpt-5`), and which provider served it. +- **The cost** — input/output/reasoning token counts and USD spend per turn. +- **The decision graph** — a causal graph of the agent's tool calls: what it + explored, what it edited, what it verified, what failed — and which step led + to which. +- **The attestation** — a session-level audit record: this agent, this model, + spent $X and N tokens producing these M changes. + +This data is not logged to some external service. It is embedded into the +recorded changes themselves and stored content-addressed in the repository, +right next to the code. You can inspect it with `atomic change -p` (per-change +provenance) and `atomic agent attest` (session attestation). Months later, +"why is this line here?" has a real answer: the prompt that asked for it, the +model that wrote it, and the reasoning chain that produced it. + +**That is what "adding an agent" means: teaching Atomic to capture that +provenance from one specific agent's lifecycle — and teaching that agent to +behave like an Atomic-native developer so the captured work is clean and +reviewable.** -Agent support spans **three** repositories. Know which one owns which concern. +An integration therefore has two halves: + +| Half | Question it answers | Built from | +|------|--------------------|------------| +| **Behavior** | Does the agent work the Atomic way — intent-first, using Atomic's tools, not fighting the recorder? | A system prompt + three skills (shipped in the `atomic-` package) | +| **Capture** | Does Atomic receive the agent's lifecycle events and turn them into provenance-bearing changes? | Lifecycle wiring (plugin or hooks manifest) + a hook adapter in the `atomic` crate | + +And one requirement that spans both: **testing**, via the agent harness. + +### The three repositories + +Agent support spans three repositories. Know which one owns which concern: | Repo | Role | What lives here | |------|------|-----------------| -| **`atomic`** (this repo) | The engine + CLI | The `atomic-agent` crate: per-agent *hook adapters*, the `AgentRegistry`, the verb→event map, and the `atomic agent …` CLI. This is where you write Rust to make Atomic *understand* an agent. | -| **`atomic-`** (e.g. `atomic-opencode`, `atomic-claude`) | The integration package | The agent-facing glue: the system prompt (`agents/*.md`, `CLAUDE.md`, …), the skills (`skills/*/SKILL.md`), the wiring that makes the agent call back into `atomic agent hooks …` (a plugin, or a hooks manifest), and an installer. Published to npm / installed via `install.sh`. | -| **`atomic-agents`** | The test harness | An ACP-based harness (`atomic-agent-harness`) that spawns each agent, sends real prompts, and asserts on the ACP stream and repository side effects. Also a native pure-Rust ACP agent (`atomic-agent`). This is where you register an agent so it gets *tested*. | +| **`atomic`** (this repo) | The engine + CLI | The `atomic-agent` crate: per-agent *hook adapters*, the `AgentRegistry`, the verb→event map, the `TurnOrchestrator` that does the recording, and the `atomic agent …` CLI. This is where you write Rust so Atomic can *understand* your agent. | +| **`atomic-`** (e.g. [`atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode), [`atomic-claude`](https://github.com/atomicdotdev/atomic-claude)) | The integration package | The agent-facing glue: the system prompt, the skills, the wiring that makes the agent call back into `atomic agent hooks …` (a plugin or a hooks manifest), and an installer. Published to npm / installed via `install.sh`. | +| **`atomic-agents`** ([repo](https://github.com/atomicdotdev/atomic-agents)) | The test harness | An ACP-based harness that spawns each agent, sends real prompts, and asserts on the ACP stream and repository side effects. This is where you register your agent so it gets *tested*. | + +--- + +## The skills: what every agent carries + +A **skill** is an on-demand reference document the agent loads when a task +calls for it (kept out of the always-on prompt to save context). Every Atomic +agent ships the same three core skills, so that **behavior is identical no +matter which agent the user runs** — the agent is interchangeable; the Atomic +workflow is not. + +### 1. Intents (`atomic-vault`) — capturing the *why* + +The vault is Atomic's built-in project-management and context layer. It tracks +**intents** (units of work, like tickets), **goals** (work sessions), and +**memory** (durable knowledge that persists across sessions). + +This skill teaches the agent the intent lifecycle: + +```bash +atomic vault intent list # always check first +atomic vault intent create --title "Implement JWT signing" +atomic vault intent update --status planned # after the user accepts the plan +atomic vault sync # persist .vault/ file edits to the DB +``` + +Why it matters: the prompt alone is not enough. The intent is where the agent +writes the **problem statement**, the **testable success criteria**, and the +**task list** — before writing any code. That artifact lives in the repo, so +the "why" survives the chat session. This is the foundation of Atomic's +problem-first workflow: the user's request is usually a *solution* ("build me +X"); the agent reframes it as a *problem*, gets agreement, then executes. + +### 2. Code Intelligence (`code-intelligence`) — navigating the code + +Atomic maintains a knowledge graph and content index of the repository. This +skill teaches the agent to use it **instead of blind `grep`/`find`**: + +```bash +atomic vault query code "fn parse_query" -t rs # source content search (grep replacement) +atomic vault query search "authentication" # structural KG search: files, entities, changes +atomic vault query neighbors # relationships between entities +atomic vault query entities # file outline +``` + +Why it matters: exploration becomes structural and cheap. The agent finds the +function by relationship, not by scanning the filesystem — and Atomic learns +what the agent looked at, which feeds the decision graph. + +### 3. VCS (`atomic-vcs`) — speaking the Atomic CLI + +This skill teaches the agent the **read-only** side of the Atomic CLI: + +```bash +atomic status # what's different in the working copy right now? +atomic log # recent history of this view +atomic change -p # what's in one change, including AI provenance +atomic change -a # AI attestation for a change +atomic diff # precise line/token edits, working copy vs recorded +``` + +Why it matters: it lets the agent ground itself in what actually changed and +audit its own recorded work instead of guessing. It also reinforces the +division of labor: **reading history is the agent's job; recording is the +hook's job.** + +> Some agents ship extras on top of the core three — `atomic-claude` adds +> `intent-builder` and `codebase-context` — but `atomic-vault`, +> `code-intelligence`, and `atomic-vcs` are the baseline every package +> includes. Reuse the existing `SKILL.md` files verbatim (copy them from +> `atomic-claude/skills/`); keeping the content shared is the point — fix a +> workflow detail once and every agent benefits. + +--- + +## The system prompt: `AGENTS.md` and friends + +The hooks and adapter make Atomic *record* what the agent does. The **system +prompt** makes the agent *do the right things* in the first place. It is the +most important file in the integration package. + +Without it, you get perfect provenance for an agent that still thinks it's +using git, invents its own workflow, and greps the filesystem blindly. With +it, the agent works problem-first, keeps history clean, and uses Atomic's own +tools for discovery. **Capture without behavior is a faithful recording of a +mess.** + +Each agent reads its system prompt from a different file convention: + +| Convention | Agents | +|-----------|--------| +| `CLAUDE.md` at root | Claude Code | +| `AGENTS.md` at root | Codex, Devin, Gemini | +| `agents/*.md` | OpenCode, Pi | +| `rules/*.md` | Cursor, Cline | +| `steering/*.md` | Kiro | +| `copilot-instructions.md` | Copilot | + +Whatever the filename, the prompt must establish the same four things. Real +examples to copy from: [`atomic-claude/CLAUDE.md`](https://github.com/atomicdotdev/atomic-claude/blob/main/CLAUDE.md) +(full version) and +[`atomic-opencode/agents/atomic.md`](https://github.com/atomicdotdev/atomic-opencode/blob/main/agents/atomic.md) +(compact version). + +1. **"You use Atomic VCS, not git."** — Set the tool up front so the agent + stops reaching for `git` commands. + +2. **The intent-first workflow.** — Every unit of work becomes an *intent*: + check for an existing one, create one if needed, reframe the request as a + problem statement with testable success criteria, write the plan into the + intent file, get human agreement, then execute and check off tasks. The + plan lives in the file, not just in chat. + +3. **"Do NOT run `atomic add` or `atomic record`."** — Critical. The hook + system records automatically, with provenance, at turn end. If the agent + records manually it produces changes with no AI provenance and can race the + orchestrator. Companion rules: "do not create or switch views" (the session + view is automatic) and "do not run `atomic agent enable`" (already + configured). + +4. **Point at the skills.** — Tell the agent to load `atomic-vault`, + `atomic-vcs`, and `code-intelligence` on demand. + +Copy an existing prompt and adapt the surface details (how that agent invokes +skills, its permission block, its frontmatter) rather than writing from +scratch — the workflow content should stay consistent across all agents. + +--- + +## Hooks: how the agent reports to Atomic + +A **hook** is a lifecycle event the agent fires, translated into a call to the +Atomic CLI. This is the capture half of the integration. + +### The events we want + +No matter which agent or wiring style, the whole job is to notify Atomic at +six moments in an agent's life. Each event is delivered as: + +```bash +echo '' | atomic agent hooks +``` + +Session state is persisted between calls under `.atomic/sessions/` — each hook +invocation is a fresh, stateless CLI process keyed by `session_id`. + +| Event (`HookType`) | Typical verb(s) | Fires when | What Atomic does | +|--------------------|-----------------|------------|------------------| +| `SessionStart` | `session-start` | agent session opens | Forks a **draft view** for the session and switches the working copy onto it — 1 session = 1 view, so the agent's work is isolated and reviewable as a unit | +| `TurnStart` | `user-prompt`, `user-prompt-submit`, `before-agent` | user submits a prompt | Saves the prompt + model/provider, starts a file-change baseline, opens a **Goal** node in the decision graph | +| `PreToolUse` | `before-tool`, `pre-tool` | before a tool runs | Bookkeeping only (no output yet) | +| `PostToolUse` | `after-tool`, `post-tool` | after a tool runs | Appends a classified node (`Exploration` / `Commitment` / `Verification` / `Execution` / `Error`) plus inferred causal edges to the session's **decision graph** | +| `TurnEnd` | `stop`, `after-agent`, `turn-end` | agent finishes a turn | **Records a change** on the draft view with full AI provenance embedded | +| `SessionEnd` | `session-end` | agent session closes | Flushes any unrecorded work, writes the **AI attestation**, restores the parent view | + +**The golden rule of responsibility:** the agent side (plugin or hook command) +only does two things — fire the event at the right moment, and attach a JSON +telemetry payload. **Atomic does all version-control work itself** inside the +`TurnOrchestrator` (`atomic-agent/src/turn/orchestrator.rs`). You never call +`atomic add` or `atomic record` from the integration; you emit events and +Atomic records. This is why a correct integration is small. + +Two events deserve emphasis: + +- **`TurnEnd` is the one that matters most.** This is where a turn's edits + become a permanent, provenance-bearing change. The orchestrator checks the + working copy (no changes → no empty record), auto-adds untracked files, + records on the session's draft view, and embeds everything the payload + carries: vendor, model, the prompt (hashed), token counts, `cost_usd`, + finish reason, reasoning, the task plan — plus a session envelope. The more + your payload sends, the richer `atomic change -p` output is. If you + integrate only one event beyond `SessionStart`, make it this one. + +- **Tool events are the "nice to have," not the backbone.** If your agent + can't emit tool-level events, you simply get no decision graph — provenance + still works (change, prompt, model, tokens, attestation are all captured at + turn/session end). + +Because Atomic does all the VCS work, the smallest useful integration is just +**two CLI calls**: + +```bash +# Once, when the session starts (creates the draft view): +echo '{"session_id":"my-sess-1","cwd":"'"$PWD"'"}' \ + | atomic agent hooks session-start + +# ... agent edits files ... + +# When a unit of work finishes (records the change WITH provenance): +echo '{"session_id":"my-sess-1","prompt":"add retry logic", + "model":"...","provider":"...","input_tokens":1200,"output_tokens":800, + "cost_usd":0.04}' \ + | atomic agent hooks stop +``` + +Add `user-prompt` (captures the prompt/Goal), `before-tool`/`after-tool` +(builds the decision graph), and `session-end` (attestation + view restore) as +your agent is able to signal them. Every field beyond `session_id` is optional +and simply enriches the recorded provenance. + +Every hook invocation should be guarded so it only fires inside an Atomic repo +and never breaks the agent if something fails: + +```bash +test -d .atomic && atomic agent hooks || true +``` + +--- + +## Why each agent must be added explicitly + +If hooks are just "pipe JSON to a CLI," why does every agent need its own Rust +adapter in this repo? **Because no two agents speak the same dialect.** + +- **Different hook names.** Claude Code fires `Stop` when a turn ends and + `UserPromptSubmit` when a prompt arrives. OpenCode fires `session.idle` and + `chat.message`. Codex, Gemini, and Cursor each have their own names again. +- **Different payload shapes.** One agent sends + `{"session_id": ..., "model": ...}`; another nests the model under + `message.model.id`; a third doesn't send token counts at all. Each agent's + JSON is its own schema. + +Atomic's internals don't want to know about any of that. Internally there is +one **standardized event format**: + +- `HookType` (`atomic-agent/src/event.rs:67`) — the six canonical events: + `SessionStart`, `SessionEnd`, `TurnStart`, `TurnEnd`, `PreToolUse`, + `PostToolUse`. +- `TurnEvent` (`atomic-agent/src/event.rs`) — one normalized struct carrying + `session_id`, optional `prompt`, `tool_name`, `tool_use_id`, and a + `raw_json` bag for everything else (model, provider, tokens, cost, …). + +The **hook adapter** is the translator between the two. Each adapter: + +1. Maps the agent's verb strings to a `HookType` + (`HookType::from_verb`, `atomic-agent/src/event.rs:166` — one function that + is the union of all agents' verb strings). +2. Deserializes that agent's stdin JSON and builds a `TurnEvent` + (`AgentHook::parse_event`), stashing extra telemetry into `raw_json`. + +``` +agent-native event standardized event +───────────────────── ────────────────── +"session.idle" + OpenCode JSON ──► HookType::TurnEnd + TurnEvent +"Stop" + Claude JSON ──► HookType::TurnEnd + TurnEvent + + your JSON ──► HookType::TurnEnd + TurnEvent + │ + ▼ + TurnOrchestrator (one code path, + agent-agnostic) → provenance-bearing change +``` + +That translation layer is the entire reason "adding an agent" is an explicit +act: you are teaching Atomic a new dialect so everything downstream — +recording, provenance, attestation, diffing — works through a single +agent-agnostic pipeline. + +--- + +## Plugin vs. config file: choosing the wiring + +The last design question is *how the agent's lifecycle events end up calling +the CLI*. There are two styles — and **which one you use is dictated by the +agent's extension model, not by preference.** + +### A. Native-hooks manifest (the config-file style) + +Used when the agent exposes its own hook system in a user-editable settings +file (Claude Code, Codex, Gemini, Cursor, …). + +The integration package ships a **hooks manifest** JSON describing where the +agent's settings file lives and which commands to register +([`atomic-claude/hooks/claude-code.atomic-hooks.json`](https://github.com/atomicdotdev/atomic-claude/blob/main/hooks/claude-code.atomic-hooks.json)). +`atomic agent enable --hooks ` merges it into the agent's settings +file — the merge engine is built into `atomic` +(`atomic-agent/src/hooks/manifest.rs`), is idempotent, and preserves the +user's non-Atomic hooks: + +```json +{ + "target": "~/.claude/settings.json", + "hooks_key": "hooks", + "command_prefix": "atomic agent hooks claude-code", + "hooks": { + "SessionStart": [ { "matcher": "", "hooks": [ + { "type": "command", + "command": "test -d .atomic && atomic agent hooks claude-code session-start || true" } ] } ], + "Stop": [ { "matcher": "", "hooks": [ + { "type": "command", + "command": "test -d .atomic && atomic agent hooks claude-code stop || true" } ] } ] + }, + "merge": { "permissions": { "deny": [ "Read(./.atomic/metadata/**)" ] } } +} +``` + +- `target` — the agent's settings file (`~` expands to home). +- `command_prefix` — substring identifying *our* hooks, so re-runs are + idempotent and uninstall removes only ours. +- `hooks` — event → entries in the agent's native shape. +- `merge` — extra non-hook settings deep-merged into the file. + +The big win: the manifest is **declarative and lives in the integration +package**, so changing hook wiring never requires rebuilding `atomic` — just +re-publish the package. + +### B. Plugin (the code style) -The mental model: +Used when the agent exposes a plugin/extension API instead of a hooks config +(OpenCode, …). +The integration package ships a plugin that subscribes to lifecycle events in +code and shells out to the CLI +([`atomic-opencode/plugins/atomic-hooks.ts`](https://github.com/atomicdotdev/atomic-opencode/blob/main/plugins/atomic-hooks.ts)). +The essential shape: + +```ts +// On each lifecycle event, pipe JSON to the CLI: +await $`echo ${JSON.stringify(payload)} | atomic agent hooks ${verb} 2>/dev/null`.nothrow(); ``` - atomic- package atomic (this repo) - ───────────────────── ────────────────── - agent runs, fires lifecycle ──► atomic agent hooks - events → calls the CLI │ - (plugin or native hooks) ▼ - AgentRegistry.require() - adapter.parse_event(verb, stdin-json) - │ - ▼ - TurnEvent → TurnOrchestrator - │ - ▼ - change recorded with AI provenance - - - atomic-agents (harness) ──► spawns the agent over ACP, prompts it, - verifies it can search / status / record + +The plugin maps the agent's events to Atomic verbs — OpenCode's mapping is +`session.created→session-start`, `chat.message→user-prompt`, +`tool.execute.before→before-tool`, `tool.execute.after→after-tool`, +`session.idle→after-agent` (→ `TurnEnd`), `session.deleted→session-end`. + +A plugin is more work than a manifest, but it earns its keep: it can observe +**rich telemetry a shell hook cannot** — model, provider, token counts, cost, +timing — and put it in the payload, which is exactly what makes recorded +provenance valuable. The plugin also decides *when* to fire (e.g. OpenCode's +plugin auto-records on idle as a safety net) and disables itself outside +Atomic repos. + +### How to choose + +| Agent exposes… | You ship… | +|----------------|-----------| +| Only a plugin API (no user hooks config) | A plugin — your only option (this is why `atomic-opencode` exists) | +| Only a settings/hooks file (no plugin API) | A hooks manifest — your only option (this is why `atomic-claude` exists) | +| Both | Prefer whichever gives richer lifecycle data (usually the plugin: model/tokens/cost/timing) with the simpler install | +| Neither cleanly | Degraded mode: use whatever coarse signal exists (e.g. session boundary) and have the adapter's `supported_hooks()` advertise only what you can actually observe | + +**Investigate the target agent's extension model first and let it decide.** +Whichever style you land on, the payload that reaches Atomic is identical: +JSON on stdin to `atomic agent hooks `. + +### Worked example: the OpenCode flow end-to-end + +``` +user runs `opencode` in a project that has .atomic/ + │ + ▼ +OpenCode loads plugins/atomic-hooks.ts (registered in opencode.json) + │ the plugin first checks: `atomic` on PATH and .atomic/ present? + │ if not, it disables itself. No atomic repo → no-op. + ▼ +OpenCode fires lifecycle events; the plugin translates each to a CLI call: + session.created → atomic agent hooks opencode session-start + chat.message → atomic agent hooks opencode user-prompt + tool.execute.after → atomic agent hooks opencode after-tool + session.idle → atomic agent hooks opencode after-agent + session.deleted → atomic agent hooks opencode session-end + │ each call pipes a JSON payload (model, provider, tokens, timing) + ▼ +`atomic agent hooks opencode ` (atomic-cli/src/commands/agent/hooks.rs) + │ AgentRegistry.require("opencode") → OpenCodeHook + │ OpenCodeHook::parse_event(verb → HookType, stdin JSON) → TurnEvent + ▼ +TurnOrchestrator records the turn as an Atomic change with AI provenance +(1 session = 1 draft view) ``` -Two integration *styles* exist. **Which one(s) you can use is dictated by the -agent, not by preference** — it depends entirely on what extension mechanism -the target agent exposes: - -1. **Native-hooks style** (Claude Code, Codex, Gemini, Cursor, …). The agent - has its own hook system in a settings file. The integration package ships a - **hooks manifest** JSON; `atomic agent enable --hooks ` merges it - into the agent's settings file. See `atomic-claude`. -2. **Plugin style** (OpenCode, …). The agent exposes a plugin/extension API. - The integration package ships a plugin that subscribes to lifecycle events - and shells out to `atomic agent hooks `. See `atomic-opencode` - (`plugins/atomic-hooks.ts`). - -You do not freely pick between these — the agent constrains you: - -- Some agents **only** support a plugin (no user-editable hooks config), so the - plugin style is your only option — this is why OpenCode ships a plugin. -- Some agents **only** expose a settings/hooks file (no plugin API), so the - native-hooks manifest is the only option — this is why Claude Code ships a - manifest. -- Some agents support **both**, in which case pick whichever gives you richer - lifecycle data (a plugin can usually report model/tokens/cost/timing that a - shell hook cannot) and the simpler install. -- Some agents support **neither** cleanly. Then you're limited to whatever - coarse signal is available (e.g. detecting a config directory and recording - on a file-watch / session boundary) — and the adapter's `supported_hooks()` - should advertise only the events you can actually observe. - -Before writing anything, **investigate the target agent's extension model -first** and let that decide the style. Whichever style you land on, the payload -that reaches Atomic is identical: JSON on stdin to -`atomic agent hooks `. +The plugin is the driver (it decides when to call Atomic and what to send); +the Rust adapter is a thin parser that turns the payload into a `TurnEvent`. +The user never types `atomic agent hooks …` — the plugin does, automatically, +on every event. --- -## Part 1 — The hook adapter in `atomic` (required) +## Building the integration + +Now the concrete work, in three parts. Everything above is the theory; this is +the generalization of the flow you just saw. + +### Part 1 — The hook adapter in `atomic` (required) Everything in the `atomic agent hooks ` pipeline is keyed off a -**string agent name**, dispatched through the `AgentRegistry`. To make Atomic +string agent name, dispatched through the `AgentRegistry`. To make Atomic understand a new agent you implement one trait and register it. -### 1.1 Create the adapter file +#### 1.1 Create the adapter file Create `atomic-agent/src/hooks/.rs`. Use -`atomic-agent/src/hooks/opencode.rs` as the reference implementation — it is -the cleanest example and covers all six hook types. +[`atomic-agent/src/hooks/opencode.rs`](atomic-agent/src/hooks/opencode.rs) as +the reference implementation — it is the cleanest example and covers all six +hook types. Implement the `AgentHook` trait (`atomic-agent/src/hooks/mod.rs:131`): @@ -107,52 +477,48 @@ pub trait AgentHook: Send + Sync + fmt::Debug { Key responsibilities of `parse_event`: -- Deserialize the agent's stdin JSON (each agent sends a different shape — model - one struct per verb, as `opencode.rs` does). -- Build a `TurnEvent` (`atomic-agent/src/event.rs`) with `session_id`, and - attach `prompt`, `tool_name`, `tool_use_id` where relevant. +- Deserialize the agent's stdin JSON (each agent sends a different shape — + model one struct per verb, as `opencode.rs` does). +- Build a `TurnEvent` with `session_id`, attaching `prompt`, `tool_name`, + `tool_use_id` where relevant. - Stash anything else the orchestrator/provenance wants (model, provider, tokens, cost, finish reason) into `raw_json` — see how `opencode.rs` re-inserts `model`/`provider` into the raw JSON object. -The six canonical hook types (`atomic-agent/src/event.rs:67`) are: -`SessionStart`, `SessionEnd`, `TurnStart`, `TurnEnd`, `PreToolUse`, -`PostToolUse`. An agent need not support all of them — return only what it -emits from `supported_hooks()` and `hook_verbs()`. +An agent need not support all six hook types — return only what it can +actually emit from `supported_hooks()` and `hook_verbs()`. Regarding `install`/`uninstall`/`is_installed`: if the integration package -handles installation itself (plugin style, or manifest style), these can be -near no-ops. OpenCode's adapter returns `Ok(1)`/`Ok(0)` from `install` by -checking whether the plugin file exists, and `uninstall` is a no-op — because -the `atomic-opencode` npm package owns installation. Only implement real -config-file writing here if you want `atomic agent enable --agent ` to be -the installer (the older per-repo path). +handles installation itself (plugin or manifest style), these are near no-ops. +OpenCode's adapter just checks whether the plugin file exists, because the +`atomic-opencode` npm package owns installation. Only implement real +config-file writing here if you want `atomic agent enable --agent ` to +be the installer. -### 1.2 Register the adapter +#### 1.2 Register the adapter Add the module and register it in the default registry (`atomic-agent/src/hooks/mod.rs`): ```rust -// near line 59, with the other `pub mod` declarations +// with the other `pub mod` declarations (~line 59) pub mod myagent; -// in AgentRegistry::with_defaults() near line 319 +// in AgentRegistry::with_defaults() (~line 319) registry.register(Box::new(myagent::MyAgentHook::new())); ``` -That is the *only* place that decides which agents exist. `atomic agent hooks`, -`enable`, `status`, and auto-detection all read from this registry. +That is the *only* place that decides which agents exist. `atomic agent +hooks`, `enable`, `status`, and auto-detection all read from this registry. -### 1.3 Map the agent's verbs to hook types +#### 1.3 Map the agent's verbs to hook types `atomic agent hooks ` turns `` into a `HookType` via `HookType::from_verb` (`atomic-agent/src/event.rs:166`). This one function is -the union of *all* agents' verb strings. If your agent introduces a verb string -that is not already mapped, add an arm: +the union of *all* agents' verb strings. If your agent introduces a verb +string that is not already mapped, add an arm: ```rust -// in HookType::from_verb "my-turn-begin" => Some(HookType::TurnStart), "my-turn-done" => Some(HookType::TurnEnd), ``` @@ -161,156 +527,75 @@ Many common verbs (`session-start`, `session-end`, `user-prompt`, `stop`, `before-tool`, `after-tool`, …) are already mapped — reuse them if your plugin can emit them, and you may not need to touch this function at all. -### 1.4 Wire correct provenance (strongly recommended) +#### 1.4 Wire correct provenance (strongly recommended) The agent name flows through end-to-end as a free-form string (`AITool::Cli(String)`), so recording will *work* without these. But several -hardcoded per-agent maps make the output correct and pretty. Update them: +hardcoded per-agent maps make the output correct and pretty: -| What | File:line | Why | -|------|-----------|-----| +| What | Where | Why | +|------|-------|-----| | Vendor inference | `atomic-agent/src/record/provenance.rs:161` (`vendor_from_agent_name`) | Maps agent → `AIVendor`. Without an arm, vendor becomes `Other("")`. | -| Author-is-agent classification | `atomic-repository/src/repository/provenance_summary.rs:208` (`KNOWN_AGENT_PREFIXES`) and the fallback name list (~`:241`) | Otherwise the agent's changes are miscounted as human-authored in `atomic agent attest --summary`. | +| Author-is-agent classification | `atomic-repository/src/repository/provenance_summary.rs:208` (`KNOWN_AGENT_PREFIXES`) + fallback list (~`:241`) | Otherwise the agent's changes are miscounted as human-authored in `atomic agent attest --summary`. | | Display prettifier | `atomic-cli/src/commands/agent/attest.rs:607` (`pretty_tool`) | Nice name in attestation output. | -Note: `AIVendor` itself is an enum (`atomic-core/src/change/provenance/types.rs:21`). -If your agent's provider isn't represented and you don't want `Other(...)`, add -a variant there and to its `parse()`. +`AIVendor` itself is an enum (`atomic-core/src/change/provenance/types.rs:21`); +if your agent's provider isn't represented and you don't want `Other(...)`, +add a variant there and to its `parse()`. -### 1.5 (Optional) global install support +#### 1.5 (Optional) global install support `atomic agent enable --global` uses a hardcoded `match agent_name` in `atomic-cli/src/commands/agent/enable.rs` (~`:324`). Only add an arm if your agent supports a single global settings file *and* you want `enable --global` -to be the installer. Plugin/manifest-style integrations don't need this — they -install themselves. - ---- +to be the installer. Plugin/manifest-style integrations don't need this — +they install themselves. -## Part 2 — The integration package `atomic-` (required) +### Part 2 — The integration package `atomic-` (required) -This is a separate repo (published so users can install it). It contains no -Atomic Rust code — only the agent-facing assets and the wiring that makes the -agent call `atomic agent hooks …`. +A separate repo (published so users can install it). It contains no Atomic +Rust code — only the agent-facing assets and the wiring. -Standard layout (see `atomic-opencode` and `atomic-claude`): +Standard layout (see [`atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode) +and [`atomic-claude`](https://github.com/atomicdotdev/atomic-claude)): ``` atomic-/ -├── agents/.md or CLAUDE.md / AGENTS.md # system prompt +├── agents/.md or CLAUDE.md / AGENTS.md # system prompt (see above) ├── skills/ │ ├── atomic-vault/SKILL.md │ ├── atomic-vcs/SKILL.md │ └── code-intelligence/SKILL.md -├── hooks/.atomic-hooks.json # manifest (native-hooks style) +├── hooks/.atomic-hooks.json # manifest (config-file style) │ —or— -├── plugins/atomic-hooks.ts # plugin (plugin style) -├── install.sh # dev install (symlinks) -├── install.js # npm postinstall +├── plugins/atomic-hooks.ts # plugin (plugin style) +├── install.sh # dev install (symlinks into the agent's config dir) +├── install.js # npm postinstall equivalent ├── package.json └── README.md ``` -### 2.1 The system prompt - -Ship the agent's system prompt in whatever file the agent reads. The prompt -location convention per agent is recorded in the harness -(`atomic-agents/.../env.rs`, `PromptKind`): - -- `CLAUDE.md` at root — Claude Code -- `AGENTS.md` at root — Codex, Devin, Gemini -- `agents/*.md` — OpenCode, Pi -- `rules/*.md` — Cursor, Cline -- `steering/*.md` — Kiro -- `copilot-instructions.md` — Copilot - -The prompt should teach the intent-first Atomic workflow (create an intent, -define the problem, plan, execute, and *don't* run `atomic add`/`record` — -hooks do that). Copy `atomic-claude/CLAUDE.md` or `atomic-opencode/agents/atomic.md` -as a starting point. - -### 2.2 The skills - -Skills are on-demand reference docs the agent loads when relevant. The common -set is `atomic-vault`, `atomic-vcs`, and `code-intelligence`. Reuse the -existing skill content; the installer symlinks them into the agent's skills -directory. - -### 2.3 The lifecycle wiring — use the style the agent supports - -Use whichever style the target agent's extension model allows (see the -constraints in [The three repositories](#the-three-repositories) above): a -manifest if it has a user-configurable hooks file, a plugin if it exposes a -plugin API, both-then-prefer-plugin if it supports both. - -**A. Native-hooks style (manifest).** Write -`hooks/.atomic-hooks.json` describing where the agent's settings file is -and which commands to register. The manifest is merged idempotently by -`atomic agent enable --hooks ` — the merge engine is built into -`atomic` (no `jq`/Node needed), and it preserves the user's non-Atomic hooks. -See `atomic-claude/hooks/claude-code.atomic-hooks.json`. Format -(`atomic-agent/src/hooks/manifest.rs`): - -```json -{ - "target": "~/.claude/settings.json", - "hooks_key": "hooks", - "command_prefix": "atomic agent hooks claude-code", - "hooks": { - "SessionStart": [ { "matcher": "", "hooks": [ - { "type": "command", - "command": "test -d .atomic && atomic agent hooks claude-code session-start || true" } ] } ], - "Stop": [ { "matcher": "", "hooks": [ - { "type": "command", - "command": "test -d .atomic && atomic agent hooks claude-code stop || true" } ] } ] - }, - "merge": { "permissions": { "deny": [ "Read(./.atomic/metadata/**)" ] } } -} -``` - -- `target` — the agent's settings file (`~` expands to home). -- `command_prefix` — substring identifying *our* hooks so re-runs are - idempotent and uninstall removes only ours. -- `hooks` — `event → [entry]` in the agent's native shape (nested - `{matcher, hooks:[{command}]}` or flat `{command}` both supported). -- `merge` — extra non-hook settings deep-merged into the file. +You have already seen the three ingredients — the prompt, the skills, and the +wiring — in the conceptual half of this doc. Assembly notes: -The big win: because the manifest lives in the integration repo, changing hook -wiring never requires rebuilding `atomic` — just re-publish the package. +- **Prompt**: ship it under the filename convention your agent reads (see the + table in [The system prompt](#the-system-prompt-agentsmd-and-friends)). +- **Skills**: copy the three core `SKILL.md` files verbatim; the installer + symlinks them into the agent's skills directory (e.g. + `~/.config/opencode/skills/`, `~/.claude/skills/`). +- **Wiring**: whichever style the agent's extension model dictates (see + [Plugin vs. config file](#plugin-vs-config-file-choosing-the-wiring)). + Guard every hook: `test -d .atomic && … || true`. +- **Installer**: `install.sh` (dev) symlinks the prompt + skills and, for + manifest style, calls `atomic agent enable --hooks `. `install.js` + is the npm `postinstall` equivalent. Copy from whichever existing package + matches your style. -**B. Plugin style.** If the agent has a plugin API, write a plugin that -subscribes to lifecycle events and shells out to the CLI. See -`atomic-opencode/plugins/atomic-hooks.ts`. The essential shape: - -```ts -// on each lifecycle event, pipe JSON to the CLI -await $`echo ${JSON.stringify(payload)} | atomic agent hooks ${verb}`.nothrow(); -``` - -Map the agent's events to Atomic verbs, e.g. OpenCode: -`session.created→session-start`, `chat.message→user-prompt`, -`tool.execute.before→before-tool`, `tool.execute.after→after-tool`, -`session.idle→stop`, `session.deleted→session-end`. Send model, provider, -tokens, cost, and timing in the payload so provenance is rich. - -Guard every hook so it only fires inside an Atomic repo: -`test -d .atomic && … || true` (or the sandbox-aware form in -`guarded_hook_command`, `atomic-agent/src/hooks/mod.rs:103`). - -### 2.4 The installer - -`install.sh` (dev) symlinks prompt + skills into the agent's config dir and, for -native-hooks style, calls `atomic agent enable --hooks `. `install.js` -is the npm `postinstall` equivalent. Copy from whichever existing package -matches your style. - ---- - -## Part 3 — Register the agent in the test harness `atomic-agents` (required) +### Part 3 — Register the agent in the test harness (required) The harness in `atomic-agents` auto-discovers and tests every agent that (a) has an integration package present and (b) is spawnable per the live ACP -registry. To include your agent, add one entry to `AGENT_REGISTRY` in +registry. To include yours, add one entry to `AGENT_REGISTRY` in `crates/atomic-agent-harness/src/env.rs` (~`:48`): ```rust @@ -318,26 +603,61 @@ AgentEntry { registry_id: "myagent-acp", // ID in the canonical ACP registry name: "myagent", // label in test output package: "atomic-myagent", // dir name under AGENTS_DIR - prompt: PromptKind::AgentsDir, // where the prompt lives (see 2.1) + prompt: PromptKind::AgentsDir, // where the prompt lives installed_skills_dir: "~/.config/myagent/skills", skills: &["atomic-vault", "atomic-vcs", "code-intelligence"], -}, +} ``` Notes: -- The **spawn command** is *not* hardcoded — it comes from the live ACP registry - (`registry.rs`, fetched from `cdn.agentclientprotocol.com`). `registry_id` - must match the agent's ID there. If the agent is stdio-only and needs a - local install hint, add it to `spawn.rs`'s `AGENTS` table. +- The **spawn command** is *not* hardcoded — it comes from the live ACP + registry (`registry.rs`, fetched from `cdn.agentclientprotocol.com`). + `registry_id` must match the agent's ID there. If the agent is stdio-only + and needs a local install hint, add it to `spawn.rs`'s `AGENTS` table. - `available_agents()` only returns an agent when its package directory exists - in `AGENTS_DIR` (default `~/Projects/agents`) *and* the registry knows how to - spawn it on this platform. + in `AGENTS_DIR` (default `~/Projects/agents`) *and* the registry knows how + to spawn it on this platform. + +--- + +## Testing: use the agent harness + +**Do not rely on manual smoke tests alone — register your agent in the +[harness](https://github.com/atomicdotdev/atomic-agents) and run it.** The +harness exists precisely because integrations fail in ways unit tests can't +see: it spawns the *real agent* over ACP, sends it *real prompts*, and asserts +on both the ACP stream and the repository side effects. It verifies your +prompt and skills actually work — that the agent responds, uses code search, +checks repo status, and creates intents the way the workflow demands. + +The shared `all_agents_*` integration tests live in +`crates/atomic-agent-harness/tests/acp_integration.rs`. They are `#[ignore]`d +by default (they make real LLM calls); run them explicitly: + +```bash +# 1. Build atomic with your adapter and run its unit tests. +cargo build -p atomic +cargo test -p atomic-agent # adapter unit tests — copy opencode.rs's test module + +# 2. Install the integration package (dev mode: symlinks, edits go live immediately). +cd ~/code/work/atomic- && ./install.sh + +# 3. Manual smoke test — this is exactly what the agent will do. +cd /some/atomic/repo +echo '{"session_id":"t1","cwd":"'"$PWD"'"}' | atomic agent hooks session-start +echo '{"session_id":"t1","prompt":"hi","model":"...","provider":"..."}' | atomic agent hooks user-prompt +echo '{"session_id":"t1","turn_number":1}' | atomic agent hooks stop +atomic agent attest # confirm a provenance/attestation record appeared + +# 4. Full ACP integration test via the harness (needs API key + package in AGENTS_DIR). +cd ~/code/work/atomic-agents +cargo test -p atomic-agent-harness --test acp_integration -- --ignored --nocapture +``` -The harness then runs the shared `all_agents_*` integration tests against your -agent (`crates/atomic-agent-harness/tests/acp_integration.rs`): respond to a -prompt, use code search, check repo status, create an intent. These are -`#[ignore]` by default (they make real LLM calls); run explicitly. +Step 3 validates the capture half (events → provenance). Step 4 validates the +behavior half (prompt + skills → correct agent behavior). You want both green +before calling the integration done. --- @@ -356,8 +676,8 @@ prompt, use code search, check repo status, create an intent. These are **In `atomic-` (integration package):** -- [ ] System prompt in the agent's convention (`CLAUDE.md` / `agents/*.md` / …). -- [ ] Skills (`atomic-vault`, `atomic-vcs`, `code-intelligence`). +- [ ] System prompt in the agent's convention (`CLAUDE.md` / `AGENTS.md` / `agents/*.md` / …). +- [ ] Skills: `atomic-vault`, `atomic-vcs`, `code-intelligence`. - [ ] Lifecycle wiring: a hooks manifest **or** a plugin that calls `atomic agent hooks `. - [ ] Every hook guarded with `test -d .atomic && … || true`. - [ ] `install.sh` / `install.js` + `package.json` + `README.md`. @@ -366,52 +686,27 @@ prompt, use code search, check repo status, create an intent. These are - [ ] `AgentEntry` added to `AGENT_REGISTRY` (`env.rs`). - [ ] `registry_id` matches the canonical ACP registry (add spawn hint to `spawn.rs` if stdio-only). +- [ ] `acp_integration` tests pass for your agent. -## Verifying end-to-end - -```bash -# 1. Build atomic with your adapter. -cargo build -p atomic -cargo test -p atomic-agent - -# 2. Install the integration package into your agent (dev mode). -cd ~/code/work/atomic- && ./install.sh - -# 3. Smoke-test the hook path by hand — this is exactly what the agent will do. -cd /some/atomic/repo -echo '{"session_id":"t1","cwd":"'"$PWD"'"}' | atomic agent hooks session-start -echo '{"session_id":"t1","prompt":"hi","model":"...","provider":"..."}' | atomic agent hooks user-prompt -echo '{"session_id":"t1","turn_number":1}' | atomic agent hooks stop -atomic agent attest # confirm a provenance/attestation record appeared - -# 4. Full ACP integration test via the harness (real LLM calls; needs API key + package in AGENTS_DIR). -cd ~/code/work/atomic-agents -cargo test -p atomic-agent-harness --test acp_integration -- --ignored --nocapture -``` - -## What is agent-agnostic vs. what you must touch - -Agent-agnostic (no change needed): the `atomic agent hooks ` -command itself, the `AgentRegistry` dispatch machinery, the `AITool::Cli(String)` -provenance carrier, the manifest merge engine, and the W3C PROV projection -(the agent slug is free-form). +## Example repositories -Must touch to add a *fully supported* agent: the adapter file, its registry -registration, and (if it uses new verb strings) the verb map — plus the -provenance/display maps for correct attribution. +| Repo | Style | Look at it for | +|------|-------|----------------| +| [`atomicdotdev/atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode) | Plugin | `plugins/atomic-hooks.ts` (lifecycle → CLI), `agents/atomic.md` (compact prompt) | +| [`atomicdotdev/atomic-claude`](https://github.com/atomicdotdev/atomic-claude) | Hooks manifest | `hooks/claude-code.atomic-hooks.json` (manifest), `CLAUDE.md` (full prompt), all five skills | +| [`atomicdotdev/atomic-agents`](https://github.com/atomicdotdev/atomic-agents) | Test harness | `crates/atomic-agent-harness/src/env.rs` (agent registry) | +| [`atomicdotdev/atomic`](https://github.com/atomicdotdev/atomic) | Engine (this repo) | `atomic-agent/src/hooks/opencode.rs` (reference adapter) | ## Reference: key files - Trait + registry: `atomic-agent/src/hooks/mod.rs` - Example adapter (plugin style): `atomic-agent/src/hooks/opencode.rs` -- Example adapter set: `atomic-agent/src/hooks/{claude_code,codex,gemini_cli,cursor,…}.rs` +- More adapters: `atomic-agent/src/hooks/{claude_code,codex,gemini_cli,cursor,…}.rs` - Verb → hook-type map: `atomic-agent/src/event.rs` (`HookType::from_verb`) - Manifest install engine: `atomic-agent/src/hooks/manifest.rs` +- Orchestrator (does the recording): `atomic-agent/src/turn/orchestrator.rs` - Hooks CLI entry: `atomic-cli/src/commands/agent/hooks.rs` - Enable/attest CLI: `atomic-cli/src/commands/agent/{enable,attest}.rs` - Provenance mapping: `atomic-agent/src/record/provenance.rs`, `atomic-repository/src/repository/provenance_summary.rs` -- Integration packages: `atomic-opencode/` (plugin), `atomic-claude/` (manifest) - Test harness registry: `atomic-agents/crates/atomic-agent-harness/src/env.rs` - - From f63dce93e34527d7d03e7b68cdecd25f2d191482 Mon Sep 17 00:00:00 2001 From: Aaron Ogle Date: Mon, 27 Jul 2026 16:33:07 -0500 Subject: [PATCH 3/3] docs: update adding-agents guide for storage-based integration install - New 'How installation works' section: the integrations engine, registry.toml (where to fetch) vs atomic-integration.toml (what to install), receipt-driven uninstall, --from dev loop - Part 1: adapters are parser + presence checks only (no installers); added registry.toml step 1.2b - Part 2: package layout centers on atomic-integration.toml; publish via git import to a public Atomic storage project; install.sh/install.js/npm guidance removed - Testing: install_integration.rs harness suite (install half) documented alongside acp_integration.rs (behavior half) - Checklist + key files updated; sandbox-aware hook guards throughout --- docs/adding-agents.md | 244 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 202 insertions(+), 42 deletions(-) diff --git a/docs/adding-agents.md b/docs/adding-agents.md index 0fad20a6..b499af8a 100644 --- a/docs/adding-agents.md +++ b/docs/adding-agents.md @@ -57,7 +57,7 @@ Agent support spans three repositories. Know which one owns which concern: | Repo | Role | What lives here | |------|------|-----------------| | **`atomic`** (this repo) | The engine + CLI | The `atomic-agent` crate: per-agent *hook adapters*, the `AgentRegistry`, the verb→event map, the `TurnOrchestrator` that does the recording, and the `atomic agent …` CLI. This is where you write Rust so Atomic can *understand* your agent. | -| **`atomic-`** (e.g. [`atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode), [`atomic-claude`](https://github.com/atomicdotdev/atomic-claude)) | The integration package | The agent-facing glue: the system prompt, the skills, the wiring that makes the agent call back into `atomic agent hooks …` (a plugin or a hooks manifest), and an installer. Published to npm / installed via `install.sh`. | +| **`atomic-`** (e.g. [`atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode), [`atomic-claude`](https://github.com/atomicdotdev/atomic-claude)) | The integration package | The agent-facing glue: the system prompt, the skills, the wiring that makes the agent call back into `atomic agent hooks …` (a plugin or a hooks manifest), and an **`atomic-integration.toml`** describing what gets installed where. Published as a public project on **Atomic storage** — `atomic agent enable` syncs and installs it. | | **`atomic-agents`** ([repo](https://github.com/atomicdotdev/atomic-agents)) | The test harness | An ACP-based harness that spawns each agent, sends real prompts, and asserts on the ACP stream and repository side effects. This is where you register your agent so it gets *tested*. | --- @@ -437,6 +437,53 @@ on every event. --- +## How installation works: the integrations engine + +Everything above is about *runtime* — how the agent reports to Atomic once +it's set up. But how does the integration get onto the user's machine in the +first place? **Through Atomic itself.** + +Integration packages are published as **public projects on Atomic storage**. +`atomic agent enable --agent ` then: + +``` +1. registry.toml (embedded in the CLI) → agent = storage URL + view +2. atomic clone (Atomic's own sync) → ~/.atomic/integrations//repo +3. read atomic-integration.toml → check requires.atomic vs CLI version +4. copy files (never symlinks) → merge JSON settings (never clobber) +5. write receipt.json → clean uninstall + user-file protection +``` + +Two artifacts make this work, and they live in different places on purpose: + +| Artifact | Question it answers | Where it lives | +|----------|--------------------|----------------| +| **`registry.toml`** (`atomic-agent/src/integrations/registry.toml`) | **Where to fetch** — adapter name → storage URL + view | In the **atomic** repo, embedded at build time. Adding an agent = a one-line PR here. | +| **`atomic-integration.toml`** | **What to install** — files→destinations, settings manifests to merge, `requires.atomic` semver gate | In the **integration repo** (each `atomic-` package). The producer's contract: change the package layout without a CLI release. | + +Key properties of this model: + +- **The CLI executes nothing from the package** — no `install.sh`, no + postinstall. Files are copied, JSON is merged. Pure Rust, Windows-safe, + no bash/node/bun at install time. +- **User files are sacred.** A destination the CLI didn't install, or one the + user modified since, is skipped (unless `--force`). The receipt + (`~/.atomic/integrations//receipt.json`) is what makes this possible. +- **Uninstall is receipt-driven** — `atomic agent disable --agent ` + removes exactly what was installed and strips hook commands from settings, + without needing the package on disk. +- **Offline after first sync**; `atomic agent enable --agent --from + ` installs from a local checkout for development (this replaces + `./install.sh` — see Part 2). + +The engine lives in `atomic-agent/src/integrations/` (registry, manifest, +installer, receipt). **Adapters never install anything themselves** — the +agy adapter learned this lesson too: its once-embedded installer (plugin +staging, `AGENTS.md` managed sections) was deleted in favor of the +`atomic-agy` package; nothing agent-specific ships in the binary. + +--- + ## Building the integration Now the concrete work, in three parts. Everything above is the theory; this is @@ -488,12 +535,13 @@ Key responsibilities of `parse_event`: An agent need not support all six hook types — return only what it can actually emit from `supported_hooks()` and `hook_verbs()`. -Regarding `install`/`uninstall`/`is_installed`: if the integration package -handles installation itself (plugin or manifest style), these are near no-ops. -OpenCode's adapter just checks whether the plugin file exists, because the -`atomic-opencode` npm package owns installation. Only implement real -config-file writing here if you want `atomic agent enable --agent ` to -be the installer. +Regarding `install`/`uninstall`/`is_installed`: **adapters don't install +anything** — the integrations engine does (see [How installation +works](#how-installation-works-the-integrations-engine)). Implement these as +presence checks so `enable`/`disable`/`status` can report state: OpenCode's +`install()` just returns whether the plugin file exists, and `uninstall()` is +a no-op (removal is receipt-driven). Only implement real config-file writing +here for agents that have no external package at all. #### 1.2 Register the adapter @@ -511,6 +559,22 @@ registry.register(Box::new(myagent::MyAgentHook::new())); That is the *only* place that decides which agents exist. `atomic agent hooks`, `enable`, `status`, and auto-detection all read from this registry. +#### 1.2b Add the agent to the integrations registry + +If the agent has an external package (it should — see Part 2), add one entry +to `atomic-agent/src/integrations/registry.toml` pointing at its Atomic +storage project: + +```toml +[agents.myagent] +url = "https://atomic.atomic.storage/workspaces/oss/projects/atomic-myagent/code" +view = "release" +``` + +This is what makes `atomic agent enable --agent myagent` fetch and install +the package. Without an entry, `enable` falls back to the adapter's +(presence-check) `install()` and nothing is installed. + #### 1.3 Map the agent's verbs to hook types `atomic agent hooks ` turns `` into a `HookType` via @@ -553,26 +617,25 @@ they install themselves. ### Part 2 — The integration package `atomic-` (required) -A separate repo (published so users can install it). It contains no Atomic -Rust code — only the agent-facing assets and the wiring. +A separate repo, published as a **public project on Atomic storage** (GitHub +mirror optional). It contains no Atomic Rust code — only the agent-facing +assets, the wiring, and the manifest that makes it installable. Standard layout (see [`atomic-opencode`](https://github.com/atomicdotdev/atomic-opencode) and [`atomic-claude`](https://github.com/atomicdotdev/atomic-claude)): ``` atomic-/ +├── atomic-integration.toml # REQUIRED — the install manifest (below) ├── agents/.md or CLAUDE.md / AGENTS.md # system prompt (see above) ├── skills/ │ ├── atomic-vault/SKILL.md │ ├── atomic-vcs/SKILL.md │ └── code-intelligence/SKILL.md -├── hooks/.atomic-hooks.json # manifest (config-file style) +├── hooks/.atomic-hooks.json # settings manifest (config-file style) │ —or— -├── plugins/atomic-hooks.ts # plugin (plugin style) -├── install.sh # dev install (symlinks into the agent's config dir) -├── install.js # npm postinstall equivalent -├── package.json -└── README.md +├── plugins/atomic-hooks.ts # plugin (plugin style) +└── README.md # notes the definitive source is Atomic storage ``` You have already seen the three ingredients — the prompt, the skills, and the @@ -580,16 +643,89 @@ wiring — in the conceptual half of this doc. Assembly notes: - **Prompt**: ship it under the filename convention your agent reads (see the table in [The system prompt](#the-system-prompt-agentsmd-and-friends)). -- **Skills**: copy the three core `SKILL.md` files verbatim; the installer - symlinks them into the agent's skills directory (e.g. +- **Skills**: copy the three core `SKILL.md` files verbatim; the manifest + copies them into the agent's skills directory (e.g. `~/.config/opencode/skills/`, `~/.claude/skills/`). - **Wiring**: whichever style the agent's extension model dictates (see [Plugin vs. config file](#plugin-vs-config-file-choosing-the-wiring)). - Guard every hook: `test -d .atomic && … || true`. -- **Installer**: `install.sh` (dev) symlinks the prompt + skills and, for - manifest style, calls `atomic agent enable --hooks `. `install.js` - is the npm `postinstall` equivalent. Copy from whichever existing package - matches your style. + Guard every hook: `test -d .atomic || test -f .atomic-sandbox && … || true` + (the sandbox-aware form — a `.atomic`-only guard silently drops provenance + for sandboxed agents). + +#### 2.4 The `atomic-integration.toml` manifest + +This file is what `atomic agent enable` installs by. It replaces any +`install.sh`/`install.js` — the CLI never executes the package, it reads +this: + +```toml +schema = 1 +agent = "myagent" # must match the adapter name in the registry +version = "1.0.0" + +[requires] +atomic = ">=0.11.0" # semver gate — older CLIs get a hard error, + # not a silently broken install + +# Every file to copy, package-relative src → absolute dst (~ expands): +[[file]] +src = "agents/atomic.md" +dst = "~/.config/myagent/agents/atomic.md" + +[[file]] +src = "skills/atomic-vault/SKILL.md" +dst = "~/.config/myagent/skills/atomic-vault/SKILL.md" + +# Settings manifests to merge (the hooks-manifest format — same engine as +# `atomic agent enable --hooks`): +[[settings]] +manifest = "hooks/myagent.atomic-hooks.json" +``` + +Rules of thumb: + +- `[[file]]` copies (permissions preserved); destinations the user owns or + modified are skipped unless `--force`. Absolute paths inside the package + (`src` starting with `/` or containing `..`) are rejected. +- `[[settings]]` is also how you register things in the agent's own JSON + config without clobbering it — e.g. atomic-opencode registers its plugin in + `opencode.json` via a merge-only manifest (`"hooks": {}`, just a `merge` + block); the engine deep-merges objects and unions arrays. +- If the package needs something the schema can't express (a native plugin + manager, TOML edits), that's a gap — document it as a manual step in the + README and bring it up for a schema extension rather than working around it + with a script. + +#### 2.5 Publish the package to Atomic storage + +The package's definitive home is its Atomic storage project — full git +history, imported with `atomic git import` (never squashed records): + +```bash +cd atomic- +git commit -am "..." && git push # keep the GitHub mirror current +rm -rf .atomic && atomic git import # import full git history +atomic project create atomic- --org atomic --workspace oss +atomic project update oss/atomic- --visibility public --org atomic +atomic remote add origin https://atomic.atomic.storage/workspaces/oss/projects/atomic-/code +atomic push +``` + +Then add the `registry.toml` entry (step 1.2b) so `enable` can find it. +Public visibility matters: private projects can't be pulled anonymously, and +the failure surfaces as a confusing "view not found". + +#### 2.6 Development loop + +Work on the package locally and install from the checkout — no push needed: + +```bash +atomic agent enable --agent myagent --from ~/code/work/atomic-myagent +atomic agent disable --agent myagent # clean removal, then iterate +``` + +This uses the exact same installer as the storage path, so what you test +locally is what users get. ### Part 3 — Register the agent in the test harness (required) @@ -619,6 +755,16 @@ Notes: in `AGENTS_DIR` (default `~/Projects/agents`) *and* the registry knows how to spawn it on this platform. +The harness has **two** complementary suites for your agent: + +- `tests/install_integration.rs` — the **install half**: pulls your package + from Atomic storage in a sandboxed `$HOME`, asserts every receipt-listed + file and settings merge landed, then disables and asserts clean removal. + Covers all 11 current agents; add your adapter name to the `ADAPTERS` list + and the `install_test!` macro block. Run: + `ATOMIC_BIN=$(pwd)/target/debug/atomic cargo test -p atomic-agent-harness --test install_integration -- --ignored --nocapture` +- `tests/acp_integration.rs` — the **behavior half** (below). + --- ## Testing: use the agent harness @@ -626,38 +772,46 @@ Notes: **Do not rely on manual smoke tests alone — register your agent in the [harness](https://github.com/atomicdotdev/atomic-agents) and run it.** The harness exists precisely because integrations fail in ways unit tests can't -see: it spawns the *real agent* over ACP, sends it *real prompts*, and asserts -on both the ACP stream and the repository side effects. It verifies your -prompt and skills actually work — that the agent responds, uses code search, -checks repo status, and creates intents the way the workflow demands. +see. Two suites cover the two halves: -The shared `all_agents_*` integration tests live in -`crates/atomic-agent-harness/tests/acp_integration.rs`. They are `#[ignore]`d -by default (they make real LLM calls); run them explicitly: +- **Install half** (`install_integration.rs`): does your package actually + install from storage? (It caught a real bug in atomic-devin the day it was + written — hook commands pointing at scripts that never resolved.) +- **Behavior half** (`acp_integration.rs`): it spawns the *real agent* over + ACP, sends it *real prompts*, and asserts on both the ACP stream and the + repository side effects — that the agent responds, uses code search, checks + repo status, and creates intents the way the workflow demands. + +Both are `#[ignore]`d by default (the ACP suite makes real LLM calls; the +install suite hits storage). Run them explicitly: ```bash # 1. Build atomic with your adapter and run its unit tests. cargo build -p atomic cargo test -p atomic-agent # adapter unit tests — copy opencode.rs's test module -# 2. Install the integration package (dev mode: symlinks, edits go live immediately). -cd ~/code/work/atomic- && ./install.sh +# 2. Dev-loop the package install (same installer as the storage path). +cd /some/atomic/repo +atomic agent enable --agent --from ~/code/work/atomic- +atomic agent disable --agent # 3. Manual smoke test — this is exactly what the agent will do. -cd /some/atomic/repo echo '{"session_id":"t1","cwd":"'"$PWD"'"}' | atomic agent hooks session-start echo '{"session_id":"t1","prompt":"hi","model":"...","provider":"..."}' | atomic agent hooks user-prompt echo '{"session_id":"t1","turn_number":1}' | atomic agent hooks stop atomic agent attest # confirm a provenance/attestation record appeared -# 4. Full ACP integration test via the harness (needs API key + package in AGENTS_DIR). +# 4. Harness: install verification from storage (all agents, ~20s). cd ~/code/work/atomic-agents +ATOMIC_BIN=$(pwd)/../atomic/target/debug/atomic \ + cargo test -p atomic-agent-harness --test install_integration -- --ignored --nocapture + +# 5. Harness: full ACP behavior test (needs API key + package in AGENTS_DIR). cargo test -p atomic-agent-harness --test acp_integration -- --ignored --nocapture ``` -Step 3 validates the capture half (events → provenance). Step 4 validates the -behavior half (prompt + skills → correct agent behavior). You want both green -before calling the integration done. +Steps 2–4 validate the install + capture halves; step 5 validates behavior. +You want all of them green before calling the integration done. --- @@ -665,28 +819,31 @@ before calling the integration done. **In `atomic` (this repo):** -- [ ] `atomic-agent/src/hooks/.rs` implements `AgentHook`. +- [ ] `atomic-agent/src/hooks/.rs` implements `AgentHook` (parser + presence checks — no installer). - [ ] Registered in `AgentRegistry::with_defaults()` (`hooks/mod.rs`), module declared. +- [ ] Entry in `atomic-agent/src/integrations/registry.toml` (storage URL + view). - [ ] Any new verbs added to `HookType::from_verb` (`event.rs`). - [ ] Vendor arm in `vendor_from_agent_name` (`record/provenance.rs`). - [ ] Author classification in `provenance_summary.rs` (`KNOWN_AGENT_PREFIXES` + fallback list). - [ ] Display name in `pretty_tool` (`agent/attest.rs`). -- [ ] (Optional) `enable --global` arm (`agent/enable.rs`). - [ ] `cargo test -p atomic-agent` passes; adapter has unit tests (copy `opencode.rs`'s test module). **In `atomic-` (integration package):** +- [ ] `atomic-integration.toml` with `agent` matching the adapter name, `requires.atomic`, all `[[file]]` srcs verified to exist. - [ ] System prompt in the agent's convention (`CLAUDE.md` / `AGENTS.md` / `agents/*.md` / …). - [ ] Skills: `atomic-vault`, `atomic-vcs`, `code-intelligence`. - [ ] Lifecycle wiring: a hooks manifest **or** a plugin that calls `atomic agent hooks `. -- [ ] Every hook guarded with `test -d .atomic && … || true`. -- [ ] `install.sh` / `install.js` + `package.json` + `README.md`. +- [ ] Every hook guarded with `test -d .atomic || test -f .atomic-sandbox && … || true`. +- [ ] Pushed to Atomic storage (`git import` for full history), project **public**, README notes the definitive source. +- [ ] `atomic agent enable --agent --from .` installs and `disable` removes it cleanly. **In `atomic-agents` (harness):** - [ ] `AgentEntry` added to `AGENT_REGISTRY` (`env.rs`). - [ ] `registry_id` matches the canonical ACP registry (add spawn hint to `spawn.rs` if stdio-only). -- [ ] `acp_integration` tests pass for your agent. +- [ ] Adapter name added to `install_integration.rs` (`ADAPTERS` + `install_test!`). +- [ ] `install_integration` and `acp_integration` tests pass for your agent. ## Example repositories @@ -703,10 +860,13 @@ before calling the integration done. - Example adapter (plugin style): `atomic-agent/src/hooks/opencode.rs` - More adapters: `atomic-agent/src/hooks/{claude_code,codex,gemini_cli,cursor,…}.rs` - Verb → hook-type map: `atomic-agent/src/event.rs` (`HookType::from_verb`) -- Manifest install engine: `atomic-agent/src/hooks/manifest.rs` +- Integrations engine: `atomic-agent/src/integrations/` (`registry.toml`, + `manifest.rs`, `install.rs`, `receipt.rs`) +- Manifest install engine (settings merge): `atomic-agent/src/hooks/manifest.rs` - Orchestrator (does the recording): `atomic-agent/src/turn/orchestrator.rs` - Hooks CLI entry: `atomic-cli/src/commands/agent/hooks.rs` - Enable/attest CLI: `atomic-cli/src/commands/agent/{enable,attest}.rs` - Provenance mapping: `atomic-agent/src/record/provenance.rs`, `atomic-repository/src/repository/provenance_summary.rs` - Test harness registry: `atomic-agents/crates/atomic-agent-harness/src/env.rs` +- Install test suite: `atomic-agents/crates/atomic-agent-harness/tests/install_integration.rs`