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

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

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

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

# 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

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

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

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