Architecture Decision Records

On this page

Architecture Decision Records (ADRs) document non-obvious architectural choices made in this project. They capture the why behind decisions so future contributors (human and AI) can understand the context and consequences without having to reconstruct them from commit history.

When to write an ADR

Write an ADR when:

  • Choosing a framework, library, database, or protocol that has viable alternatives

  • Picking a design pattern that meaningfully constrains future work

  • Establishing a new convention or banning a previously-allowed pattern

  • Making a security or operational trade-off with long-term consequences

You do not need an ADR for:

  • Routine bug fixes

  • Adding features that follow existing patterns

  • Refactoring with no architectural impact

  • Choices fully constrained by existing ADRs (just reference the existing ADR)

Format

ADRs follow the standard five-section format (matching adr-000-template.adoc and coding-conventions.md):

  1. Status — Proposed / Accepted / Superseded by ADR-NNN / Deprecated

  2. Context — What problem are we solving? What constraints apply?

  3. Decision — What did we choose? Be specific.

  4. Alternatives Considered — What else was on the table, and why not?

  5. Consequences — What does this enable, prevent, require, or trade away?

Naming

  • File name: adr-NNN-short-title.adoc (zero-padded 3-digit sequence number)

  • Title: action-oriented, present tense (e.g., "Use SQLx for database access", "Ban OpenSSL")

Lifecycle

  • ADRs are immutable once accepted. Do not edit them.

  • To change a decision, write a new ADR that supersedes the old one. Update the old ADR’s Status to "Superseded by ADR-NNN".

  • Status updates (Accepted → Deprecated, etc.) are the only edits allowed.

Template

See adr-000-template.adoc for a starter template. Copy it to adr-NNN-your-decision.adoc and fill in each section.

Index

ADR Title Status

000

Template

N/A

001

TypeScript toolchain (pnpm, Biome, vitest, strict tsc)

Accepted

002

Downstream-in-spirit of claude-quickstart (deferred sync gating)

Accepted (amended by ADR-003)

003

Agent configuration lives in @gadhs/pi; claude-quickstart sunsets as the agent vehicle

Accepted

004

Package boundaries — policy, workflow, and content are separate packages

Accepted

005

One first-party Vertex provider for every publisher, delegating the wire

Accepted
Edit this page · latest