Every non-trivial architectural, product, or process decision in Relavium is recorded here as an ADR (Architecture Decision Record) using a lightweight MADR (Markdown Architectural Decision Records) style.
- They preserve the why, not just the what. The reasoning behind a choice is the information that decays fastest and is most expensive to re-derive later.
- They make the evolution of the project readable: you can follow the numbered history and see how the design language developed, including the options that were rejected.
- They give future contributors (human or AI) a way to disagree with a decision by writing a new ADR that supersedes an old one, rather than silently changing code or docs.
Concrete specifications (workflow/agent YAML, the SSE event schema, the IPC contract, store shapes, DB DDL) live in their canonical reference/ files. ADRs cite those by relative link and never restate them; they capture the decision and its drivers, not the spec.
Every ADR is a single file named NNNN-short-kebab-slug.md, where NNNN is a zero-padded four-digit sequence number. Each one opens with an H1 title and bold metadata lines, then four sections:
- Context — the situation, the problem, the constraints that applied.
- Decision — the option chosen, the alternatives considered, and the drivers that connected them.
- Consequences — split into Positive and Negative effects, with mitigations where relevant.
Pinned tool and library versions are not restated in ADRs; they live in tech-stack.md and are referenced from there.
Relavium will ship as more than one git repository. To avoid renumbering pain across repos, there are two independent ADR number spaces — one for this meta repo, one reserved for the Phase-2 cloud repo.
| Space | Location | Scope | Numbering |
|---|---|---|---|
| Product / cross-cutting ADR | this repo docs/decisions/ (this folder) |
Decisions that touch more than one surface (desktop, CLI, VS Code, portal), the shared engine, or product scope / phasing | Independent ADR-0001.. |
| Cloud backend ADR (Phase 2) | reserved relavium-cloud/docs/decisions/ |
Decisions internal to the Phase-2 cloud execution backend only (worker orchestration, queue tuning, secrets injection, VPC peering) | Independent ADR-0001.. |
The two spaces are deliberately separate; a collision (e.g. two ADR-0005s) is expected and is not a problem — the files live in different repos. Renumbering would touch every cross-reference (high risk, no value), so it is never done. Citation convention: "Product ADR-00NN" (this folder) vs "Cloud ADR-00NN" (relavium-cloud/docs/decisions/).
The cloud repo and its ADR space do not exist yet — they are a Phase-2 carry-forward. See ADR-0008 for the phasing decision that creates this split, and the (Phase 2) cloud architecture doc.
flowchart TD
Q{What does the decision affect?}
Q -->|More than one surface, the shared<br/>engine, or product scope / phasing| META[Product ADR<br/>this folder]
Q -->|Phase-2 cloud backend internals only| CLOUD[Cloud ADR<br/>relavium-cloud/docs/decisions/<br/>reserved, does not exist yet]
- Copy the structure of an existing ADR to the next available number:
NNNN-your-slug.md. - Fill in the H1, bold Status / Date / Related lines, then
## Context,## Decision,## Consequences(### Positive/### Negativewith mitigations / optionally### Neutralfor scope notes, non-reversals, and forward pointers). - Start at status
Acceptedonce the decision is settled; cross-link sibling ADRs and reference tech-stack.md for versions. - If a later ADR overrides this one, mark the old one
Superseded by NNNNand link forward. Do not delete or rewrite the old ADR — the historical reasoning is the point. - To refine, clarify, or reconcile an Accepted ADR without reversing it (e.g. a later ADR refines its mechanism), amend it in place with a dated
> Amended YYYY-MM-DD: …note that points to the driving ADR — never a silent rewrite. Reversing a decision is a supersession (step 4), not an amendment. The rule is in documentation-style.md §7.