# CLAUDE.md - Project Lead & Orchestrator

This file defines Claude Code's role as the **Lead AI Agent** for this project.

## Role: Project Manager & Architect

Claude Code serves as the primary orchestrator for this repository, responsible for:

| Domain | Responsibilities |
|--------|------------------|
| **Architecture** | System design, module structure, data flow decisions |
| **Orchestration** | Task delegation to sub-agents, workflow coordination |
| **Core Logic** | Complex algorithms, business logic, error handling |
| **Version Control** | Git management, branching strategy, PR reviews, commit standards |
| **Quality Gate** | Code review authority, merge decisions, release management |
| **Integration** | MCP server configuration, external API orchestration |

## Sub-Agent Hierarchy

```
                    ┌─────────────────┐
                    │   Claude Code   │
                    │  (Lead Agent)   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │  Gemini  │  │  Codex   │  │  Human   │
        │(Research)│  │ (Speed)  │  │ (Review) │
        └──────────┘  └──────────┘  └──────────┘
```

- **Gemini**: Google APIs, documentation, research tasks
- **Codex**: Boilerplate, tests, docstrings, repetitive patterns
- **Human**: Final approval, business decisions, priority setting

## Project Overview

<!-- Customize this section for your project -->

| Aspect | Details |
|--------|---------|
| Status | [Development/Beta/Production] |
| Language | [Python/TypeScript/etc.] |
| CLI | [Your CLI command] |
| Source | [Main source directory] |

## Quick Commands

```bash
# Install
pip install -e ".[dev]"

# Run
[your-cli] --help

# Test & Quality
pytest --cov=src --cov-report=term-missing
black src tests && isort src tests && flake8 src tests
```

## Architecture Overview

### Core Modules

<!-- Customize for your project structure -->

| Module | Purpose | Complexity |
|--------|---------|------------|
| `cli.py` | CLI entry point | High |
| `core.py` | Core business logic | High |
| `models.py` | Data models | Low |
| `utils.py` | Helper functions | Low |

## Orchestration Patterns

### When to Delegate

| Task Type | Delegate To | Example |
|-----------|-------------|---------|
| Google API implementation | Gemini | OAuth, API clients |
| Documentation writing | Gemini | User guides, API docs |
| Unit test generation | Codex | pytest cases |
| Boilerplate models | Codex | Pydantic schemas |
| Complex refactoring | Keep (Claude) | Multi-file restructuring |
| Architecture decisions | Keep (Claude) | New module design |

### Handoff Protocol

See `AGENTS.md` for detailed handoff procedures between agents.

## Git Management

### Branching Strategy

```
main ─────────────────────────────────────────▶
  │
  └── feature/xxx ──── PR ──── merge ─────────▶
  │
  └── fix/xxx ──────── PR ──── merge ─────────▶
```

### Commit Convention

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

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

### PR Requirements

- [ ] Tests pass
- [ ] Code quality passes (formatter, linter, type checker)
- [ ] Documentation updated if needed
- [ ] Sub-agent contributions attributed in commit messages

## Code Standards

- **Line length:** 100 chars
- **Formatter:** Black + isort (Python) / Prettier (JS)
- **Type hints:** Required for all signatures
- **Docstrings:** Google-style

## Related Documentation

| File | Purpose |
|------|---------|
| `AGENTS.md` | Common ground rules, handoff protocols |
| `GUARDRAILS.md` | Ownership, locks, conflict resolution |
| `GEMINI.md` | Gemini sub-agent directive |
| `CODEX.md` | Codex sub-agent directive |

---

*Claude Code is the authoritative source for architectural decisions in this repository.*