# Multi-Agent Development Framework

**Version:** 1.0
**Applies to:** {{PROJECT_NAME}}
**Last Updated:** {{DATE}}

---

## 1. Agent Hierarchy

```
                    Human (Final Authority)
                           │
                           ▼
                    ┌─────────────┐
                    │ Claude Code │ ← Lead Agent
                    │ Orchestrator│
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
    ┌─────────┐      ┌─────────┐      ┌─────────┐
    │ Gemini  │      │  Codex  │      │  Human  │
    │Research │      │  Speed  │      │ Approve │
    └─────────┘      └─────────┘      └─────────┘
```

| Agent | Role | Scope |
|-------|------|-------|
| **Claude** | Lead / Orchestrator | Architecture, core logic, integration, git, final review |
| **Gemini** | Sub-agent | Google APIs, documentation, research, visualization |
| **Codex** | Sub-agent | Tests, boilerplate, models, docstrings, utilities |
| **Human** | Authority | Business decisions, priorities, release approval |

---

## 2. File Ownership

### 2.1 Standard Ownership Matrix

| Pattern | Owner | Examples |
|---------|-------|----------|
| `src/*/core/`, `src/*/services/` | Claude | Business logic, orchestration |
| `src/*/api/`, `src/*/mcp/` | Claude | API clients, MCP servers |
| `src/*/connectors/` | Claude | Data source integrations |
| `src/*/visualization/`, `src/*/app/` | Gemini | Dashboards, charts |
| `docs/*.md` | Gemini | User documentation |
| `tests/` | Codex | All test files |
| `src/*/utils/`, `src/*/models.py` | Codex | Utilities, Pydantic models |

### 2.2 Shared Files (Require Claude Approval)

| Files | Rule |
|-------|------|
| `pyproject.toml`, `requirements*.txt` | Claude approves dependency changes |
| `.github/workflows/` | Claude approves CI/CD changes |
| `CLAUDE.md`, `AGENTS.md`, `GUARDRAILS.md` | Claude only |
| `PROJECT_PLAN.md` | Human approves roadmap changes |

### 2.3 Unrestricted Files

Any agent can modify: `.agent-state/*`, `.gitignore`, `README.md`

---

## 3. State Management

All state tracked in `.agent-state/` directory:

```
.agent-state/
├── tasks.yaml    # Task registry
└── locks.yaml    # File locks
```

### 3.1 Task Entry

```yaml
tasks:
  - id: "TASK-001"
    agent: "codex"
    status: "in_progress"    # pending | in_progress | completed | abandoned | blocked
    description: "Add unit tests for crawler"
    files: ["tests/test_crawler.py"]
    claimed_at: "{{DATE}}T10:00:00Z"
    expires_at: "{{DATE}}T22:00:00Z"
```

### 3.2 Lock Entry

```yaml
locks:
  - path: "src/crawler.py"
    agent: "claude"
    task_id: "TASK-001"
    lock_type: "exclusive"   # exclusive | shared | override
    expires_at: "{{DATE}}T22:00:00Z"
```

### 3.3 Expiration Rules

| Scenario | Duration |
|----------|----------|
| Standard task | 12 hours |
| Complex refactoring | 24 hours |
| Emergency fix | 4 hours |
| Override (Claude) | 4 hours |

---

## 4. Workflow

### 4.1 Task Claiming

```bash
# 1. Set identity
export AGENT_AUTHOR=codex

# 2. Check state
cat .agent-state/tasks.yaml
cat .agent-state/locks.yaml

# 3. Claim task (add to tasks.yaml)
git commit -m "[Codex] chore: claim TASK-001"

# 4. Do work, then commit
git commit -m "[Codex] test(crawler): add unit tests"

# 5. Complete (update status, remove locks)
git commit -m "[Codex] chore: complete TASK-001"
```

### 4.2 Conflict Resolution

```
1. Ownership Matrix  → Owner has priority
         ↓
2. Active Locks      → Lock holder has priority
         ↓
3. Task Assignment   → Assigned agent has priority
         ↓
4. Escalate to Claude → Final decision
```

---

## 5. Handoff Protocols

### 5.1 Claude → Sub-agent

```markdown
## Task for [Gemini/Codex]

**Type:** [API | Docs | Tests | Models]
**Priority:** [High | Medium | Low]

### Objective
[What needs to be done]

### Deliverables
- [ ] Implementation
- [ ] Tests (if applicable)
- [ ] Documentation update
```

### 5.2 Sub-agent → Claude (Escalation)

```markdown
## Escalation to Claude

**Reason:** [Architecture | Integration | Security | Complexity]

### Completed
[What was finished]

### Blocking Issue
[What needs Claude's decision]
```

---

## 6. Commit Standards

### 6.1 Format

```
[Agent] type(scope): description

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

### 6.2 Types & Tags

| Type | Purpose | Agent Tags |
|------|---------|------------|
| `feat` | New feature | `[Claude]` |
| `fix` | Bug fix | `[Gemini]` |
| `docs` | Documentation | `[Codex]` |
| `test` | Tests | `[Human]` |
| `refactor` | Refactoring | `[CI]` |
| `chore` | Maintenance | |

---

## 7. Quality Gates

### 7.1 Pre-merge Checklist

- [ ] Tests pass (`pytest`)
- [ ] Code quality passes (`black`, `isort`, `flake8`, `mypy`)
- [ ] Ownership check passes
- [ ] No hardcoded secrets
- [ ] Documentation updated
- [ ] Agent attribution in commits

### 7.2 Coverage Targets

| Scope | Minimum | Target |
|-------|---------|--------|
| Overall | 70% | 80% |
| Core modules | 80% | 90% |
| New code | 80% | 100% |

---

## 8. Quick Reference

### Environment Setup

```bash
export AGENT_AUTHOR=claude   # claude | gemini | codex | human
pip install -e ".[dev]"
pre-commit install
```

### Ownership Lookup

```
Core logic, APIs, services    → Claude
Visualization, dashboards     → Gemini
Documentation                 → Gemini
Tests, fixtures               → Codex
Utilities, models             → Codex
Dependencies, CI/CD           → Shared (Claude approves)
```

### Escalation Triggers

- Architectural decisions needed
- Multi-file integration required
- Security concerns
- Performance optimization

---

*Generated by Multi-Agent Guide Skill v2.0*