feat: Add multi-agent-guide skill and update reference-curator configs
- Add 91-multi-agent-guide skill for setting up multi-agent collaboration with templates for AGENTS.md, Claude, Gemini, Codex configs, and CI/CD - Add USER-GUIDE.md for reference-curator documentation - Update default paths in reference-curator configs to use ~/Documents/05_AI Agent/10_Reference Library/ - Update settings-audit-report.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
327
custom-skills/91-multi-agent-guide/templates/agents-md.md
Normal file
327
custom-skills/91-multi-agent-guide/templates/agents-md.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 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`](./PROJECT_PLAN.md) if available.
|
||||
|
||||
> **Enforcement Layer**: For ownership rules, task claiming, and conflict resolution, see [`GUARDRAILS.md`](./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
|
||||
|
||||
<!-- Customize this section for your project -->
|
||||
|
||||
| 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:**
|
||||
```markdown
|
||||
## 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`](./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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
[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
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`](./GUARDRAILS.md) | Ownership, locks, conflict resolution |
|
||||
| [`CLAUDE.md`](./CLAUDE.md) | Lead agent directive |
|
||||
| [`GEMINI.md`](./GEMINI.md) | Gemini sub-agent directive |
|
||||
| [`CODEX.md`](./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]*
|
||||
Reference in New Issue
Block a user