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.
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
Critical Constraints
- Fill All Sections: Never leave an ADR partially empty; extrapolate context, decision, consequences, and alternatives.
- Filename Convention: Always format filenames as
NNN-short-descriptive-title.md. - Status Lifecycle: Mark new records
ProposedorAccepted; mark superseded recordsSupersededwith links.
Quick start
Create a new ADR with an automatic sequential ID:
python3 scripts/adr_manager.py create "Title" --context "Context" --decision "Decision" --consequences "Consequences"
Workflow
- Scaffold Record: Run
adr_manager.py create "<Title>"to create the template file indocs/architecture/decisions/orADRs/. - Populate Content: Open the generated file and document technical context, rationale, consequences, and alternatives.
- 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:
python3 scripts/adr_manager.py list
References
- adr-template.md — Template used by
adr_manager.py create. - 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 |