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:
- 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 | Use Architecture Decision Records | Accepted | 2026-01-01 |
| 0002 | Use uv for Python Package and Environment Management | Accepted | 2024-09-01 |
| 0003 | Use Ruff for Linting and Formatting | Accepted | 2024-06-01 |
| 0004 | Adopt a Modular Makefile Architecture | Accepted | 2024-03-01 |
| 0005 | Separate rhiza Template Repository from rhiza-cli | Accepted | 2024-05-01 |
| 0006 | Organise Templates into Bundles | Accepted | 2025-01-01 |
| 0007 | Support Dual CI/CD with GitHub Actions and GitLab CI | Accepted | 2024-08-01 |
| 0008 | Use Marimo for Interactive Notebooks | Accepted | 2025-03-01 |
| 0009 | Use Pre-commit Hooks for Automated Code Quality Enforcement | Accepted | 2024-04-01 |
Creating a New ADR
Option 1: Using AI Assistance (Recommended)
The easiest way to create a new ADR is using the automated workflow:
This will: 1. Prompt you for the ADR title and optional context 2. Trigger an AI-powered workflow that generates a comprehensive ADR 3. Automatically determine the next ADR number 4. Create the ADR file with well-researched content 5. Update the index table 6. Open a pull request for review
Option 2: Manual Creation
If you prefer to create an ADR manually:
- Copy the template:
cp docs/adr/0000-adr-template.md docs/adr/0010-example-decision.md - Use the next available 4-digit number (e.g., 0010, 0011, 0012)
- Fill in all sections with relevant information
- Update this README to add your ADR to the index
- Submit via pull request for review