<!--

ADR TEMPLATE — copy this file to create a new ADR

How to use:

1. Copy this file to docs/architecture/decisions/NNNN-.md where NNNN is the next available 4-digit number (zero-padded) and is a short kebab-case description. Examples: 0003-license.md 0008-prereq-install-policy.md 0014-template-interpolation-format.md
2. Delete this instruction block.
3. Fill in the template, removing the comments as you go.
4. Open a PR; reference the ADR in the PR description.

Naming conventions:

• 4-digit zero-padded number (0001 .. 9999)
• Slug is kebab-case, 2–5 words
• File extension is .md

Status workflow: Proposed → still under discussion; may change Accepted → decision is final, work proceeds against it Deprecated → no longer recommended, but no replacement Superseded by ADR-NNNN → replaced by a newer ADR

When superseding an older ADR:

• Set the old ADR's status to "Superseded by ADR-NNNN"
• Set the new ADR's Supersedes field to the old ADR number
• Do NOT edit the old ADR's substantive content (preserve history)

When to write an ADR:

• The decision is irreversible or expensive to reverse
• The decision has competing reasonable alternatives
• Future-you (or a contributor) might second-guess this choice without context
• You're locking in an interface, protocol, or contract
• You're choosing between technologies, patterns, or designs

When NOT to write an ADR:

• Trivial choices (variable naming, file ordering)
• Decisions that follow obviously from a previous ADR
• Implementation details that don't affect architecture

Length guidance:

• Aim for 200–500 lines
• The Decision and Alternatives sections should be the heaviest
• Don't pad; brevity is a virtue

Tone:

• Honest about negatives — list real downsides, not hedged ones
• Concrete — name specific tools, versions, patterns
• Self-contained — a reader should not need to read another doc to understand the decision

See completed examples:

• 0001-runtime-language.md
• 0002-monorepo-tooling.md

• 0005-adapter-contract-shape.md

  -->

ADR NNNN:

Summary

Context

Decision

1.

2.

Consequences

Positive

• :
• :

Negative

• : .
• : .

Neutral

• :

Alternatives considered

Alternative 1:

Pros

Cons

Reason rejected:

Alternative 2:

Implementation notes

Validation

This decision is validated when:

• [ ]
• [ ]
• [ ]

References

Internal

• ADR NNNN —
• docs/specs/<name>.md —
• ARCHITECTURE.md §
  —

External