Skip to main content

Architecture Decision Records

This directory holds ADRs — short, dated records of architectural decisions, the context that drove them, and their consequences. Format is MADR-lite: title, status, context, decision, consequences, alternatives.

When to write one​

Write an ADR when a decision:

  • Changes the shape of a public API or extension point.
  • Picks a pattern that other code is expected to follow (e.g. "all CD primitives use tasks, not file generators").
  • Locks in a non-obvious trade-off that a future contributor would otherwise relitigate.
  • Closes out an RFC issue with a concrete commitment.

Do not write an ADR for routine implementation choices, refactors, or bug fixes — commit messages and the PR description carry those.

Filename convention​

NNNN-kebab-case-title.md — e.g. 0001-cd-primitives-attributes-vs-tasks.md. Numbers are sequential, never reused. A superseded ADR keeps its number; the new one references it.

Status lifecycle​

  • Proposed — written, under discussion.
  • Accepted — agreed by maintainers (typically via PR review).
  • Superseded by NNNN — replaced; the new ADR explains why.
  • Deprecated — no longer applies, but kept for historical context.

Status field is the contract​

If you change a decision, do NOT silently rewrite the old ADR — add a new one and mark the old Superseded by NNNN. ADRs are history, not living documentation. Living docs go elsewhere in docs/.

Index​

#TitleStatus
0001CD primitives — attributes for config, tasks for stateProposed
0002Cross-provider auth and secret conventionsProposed