49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# 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
|
||
```
|