# Multi-Agent Guide Plugin

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

## 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

```bash
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`:

```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 Command

Use the slash command:

```
/setup-agents
```

This will guide you through the complete setup process interactively.

## 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:

```bash
# 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