ADR Process

CleverThis uses Architectural Decision Records (ADRs) to document significant technical decisions. An ADR captures the context of a decision, the options considered, the decision made, and the rationale. Future contributors can read ADRs to understand why the codebase looks the way it does.

ADRs live in docs/adr/ and are numbered sequentially (0001-use-fastapi.md, 0002-actor-yaml-format.md, etc.).

When to write an ADR

Write an ADR when you are making a decision that:

• Affects the public API surface (inference or A2A)
• Changes a significant component boundary (e.g. moving logic between server and cleveractors-core)
• Introduces a new dependency that will be used widely
• Adopts a new architectural pattern
• Reverses a previous decision

You do not need an ADR for routine implementation choices, bug fixes, or refactors that don't change behavior.

ADR template

# ADR-NNNN: Short title

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-MMMM

## Context

What is the situation that motivates this decision? What constraints apply?

## Options considered

### Option A: ...
Pros: ...
Cons: ...

### Option B: ...
Pros: ...
Cons: ...

## Decision

Which option was chosen and why.

## Consequences

What does this decision make easier? What does it make harder?
What follow-up work is required?

Process

1. Copy the template to docs/adr/NNNN-short-title.md (next sequential number).
2. Set status to Proposed.
3. Open a PR with the ADR and tag relevant stakeholders for review.
4. Discussion happens in the PR. Once consensus is reached, the status changes to Accepted and the PR is merged.
5. Link the ADR from the relevant architecture documentation page.

Coming soon

The full list of accepted ADRs is being added to this section.