Short, immutable records of decisions that were not obvious — where a reasonable engineer could have chosen differently, and where the reason would otherwise be lost.
| Artefact | Answers | Lifecycle |
|---|---|---|
openspec/specs/<cap>/spec.md |
What the system does, normatively | Living — updated on archive |
openspec/changes/<change>/design.md |
How this change is built | Archived with the change |
docs/adr/NNNN-*.md |
Why we chose X over Y | Immutable — superseded, never edited |
A design.md dies with its change. An ADR outlives it. When a design
decision will still be load-bearing in six months — when someone will read
the code and ask "why on earth is it done this way?" — it gets an ADR, and
design.md links to it rather than restating it.
- Filename:
NNNN-kebab-case-title.md, zero-padded, never reused. - Status:
Proposed→Accepted→ (Superseded by ADR-NNNN|Deprecated). - An accepted ADR is never edited except to change its status line. A changed mind means a new ADR that supersedes it.
- Every ADR names the change that motivated it, so the full context is
recoverable from
openspec/changes/(or its archive).
| ADR | Title | Status | Change |
|---|---|---|---|
| 0001 | Body Double reuses POST /api/session/start |
Accepted | body-double-own-agent-picker |
| 0002 | Origin-scoped addressing for liveAgentConsole() |
Accepted | body-double-own-agent-picker |
| 0003 | Body Double is exempt from park-first friction | Accepted | body-double-own-agent-picker |
| 0004 | Unmount terminalPanel() without deleting it |
Superseded by ADR-0008 | body-double-own-agent-picker |
| 0005 | Retire the ttyd browser surface, keep the server transport | Superseded in part by ADR-0008 | live-agent-console.js, index.html |
| 0006 | Bridge-aware deferred topics, behind a testable 0.1.0 boundary | Proposed | reviews/0.1.0-SCOPE-DECISION.md |
| 0007 | Dev-only vendored assets live in git, not in the wheel | Accepted | vendor/dev/ |
| 0008 | Retire ttyd entirely; the Web UI owns interactive sessions | Accepted | ttyd retirement stages 2-7 |
| 0009 | The session-state file is the claim; the in-process slot is a cache | Accepted | M2 session-authority remediation |
| 0010 | Second brains are projections; plan Markdown is the source of truth | Accepted | second-brain |
| 0011 | Retire the OKF import, the tier-1 ontology and the concept sidecar — no functional remnant | Accepted | 2026-09-10 OKF removal (Stages 4–6) |