Architecture Decision Records (ADRs) — the durable log of significant architectural decisions. See CLAUDE.md § ADRs for the routing-layer treatment of where decisions sit in the pipeline.
An ADR records a decision when it is made, so the reasoning survives the moment. Unlike the per-session prompt/retro pair (which captures session intent and outcome), an ADR captures a cross-cutting decision that outlives any one session and that later contributors would otherwise re-derive.
Per CLAUDE.md, capture an ADR when any of these holds:
- (a) reversing the decision would require touching multiple bounded contexts,
- (b) the tradeoff is non-obvious, or
- (c) the next contributor would otherwise have to re-derive the reasoning.
Below that bar, the decision lives in the prompt/retro pair that made it — not here. Resist minting an ADR for a choice that only affects one slice's internals.
NNN-{slug}.md where NNN is the ADR's number (zero-padded, monotonic) and {slug} is a short kebab-case identifier (e.g., 007-process-manager-via-handlers-for-order.md).
The house format is terse and prose-shaped:
- Top-line title
# ADR NNN: {Title}. **Status**: {Accepted | Proposed | Superseded}immediately under the title.## Context— the situation and the question.## Decision— what was chosen.## Consequences— what follows, including costs, risks, and rejected alternatives folded into prose.
ADRs are append-only. A later ADR may supersede an earlier one (mark the old one's status Superseded and cross-reference), but the original is not deleted or rewritten — the log is the history.
| ADR | Title | Status |
|---|---|---|
| 001 | Separate Services Topology | Accepted |
| 002 | Shared PostgreSQL with Schema-per-Service | Accepted |
| 003 | Wolverine Messaging with RabbitMQ Transport | Accepted |
| 004 | .NET Aspire as Orchestrator | Accepted |
| 005 | OpenTelemetry Tracing Enabled | Accepted |
| 006 | Wolverine.Http API Surface per Service, No Separate BFF for Round One | Accepted |
| 007 | Process Manager via Handlers for the Order Aggregate | Accepted |
| 008 | Inline Snapshot Projections, One Async Teaser, No Daemon for Round One | Accepted |
| 009 | Polecat Deferred for Round One | Accepted |
| 010 | OpenSpec + Sibling Narrative for the SDD Pipeline | Accepted |
| 011 | openspec CLI as Proposal Tooling, Grain-Aware Layered Integration | Accepted |
| 012 | Critter Stack 2026 Upgrade (Wolverine 6 / Marten 9) | Accepted |
| 013 | CritterWatch Deferred to the 4.x Messaging Slices | Accepted |
| 014 | Published-Language Cross-BC Contracts in a Shared CritterMart.Contracts Project |
Accepted |
| 015 | Vite + React SPA as the Round-Two Frontend Stack | Accepted |
| 016 | Frontend Modeled Through the Full Pipeline — UI First-Class in the Event Model | Accepted |
| 017 | CritterWatch Integrated — Out-of-Band Trial, Single-Node, nuget.org-Sourced | Accepted |
| 018 | Frontend-to-Three-Services Dev-Server + CORS Posture | Accepted |
| 019 | Wolverine Runtime Health Exposed via ASP.NET Health Checks | Accepted |
| 020 | Aggregates Are Domain-Named Immutable Write Models; Read Models Are Separate *View Projections |
Accepted |
| 021 | Feature/Slice Folders Named for the Activity (Verb); Domain Types Keep Canonical Noun Names | Accepted |
| 022 | Convention Sagas Are Additive to PMvH | Accepted |
Keep this table in sync when an ADR is added or its status changes — it is the discoverability payload of this README.
- CLAUDE.md § ADRs — ADR routing-layer treatment and capture threshold.
- CLAUDE.md § External-skill path overrides — the mattpocock skill family assumes
docs/adr/; CritterMart usesdocs/decisions/. Treat the two as equivalent when invoking those skills. ../prompts/and../retrospectives/— where below-threshold decisions live instead.