Add Architecture Decision Record (ADR) system with AI-powered automation (#212)

Copilot · tschm · claude · web-flow · commit 20da56511ecc · 2026-02-21T10:52:55.000+04:00
* Initial plan

* Add Architecture Decision Records (ADR) system to project

Co-authored-by: tschm &lt;2046079+tschm@users.noreply.github.com&gt;

* Clarify ADR naming conventions and use consistent examples

Co-authored-by: tschm &lt;2046079+tschm@users.noreply.github.com&gt;

* Add AI-powered ADR creation workflow and make adr command

- Create .github/workflows/adr-create.md agentic workflow
- Add `make adr` command for easy ADR creation
- Update docs/adr/README.md with workflow instructions
- Update main README.md to mention make adr
- Fix review comment: use consistent example filename

Co-authored-by: tschm &lt;2046079+tschm@users.noreply.github.com&gt;

* Fix gh-aw compilation error: remove unsupported create-pr safe-output

The create-pr safe-output is not supported in the current gh-aw version.
Since the workflow already has contents:write and pull-requests:write
permissions, it can create PRs directly without needing safe-outputs.

Co-authored-by: tschm &lt;2046079+tschm@users.noreply.github.com&gt;

* Fix invalid 'contents' toolset in adr-create.md agent workflow

'contents' is not a valid gh-aw toolset; 'repos' already covers
reading and writing repository files.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* Fix adr-create.md: use safe-outputs for PR creation instead of write permissions

Strict mode disallows 'contents: write'; replace with 'contents: read'
and 'safe-outputs: create-pull-request:' as required by gh-aw.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

---------

Signed-off-by: Thomas Schmelzer &lt;thomas.schmelzer@gmail.com&gt;
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: tschm &lt;2046079+tschm@users.noreply.github.com&gt;
Co-authored-by: Thomas Schmelzer &lt;thomas.schmelzer@gmail.com&gt;
Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/adr-create.md b/.github/workflows/adr-create.md
@@ -0,0 +1,192 @@
+---
+on:
+  workflow_dispatch:
+    inputs:
+      title:
+        description: "ADR title (e.g., 'Use PostgreSQL for data storage')"
+        required: true
+        type: string
+      context:
+        description: "Brief context or problem statement (optional)"
+        required: false
+        type: string
+
+description: "Create a new Architecture Decision Record (ADR) with AI assistance"
+
+engine: copilot
+
+permissions:
+  contents: read
+
+tools:
+  github:
+    toolsets: [repos, pull_requests]
+
+safe-outputs:
+  create-pull-request:
+
+network:
+  allowed:
+    - defaults
+
+timeout-minutes: 10
+---
+
+# Create Architecture Decision Record (ADR)
+
+You are tasked with creating a new Architecture Decision Record (ADR) for the Rhiza project.
+
+## Input Parameters
+
+- **Title**: {{ inputs.title }}
+- **Context** (if provided): {{ inputs.context }}
+
+## Project Context
+
+This is a Rhiza-based Python project that maintains ADRs in `docs/adr/`. The ADR system follows these conventions:
+
+- **Location**: `docs/adr/` directory
+- **Naming**: Files use 4-digit sequential numbering: `XXXX-title-with-hyphens.md` (e.g., `0002-use-postgresql.md`)
+- **Template**: `docs/adr/0000-adr-template.md` defines the standard format
+- **Index**: `docs/adr/README.md` maintains a table of all ADRs
+
+### ADR Format
+
+Each ADR must include:
+
+1. **Title**: `# [NUMBER]. [TITLE]` (e.g., `# 2. Use PostgreSQL for Data Storage`)
+2. **Date**: Current date in `YYYY-MM-DD` format
+3. **Status**: `Proposed` (default for new ADRs)
+4. **Context**: Why is this decision needed? What problem are we solving?
+5. **Decision**: What approach are we taking?
+6. **Consequences**: What becomes easier or harder? (Positive, Neutral, Negative)
+
+## Instructions
+
+### Step 1: Determine ADR Number
+
+1. Read `docs/adr/README.md` to find the current ADR index table
+2. Identify the highest numbered ADR
+3. Use the next sequential 4-digit number (e.g., if latest is 0001, use 0002)
+
+### Step 2: Create Filename Slug
+
+Convert the title to a filename-friendly slug:
+- Convert to lowercase
+- Replace spaces with hyphens
+- Remove special characters
+- Example: "Use PostgreSQL for Data Storage" → "use-postgresql-for-data-storage"
+
+### Step 3: Generate ADR Content
+
+Create a comprehensive ADR with the following:
+
+**Context Section**:
+- If context was provided in inputs, use it as a starting point
+- Expand with research about:
+  - Why this decision is needed for Rhiza
+  - What problem or requirement motivates it
+  - Current state and limitations (if applicable)
+- Be specific and thorough (3-5 paragraphs)
+
+**Decision Section**:
+- Clearly state what is being decided
+- Explain the approach or solution
+- Include key technical details
+- List alternatives considered (if applicable)
+- Be concrete and actionable
+
+**Consequences Section**:
+Analyze and document:
+- **Positive**: Benefits, improvements, what becomes easier
+- **Neutral**: Trade-offs, things that change but aren't clearly better/worse
+- **Negative**: Costs, limitations, what becomes harder
+
+Each section should have 2-4 bullet points with substantive detail.
+
+### Step 4: Create the ADR File
+
+1. Copy the template: `docs/adr/0000-adr-template.md` → `docs/adr/XXXX-slug.md`
+2. Replace all template placeholders with actual content:
+   - `[NUMBER]` → actual number
+   - `[TITLE]` → actual title
+   - `[YYYY-MM-DD]` → current date
+   - `[Proposed | ...]` → `Proposed`
+   - Fill in Context, Decision, and Consequences sections
+3. Ensure all sections are complete and well-written
+
+### Step 5: Update the Index
+
+Edit `docs/adr/README.md`:
+1. Add a new row to the ADR Index table:
+   ```
+   | [XXXX](XXXX-slug.md) | Title | Proposed | YYYY-MM-DD |
+   ```
+2. Insert it in numerical order (usually at the end)
+3. Keep table formatting aligned
+
+### Step 6: Create Pull Request
+
+1. Create a new branch: `adr/XXXX-slug`
+2. Commit both files with message: `Add ADR-XXXX: [Title]`
+3. Create a pull request with:
+   - **Title**: `ADR: [Title]`
+   - **Description**: Brief summary of the ADR and request for review
+   - **Labels**: `documentation`, `adr`
+
+## Guidelines
+
+- **Be thorough**: ADRs are permanent records. Make them comprehensive.
+- **Research context**: If the input context is brief, research the topic to provide fuller context.
+- **Consider alternatives**: Mention other approaches that were or could be considered.
+- **Be honest about trade-offs**: Document both benefits and costs.
+- **Use professional tone**: Clear, factual, objective writing.
+- **Follow template exactly**: Don't add or remove sections from the standard format.
+
+## Example ADR Structure
+
+```markdown
+# 2. Use PostgreSQL for Data Storage
+
+Date: 2026-02-21
+
+## Status
+
+Proposed
+
+## Context
+
+Rhiza currently stores all configuration data in YAML files. As the system grows...
+[3-5 paragraphs explaining the problem and motivation]
+
+## Decision
+
+We will adopt PostgreSQL as the primary data store for Rhiza configuration data...
+[2-4 paragraphs detailing the decision and approach]
+
+## Consequences
+
+### Positive
+
+- **Improved query capabilities**: PostgreSQL enables complex queries...
+- **Better concurrency**: ACID transactions prevent data corruption...
+- **Scalability**: Can handle larger datasets...
+
+### Neutral
+
+- **Operational complexity**: Requires PostgreSQL installation...
+- **Learning curve**: Team needs to learn SQL...
+
+### Negative
+
+- **Migration effort**: Existing YAML data must be migrated...
+- **Infrastructure dependency**: Requires database server...
+```
+
+## Success Criteria
+
+- ADR file created with next sequential number
+- All template sections filled with substantial, thoughtful content
+- Index updated with new ADR entry
+- Pull request created for review
+- Files follow naming conventions exactly
diff --git a/Makefile b/Makefile
@@ -11,3 +11,36 @@ include .rhiza/rhiza.mk
 
 # Optional: developer-local extensions (not committed)
 -include local.mk
+
+## Custom targets
+
+.PHONY: adr
+adr: install-gh-aw ## Create a new Architecture Decision Record (ADR) using AI assistance
+	@echo "Creating a new ADR..."
+	@echo "This will trigger the adr-create workflow."
+	@echo ""
+	@read -p "Enter ADR title (e.g., 'Use PostgreSQL for data storage'): " title; \
+	echo ""; \
+	read -p "Enter brief context (optional, press Enter to skip): " context; \
+	echo ""; \
+	if [ -z "$$title" ]; then \
+		echo "Error: Title is required"; \
+		exit 1; \
+	fi; \
+	if [ -z "$$context" ]; then \
+		gh workflow run adr-create.md -f title="$$title"; \
+	else \
+		gh workflow run adr-create.md -f title="$$title" -f context="$$context"; \
+	fi; \
+	echo ""; \
+	echo "✅ ADR creation workflow triggered!"; \
+	echo ""; \
+	echo "The workflow will:"; \
+	echo "  1. Generate the next ADR number"; \
+	echo "  2. Create a comprehensive ADR document"; \
+	echo "  3. Update the ADR index"; \
+	echo "  4. Open a pull request for review"; \
+	echo ""; \
+	echo "Check workflow status: gh run list --workflow=adr-create.md"; \
+	echo "View latest run: gh run view"
+
diff --git a/README.md b/README.md
@@ -116,7 +116,22 @@ make install
 
 ## ✨ What You Get
 
-### Core Features
+## 📝 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)
+
+**Create a new ADR**: Use `make adr` to create a new ADR with AI assistance. The workflow will generate a comprehensive ADR document, update the index, and create a pull request for review.
+
+For more information about the ADR format and how to create new records, see the [ADR README](docs/adr/README.md).
+
+## 📁 Available Templates
 
 - 🚀 **CI/CD Templates** - Ready-to-use GitHub Actions and GitLab CI workflows
 - 🧪 **Testing Framework** - Comprehensive test setup with pytest
diff --git a/docs/adr/0000-adr-template.md b/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?
diff --git a/docs/adr/0001-use-architecture-decision-records.md b/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.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,57 @@
+# 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
+
+### Option 1: Using AI Assistance (Recommended)
+
+The easiest way to create a new ADR is using the automated workflow:
+
+```bash
+make adr
+```
+
+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:
+
+1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-example-decision.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)
