Skip to content

Building AI agents, atomically

fix(claude-plugin): stop atomic-reviewer from flagging embeddings and initialize_turn as bugs (v2.0.1)

KennyVaneetveldeeff0487e513d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 193c944..667964d 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -10,7 +10,7 @@
{
"name": "atomic-agents",
"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",
+ "version": "2.0.1",
"author": {
"name": "BrainBlend AI",
"email": "[email protected]"
diff --git a/claude-plugin/atomic-agents/.claude-plugin/plugin.json b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
index 07881a2..af3b21a 100644
--- a/claude-plugin/atomic-agents/.claude-plugin/plugin.json
+++ b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "atomic-agents",
- "version": "2.0.0",
+ "version": "2.0.1",
"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",
diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md
index a71b6de..ed79efd 100644
--- a/claude-plugin/atomic-agents/CHANGELOG.md
+++ b/claude-plugin/atomic-agents/CHANGELOG.md
@@ -5,6 +5,15 @@ All notable changes to the Atomic Agents Claude Code Plugin will be documented i
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [2.0.1] - 2026-04-16
+
+Bug-fix release addressing two recurring false positives from `atomic-reviewer` reported in [issue #238](https://github.com/BrainBlend-AI/atomic-agents/issues/238).
+
+### Fixed
+
+- **Reviewer no longer flags raw provider-SDK use for embeddings, image generation, audio, or moderation as a framework violation.** The "Instructor-wrapped client" rule now carries an explicit scope note: it applies only to clients passed to `AgentConfig.client`. The framework doesn't expose embeddings/image/audio/moderation APIs, so using the provider SDK directly for those capabilities is correct usage, not a rule break. Scope note added to `agents/atomic-reviewer.md` section 2 and `skills/framework/SKILL.md` anti-patterns.
+- **Reviewer no longer confabulates a bug for `ChatHistory.initialize_turn()`.** The method only rotates `current_turn_id` (a UUID) — it does not append a system prompt, add a message, or mutate `history`. Added an explicit "methods that are NOT misuses" block to `agents/atomic-reviewer.md` section 9 documenting both non-misuses so Claude doesn't invent them.
+
## [2.0.0] - 2026-04-16
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`).
diff --git a/claude-plugin/atomic-agents/agents/atomic-reviewer.md b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
index f82e348..75609fd 100644
--- a/claude-plugin/atomic-agents/agents/atomic-reviewer.md
+++ b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
@@ -41,6 +41,7 @@ Work through the categories below in order. Raise an issue only at ≥75% confid
- 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.
+ - **Scope**: this rule applies *only* to clients passed to `AgentConfig.client` — i.e., anything an `AtomicAgent` uses for chat/completions. It does **not** apply to provider-SDK calls for capabilities the framework does not cover: embeddings (`client.embeddings.create`), image generation, audio (TTS/STT), moderation, fine-tuning management, etc. Using a raw `openai` / `anthropic` / `groq` client for those is correct, not a violation. Do not flag such calls.
- `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.
@@ -97,6 +98,11 @@ Work through the categories below in order. Raise an issue only at ≥75% confid
- 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`.
+**Methods that are NOT misuses** — do not flag these; the reviewer has historically confabulated bugs here that do not exist:
+
+- `ChatHistory.initialize_turn()` only rotates the internal `current_turn_id` (a UUID). It does **not** append a system prompt, add a message, or otherwise mutate `history`. Calling it repeatedly is a no-op with respect to message content. The `add_message(...)` → `initialize_turn()` at end-of-turn pattern (including when replaying history) is correct usage, not a bug.
+- Using a raw provider SDK client (e.g. `openai.OpenAI()`) for embeddings, image generation, audio, or moderation — see scope note under section 2. Not a violation.
+
### 10. Testing
- Unit tests don't hit real providers by default. When they can, an env-var or offline-mock guard is present.
diff --git a/claude-plugin/atomic-agents/skills/framework/SKILL.md b/claude-plugin/atomic-agents/skills/framework/SKILL.md
index 3b107ad..6d0fb40 100644
--- a/claude-plugin/atomic-agents/skills/framework/SKILL.md
+++ b/claude-plugin/atomic-agents/skills/framework/SKILL.md
@@ -126,7 +126,7 @@ Delegate to the `atomic-reviewer` subagent — do not review in the main thread.
- Plain `BaseModel` instead of `BaseIOSchema`.
- Missing docstrings on `BaseIOSchema` subclasses (framework raises at import).
- `Field(..., description="...")` missing — Instructor leans on descriptions for prompt generation.
-- Raw provider client (not wrapped in Instructor).
+- Raw provider client passed as `AgentConfig.client` (must be wrapped in Instructor). Raw SDK use for embeddings, image generation, audio, or moderation is fine — the framework only covers structured chat/completions.
- Hardcoded API keys instead of env vars.
- Unbounded `ChatHistory` on long-running sessions.
- Blocking I/O inside `BaseDynamicContextProvider.get_info()` — it runs on every `agent.run()`.