richfrem/agent-plugins-skills / plugins/dev-utils/.apm/skills/managing-adrs
managing-adrs
VerifiedScaffolds, lists, searches, and manages Architecture Decision Records (ADRs) to record permanent institutional memory.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.1 KB |
| assets/templates/adr-template.md | markdown | 365 B |
| evals/evals.json | config | 633 B |
| evals/results.tsv | other | 301 B |
| references/acceptance-criteria.md | markdown | 879 B |
| scripts/adr_manager.py | script | 7.8 KB |
| scripts/next_number.py | script | 7.8 KB |
| tests/test_next_number_worktree_resolution.py | script | 3.4 KB |
SKILL.md
View on GitHub---
name: managing-adrs
plugin: dev-utils
description: Scaffolds, lists, searches, and manages Architecture Decision Records (ADRs) to record permanent institutional memory.
allowed-tools: Bash, Read, Write
---
## Dependencies
Requires Python 3.8+ (standard library only).
---
# Managing ADRs (`managing-adrs`)
Manages Architecture Decision Records to ensure significant technical and architectural choices are permanently documented.
## Contents
- [Dependencies](#dependencies)
- [Critical Constraints](#critical-constraints)
- [Quick start](#quick-start)
- [Workflow](#workflow)
- [Querying ADRs](#querying-adrs)
- [Verification](#verification)
- [References](#references)
## Critical Constraints
1. **Fill All Sections**: Never leave an ADR partially empty; extrapolate context, decision, consequences, and alternatives.
2. **Filename Convention**: Always format filenames as `NNN-short-descriptive-title.md`.
3. **Status Lifecycle**: Mark new records `Proposed` or `Accepted`; mark superseded records `Superseded` with links.
## Quick start
Create a new ADR with an automatic sequential ID:
```bash
python3 scripts/adr_manager.py create "Title" --context "Context" --decision "Decision" --consequences "Consequences"
```
## Workflow
1. **Scaffold Record**: Run `adr_manager.py create "<Title>"` to create the template file in `docs/architecture/decisions/` or `ADRs/`.
2. **Populate Content**: Open the generated file and document technical context, rationale, consequences, and alternatives.
3. **Cross-Reference**: Link related decisions by number (e.g. `ADR-003`).
## Querying ADRs
- **View Record**: `python3 scripts/adr_manager.py get <NUMBER>`
- **Search Keywords**: `python3 scripts/adr_manager.py search "<KEYWORD>"`
- **Next Number**: `python3 scripts/next_number.py --type adr`
## Verification
List existing ADRs and verify sequential indexing:
```bash
python3 scripts/adr_manager.py list
```
## References
- [adr-template.md](assets/templates/adr-template.md) — Template used by `adr_manager.py create`.
- [acceptance-criteria.md](references/acceptance-criteria.md) — Acceptance criteria for ADR scaffolding and indexing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |