Integrate Claude Agent SDK Plugin System and Specialized Agents

[cdnsteve]

Summary

Integrate the Claude Agent SDK's plugin system and specialized agents (including the newly open-sourced code-simplifier) into Sugar's autonomous task execution system. This enables Sugar to leverage Claude Code's powerful plugin ecosystem for enhanced code quality, PR review, and autonomous development workflows.

Key Decision: The code-simplifier agent will ship as a built-in agent with Sugar - zero configuration required for users.

Background Research

Claude Agent SDK (Latest)

Sugar already depends on claude-agent-sdk>=0.1.0. The SDK provides:

• Built-in Tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion
• Hooks System: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd callbacks
• Subagents: Spawn specialized agents for focused subtasks with AgentDefinition
• MCP Servers: Connect to external systems via Model Context Protocol
• Sessions: Maintain context across multiple exchanges, with resume/fork capabilities
• Permission Modes: Control tool access (bypassPermissions, acceptEdits, etc.)

Documentation: https://platform.claude.com/docs/en/agent-sdk/overview
Python SDK: https://github.com/anthropics/claude-agent-sdk-python
Demo Agents: https://github.com/anthropics/claude-agent-sdk-demos

Claude Code Plugin System

Claude Code plugins bundle slash commands, specialized agents, MCP servers, and hooks into installable units.

Plugin Structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json       # Plugin metadata (REQUIRED)
├── .mcp.json             # MCP server configuration (optional)
├── commands/             # Slash commands (optional)
├── agents/               # Agent definitions (optional)
├── skills/               # Skill definitions (optional)
└── README.md

Official Plugins: https://github.com/anthropics/claude-plugins-official

PR Review Toolkit (Open Sourced)

The pr-review-toolkit includes 6 specialized agents for comprehensive code review:

Agent	Focus	Scoring
comment-analyzer	Comment accuracy vs code	High confidence checks
pr-test-analyzer	Test coverage quality	Rates gaps 1-10
silent-failure-hunter	Error handling issues	Severity flags
type-design-analyzer	Type design quality	4 dimensions, 1-10 scale
code-reviewer	General code quality	Issues 0-100
code-simplifier	Code simplification	Complexity identification

Install: /plugin install pr-review-toolkit
Source: https://github.com/anthropics/claude-code/tree/main/plugins/pr-review-toolkit

---

Proposed Implementation

1. Built-in Code-Simplifier Agent (Ships with Sugar)

The code-simplifier agent will be built-in to Sugar - available immediately after pip install sugarai with zero configuration.

Rationale:

• Zero friction - works immediately, no plugin install required
• No network dependency for core functionality
• Sugar can customize the agent for its specific workflow (e.g., respecting .sugar/ conventions)
• Users who want additional review agents can still install the full PR Review Toolkit plugin

Implementation (sugar/agents/builtin.py):

from claude_agent_sdk import AgentDefinition

BUILTIN_AGENTS = {
    "code-simplifier": AgentDefinition(
        description="Code simplification and refactoring specialist. "
                    "Preserves functionality while improving structure and maintainability.",
        prompt="""You are a code simplification specialist. Analyze code for:

- Code clarity and readability issues
- Unnecessary complexity and deep nesting
- Redundant code and premature abstractions
- Overly compact or "clever" code that sacrifices readability
- Inconsistency with project standards and patterns

Your goal is to preserve functionality while improving:
- Maintainability
- Readability
- Consistency

Do NOT add features or change behavior. Focus only on simplification.
When suggesting changes, explain why the simplified version is better.""",
        tools=["Read", "Glob", "Grep", "Edit"]
    ),
    
    "silent-failure-hunter": AgentDefinition(
        description="Error handling and silent failure detector. "
                    "Finds inadequate error handling and missing error logging.",
        prompt="""You are an error handling specialist. Analyze code for:

- Silent failures in catch/except blocks (empty handlers, pass statements)
- Inadequate error handling that swallows exceptions
- Missing error logging where failures should be recorded
- Inappropriate fallback behavior that masks problems
- Try/catch blocks that are too broad

Flag severity of issues found. Critical issues are those that could cause
data loss, security problems, or make debugging impossible.""",
        tools=["Read", "Glob", "Grep"]
    ),
}

2. New Slash Commands

Command	Description	Usage
/sugar-simplify	Run built-in code-simplifier on files	sugar simplify src/complex.py
/sugar-review	Run review agents on staged changes	sugar review [--full|--quick]
/sugar-plugin-list	List installed plugins and available marketplace plugins	sugar plugin list
/sugar-plugin-install	Install a plugin from marketplace	sugar plugin install pr-review-toolkit
/sugar-plugin-remove	Uninstall a plugin	sugar plugin remove <name>

3. Config.yaml Additions

sugar:
  # ... existing config ...

  # Built-in Agents Configuration
  # These agents ship with Sugar - no installation required
  builtin_agents:
    code-simplifier:
      enabled: true
      # Auto-run after task completion
      auto_run: false
      # Run on specific task types
      task_types: ["refactor", "feature"]
    
    silent-failure-hunter:
      enabled: true
      auto_run: false
      task_types: ["bug_fix"]

  # Plugin System Configuration (for additional agents)
  plugins:
    enabled: true
    
    # Plugin discovery sources
    marketplaces:
      - name: "anthropic-official"
        url: "https://github.com/anthropics/claude-plugins-official"
      # Support custom marketplaces
      # - name: "team-plugins"
      #   url: "https://github.com/myorg/claude-plugins"
    
    # Installed plugins (auto-managed)
    installed: []
    
    # Plugin-specific settings
    settings:
      pr-review-toolkit:
        # Which additional agents to enable (beyond built-ins)
        agents: ["code-reviewer", "pr-test-analyzer", "type-design-analyzer", "comment-analyzer"]
        # Minimum confidence to pass
        min_score: 70
  
  # Post-completion hooks for quality agents
  quality_gates:
    post_completion:
      - name: "code-simplifier"
        enabled: true
        blocking: false  # Warn but don't fail
      - name: "silent-failure-hunter"
        enabled: true
        blocking: true   # Fail if critical issues found

4. Integration Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Sugar CLI                               │
├─────────────────────────────────────────────────────────────┤
│  /sugar-add  │  /sugar-run  │  /sugar-simplify │  /sugar-...│
└──────┬───────────────┬───────────────┬──────────────────────┘
       │               │               │
       ▼               ▼               ▼
┌─────────────────────────────────────────────────────────────┐
│                   Agent Registry                             │
│  ┌─────────────────┐  ┌─────────────────────────────────┐   │
│  │  Built-in Agents │  │  Plugin Agents (optional)       │   │
│  │  - code-simplifier│  │  - code-reviewer               │   │
│  │  - silent-failure │  │  - pr-test-analyzer            │   │
│  │    -hunter        │  │  - type-design-analyzer        │   │
│  └─────────────────┘  │  - comment-analyzer             │   │
│                        └─────────────────────────────────┘   │
└──────┬───────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│              Agent SDK Executor (Existing)                   │
│  - SugarAgent                                                │
│  - SubAgentManager (enhanced for built-in + plugin agents)   │
│  - Quality Gates (hooks for review agents)                   │
└──────┬───────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│                Claude Agent SDK                              │
│  - query() / ClaudeSDKClient                                 │
│  - AgentDefinition (for all agents)                          │
│  - Hooks (PreToolUse, PostToolUse)                          │
│  - MCP Server Integration                                    │
└─────────────────────────────────────────────────────────────┘

5. Files to Create/Modify

New Files:

• sugar/agents/builtin.py - Built-in agent definitions (code-simplifier, silent-failure-hunter)
• sugar/agents/registry.py - Agent registry combining built-in + plugin agents
• sugar/plugins/__init__.py - Plugin system module
• sugar/plugins/manager.py - Plugin installation/management
• sugar/plugins/marketplace.py - Marketplace discovery and sync
• sugar/plugins/loader.py - Plugin loading and initialization
• sugar/config/plugin_config.py - Plugin configuration schema

Modify:

• sugar/main.py - Add /sugar-simplify, /sugar-review, plugin commands
• sugar/agent/subagent_manager.py - Load agents from registry (built-in + plugins)
• sugar/executor/agent_sdk_executor.py - Hook agents into execution pipeline
• sugar/quality_gates/coordinator.py - Add post-completion review agent hooks

6. User Experience

Out-of-the-Box (Zero Config):

# Install Sugar
pip install sugarai

# code-simplifier is immediately available
sugar simplify src/complex_module.py

# Run on staged changes
sugar review --quick

With Full PR Review Toolkit:

# Install additional review agents
sugar plugin install pr-review-toolkit

# Now have access to all 6 agents
sugar review --full  # Runs all agents

Automatic Integration:

# Add a task - built-in agents run automatically post-completion
sugar add "Refactor authentication module"

# Sugar runs task...
# → Quality gates pass
# → code-simplifier runs automatically (if enabled in config)
# → Suggestions incorporated or flagged for review

7. Agent SDK Integration Code

from claude_agent_sdk import query, ClaudeAgentOptions
from sugar.agents.registry import get_all_agents

async def execute_with_agents(prompt: str, work_item: dict):
    # Registry combines built-in + installed plugin agents
    all_agents = get_all_agents()
    
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Edit", "Task"],
            agents=all_agents,
            permission_mode="acceptEdits"
        )
    ):
        process_message(message)

---

Implementation Tasks

Phase 1: Built-in Agents (Priority)

• Create sugar/agents/builtin.py with code-simplifier and silent-failure-hunter
• Create sugar/agents/registry.py for agent management
• Add /sugar-simplify slash command
• Add /sugar-review slash command (uses built-in agents)
• Integrate with SubAgentManager

Phase 2: Quality Gate Integration

• Post-completion hooks for built-in agents
• Config options for auto-run behavior
• Task type filtering (run simplifier on refactor tasks, etc.)

Phase 3: Plugin System (Optional Enhancement)

• Plugin manager for installing additional agents
• Marketplace discovery
• CLI commands: sugar plugin list/install/remove
• Plugin agent loading into registry

Phase 4: Polish

• Documentation and examples
• Error handling
• Caching for marketplace data

---

References

• Claude Agent SDK Overview
• Claude Agent SDK Python
• Official Plugins Directory
• PR Review Toolkit
• Agent SDK Demos
• Plugin Creation Guide

---

Priority & Effort

Priority: High - Enables powerful quality automation out-of-the-box
Effort: Medium (Phase 1-2), Medium-Large (with Phase 3-4)
Dependencies: Claude Agent SDK >= 0.1.0 (already satisfied)

Key Benefit: Every Sugar user gets code-simplifier immediately after install - zero friction.