Skip to content

Latest commit

 

History

History
517 lines (373 loc) · 15 KB

README.md

File metadata and controls

517 lines (373 loc) · 15 KB

OAC - Claude Code Plugin

OpenAgents Control (OAC) - Multi-agent orchestration and automation for Claude Code.

🎯 Overview

OpenAgents Control brings powerful multi-agent capabilities to Claude Code through a skills + subagents architecture:

  • 8 Skills orchestrate workflows and guide the main agent through multi-stage processes
  • 6 Subagents execute specialized tasks (context discovery, task breakdown, code implementation, testing, review)
  • 4 Commands provide setup, status, help, and cleanup functionality
  • Flat delegation hierarchy - only the main agent can invoke subagents (no nested calls)
  • Context pre-loading - all standards and patterns loaded upfront to prevent nested discovery
  • 6-stage workflow - ensures context-aware, high-quality code delivery with approval gates

Key Features

  • Intelligent Context Discovery - Smart discovery of coding standards, security patterns, and conventions
  • Task Management - Break down complex features into atomic, verifiable subtasks
  • Code Execution - Context-aware implementation following project standards
  • Test Engineering - TDD-driven test creation and validation
  • Code Review - Automated code quality and security analysis

📦 Installation

Option 1: From Claude Code Marketplace (Recommended)

Install directly from the Claude Code marketplace:

# Add the OpenAgents Control marketplace repository
/plugin marketplace add https://github.com/darrenhinde/OpenAgentsControl

# Install the OAC plugin
/plugin install oac

# Download context files (interactive profile selection)
/install-context

First time? Run /install-context to download context files, then /oac:status to verify.

That's it! The plugin is now installed and ready to use.

Option 2: Local Development

For plugin development or testing:

# Clone the repository
git clone https://github.com/darrenhinde/OpenAgentsControl.git
cd OpenAgentsControl

# Load plugin locally
claude --plugin-dir ./plugins/claude-code

# Download context files
/install-context

🚀 Quick Start

After installation, the plugin is ready to use:

# Verify installation
/oac:status

# Get help and usage guide
/oac:help

# Start a development task (using-oac skill auto-invokes)
"Build a user authentication system"

The using-oac skill is automatically invoked when you start a development task, guiding you through the 6-stage workflow with parallel execution for 5x faster feature development.

Context Files

Context files are automatically downloaded during installation via /install-context. You can update or change profiles anytime:

# Install different profile
/install-context --profile=extended

# Force reinstall
/install-context --force

# Preview what would be installed
/install-context --dry-run --profile=all

📚 Available Skills

Skills guide the main agent through specific workflows:

using-oac

Main workflow orchestrator implementing the 6-stage process (Analyze → Plan → LoadContext → Execute → Validate → Complete).

Auto-invoked: When you start a development task.

context-discovery

Guide for discovering and loading relevant context files (coding standards, security patterns, conventions).

Usage: /context-discovery authentication feature

Invokes: context-scout subagent via context: fork

external-scout

Guide for fetching external library and framework documentation from Context7 and other sources.

Usage: /external-scout drizzle schemas

Invokes: external-scout subagent via context: fork

task-breakdown

Guide for breaking down complex features into atomic subtasks with dependency tracking.

Usage: /task-breakdown user authentication system

Invokes: task-manager subagent via context: fork

code-execution

Guide for executing coding tasks with full context awareness and self-review.

Usage: /code-execution implement JWT service

Invokes: coder-agent subagent via context: fork

test-generation

Guide for generating comprehensive tests using TDD principles.

Usage: /test-generation authentication service

Invokes: test-engineer subagent via context: fork

code-review

Guide for performing thorough code reviews with security and quality analysis.

Usage: /code-review src/auth/

Invokes: code-reviewer subagent via context: fork

parallel-execution

Execute multiple independent tasks in parallel to dramatically reduce implementation time for multi-component features.

Usage: Automatically used when task-manager marks tasks with parallel: true

Use when: Multiple independent tasks with no dependencies, need to speed up multi-component features

🤖 Available Subagents

Subagents execute specialized tasks in isolated contexts:

task-manager

Break down complex features into atomic, verifiable subtasks with dependency tracking and JSON-based progress management.

Tools: Read, Write, Glob, Grep
Model: sonnet

context-scout

Discover relevant context files, standards, and patterns using navigation-driven discovery.

Tools: Read, Glob, Grep
Model: haiku

external-scout

Fetch external library and framework documentation from Context7 API and other sources, with local caching.

Tools: Read, Write, Bash
Model: haiku

coder-agent

Execute coding subtasks with full context awareness, self-review, and quality validation.

Tools: Read, Write, Edit, Glob, Grep
Model: sonnet

test-engineer

Generate comprehensive tests using TDD principles with coverage analysis and validation.

Tools: Read, Write, Edit, Bash, Glob, Grep
Model: sonnet

code-reviewer

Perform thorough code review with security analysis, quality checks, and actionable feedback.

Tools: Read, Bash, Glob, Grep
Model: sonnet

📝 Available Commands

User-invocable commands for setup and status:

/install-context

Download context files from the OpenAgents Control GitHub repository.

Usage: /install-context [--core|--all|--category=<name>]

Options:

  • --core - Download only core context files (standards, workflows, patterns)
  • --all - Download all context files including examples and guides
  • --category=<name> - Download specific category (e.g., --category=standards)

/oac:help

Show usage guide for OAC workflow, skills, subagents, and commands.

Usage:

  • /oac:help - Show general help
  • /oac:help <skill-name> - Show help for specific skill

/oac:status

Show plugin status, installed context version, and available components.

Usage: /oac:status

Shows:

  • Plugin version
  • Installed context version
  • Available subagents and skills
  • Context file count

/oac:cleanup

Clean up old temporary files from .tmp directory.

Usage: /oac:cleanup [--force] [--session-days=N] [--task-days=N] [--external-days=N]

Options:

  • --force - Skip confirmation and delete immediately
  • --session-days=N - Clean sessions older than N days (default: 7)
  • --task-days=N - Clean completed tasks older than N days (default: 30)
  • --external-days=N - Clean external context older than N days (default: 7)

Cleans:

  • Old session files from .tmp/sessions/
  • Completed task files from .tmp/tasks/
  • Cached external documentation from .tmp/external-context/

Example:

# Clean with defaults
/oac:cleanup

# Clean aggressively (3 days for sessions)
/oac:cleanup --session-days=3 --force

🔄 How It Works

6-Stage Workflow

OAC implements a structured workflow for every development task:

Stage 1: Analyze & Discover

  • Understand requirements and scope
  • Invoke /context-discovery to find relevant context files
  • Identify project standards, patterns, and conventions

Stage 2: Plan & Approve

  • Present implementation plan
  • REQUEST APPROVAL before proceeding
  • Confirm approach with user

Stage 3: LoadContext

  • Read all discovered context files
  • Load coding standards, security patterns, naming conventions
  • Pre-load context for execution stage (prevents nested discovery)

Stage 4: Execute

  • Simple tasks (1-3 files): Direct implementation
  • Complex tasks (4+ files): Invoke /task-breakdown to decompose into subtasks
  • Follow loaded standards and patterns

Stage 5: Validate

  • Run tests and validation
  • STOP on failure - fix before proceeding
  • Verify acceptance criteria met

Stage 6: Complete

  • Update documentation
  • Summarize changes
  • Return results

Architecture: Skills Invoke Subagents via context: fork

OAC Pattern (nested - NOT supported in Claude Code):

Main Agent → TaskManager → CoderAgent → ContextScout

Claude Code Pattern (flat - CORRECT):

Main Agent → /context-discovery skill → context-scout subagent
Main Agent → /task-breakdown skill → task-manager subagent
Main Agent → /code-execution skill → coder-agent subagent

Key Principle: Only the main agent can invoke subagents. Skills guide the orchestration, subagents execute specialized tasks in isolated contexts (context: fork).

Context Pre-Loading

Why: Prevents nested ContextScout calls during execution.

How: Stage 3 loads ALL context upfront, so execution stages (4-6) have everything they need.

Example:

Stage 1: Discover context files → [standards.md, security.md, patterns.md]
Stage 3: Load all files → Read standards.md, Read security.md, Read patterns.md
Stage 4: Execute with loaded context → No nested discovery needed

Approval Gates

Critical checkpoints:

  • Stage 2 → Stage 3: User must approve the plan
  • Stage 5 → Stage 6: Validation must pass

Never skip approval - it prevents wasted work and ensures alignment.

🔧 Configuration

The plugin uses context files from the main OpenAgents Control repository.

Context Structure

plugins/claude-code/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata
├── agents/                      # Custom subagents (7 files)
│   ├── task-manager.md
│   ├── context-scout.md
│   ├── context-manager.md
│   ├── external-scout.md
│   ├── coder-agent.md
│   ├── test-engineer.md
│   └── code-reviewer.md
├── skills/                      # Workflow skills (8 files)
│   ├── using-oac/SKILL.md
│   ├── context-discovery/SKILL.md
│   ├── external-scout/SKILL.md
│   ├── task-breakdown/SKILL.md
│   ├── code-execution/SKILL.md
│   ├── test-generation/SKILL.md
│   ├── code-review/SKILL.md
│   ├── install-context/SKILL.md
│   └── parallel-execution/SKILL.md
├── commands/                    # User commands (4 files)
│   ├── install-context.md
│   ├── oac-help.md
│   ├── oac-status.md
│   └── oac-cleanup.md
├── hooks/                       # Event-driven automation
│   ├── hooks.json
│   └── session-start.sh
├── scripts/                     # Utility scripts
│   ├── install-context.ts       # Context installer (TypeScript)
│   ├── install-context.js       # Context installer (JS fallback)
│   └── cleanup-tmp.sh           # Temporary file cleanup
└── .context-manifest.json       # Downloaded context tracking

Context Files

Context files are downloaded from the main repository via /install-context:

.opencode/context/
├── core/                        # Core standards and workflows
│   ├── standards/
│   ├── workflows/
│   └── patterns/
├── openagents-repo/             # OAC-specific guides
│   ├── guides/
│   ├── standards/
│   └── concepts/
└── navigation.md                # Context discovery navigation

🛠️ Development

Adding New Skills

  1. Create skill directory:

    mkdir -p plugins/claude-code/skills/my-skill

  2. Create SKILL.md with frontmatter:

    ---
name: my-skill
description: What this skill does
context: fork
agent: my-subagent
---

# My Skill

Instructions for the main agent...

  3. Test locally:

    claude --plugin-dir ./plugins/claude-code
/my-skill

Adding New Subagents

  1. Create subagent file:

    touch plugins/claude-code/agents/my-subagent.md

  2. Add frontmatter:

    ---
name: my-subagent
description: What this subagent does
tools: Read, Write, Glob, Grep
model: sonnet
---

# MySubagent

Instructions for the subagent...

  3. Create skill to invoke it:

    ---
name: my-workflow
description: Workflow description
context: fork
agent: my-subagent
---

Adding Hooks

Create hooks/hooks.json:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
      "timeout": 5
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
        "timeout": 30
      }]
    }]
  }
}

🔗 Related Projects

  • OpenAgents Control - Main repository (OpenCode native)
  • OAC CLI - Command-line tool for multi-IDE management (coming soon)

📖 Documentation

🤝 Contributing

Contributions welcome! See the main OpenAgents Control repository for contribution guidelines.

📄 License

MIT License - see LICENSE for details.

🆘 Support

🗺️ Roadmap

Phase 1: Foundation ✅ COMPLETE

  • ✅ Plugin structure
  • ✅ 6 custom subagents (task-manager, context-scout, external-scout, coder-agent, test-engineer, code-reviewer)
  • ✅ 8 workflow skills (using-oac, context-discovery, external-scout, task-breakdown, code-execution, test-generation, code-review, install-context, parallel-execution)
  • ✅ 4 user commands (/install-context, /oac:help, /oac:status, /oac:cleanup)
  • ✅ SessionStart hook for auto-loading using-oac skill
  • ✅ Context download and verification scripts
  • ✅ Flat delegation hierarchy (skills invoke subagents via context: fork)

Phase 2: Advanced Features ✅ COMPLETE

  • ✅ External library documentation fetching (ExternalScout subagent + skill)
  • ✅ .tmp cleanup automation (/oac:cleanup command)
  • ✅ .oac configuration file support (context-manager skill)
  • ✅ Context management and personal task systems (context-manager skill)
  • ✅ Parallel subtask execution tracking (parallel-execution skill)
  • ⬜ MCP server integration (future)

Phase 3: JSON Config System

  • ⬜ Auto-generation from JSON config
  • ⬜ Type-safe configuration
  • ⬜ Multi-IDE conversion

Version: 1.0.0
Last Updated: 2026-02-16
Status: Production Ready