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

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

1.9 KiB Raw Blame History Unescape Escape