Architecture & ADRs

The agent is a plain async pipeline. LangGraph was dropped in 0.4.0 (ADR 0013). Each pipeline stage is a step over two seams: a browser gateway and a structured LLM call. A run writes its artifacts to runs/<id>/. Since 0.8.0 an optional decision layer can answer some of the steps’ pick-from-a-list questions.

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

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
0013	Drop LangGraph; telemetry at the LLM layer; Ink optional
0014	The run artifact is a versioned, self-describing contract
0015	The api modality generates from the spec, not from an LLM
0016	MCP, the CI/PR bot and --into-project are thin adapters over the core
0017	The pipeline grows by opt-in passes; a flag-off run is byte-identical
0018	Page understanding is an artifact, cached by ARIA fingerprint
0019	Adversarial styles: port the taxonomy, not the mechanism
0020	An LLM verdict is untrusted; only self-created data is disposable
0021	A human-authored case is a first-class input
0022	An optional decision layer (Jev / Laya): a separate seam, off by default, never trusted

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).