Architecture & ADRs
The agent is built around a graph state machine (LangGraph): each pipeline stage is a node, and
a run is one traversal with checkpoints written to runs/<id>/.
observe ground design generate & validate judge & learn
Deep-dive documents live in the repository (canonical for contributors):
| Document | Covers |
|---|---|
| overview | The big picture — how the pieces compose |
| state-machine | Graph nodes, edges, checkpoints |
| browser-gateway | The lib | cli browser backends (BROWSER_BACKEND) |
| data-contracts | Case/report file formats |
| self-improvement | Keep-best repair + learning across runs |
| module-map | Source layout |
Architecture Decision Records
Section titled “Architecture Decision Records”| ADR | Decision |
|---|---|
| 0001 | Language & agent framework |
| 0002 | LLM: Anthropic tiering |
| 0003 | Browser gateway: hybrid |
| 0004 | Prompts in Langfuse |
| 0005 | Test output format |
| 0006 | Observability: Langfuse v5 + OTel |
| 0007 | Single package, not monorepo |
| 0008 | Methodology port from qa-skills |
| 0009 | TUI on Ink |
| 0010 | Rename to Cairn |
| 0011 | Per-role model routing |
| 0012 | Relicense to Apache-2.0 |
License
Section titled “License”Cairn is Apache-2.0 (relicensed from GPL-3.0 in v0.3.0 — see
ADR 0012).
Methodology prompts are ported from AZANIR/qa-skills
(ADR 0008).