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

AGENTS.md - Common Ground Rules & Collaboration Protocols

This file defines the shared rules, handoff protocols, and guidelines for all AI agents working on this repository.

Master Plan Reference: For strategic decisions, roadmap, and feature priorities, consult PROJECT_PLAN.md if available.

Enforcement Layer: For ownership rules, task claiming, and conflict resolution, see GUARDRAILS.md.

Agent Hierarchy

Agent	Role	Authority	Context File
Claude Code	Lead / Orchestrator	Architecture, core logic, final decisions	CLAUDE.md
Gemini	Sub-agent	Google APIs, documentation, research	GEMINI.md
Codex	Sub-agent	Tests, boilerplate, docstrings	CODEX.md
Human	Supervisor	Final approval, business decisions	N/A

All agents read this file (AGENTS.md) as the shared source of truth.

---

1. Project Status

Aspect	Status	Notes
Stage	[Development/Beta/Production]
Primary Language	[Python/TypeScript/etc.]
Test Coverage	[X%]	Target: 80%
Documentation	[Status]	See docs/ directory

---

2. Handoff Protocols

2.1 Claude → Gemini Handoff

When to delegate:

• Google API implementation (GSC, GA4, PageSpeed, etc.)
• Documentation writing (user guides, tutorials)
• Research on best practices or algorithm updates
• Content quality assessment logic

Handoff format:

## Task for Gemini

**Type:** [Google API | Documentation | Research]
**Priority:** [High | Medium | Low]

### Objective
[Clear description of what needs to be done]

### Interface/Contract (if API)
```python
# Claude defines the interface
class SomeProtocol(Protocol):
    async def method(...) -> SomeResponse:
        ...

Deliverables

• Implementation file(s)
• Unit tests (optional, Codex can assist)
• Documentation updates

Constraints

• Follow code style in AGENTS.md Section 4
• Use existing patterns from the codebase

**Return protocol:**
Gemini returns completed code → Claude reviews → Claude integrates.

---

### 2.2 Claude → Codex Handoff

**When to delegate:**
- Unit test generation from existing code
- Boilerplate Pydantic/dataclass models
- Docstring generation
- Repetitive pattern implementation

**Handoff format:**
```markdown
## Task for Codex

**Type:** [Tests | Models | Docstrings | Boilerplate]

### Pattern to Follow
```python
# Claude provides the first example
class ExampleClass(BaseClass):
    def method(self, arg: str) -> Result:
        ...

Generate

• SimilarClass1 (same pattern)
• SimilarClass2 (same pattern)
• Tests for all classes

**Return protocol:**
Codex generates → Claude reviews for edge cases → Claude commits.

---

### 2.3 Sub-agent → Claude Escalation

**When to escalate back:**
- Complex error handling needed
- Multi-file integration required
- Architectural decisions needed
- Rate limiting / caching strategy

**Escalation format:**
```markdown
## Escalation to Claude

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

### Completed Work
[What was finished]

### Blocking Issue
[What requires Claude's decision]

### Proposed Options
1. Option A: ...
2. Option B: ...

---

3. Development Workflow

Task Claiming: Before starting work, claim your task in .agent-state/tasks.yaml. See GUARDRAILS.md for the full claiming protocol.

Phase 1: Planning (Claude Lead)

User Request → Claude analyzes
                  ↓
            Claude creates task breakdown
                  ↓
            Claude assigns to agents
                  ↓
            Claude defines interfaces

Phase 2: Implementation (Parallel)

┌─────────────┬─────────────┬─────────────┐
│   Claude    │   Gemini    │   Codex     │
├─────────────┼─────────────┼─────────────┤
│ Core logic  │ Google APIs │ Tests       │
│ Complex     │ Docs        │ Models      │
│ Integration │ Research    │ Docstrings  │
└─────────────┴─────────────┴─────────────┘

Before modifying files:

1. Set SEO_AGENT_AUTHOR environment variable
2. Check .agent-state/locks.yaml for active locks
3. Claim task in .agent-state/tasks.yaml

Phase 3: Review & Merge (Claude Lead)

Sub-agent work → Claude reviews
                     ↓
              Claude integrates
                     ↓
              Claude runs full test suite
                     ↓
              Claude commits with attribution

---

4. Code Style Guidelines

4.1 Python Conventions

Rule	Standard
Line length	100 characters
Formatter	Black
Import sorter	isort (Black profile)
Linter	flake8
Type checker	mypy
Docstrings	Google-style

4.2 Import Organization

# Standard library
import asyncio
import logging
from typing import Dict, List, Optional

# Third-party
import aiohttp
from pydantic import BaseModel

# Local
from mypackage.models import MyModel
from mypackage.utils import helper_function

4.3 Error Handling Pattern

try:
    result = await some_operation(arg)
except SpecificError as e:
    logger.warning(f"Specific error: {e}")
    return None
except GeneralError:
    logger.exception("Unexpected error")
    raise

---

5. Commit & PR Standards

5.1 Commit Message Format

[Agent] type(scope): description

Body explaining the change (optional)

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

Types: feat, fix, docs, test, refactor, chore

Agent tags: [Claude], [Gemini], [Codex], [Human], [CI]

5.2 Examples

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

5.3 PR Checklist

## Pre-Merge Checklist

- [ ] Tests pass
- [ ] Code quality passes (formatter, linter, type checker)
- [ ] No hardcoded secrets
- [ ] Error handling implemented
- [ ] Logging added for debugging
- [ ] Documentation updated
- [ ] Agent attribution in commit messages

---

6. Quality Assurance

6.1 Review Matrix

Review Type	Reviewer	Focus
Architecture	Claude	Design patterns, scalability
Logic correctness	Claude	Edge cases, error handling
Google API usage	Gemini	Best practices, quotas
Code style	Linter	Consistency
Documentation	Gemini	Clarity, completeness
Test coverage	Claude + Codex	Coverage, edge cases

6.2 Testing Standards

# Minimum requirements before merge
pytest --cov=src --cov-fail-under=70

# For critical modules
pytest --cov=src/critical_module --cov-fail-under=80

---

7. Quick Reference Commands

# Quality checks
black src tests && isort src tests && flake8 src tests && mypy src tests

# Testing
pytest                              # All tests
pytest tests/test_file.py -v        # Single file
pytest -k "pattern" -v              # Pattern match
pytest --cov=src --cov-report=html  # Coverage report

---

8. References

Internal Documents

Document	Purpose
GUARDRAILS.md	Ownership, locks, conflict resolution
CLAUDE.md	Lead agent directive
GEMINI.md	Gemini sub-agent directive
CODEX.md	Codex sub-agent directive

---

This document is the shared source of truth for all AI agents. Claude Code maintains and updates this file.

Last updated: [DATE]