Adapted from the repo's docs/adr/0001-record-architecture-decisions.md — Part of Internals: the platform's design set, published as content on the platform it describes.
- Status: Accepted
- Date: template baseline
- Deciders: contract-owner
- Tiers affected: all
- Related:
docs/adr/README.md
Context
The project is built contract-first by an agent team whose members act autonomously on written context only. Decisions that live in chat history or in heads are invisible to members and get violated silently; without a durable record, context is also lost between sessions.
Decision
We will record decisions that are expensive to reverse, or that a member could
unknowingly violate, as ADRs in docs/adr/, following the process in
docs/adr/README.md. ADRs are immutable once accepted; corrections come as new ADRs
that supersede the old one.
Alternatives considered
- Decisions in chat/task history only — not durable across sessions; rejected.
- Single running design doc — loses the decision/status lifecycle and the scope test; rejected.
Consequences
- Any member or session can reconstruct why the system is shaped the way it is; agents
can be pointed at
docs/adr/as binding constraints. - Slight overhead per significant decision; the scope test in
docs/adr/README.mdkeeps the bar at "expensive to reverse", not "every choice". - The auth model, baseline version bumps, and breaking contract changes all require an ADR before implementation.
Compliance
- Reviewers reject implementation work that embodies an unrecorded significant decision; the Definition of done includes "relevant ADRs written or updated".