Adr

Documents

adr

Adr is an Agent Skill for documents published in the linuxfoundation/crowd.dev repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Record an architecture decision as an ADR in docs/adr/. Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning ("we decided X instead of Y because..."); or querying past decisions ("why did we choose X?").

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/linuxfoundation/crowd.dev/blob/HEAD/.claude/skills/adr/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/adr, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Architecture Decision Records

You are recording or retrieving an Architecture Decision Record (ADR) for this project. ADRs live in docs/adr/ at the repo root.

When to record

Record these decisions:

Technology selections (frameworks, libraries, databases, cloud providers)
Architectural patterns (state management, caching strategy, API design)
Data modeling choices (schema design, indexing, query approach)
Infrastructure and deployment models
Security, authentication, or testing strategy changes
Patterns in transition: any documented migration (e.g. Sequelize → pg-promise, classes → functions, multi-tenant → single tenant) is a textbook ADR candidate

Skip: trivial choices (variable naming, formatting, minor refactors).

ADR template

Every ADR file must include all of these sections:

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context
[2–5 sentences describing the situation, constraints, and forces at play]

## Decision
[1–3 sentences stating the change clearly and unambiguously]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]

## Consequences

### Positive
- [benefit 1]

### Negative
- [trade-off 1]

### Risks
- [risk and mitigation]

Workflow — recording a new ADR

Scan existing ADRs — Glob docs/adr/[0-9]*.md to find the highest existing number.
Assign next ID — next sequential 4-digit number (e.g., 0003).
Gather context — ask the user for any missing details: who the deciders were, what alternatives were seriously considered, and what the consequences are.
Draft the ADR — populate all mandatory sections from the template above.
Present the draft — show it to the user for review before writing any file.
Write the file — docs/adr/NNNN-kebab-title.md (kebab-case title, all lowercase).
Update the index — append a new row to the | ADR | Title | Status | Date | table in docs/adr/README.md.

Workflow — reading / querying ADRs

Check if docs/adr/README.md exists. If not, offer to start the ADR directory.
Read the README index table and find entries relevant to the user's question.
Read the matching ADR file and summarise the Context and Decision sections.
If no ADR matches, suggest recording one now.

Quality standards

Each ADR should be readable in under 2 minutes.
Every rejected alternative must include a Why not reason.
When a decision is superseded, update the old ADR's Status field to superseded by ADR-NNNN and create the new ADR with a back-reference in its Context.
Keep one decision per ADR.