Merge pull request #199 from BrainBlend-AI/feature/claude-code-plugin-v2

feat: add Claude Code plugin for Atomic Agents development

Author: KennyVaneetvelde

.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "brainblend-plugins",
+  "description": "Official plugins for the Atomic Agents framework - a lightweight, modular system for building AI agents with Pydantic and Instructor",
+  "owner": {
+    "name": "BrainBlend AI",
+    "email": "support@brainblend.ai"
+  },
+  "plugins": [
+    {
+      "name": "atomic-agents",
+      "description": "Comprehensive development workflow for building well-organized Atomic Agents applications with specialized agents for schema design, architecture planning, code review, and tool development",
+      "version": "1.0.0",
+      "author": {
+        "name": "BrainBlend AI",
+        "email": "support@brainblend.ai"
+      },
+      "source": "./claude-plugin/atomic-agents",
+      "category": "development",
+      "homepage": "https://github.com/BrainBlend-AI/atomic-agents",
+      "repository": "https://github.com/BrainBlend-AI/atomic-agents",
+      "license": "MIT",
+      "keywords": [
+        "atomic-agents",
+        "ai-agents",
+        "llm",
+        "pydantic",
+        "instructor",
+        "multi-agent",
+        "orchestration"
+      ]
+    }
+  ]
+}

claude-plugin/atomic-agents/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "atomic-agents",
+  "version": "1.0.0",
+  "description": "Comprehensive development workflow for building well-organized Atomic Agents applications with specialized sub-agents for schema design, agent creation, tool development, and code review",
+  "author": {
+    "name": "BrainBlend AI",
+    "email": "support@brainblend.ai"
+  },
+  "homepage": "https://github.com/BrainBlend-AI/atomic-agents",
+  "repository": "https://github.com/BrainBlend-AI/atomic-agents",
+  "license": "MIT",
+  "keywords": [
+    "atomic-agents",
+    "ai-agents",
+    "llm",
+    "pydantic",
+    "instructor",
+    "multi-agent",
+    "orchestration",
+    "tools",
+    "schemas"
+  ]
+}

claude-plugin/atomic-agents/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to the Atomic Agents Claude Code Plugin will be documented in this file.
+
+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).
+
+## [1.0.0] - 2025-12-21
+
+### Added
+
+#### Agents
+- **atomic-explorer** - Analyzes existing Atomic Agents applications by tracing configurations, schemas, tools, and orchestration patterns
+- **atomic-architect** - Designs application architectures with pattern selection and implementation blueprints
+- **atomic-reviewer** - Reviews code for bugs, anti-patterns, security issues with confidence-based filtering
+- **schema-designer** - Generates well-structured Pydantic schemas with proper validation
+
+#### Commands
+- **/atomic-create** - 7-phase guided workflow for creating complete Atomic Agents applications
+  - Discovery, Exploration, Clarification, Architecture, Implementation, Review, Summary phases
+  - Parallel agent deployment for comprehensive analysis
+  - User approval gates at critical decision points
+- **/atomic-agent** - Quick scaffolding for new agents with schemas and configuration
+- **/atomic-tool** - Quick scaffolding for new tools with error handling patterns
+
+#### Skills
+- **atomic-schemas** - BaseIOSchema patterns, field definitions, validators, type constraints
+- **atomic-agents** - Agent configuration, ChatHistory, provider setup, execution methods
+- **atomic-tools** - BaseTool development, configuration, error handling, orchestration
+- **atomic-context** - Context providers, dynamic prompt injection, RAG patterns
+- **atomic-prompts** - SystemPromptGenerator structure, prompt engineering best practices
+- **atomic-structure** - Project organization patterns from simple to complex applications
+
+### Framework Support
+- Full coverage of Atomic Agents core components
+- Support for multiple LLM providers (OpenAI, Anthropic, Groq, Ollama)
+- Patterns for synchronous, asynchronous, and streaming execution
+- Multi-agent orchestration patterns (sequential, parallel, router, supervisor)
+
+---
+
+## [Unreleased]
+
+### Planned
+- Hook for automatic schema validation on file save
+- MCP server integration for external tool discovery
+- Additional skills for advanced patterns (MCP, testing, deployment)
+- Example templates for common application types

claude-plugin/atomic-agents/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BrainBlend AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude-plugin/atomic-agents/README.md

@@ -0,0 +1,251 @@
+# Atomic Agents Plugin for Claude Code
+
+A comprehensive Claude Code plugin for building well-organized [Atomic Agents](https://github.com/BrainBlend-AI/atomic-agents) applications. This plugin provides specialized sub-agents, guided workflows, and progressive-disclosure skills to help you create production-ready AI agent systems.
+
+## Overview
+
+The Atomic Agents framework is a lightweight, modular system for building AI agents using Pydantic schemas and the Instructor library. This plugin brings that power into Claude Code with:
+
+- **4 Specialized Agents** for analysis, design, review, and schema generation
+- **3 Workflow Commands** from guided creation to quick scaffolding
+- **6 Progressive-Disclosure Skills** for just-in-time knowledge
+
+## Installation
+
+### From a Marketplace
+
+```bash
+# If published to a marketplace
+/plugin install atomic-agents@marketplace-name
+```
+
+### Local Installation
+
+```bash
+# Clone or copy the plugin to a directory
+claude --plugin-dir /path/to/atomic-agents
+```
+
+### Validate Installation
+
+```bash
+# Check that the plugin loads correctly
+/plugin validate /path/to/atomic-agents
+```
+
+## Commands
+
+### `/atomic-create` - Guided Application Workflow
+
+The master command for building complete Atomic Agents applications through a 7-phase workflow:
+
+```bash
+/atomic-create A research agent that summarizes academic papers
+```
+
+**Phases:**
+1. **Discovery** - Understand requirements
+2. **Exploration** - Analyze existing code (if applicable)
+3. **Clarification** - Resolve ambiguities
+4. **Architecture** - Design the application
+5. **Implementation** - Build components
+6. **Review** - Validate against best practices
+7. **Summary** - Document what was created
+
+### `/atomic-agent` - Quick Agent Creation
+
+Rapidly scaffold a new agent with proper configuration:
+
+```bash
+/atomic-agent A customer support agent that handles refund requests
+```
+
+Creates:
+- Input/output schemas
+- Agent configuration with SystemPromptGenerator
+- Usage examples
+
+### `/atomic-tool` - Quick Tool Creation
+
+Scaffold a new tool for external integrations:
+
+```bash
+/atomic-tool A weather API tool that fetches current conditions
+```
+
+Creates:
+- Input/output/error schemas
+- Tool configuration with environment variables
+- Error handling patterns
+- Usage examples
+
+## Agents
+
+### atomic-explorer (Yellow)
+
+Deeply analyzes existing Atomic Agents applications:
+- Maps agent configurations and purposes
+- Catalogs schemas, tools, and context providers
+- Traces orchestration patterns and data flow
+- Identifies architecture patterns
+
+**Triggered by:** Exploring codebases, understanding existing implementations
+
+### atomic-architect (Green)
+
+Designs application architectures:
+- Analyzes requirements
+- Selects appropriate orchestration patterns
+- Creates implementation blueprints
+- Specifies component designs
+
+**Triggered by:** Planning new applications, designing multi-agent systems
+
+### atomic-reviewer (Red)
+
+Reviews code for quality and best practices:
+- Schema quality and type safety
+- Agent configuration correctness
+- Security and error handling
+- Performance considerations
+
+**Triggered by:** Code review, pre-commit validation, quality audits
+
+### schema-designer (Blue)
+
+Generates well-structured Pydantic schemas:
+- Input/output schemas for agents
+- Tool parameter schemas
+- Complex nested structures
+- Validators for business rules
+
+**Triggered by:** Schema design, data contract definition
+
+## Skills
+
+Skills provide progressive-disclosure knowledge, loading only when needed to keep context lean:
+
+| Skill | Trigger Phrases | Purpose |
+|-------|----------------|---------|
+| `atomic-schemas` | "create schema", "BaseIOSchema", "field validation" | Pydantic schema patterns |
+| `atomic-agents` | "create agent", "AgentConfig", "ChatHistory" | Agent configuration |
+| `atomic-tools` | "create tool", "BaseTool", "tool orchestration" | Tool development |
+| `atomic-context` | "context provider", "dynamic context", "share data" | Context providers |
+| `atomic-prompts` | "system prompt", "SystemPromptGenerator" | Prompt engineering |
+| `atomic-structure` | "project structure", "pyproject.toml" | Project organization |
+
+## Usage Examples
+
+### Create a Complete Application
+
+```
+You: /atomic-create A RAG chatbot that answers questions from PDF documents
+
+Claude: I'll guide you through creating this application...
+[7-phase workflow begins]
+```
+
+### Quick Agent Scaffolding
+
+```
+You: /atomic-agent A sentiment analysis agent
+
+Claude: [Creates schemas and agent configuration]
+```
+
+### Explore Existing Code
+
+```
+You: Help me understand how the agents in this project work
+
+Claude: [Deploys atomic-explorer to analyze the codebase]
+```
+
+### Review Implementation
+
+```
+You: Review my Atomic Agents code for issues
+
+Claude: [Deploys atomic-reviewer with confidence-based filtering]
+```
+
+## Framework Reference
+
+This plugin targets the [Atomic Agents](https://github.com/BrainBlend-AI/atomic-agents) framework:
+
+### Core Components
+
+- **AtomicAgent** - Main agent class with structured I/O
+- **AgentConfig** - Configuration for model, history, prompts
+- **BaseIOSchema** - Base class for Pydantic schemas
+- **SystemPromptGenerator** - Structured prompt builder
+- **BaseTool** - Base class for tools
+- **BaseDynamicContextProvider** - Dynamic context injection
+- **ChatHistory** - Conversation state management
+
+### Supported Providers
+
+- OpenAI (GPT-4, GPT-4o, etc.)
+- Anthropic (Claude)
+- Groq
+- Ollama (local models)
+- OpenRouter
+- Any OpenAI-compatible API
+
+## Best Practices
+
+### When Using This Plugin
+
+1. **Start with /atomic-create** for new projects - it ensures proper structure
+2. **Use skills for quick reference** - they load just-in-time knowledge
+3. **Let agents do deep analysis** - atomic-explorer for understanding, atomic-reviewer for validation
+4. **Follow the workflow** - the 7-phase process prevents common mistakes
+
+### Atomic Agents Best Practices
+
+1. **Always use BaseIOSchema** - never plain Pydantic BaseModel
+2. **Describe all fields** - descriptions are used in prompt generation
+3. **Use environment variables** - never hardcode API keys
+4. **Wrap with instructor** - required for structured outputs
+5. **Handle errors gracefully** - tools should return error schemas, not raise
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+1. Verify plugin structure: `.claude-plugin/plugin.json` exists
+2. Run validation: `/plugin validate /path/to/plugin`
+3. Check for JSON syntax errors in plugin.json
+
+### Skills Not Triggering
+
+1. Use explicit trigger phrases from skill descriptions
+2. Manually load: "Load the atomic-schemas skill"
+
+### Agents Not Found
+
+1. Check agents/ directory exists with .md files
+2. Verify YAML frontmatter is valid in agent files
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Follow the existing plugin structure
+2. Add tests for new components
+3. Update documentation
+4. Follow semantic versioning
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file.
+
+## Links
+
+- **Atomic Agents Framework**: https://github.com/BrainBlend-AI/atomic-agents
+- **Documentation**: https://github.com/BrainBlend-AI/atomic-agents/tree/main/docs
+- **Examples**: https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-examples
+
+---
+
+Built with care for the Atomic Agents community by [BrainBlend AI](https://github.com/BrainBlend-AI).