diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..cb15fe5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# 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
+```