> ## Documentation Index
> Fetch the complete documentation index at: https://haico.gr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0000: Record architecture decisions

> Why and how we record architectural decisions as MADR-style ADRs.

# 0000. Record architecture decisions

## Context and problem statement

HAI-Co² is a reference implementation of a published framework. Architectural choices (branching model, agent framework, deployment topology, dual-pathway contribution model) accumulate quickly, and the people who arrive on the project six months from now will not have been present for the original debates. Without a lightweight record, those discussions either die in chat history or have to be reconstructed from PR threads, which is slow and unreliable.

## Decision drivers

* Onboarding cost for new contributors must stay low.
* Decisions that constrain future work need a discoverable rationale.
* The dual-pathway model (see [ADR-0002](/docs/adr/0002-dual-development-pathways)) uses *"does this need an ADR?"* as a triage criterion, so the artefact has to exist.
* Tooling overhead should be zero. We are already comfortable with Markdown in `docs/`.

## Considered options

1. **No structured record.** Discussions live in PR threads and chat.
2. **A free-form `decisions.md` file.** One growing document of bullets.
3. **MADR-style ADRs under `docs/adr/`.** One short Markdown file per decision, numbered and version-controlled.
4. **An external system (Notion, Confluence).** Out-of-repo source of truth.

## Decision outcome

**Chosen option: MADR-style ADRs under `docs/adr/`**, because they keep the record next to the code, require no tooling, version-control naturally, and each file stays small enough that reviewers actually read it.

### Positive consequences

* Decisions live alongside the code they justify.
* ADR existence is itself a signal; see [ADR-0002](/docs/adr/0002-dual-development-pathways).
* New contributors can read `docs/adr/` top-to-bottom in under an hour.

### Negative consequences

* Maintainers have to remember to write an ADR when a decision lands. Reviewers should ask *"does this need an ADR?"* on architecture-touching PRs.
* Numbering needs a conflict-resolution step when two ADRs are drafted in parallel; the resolver simply re-numbers the later one before merge.

## Pros and cons of the options

### Option 1: No structured record

* **+** Zero overhead.
* **−** Knowledge evaporates. Hardest option to walk back.

### Option 2: Free-form `decisions.md`

* **+** Lightweight.
* **−** Grows unstructured; either re-litigates or gets ignored.

### Option 3: MADR ADRs under `docs/adr/`

* **+** Per-decision granularity; small reviewable files; version-controlled.
* **−** Mild discipline cost.

### Option 4: External system

* **+** Rich formatting; non-developers can contribute.
* **−** Drifts from the code; requires accounts; gone if the SaaS dies.

## Links

* [MADR: Markdown Architecture Decision Records](https://adr.github.io/madr/)
* [`docs/adr/README.md`](/docs/adr/index) for the project's ADR conventions.