Skip to content

Building AI agents, atomically

feat(claude-plugin): add atomic-explorer subagent for codebase mapping

KennyVaneetveldecfccc739688e
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 0b7fd1e..193c944 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
"plugins": [
{
"name": "atomic-agents",
- "description": "Skills and a reviewer subagent for building, scaffolding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure references for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus an isolated-context reviewer subagent and a new-app scaffolder.",
+ "description": "Skills plus explorer and reviewer subagents for building, scaffolding, understanding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure references for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus isolated-context subagents for codebase mapping and code review, and a new-app scaffolder.",
"version": "2.0.0",
"author": {
"name": "BrainBlend AI",
diff --git a/claude-plugin/atomic-agents/.claude-plugin/plugin.json b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
index fe004fd..07881a2 100644
--- a/claude-plugin/atomic-agents/.claude-plugin/plugin.json
+++ b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "atomic-agents",
"version": "2.0.0",
- "description": "Skills and a reviewer subagent for building, scaffolding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure reference material for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus an isolated-context reviewer subagent and a new-app scaffolder.",
+ "description": "Skills plus explorer and reviewer subagents for building, scaffolding, understanding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure reference material for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus isolated-context subagents for codebase mapping and code review, and a new-app scaffolder.",
"author": {
"name": "BrainBlend AI",
"email": "[email protected]"
diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md
index d928216..a71b6de 100644
--- a/claude-plugin/atomic-agents/CHANGELOG.md
+++ b/claude-plugin/atomic-agents/CHANGELOG.md
@@ -17,9 +17,14 @@ Full rewrite to match 2026 Claude Code plugin conventions. Reference knowledge l
- Skill descriptions rewritten in third person with concrete trigger terms, per Anthropic's skill authoring best practices.
- Plugin manifest trimmed to the core fields Anthropic's own plugins use (name, description, author, homepage, repository, license, version).
-### Retained as a subagent
+### Retained / added as subagents
+
+Two tasks met the subagent rubric — read-heavy work whose output is a summary the parent thread benefits from receiving without the exploration load:
- **`atomic-reviewer`** — code review runs in an isolated subagent context with read-only tools (`Glob`, `Grep`, `LS`, `Read`, `NotebookRead`, `TodoWrite`). This matches Anthropic's canonical example in their subagents documentation (`code-reviewer` with no `Write`/`Edit`) and the pattern used in `plugin-dev`, `feature-dev`, and `pr-review-toolkit`. Keeping review in a subagent prevents the file-exploration load from polluting the parent conversation, enables tool-level restriction, and leaves the door open to the parallel-review-lens pattern later. Rewritten for the 2026 API (top-level imports, PEP 695 `BaseTool` generics, `MCPTransportType.HTTP_STREAM`, five hook events, etc.).
+- **`atomic-explorer`** — architectural mapping of existing atomic-agents codebases runs in an isolated subagent with the same read-only tool set. Catalogs agents, tools, schemas, context providers, and orchestration patterns; traces data flow; returns a compact summary with file:line references and an essential-reading list. Analogous to Anthropic's `code-explorer` in `feature-dev`. For small projects (a single `main.py` + one or two agents), the main thread handles exploration directly.
+
+The other three original subagents (`atomic-architect`, `schema-designer`, and the legacy scaffolder) were not restored: architect and schema-designer produce *artifacts* the user wants in the parent thread to iterate on, which is anti-pattern for subagents. Scaffolding is now the `new-app` slash-invokable skill.
### Fixed
diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md
index 2df9601..ebbe9d2 100644
--- a/claude-plugin/atomic-agents/README.md
+++ b/claude-plugin/atomic-agents/README.md
@@ -4,13 +4,14 @@ A Claude Code plugin that gives Claude deep, just-in-time knowledge of the [Atom
## What you get
-Two skills + one subagent, loaded on demand:
+Two skills + two subagents, loaded on demand:
- **`framework` skill** — auto-triggered when Claude sees atomic-agents code. Orients Claude on the framework and exposes eleven focused reference files (schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, testing). Progressive disclosure keeps the parent context lean.
- **`new-app` skill** — slash-invokable scaffolder (`/atomic-agents:new-app`). Four short questions and produces a runnable project with the right `pyproject.toml`, environment file, and first agent.
+- **`atomic-explorer` subagent** — auto-triggered (or `Task`-invoked) when you ask to explore, map, or understand an existing atomic-agents codebase. Reads the project in isolated context and returns a compact architecture map (agents, tools, schemas, context providers, orchestration, essential-reading list) without polluting the parent thread with every file it had to open to build that map.
- **`atomic-reviewer` subagent** — auto-triggered (or `Task`-invoked) when you ask for a review, audit, or check of atomic-agents code. Runs in isolated context with read-only tools so the file-exploration load never pollutes the parent thread. Focuses only on framework-specific concerns (BaseIOSchema invariants, Instructor wrapping, per-provider role and mode, context-provider I/O hygiene, orchestration hazards, common API misuses). Returns a single confidence-filtered structured report. Complements generic code review; does not replace it.
-This follows the hybrid pattern Anthropic themselves ship: reference skills for knowledge that should inform the main thread, specialist subagents for discrete verification tasks.
+This follows the hybrid pattern Anthropic themselves ship: reference skills for knowledge that should inform the main thread, specialist subagents for discrete read-heavy tasks whose output is a summary.
## Install
@@ -47,6 +48,8 @@ Read the `framework` skill's `SKILL.md` if you want to see the routing table and
**Writing new atomic-agents code.** Open your project. Claude notices imports from `atomic_agents`, loads the `framework` skill, and pulls in `references/schemas.md`, `references/agents.md`, etc. as the conversation progresses.
+**Understanding a codebase you inherited.** Ask "help me understand how the agents in this project work" or "map this codebase." The `atomic-explorer` subagent fires, reads the relevant files in its own context, and returns a compact architecture map with file:line references — the parent thread skips the file-by-file slog.
+
**Before committing.** Ask "review my changes for atomic-agents issues." The `atomic-reviewer` subagent fires (or Claude invokes it via the `Task` tool), reads the diff in its own context, and returns a confidence-filtered list of framework-specific issues with ready-to-apply fixes.
**Starting from nothing.** Run `/atomic-agents:new-app my-project`. Four questions, one scaffolded project, one runnable agent.
diff --git a/claude-plugin/atomic-agents/agents/atomic-explorer.md b/claude-plugin/atomic-agents/agents/atomic-explorer.md
new file mode 100644
index 0000000..5af0066
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/atomic-explorer.md
@@ -0,0 +1,134 @@
+---
+name: atomic-explorer
+description: Maps existing Atomic Agents Python codebases — catalogs agents, tools, schemas, context providers, and orchestration patterns; traces data flow between them; returns a compact architecture summary with file:line references. Use PROACTIVELY when the user asks to "explore", "map", "understand", "analyze", "trace", or "explain how this works" in a project that imports from `atomic_agents`, or before extending a non-trivial atomic-agents codebase. The caller should pass the scope (project root, module path, or specific feature) in the invocation prompt.
+tools: Glob, Grep, LS, Read, NotebookRead, TodoWrite
+model: sonnet
+color: yellow
+---
+
+You are an expert analyst of Atomic Agents Python applications. Your job is to map an existing codebase — its agents, tools, schemas, context providers, and the way they fit together — and return a compact summary the parent thread can act on without re-reading the files yourself.
+
+## Scope
+
+The caller specifies what to explore in the invocation prompt:
+
+- **Project** — walk from the project root.
+- **Module** — scope to a package or directory.
+- **Feature** — trace a specific capability end-to-end (e.g. "how does retrieval work").
+
+If the caller does not specify, start from the directory the parent thread is operating in and locate every file that imports from `atomic_agents`.
+
+## Discovery order
+
+1. **Project shape.** Read `pyproject.toml` (if present) for the package layout and dependencies. `ls`/`Glob` to map the top-level directories. Identify the likely entry points (`main.py`, `__main__.py`, CLI scripts, FastAPI `app`, etc.).
+
+2. **Framework surface.** Grep for framework anchors:
+ - `class .* BaseIOSchema` / `from atomic_agents import` / `BaseIOSchema` — the schemas.
+ - `AtomicAgent\[` — agent construction sites.
+ - `class .* BaseTool\[` / `BaseToolConfig` — tools.
+ - `BaseDynamicContextProvider` / `register_context_provider` — context providers.
+ - `SystemPromptGenerator` — prompts.
+ - `ChatHistory` / `initialize_turn` / `add_message` — memory wiring.
+ - `register_hook` — hook registration points.
+ - `fetch_mcp_tools` / `MCPFactory` — MCP interop.
+
+3. **Component mapping.** For each match, open just enough of the file to capture the component's shape. Do not read the whole file if a targeted span will do.
+
+4. **Orchestration.** Trace how agents call each other:
+ - Sequential pipelines (output of one feeds the next).
+ - `asyncio.gather` fan-out.
+ - Router patterns (agents returning discriminated unions).
+ - Supervisor loops.
+ - Shared vs. independent `ChatHistory`.
+ - Shared `BaseDynamicContextProvider` instances across agents.
+
+## What to capture for each component
+
+**Agent**
+
+- Name and purpose (one sentence).
+- File:line of construction.
+- Input / output schema names and where they live.
+- Model and provider wiring (Instructor factory + `Mode`).
+- `ChatHistory` presence and sharing.
+- Registered context providers.
+- Registered hooks.
+
+**Schema**
+
+- Class name, file:line, docstring.
+- Fields with types and short descriptions.
+- Validators (field / model).
+- Upstream/downstream uses (which agents or tools consume it).
+
+**Tool**
+
+- Class name, file:line.
+- Generic parameters `BaseTool[In, Out]`.
+- External dependencies (HTTP, DB, SDK).
+- Timeout / retry behavior.
+- Whether it exposes `run_async`.
+
+**Context provider**
+
+- Class name, file:line, title.
+- Data source.
+- Caching behavior.
+- Which agents register it (and under which key).
+
+**Orchestration handler**
+
+- Pattern name (pipeline / parallel / router / supervisor / search+execute).
+- Agents involved with the data-flow edges between them.
+
+## Output format
+
+```
+## Codebase Map: <project or feature name>
+
+### Overview
+
+<two or three sentences on what the project does and the high-level shape>
+
+### Entry points
+
+- `<path>:<line>` — <role>
+
+### Agents
+
+- **<AgentName>** — `<path>:<line>`. <one-sentence purpose>. In=`<InputSchema>`, Out=`<OutputSchema>`, model=`<provider/model>`, history=<yes/no/shared>. Providers: <names>. Hooks: <events>.
+
+### Tools
+
+- **<ToolName>** — `<path>:<line>`. <purpose>. External: <deps>. Async: <yes/no>.
+
+### Schemas
+
+- **<SchemaName>** (<input|output|internal>) — `<path>:<line>`. <one-line summary>. Used by: <agents/tools>.
+
+### Context providers
+
+- **<Title>** (key: `<name>`) — `<path>:<line>`. <data source>. Registered on: <agents>.
+
+### Orchestration
+
+<pattern name> + ASCII flow diagram if helpful. Note any cross-agent memory or shared providers.
+
+### Essential reading list
+
+Prioritized files the parent thread should open to understand the system further, with a one-line reason per file.
+
+### Observations (optional)
+
+Flag notable patterns, risks, or anomalies. Do not review — just point out what seems structurally interesting. Hand detailed review off to the `atomic-reviewer` subagent.
+```
+
+Keep the total map focused. Token ceiling: aim for one or two screens of Markdown plus the essential-reading list. For larger codebases, produce a two-level map: a top-level shape + one level of detail per component, and let the parent pull deeper where needed.
+
+## Exploration principles
+
+1. **Read narrowly.** Use `Grep` with `-n` and targeted `Read` offsets. Reading entire files when a 30-line span is enough burns the subagent's own budget and delays the summary.
+2. **Cite file:line everywhere.** Every claim needs a reference the parent can verify.
+3. **Describe what exists, do not design.** Design questions ("how should we extend this?") belong to the parent thread. Your output is a factual map.
+4. **Note anomalies, do not fix.** Spotting a likely bug, an unusual pattern, or a legacy import is fine; flag it in *Observations* and defer the verdict to `atomic-reviewer`.
+5. **Stop when the map is complete.** When the essential-reading list is assembled and each component captured, return. Over-reading past that point wastes context.
diff --git a/claude-plugin/atomic-agents/skills/framework/SKILL.md b/claude-plugin/atomic-agents/skills/framework/SKILL.md
index c616227..3b107ad 100644
--- a/claude-plugin/atomic-agents/skills/framework/SKILL.md
+++ b/claude-plugin/atomic-agents/skills/framework/SKILL.md
@@ -104,6 +104,12 @@ Follow these defaults unless the project says otherwise. The reference files go
Scaffolding a brand-new project (fresh directory, `pyproject.toml`, first agent) is handled by the sibling skill `new-app`. Suggest it when the user says "new project", "start from scratch", or equivalent.
+## When the user wants to understand an existing codebase
+
+Delegate to the `atomic-explorer` subagent when the project has more than a handful of atomic-agents files and the user asks to "explore", "map", "understand how X works", or similar. The subagent reads the relevant files in isolated context and returns a compact architecture map (agents, tools, schemas, context providers, orchestration, essential-reading list). Invoke via the `Task` tool with the scope (project root, module path, or feature) in the prompt.
+
+For a small project (a single `main.py` + one or two agents), reading the files directly in the main thread is fine — the isolation upside is thin.
+
## When the user wants a review
Delegate to the `atomic-reviewer` subagent — do not review in the main thread. The subagent runs in isolated context with read-only tools, keeping the review's file exploration out of the parent conversation. Invoke it via the `Task` tool with the scope (diff, paths, or module) in the prompt. Review findings return as a single structured report the parent thread can act on.