# ADR-0000: Use Architecture Decision Records

## Status

✅ Accepted

## Context

As omni-dev evolves, the project accumulates architectural and design decisions that
shape the system's direction. Key choices — such as the AI provider abstraction strategy,
template resolution approach, git integration design, and CLI command structure — are
currently undocumented and exist only as implicit knowledge in the code.

Without a structured way to capture these decisions, knowledge is lost over time, newcomers
lack context for why things are the way they are, and past decisions get revisited without
understanding the original trade-offs.

We need a lightweight, version-controlled method for recording significant decisions so that
current and future contributors can understand the reasoning behind them.

## Decision

We will use Architecture Decision Records (ADRs) to document significant architectural and
design decisions for this project.

Each ADR will follow the format popularised by Michael Nygard:

- **Title** — a short noun phrase describing the decision (e.g., "ADR-0007: YAML-Based Model Registry").
- **Status** — one of `Proposed`, `Accepted`, `Deprecated`, or `Superseded`.
- **Context** — the forces at play, including technical, organisational, and project-specific factors.
- **Decision** — the response to those forces, stated in active voice ("We will ...").
- **Consequences** — the resulting context after applying the decision, covering positive, negative, and neutral outcomes.

ADRs will be:

- Stored in `docs/adrs/` within the repository, so they are versioned alongside the code they describe.
- Written in Markdown for readability and portability.
- Numbered sequentially with zero-padded four-digit identifiers (e.g., `adr-0001.md`, `adr-0002.md`). Numbers are never reused; superseded ADRs remain in the repository for historical reference.
- Kept concise — ideally one to two pages.
- Scoped to a single decision per record.

## Consequences

- Every significant architectural decision will have a written record, making it easier for
  contributors to understand the rationale behind the current design.
- Superseded decisions remain in the repository, preserving the history of how the
  architecture evolved over time.
- There is a small overhead in writing and maintaining ADRs, but this is offset by the
  reduction in repeated discussions and onboarding time.
- The team has an agreed-upon location (`docs/adrs/`) and format to look for when seeking
  context on past decisions.
