architecture-decisions git:20260908.9ba8ffaA

Immutable. This exact content is served forever at /api/v1/blob/ed5581dd480efbac.

---
description: Architectural Decision Records — agent consume/cite/conflict; humans approve
alwaysApply: true
---

# Architecture Decisions (ADRs)

- **Human playbook** (propose / discuss / approve): `docs/adrs/README.md`
- **Accepted ADRs** (current recommendations): enumerate the index in `docs/adrs/README.md` and confirm each record's Status — read explicitly; `docs/` is outside default indexing. Filenames normally use `*-accepted.md`, but do not exclude Accepted records without that suffix.
- **Agent skill** (use / cite / conflict / maintain): `dough-adr-awareness` in `.agents/skills/dough-adr-awareness/` (Codex/Cursor) and `.claude/skills/dough-adr-awareness/` (Claude Code).
- **Architecture-shaped work:** cross-cutting stack, persistence, API contracts, authentication, packaging/monorepo layout, and shared conventions across backend/frontend/cli/mcp/e2e; explicit ADR work; or changes that reverse or bypass an Accepted ADR.
- On architecture-shaped work, load relevant Accepted ADRs and follow them. Do not silently conflict. Do not approve ADRs; humans own the advice process.
- Deviations require an explicit human-owned exception (record it in a PR/commit message or note pointing at the ADR) or a human superseding ADR. These constraints also apply to planning and delivery workflows.