our-claude-skills/custom-skills/91-multi-agent-guide/README.md

Multi-Agent Guide Plugin v2.0

A Claude Code plugin for setting up multi-agent collaboration frameworks in complex software projects.

What's New in v2.0

• Consolidated Framework: Single MULTI_AGENT_FRAMEWORK.md (~250 lines vs ~2,400)
• Quick Setup: /multi-agent-setup command for rapid deployment
• Production-Tested: Based on dintel-data-agent and our-seo-agent

Overview

This plugin helps you establish a structured collaboration framework for projects where multiple AI agents (Claude Code, Gemini, Codex, and Human) work together. It provides:

• Agent Hierarchy: Clear lead/sub-agent relationships
• Ownership Matrix: File and directory ownership per agent
• Guardrails System: Lock and task claiming to prevent conflicts
• Handoff Protocols: Standardized inter-agent communication
• CI/CD Integration: Automated ownership verification
• Pre-commit Hooks: Local verification before commits

Installation

Option 1: Symlink to Skills Directory

ln -s /Users/ourdigital/Project/our-claude-skills/custom-skills/91-multi-agent-guide ~/.claude/skills/multi-agent-guide

Option 2: Add to Claude Code Settings

Add to your ~/.claude/settings.json:

{
  "plugins": {
    "local": [
      "/Users/ourdigital/Project/our-claude-skills/custom-skills/91-multi-agent-guide"
    ]
  }
}

Usage

Automatic Activation (Skill)

The skill activates automatically when you mention:

• "set up multi-agent collaboration"
• "initialize multi-agent project"
• "create agent guardrails"
• "multi-agent guide"
• "agent coordination"

Explicit Commands

Quick Setup (Recommended):

/multi-agent-setup

Rapid deployment with minimal questions. Creates consolidated framework.

Full Setup:

/setup-agents

Interactive setup with full customization options.

What Gets Created

your-project/
├── .agent-state/
│   ├── tasks.yaml          # Task registry
│   └── locks.yaml          # Lock registry
├── tools/
│   └── check-ownership.py  # Ownership verification
├── AGENTS.md               # Shared collaboration rules
├── GUARDRAILS.md           # Ownership & enforcement
├── CLAUDE.md               # Lead agent directive
├── GEMINI.md               # Sub-agent directive (optional)
├── CODEX.md                # Sub-agent directive (optional)
├── .pre-commit-config.yaml # Pre-commit hooks (optional)
└── .github/
    └── workflows/
        └── ownership-check.yml  # CI workflow (optional)

Agent Hierarchy

                ┌─────────────────┐
                │   Claude Code   │
                │  (Lead Agent)   │
                └────────┬────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │  Gemini  │  │  Codex   │  │  Human   │
    │(Research)│  │ (Speed)  │  │ (Review) │
    └──────────┘  └──────────┘  └──────────┘

Environment Setup

After installation, set your agent identity:

# Add to shell profile (.bashrc, .zshrc)
export SEO_AGENT_AUTHOR=claude  # or gemini, codex, human

# Or use direnv (.envrc in project)
export SEO_AGENT_AUTHOR=claude

Commit Message Format

All agents must use this format:

[Agent] type(scope): description

Examples:
[Claude] feat(core): implement new feature
[Gemini] docs(api): update API documentation
[Codex] test(models): add unit tests
[Human] fix(config): correct configuration

Plugin Structure

91-multi-agent-guide/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── commands/
│   └── setup-agents.md       # /setup-agents command
├── skills/
│   └── multi-agent-guide/
│       ├── SKILL.md          # Main skill definition
│       ├── templates/        # File templates
│       ├── scripts/          # Helper scripts
│       ├── references/       # Documentation
│       └── examples/         # Example setups
└── README.md                 # This file

Templates Included

Template	Purpose
agents-md.md	AGENTS.md collaboration rules
guardrails-md.md	GUARDRAILS.md ownership rules
claude-md.md	Lead agent directive
gemini-md.md	Gemini sub-agent directive
codex-md.md	Codex sub-agent directive
tasks-yaml.yaml	Task registry template
locks-yaml.yaml	Lock registry template
github-workflow.yaml	GitHub Actions workflow
pre-commit-config.yaml	Pre-commit hooks

Customization

Adding Custom Agents

1. Create AGENTNAME.md using templates as reference
2. Add to AGENTS.md hierarchy table
3. Update OWNERSHIP_MATRIX in check-ownership.py
4. Add to VALID_AGENTS set in check-ownership.py

Modifying Ownership Rules

See skills/multi-agent-guide/references/ownership-matrix.md for pattern reference.

License

MIT

Author

OurDigital