architecture-decision-records is agent-read markdown (skill) from yeaight7/agent-powerups: Use when a significant architectural choice is being finalized, revisited, or reversed -- technology selection, structural patterns, or trade-offs that future maintainers or agents might unknowingly undo..
Indexed from public GitHub and served as immutable, content-addressed versions. Install it pinned to an exact SHA-256 with the mdr CLI, and every file is verified against the hash recorded here before it reaches your agent. The deterministic audit below grades the latest version, and the same file always earns the same grade.
What the file says
## Purpose
Code tells you *how* a system works. ADRs tell you *why* it works that way, preventing future maintainers (and AI agents) from suggesting "improvements" that were already tried and discarded.
## When to Use
- Finalizing a major design decision (e.g., "Choosing Postgres over MongoDB", "Using custom event bus over Redis")
- Reversing or superseding a previous decision
- A reviewer or agent proposes a change that contradicts an existing constraint
## Inputs
- The decision, the alternatives considered, and the constraints that drove it
- The ADR directory (conventionally docs/adr/)
## Workflow
1. **Check for an existing ADR first** — the decision may already be recorded or superseded:
```bash
ls docs/adr/ # existing records
rg -ln "<topic keyword>" docs/adr/ # is this decision already covered?
```
2. **Create the record** at `docs/adr/YYYY-MM-DD-<short-title>.md` — date-prefixed for ordering, kebab-case title.
3. **Fill the structure** — keep it under 300 words; focus on constraints, not theory:
```markdown
# <Decision title>
## Status
Accepted | Superseded by <newer ADR filename>
## Context
…
Pin to a label to follow the author's releases, or to a sha256 to freeze the exact bytes forever. Either way the resolved hash is written to mdr.lock, and mdr install reproduces it on any machine.
GET https://markdownregistry.com/api/v1/artifacts/art_6u6xuhhj6fosaa35
GET https://markdownregistry.com/api/v1/resolve?ref=yeaight7/agent-powerups/architecture-decision-records
GET https://markdownregistry.com/api/v1/blob/7c9bdbe0b4faf0b5e50bd7fb63d76bc72462ca1941ddf780554cbd58a6388f55
Your agent does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
yeaight7/agent-powerups · plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md · Use when evaluating prompts, LLM outputs, red-team suites, or model behavior with local eval configs and safe…
yeaight7/agent-powerups · plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md · Use when creating or reviewing red-team eval plugins, attack templates, grader rubrics, safety fixtures, or model-risk…
yeaight7/agent-powerups · plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md · Use when designing, running, debugging, or hardening deterministic eval suites for agent skills, prompts, tool…
yeaight7/agent-powerups · plugins/agentic-systems/skills/agent-harness-design/SKILL.md · Use when designing tool definitions for a new agent or subagent, an agent shows high retry rates, ambiguous tool…
yeaight7/agent-powerups · plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md · Use when routing a prompt to a local provider CLI for a second opinion, review, or plan -- you are about to call a…
sickn33/agentic-awesome-skills · plugins/agentic-awesome-skills-claude/skills/architecture-decision-records/SKILL.md · Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the…
wshobson/agents · plugins/documentation-generation/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
dicklesworthstone/pi_agent_rust · tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
hashgraph-online/awesome-codex-plugins · plugins/Colin4k1024/tsp/skills/architecture-decision-records/SKILL.md · Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments…
rudycity/superagent · .agents/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
amey-thakur/ai-skills · skills/architecture/architecture-decision-records/SKILL.md · Capture each significant architecture decision as a short, immutable record of context, decision, and consequences with…
yeaight7/agent-powerups · plugins/documentation-systems/skills/architecture-decision-records/SKILL.md · Use when a significant architectural choice is being finalized, revisited, or reversed -- technology selection…
