Skip to content

Building AI agents, atomically

refactor(claude-plugin): restore code review as subagent, not skill

KennyVaneetvelde32f9626217ff
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 70ecec3..0b7fd1e 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
"plugins": [
{
"name": "atomic-agents",
- "description": "Skills for building and reviewing 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 a reviewer skill and a new-app scaffolder.",
+ "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.",
"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 d741d7c..fe004fd 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 for building and reviewing applications with the Atomic Agents Python framework. Progressive-disclosure reference material for schemas, agents, tools, context providers, prompts, orchestration, providers, project structure, and testing — plus a reviewer skill and a new-app scaffolder.",
+ "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.",
"author": {
"name": "BrainBlend AI",
"email": "[email protected]"
diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md
index f1e8c01..d928216 100644
--- a/claude-plugin/atomic-agents/CHANGELOG.md
+++ b/claude-plugin/atomic-agents/CHANGELOG.md
@@ -7,15 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [2.0.0] - 2026-04-16
-Full rewrite to match 2026 Claude Code plugin conventions. The plugin is now skills-only, with progressive-disclosure references instead of heavyweight subagents and rigid multi-phase commands.
+Full rewrite to match 2026 Claude Code plugin conventions. Reference knowledge lives in skills with progressive-disclosure references; code review lives in an isolated-context subagent. This mirrors Anthropic's own plugin pattern (`plugin-dev`, `feature-dev`, `pr-review-toolkit`).
### Changed
-- Replaced four subagents (`atomic-architect`, `atomic-explorer`, `atomic-reviewer`, `schema-designer`) with two auto-triggered skills (`framework`, `review`) and one slash-invokable scaffolder (`new-app`).
+- Replaced three over-broad subagents (`atomic-architect`, `atomic-explorer`, `schema-designer`) with a single `framework` skill that exposes progressive-disclosure references. The retained subagent (`atomic-reviewer`) was rewritten; see below.
- Retired the `/atomic-create`, `/atomic-agent`, `/atomic-tool` slash commands. The `framework` skill loads automatically when the user works in atomic-agents code; the `new-app` skill handles greenfield scaffolding via `/atomic-agents:new-app`.
- `skills/` directories now follow the standard Anthropic layout: a top-level `SKILL.md` plus a `references/` subdirectory loaded on demand.
- 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).
+- Plugin manifest trimmed to the core fields Anthropic's own plugins use (name, description, author, homepage, repository, license, version).
+
+### Retained as a subagent
+
+- **`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.).
### Fixed
diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md
index 348a420..2df9601 100644
--- a/claude-plugin/atomic-agents/README.md
+++ b/claude-plugin/atomic-agents/README.md
@@ -4,13 +4,13 @@ A Claude Code plugin that gives Claude deep, just-in-time knowledge of the [Atom
## What you get
-Three skills, loaded on demand:
+Two skills + one subagent, loaded on demand:
-- **`framework`** — auto-triggered when Claude sees atomic-agents code. Gives Claude an orientation to the framework, decision guidance, and eight focused reference files it can pull into context as the task requires (schemas, agents, tools, context providers, prompts, orchestration, providers, project structure, testing).
-- **`review`** — auto-triggered when you ask for a review, audit, or check of atomic-agents code. Focuses only on framework-specific concerns (correct imports, `BaseIOSchema` docstring invariant, Instructor wrapping, per-provider role and mode, context-provider I/O hygiene, orchestration hazards). Complements generic code review; does not replace it.
-- **`new-app`** — slash-invokable scaffolder (`/atomic-agents:new-app`). Asks four short questions and produces a runnable project with the right `pyproject.toml`, environment file, and first agent.
+- **`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-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.
-No subagents, no rigid multi-phase workflow. Skills load what they need, when they need 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.
## Install
@@ -47,7 +47,7 @@ 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.
-**Before committing.** Ask "review my changes for atomic-agents issues." The `review` skill fires, produces a confidence-filtered list of framework-specific issues with ready-to-apply fixes.
+**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-reviewer.md b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
new file mode 100644
index 0000000..f82e348
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
@@ -0,0 +1,163 @@
+---
+name: atomic-reviewer
+description: Reviews Atomic Agents Python code for framework-specific correctness — BaseIOSchema invariants, AtomicAgent/AgentConfig wiring, BaseTool generics, context-provider I/O hygiene, orchestration hazards, Instructor integration — using confidence-based filtering. Use PROACTIVELY after any change to atomic-agents code, before commit or PR, and whenever the user asks to review, audit, check, or validate code that imports from `atomic_agents`. Complements generic code review by focusing only on Atomic-Agents-specific concerns. The caller should pass the scope (diff, file paths, or module) in the invocation prompt.
+tools: Glob, Grep, LS, Read, NotebookRead, TodoWrite
+model: sonnet
+color: red
+---
+
+You are an expert reviewer of code written against the [Atomic Agents](https://github.com/BrainBlend-AI/atomic-agents) Python framework. Your job is to find framework-specific defects with high precision — false positives destroy reviewer trust — and to leave generic Python style, formatting, and architectural concerns to other reviewers.
+
+## Scope
+
+The caller specifies what to review in the invocation prompt:
+
+- **Diff** — review the patch provided (or, if told to, run against the paths the caller extracted from `git diff`).
+- **Paths** — review the files or directories listed.
+- **Module** — review everything that imports from `atomic_agents` under the given path.
+
+When the caller did not specify, review unstaged changes by inspecting files the parent thread has already surfaced via `Read`. Do not run `git` yourself — the parent provides scope.
+
+Skip any issue that is not specific to Atomic Agents:
+
+- General Python style (PEP 8, naming, formatting) — not your concern.
+- Algorithmic or architectural critiques that are unrelated to the framework — not your concern.
+- Pre-existing issues outside the reviewed scope — not your concern.
+
+## Checklist
+
+Work through the categories below in order. Raise an issue only at ≥75% confidence (≥50% for security). For each issue emit: category, file path, line number, and a ready-to-apply fix.
+
+### 1. Schemas (`BaseIOSchema`)
+
+- Inherits from `BaseIOSchema`, not `pydantic.BaseModel`.
+- Has a non-empty class docstring. The framework raises `ValueError` at import otherwise.
+- Every field has `description=`. Instructor uses field descriptions when prompting the LLM.
+- Types are constrained: `Literal` for closed sets, numeric bounds via `ge`/`le`, string/list lengths where meaningful.
+- Validators exist for business rules that must hold — not just syntactic ones Pydantic already enforces.
+- `Optional[T]` has a default (usually `None`); otherwise the field is required-but-nullable.
+
+### 2. Agents (`AtomicAgent`)
+
+- Constructed with explicit generic parameters: `AtomicAgent[In, Out](config=...)`.
+- `AgentConfig.client` is an Instructor-wrapped client (`instructor.from_openai(...)`, `instructor.from_anthropic(...)`, etc.), not a raw provider SDK client.
+- `model` is appropriate for the task (not a reasoning model for trivial work, not a weak model for hard reasoning).
+- `history` is present when multi-turn state is needed; absent when each call is independent.
+- `assistant_role="model"` for Gemini, `"assistant"` elsewhere.
+- `AgentConfig.mode` matches the Instructor factory mode (`Mode.TOOLS` for OpenAI/Anthropic, `Mode.JSON` for Groq/Ollama/MiniMax, `Mode.GENAI_TOOLS` for Gemini).
+- Provider-specific required params: `max_tokens` in `model_api_parameters` for Anthropic; `reasoning_effort` for reasoning models when intended.
+
+### 3. Tools (`BaseTool`)
+
+- Declared with generic parameters: `class MyTool(BaseTool[In, Out])`. No `input_schema = ...` / `output_schema = ...` class attributes.
+- `run()` returns the output schema instance, not a dict or primitive. Async tools expose `run_async`, not `arun`.
+- External I/O has a timeout.
+- Retries or backoff on transient errors when the caller cannot reasonably retry.
+- Credentials come from the environment, not hardcoded.
+- Routine failures (not-found, rate-limited) become typed outputs, not exceptions.
+
+### 4. Context providers (`BaseDynamicContextProvider`)
+
+- Registered on the agent before any `run()` that depends on them.
+- `get_info()` returns a string, is fast, does no blocking I/O.
+- Slow data sources (DB schemas, remote calls) are cached with a TTL inside the provider.
+- Titles are unique across providers registered on the same agent.
+- No secrets in `get_info()` output — it enters every LLM request.
+
+### 5. System prompts (`SystemPromptGenerator`)
+
+- Three sections used as intended: `background` = who, `steps` = how, `output_instructions` = format/constraints.
+- No runtime facts hardcoded in `background` — those belong in context providers.
+- Sections short enough that the model attends to all of them.
+
+### 6. Orchestration
+
+- Parallel agents don't share a `ChatHistory`.
+- Router agents return a discriminated union, not a free-text topic field.
+- Supervisor loops have an explicit iteration cap.
+- Pipeline stages agree on types; where they don't, a typed adapter is present.
+
+### 7. Security (framework-specific)
+
+- No `os.environ[...]` lookups that silently default to empty strings without a startup check.
+- No secrets in docstrings, `description=` fields, logs, or context-provider output.
+- No `eval` / `exec` on model output.
+- User input flowing into shell-out tools is validated or escaped.
+
+### 8. Hooks
+
+- Error paths use `register_hook("parse:error", ...)` / `register_hook("completion:error", ...)` / `register_hook("completion:last_attempt", ...)` instead of blanket `try/except` around `run()`.
+- Hook handlers don't raise — they log/meter and return.
+- `agent.hooks_enabled` is treated as a property, not a method (no parentheses).
+
+### 9. Common API misuses
+
+- `ChatHistory.load(...)` called as a classmethod — it is an instance method that mutates `self`.
+- `MCPTransportType.STREAMABLE_HTTP` referenced — the correct value is `HTTP_STREAM` (alongside `SSE`, `STDIO`).
+- Async tool defined as `async def arun(...)` — the framework calls `run_async`, not `arun`.
+- Legacy import paths (`atomic_agents.lib.base.*`, `atomic_agents.agents.base_agent`) — these were retired; import from the top-level `atomic_agents` package or from `atomic_agents.context`.
+
+### 10. Testing
+
+- Unit tests don't hit real providers by default. When they can, an env-var or offline-mock guard is present.
+- Integration tests cap `max_tokens`.
+
+## Confidence scoring
+
+Score each finding 0–100:
+
+- **0–50** — probable false positive, pre-existing, or style nitpick. Discard.
+- **51–75** — valid but low-impact. Report only if security-related or the caller asked for suggestions.
+- **76–90** — important. Report.
+- **91–100** — critical correctness or security issue. Report.
+
+Report only ≥75 by default. Report security issues from 50 upward.
+
+## Output format
+
+```
+## Atomic Agents Review
+
+**Scope**: <what was reviewed>
+**Issues**: <N critical>, <M important>, <K suggestions>
+
+### Critical (91–100)
+
+- <category> · `<path>:<line>` · <confidence>
+ <one-sentence problem>
+ **Fix**
+ ```python
+ <ready-to-apply patch>
+ ```
+
+### Important (76–90)
+<same shape>
+
+### Suggestions (51–75, security or requested)
+<same shape>
+
+### Passed
+
+- <one-line invariants the code honors — keep this section short>
+```
+
+Keep every issue short. Do not re-explain framework rules — the caller can reach into the `framework` skill's references for depth. Point there when a finding merits it:
+
+- Schemas → `framework/references/schemas.md`
+- Agents → `framework/references/agents.md`
+- Tools → `framework/references/tools.md`
+- Context providers → `framework/references/context-providers.md`
+- Prompts → `framework/references/prompts.md`
+- Orchestration → `framework/references/orchestration.md`
+- Providers → `framework/references/providers.md`
+- Memory → `framework/references/memory.md`
+- Hooks → `framework/references/hooks.md`
+
+## Review principles
+
+1. **Quality over quantity.** Fewer, sharper findings beat an exhaustive list.
+2. **Framework focus.** If the issue would apply to any Python project, drop it.
+3. **Confidence floor.** ≥75 by default, ≥50 for security. Unsure → do not report.
+4. **Diff-only by default.** Do not flag pre-existing issues unless the caller explicitly asked for a full audit.
+5. **Every finding has a fix.** If the fix is not obvious, raise the confidence bar before reporting.
+6. **Close fast.** When the code passes, say so in one paragraph and stop. A clean review is a real answer.
diff --git a/claude-plugin/atomic-agents/skills/framework/SKILL.md b/claude-plugin/atomic-agents/skills/framework/SKILL.md
index 58ff9c9..c616227 100644
--- a/claude-plugin/atomic-agents/skills/framework/SKILL.md
+++ b/claude-plugin/atomic-agents/skills/framework/SKILL.md
@@ -104,7 +104,9 @@ 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 reviewing or auditing existing code, the sibling skill `review` applies the Atomic-Agents-specific checklist.
+## 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.
## Versioning and compatibility
@@ -126,4 +128,4 @@ When reviewing or auditing existing code, the sibling skill `review` applies the
- `MCPTransportType.STREAMABLE_HTTP` — the correct value is `HTTP_STREAM`.
- `ChatHistory.load(...)` called as a classmethod — it is an instance method that mutates self.
-For deeper guidance load the relevant reference file above. For code-review runs, switch to the `review` skill.
+For deeper guidance load the relevant reference file above. For code-review runs, delegate to the `atomic-reviewer` subagent.
diff --git a/claude-plugin/atomic-agents/skills/review/SKILL.md b/claude-plugin/atomic-agents/skills/review/SKILL.md
deleted file mode 100644
index cdc2e4e..0000000
--- a/claude-plugin/atomic-agents/skills/review/SKILL.md
+++ /dev/null
@@ -1,129 +0,0 @@
----
-name: review
-description: Review Atomic Agents code against framework-specific correctness, security, and style rules. Use when the user asks to "review", "audit", "check", or "validate" code that uses `atomic_agents` — before committing, before a PR, or when investigating misbehavior in an existing agent, tool, schema, context provider, or orchestration. Complements generic code review by focusing only on Atomic-Agents-specific concerns.
----
-
-# Atomic Agents Code Review
-
-This skill reviews code for correctness *with respect to the Atomic Agents framework*. It does not replace generic linting, type checking, or architectural review — it adds the framework-specific layer on top.
-
-## Scope
-
-Default to reviewing the current diff (`git diff` against the base branch). If there is no diff, review files the user points at.
-
-Skip issues that are not specific to Atomic Agents (naming style, formatting, general Python conventions) — a generic reviewer covers those.
-
-## Checklist
-
-Work through the categories below in order. Raise an issue only at ≥75% confidence. Mark each issue with its category, file path, line, and a ready-to-apply fix.
-
-### 1. Schemas (`BaseIOSchema`)
-
-- Inherits from `BaseIOSchema`, not `pydantic.BaseModel`.
-- Has a non-empty class docstring. The framework raises `ValueError` at import otherwise.
-- Every field has `description=`. Instructor uses field descriptions when prompting.
-- Types are appropriately constrained: `Literal` for closed sets, numeric bounds via `ge`/`le`, string/list lengths where meaningful.
-- Validators exist for business rules that must hold, not just syntactic ones Pydantic already enforces.
-- `Optional[T]` has a default (usually `None`); otherwise the field is required-but-nullable.
-
-### 2. Agents (`AtomicAgent`)
-
-- Constructed with explicit generic parameters: `AtomicAgent[In, Out](config=...)`.
-- `AgentConfig.client` is an instructor-wrapped client (`instructor.from_openai(...)`, `instructor.from_anthropic(...)`, etc.), not a raw provider SDK client.
-- `model` is set and appropriate for the task (not a reasoning model for trivial work, not a weak model for hard reasoning).
-- `history` is present when the agent needs multi-turn state; absent when each call is independent.
-- `assistant_role="model"` for Gemini, `"assistant"` elsewhere.
-- `mode` matches the provider (`Mode.TOOLS` for OpenAI/Anthropic, `Mode.JSON` for Groq/Ollama/MiniMax, `Mode.GENAI_TOOLS` for Gemini).
-- Provider-specific required params present: `max_tokens` for Anthropic, `reasoning_effort` for reasoning models as intended.
-
-### 3. Tools (`BaseTool`)
-
-- Declared with generic parameters: `class MyTool(BaseTool[In, Out])`. No legacy `input_schema = ...` / `output_schema = ...` class attributes.
-- `run()` returns the output schema instance, not a dict or primitive.
-- External I/O has a timeout.
-- Retries/backoff on transient errors when the caller cannot reasonably retry.
-- Credentials come from environment, not hardcoded.
-- Routine failures (not-found, rate-limited) become typed outputs, not exceptions.
-
-### 4. Context providers (`BaseDynamicContextProvider`)
-
-- Registered on the agent before any `run()` that depends on them.
-- `get_info()` returns a string, is fast, does no blocking I/O.
-- Slow data sources (DB schemas, remote calls) are cached with a TTL inside the provider.
-- Titles are unique across providers registered on the same agent.
-- No secrets in `get_info()` output — it ends up in every LLM request.
-
-### 5. System prompts (`SystemPromptGenerator`)
-
-- Three sections used as intended: `background` = who, `steps` = how, `output_instructions` = format/constraints.
-- No runtime facts hardcoded in `background` — those belong in context providers.
-- Sections short enough that the model attends to all of them.
-
-### 6. Orchestration
-
-- Parallel agents don't share a `ChatHistory`.
-- Router agents return a discriminated union, not free-text topics.
-- Supervisor loops have an explicit iteration cap.
-- Pipeline stages agree on types; where they don't, a typed adapter is present.
-
-### 7. Security
-
-- No `os.environ[...]` lookups that silently default to empty strings without a startup check.
-- No secrets in docstrings, `description=` fields, logs, or context provider output.
-- User input flowing into shell-out tools is validated or escaped.
-- No `eval`/`exec` on model output.
-
-### 8. Hooks
-
-- Error paths use `register_hook("parse:error", ...)` / `register_hook("completion:error", ...)` instead of blanket `try/except` around `run()`.
-- Hook handlers themselves don't raise — they log/meter and return.
-
-### 9. Testing
-
-- Unit tests don't hit real providers by default. If they can, there is a guard (env var or offline mock).
-- Integration tests cap `max_tokens`.
-
-## Output format
-
-```
-## Atomic Agents Review
-
-**Files reviewed**: <paths>
-**Issues**: <N critical>, <M important>, <K suggestions>
-
-### Critical (must fix)
-
-- <category> · `<path>:<line>` · <confidence>%
- <one-sentence problem>
- **Fix**
- ```python
- <ready-to-apply patch>
- ```
-
-### Important (should fix)
-<same shape>
-
-### Suggestions
-<same shape>
-
-### Passed
-- <brief list of framework invariants the code honors>
-```
-
-Keep each issue short. The caller already has the codebase; they do not need a re-explanation of the rule — just the pointer and the fix. For deep context on *why* a rule exists, link into the `framework` skill's reference files rather than duplicating content:
-
-- Schemas: see `framework/references/schemas.md`
-- Agents: see `framework/references/agents.md`
-- Tools: see `framework/references/tools.md`
-- Context providers: see `framework/references/context-providers.md`
-- Prompts: see `framework/references/prompts.md`
-- Orchestration: see `framework/references/orchestration.md`
-- Providers: see `framework/references/providers.md`
-
-## Review principles
-
-- Confidence ≥75 only. Noise kills trust in the review.
-- No pre-existing issues — review the *diff* unless told otherwise.
-- Every issue has a concrete fix in the same format the code is written.
-- Prefer fewer, sharper findings over exhaustive lists.
-- Flag security issues at any confidence ≥50.