# CLAUDE.md — Agent Quick Reference

Read this before exploring the codebase. It saves tokens.

## What This Is

A tiered multi-agent orchestration framework. T1 decomposes goals → T2 architects → T3 leads → T4 implements → T5 verifies. SQLite blackboard tracks state. All external dependencies (LLM, VCS, notify, runtime) are pluggable adapters.

## Key Docs

- `docs/design.md` — architecture decisions, tier design, key choices
- `docs/buildspec.md` — 15-step build order, phase breakdown

## Project Layout

```
core/           — task_brief.py, blackboard.py, escalation.py, team_runner.py
adapters/base/  — abstract base classes (LLMAdapter, VCSAdapter, NotifyAdapter, RuntimeAdapter)
adapters/llm/   — anthropic.py
adapters/vcs/   — github.py
adapters/notify/— openclaw.py
adapters/runtime— openclaw.py, claude_code.py
prompts/        — T1–T5 system prompt .md files
config/         — team.yaml (run config), role_registry.yaml (tier→role→persona)
agents/         — git submodule, agent persona .md files
runs/           — per-run blackboard.db files (gitignored)
```

## Conventions

- **Never commit or push directly to `main`** — always branch (`hans/...` or `feature/...`) and PR
- New adapters: subclass the relevant `adapters/base/*.py` abstract class
- New roles: add persona `.md` to `agents/` submodule + entry in `config/role_registry.yaml`
- Failure handling lives in `core/escalation.py` — extend `FailureType` there
- `TaskBrief` is the canonical work unit — all tiers pass briefs to each other
- Blackboard is the single source of truth per run — always write events there

## Current State

Phase 2 adapter implementations exist. `core/team_runner.py` may still have stubs — check before assuming it's wired up end-to-end.

## Running

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m core.team_runner --config config/team.yaml
```