Add Architecture Decision Record (ADR) system

README.md

@@ -216,6 +216,19 @@ To customize the book:
 1. Create the directory: `mkdir -p book/minibook-templates`
 2. Create your custom template at `book/minibook-templates/custom.html.jinja2`.
 
+## 📝 Architecture Decision Records
+
+This project maintains Architecture Decision Records (ADRs) to document important architectural and design decisions.
+
+ADRs help preserve the reasoning behind key decisions, making it easier for current and future contributors to understand why the project is structured the way it is.
+
+**Browse ADRs**: See [docs/adr/](docs/adr/) for all architecture decisions.
+
+**Key decisions documented:**
+- [ADR-0001: Use Architecture Decision Records](docs/adr/0001-use-architecture-decision-records.md)
+
+For more information about the ADR format and how to create new records, see the [ADR README](docs/adr/README.md).
+
 ## 📁 Available Templates
 
 This repository provides a curated set of reusable configuration templates, organised by purpose.

docs/adr/0000-adr-template.md

@@ -0,0 +1,19 @@
+# [NUMBER]. [TITLE]
+
+Date: [YYYY-MM-DD]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by [ADR-XXXX](XXXX-title.md)]
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?

docs/adr/0001-use-architecture-decision-records.md

@@ -0,0 +1,65 @@
+# 1. Use Architecture Decision Records
+
+Date: 2026-01-01
+
+## Status
+
+Accepted
+
+## Context
+
+As the Rhiza project grows and evolves, we need a systematic way to document important architectural and design decisions. Team members (both current and future) need to understand:
+
+- Why certain approaches were chosen over alternatives
+- What constraints or requirements influenced past decisions
+- The expected consequences of architectural choices
+- The historical context behind the current system design
+
+Without such documentation, we risk:
+- Repeating past mistakes or debates
+- Making inconsistent decisions across the project
+- Losing institutional knowledge when team members change
+- Spending time explaining the same decisions repeatedly
+
+## Decision
+
+We will maintain Architecture Decision Records (ADRs) for architecturally significant decisions in the project.
+
+**Key aspects:**
+
+1. **Location**: ADRs will be stored in `docs/adr/` directory
+2. **Format**: Each ADR will follow the template defined in `0000-adr-template.md`
+3. **Naming**: Files will be named `XXXX-title-with-hyphens.md` with sequential 4-digit numbering (e.g., `0002-example-decision.md`)
+4. **Index**: The `docs/adr/README.md` will maintain an index of all ADRs
+5. **Immutability**: Once accepted, ADRs should not be modified; instead, create new ADRs that supersede old ones
+6. **Review**: ADRs should be reviewed and discussed before being marked as "Accepted"
+
+**What qualifies as an ADR-worthy decision:**
+
+- Changes to the project structure or organization
+- Technology or tool adoption/removal
+- Significant changes to development workflows or processes
+- Design patterns or architectural approaches
+- Changes to build, test, or deployment strategies
+
+## Consequences
+
+### Positive
+
+- **Knowledge preservation**: Important decisions and their rationale are documented for future reference
+- **Better onboarding**: New contributors can understand why things work the way they do
+- **Reduced debate**: Past decisions are clearly documented, reducing repetitive discussions
+- **Audit trail**: Clear history of architectural evolution
+- **Better decision-making**: Forces thoughtful consideration of context and consequences
+
+### Neutral
+
+- **Process overhead**: Contributors need to write ADRs for significant decisions (but this is offset by reduced future confusion)
+- **Learning curve**: Team members need to learn when and how to write ADRs
+
+### Negative
+
+- **Initial setup time**: Creating the ADR system and first records requires upfront effort
+- **Maintenance**: The ADR index needs to be kept up-to-date
+
+Overall, the benefits of maintaining ADRs far outweigh the minimal overhead required to keep them up-to-date.

docs/adr/README.md

@@ -0,0 +1,37 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for the Rhiza project.
+
+## What is an ADR?
+
+An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
+
+## ADR Format
+
+Each ADR follows a consistent format defined in [0000-adr-template.md](0000-adr-template.md):
+
+- **Title and Number**: Sequential numbering with descriptive title
+- **Date**: When the decision was made
+- **Status**: Current state (Proposed, Accepted, Deprecated, Superseded)
+- **Context**: The issue or situation that motivates the decision
+- **Decision**: The change or approach being taken
+- **Consequences**: What becomes easier or harder as a result
+
+## ADR Index
+
+| Number | Title | Status | Date |
+|--------|-------|--------|------|
+| [0001](0001-use-architecture-decision-records.md) | Use Architecture Decision Records | Accepted | 2026-01-01 |
+
+## Creating a New ADR
+
+1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-your-title.md`
+2. Use the next available 4-digit number (e.g., 0002, 0003, 0004)
+3. Fill in all sections with relevant information
+4. Update this README to add your ADR to the index
+5. Submit via pull request for review
+
+## Resources
+
+- [ADR GitHub Organization](https://adr.github.io/)
+- [Michael Nygard's article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)