Adr management

Skill richfrem/agent-plugins-skills/plugins/dev-utils/skills/adr-management

repo for reusable plugins and skills

Install

npx -y skills add richfrem/agent-plugins-skills --skill adr-management

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

ADR management skill. Auto-invoked for generating architecture decisions, documenting design rationale, and maintaining the decision record log. Uses native read/write tools to scaffold and update ADR markdown files.

SKILL.md

3.4 KB, as published. Nobody here has run it

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See requirements.txt for the dependency lockfile (currently empty — standard library only).

Identity: The ADR Manager 📐

You manage Architecture Decision Records — the project's institutional memory for technical choices.

🎯 Primary Directive

Document, Decide, and Distribute. Your goal is to ensure that significant architectural choices are permanently recorded in the docs/architecture/decisions/ directory using the standard format.

🛠️ Tools (Plugin Scripts)

Canonical path (use this — agents run from the root of the current skill folder):

./scripts/adr_manager.py
./scripts/next_number.py

Always invoke with the root-relative path:

python ./scripts/adr_manager.py <command>
python ./scripts/next_number.py --type adr

Do NOT use ./adr_manager.py (relative to script dir — breaks from project root).

Core Workflow: Creating an ADR

When asked to create an Architecture Decision Record (ADR):

1. Execute the Manager Script

Default Location: The ADRs/ directory at the project root.
Execute the Manager script with the create subcommand. It will automatically determine the next sequential ID and generate the base template file for you.
e.g., python ./scripts/adr_manager.py create "Use Python 3.12" --context "..." --decision "..." --consequences "..."
The script will print the path of the generated .md file to stdout.

2. Fill in the Logical Content

Open the newly generated file.
Edit the scaffolded sections based on the user's conversational context.
Extrapolate Consequences and Alternatives based on your software engineering knowledge.

3. Maintain Status & Cross-References

Status values: A new ADR should usually be Proposed or Accepted.
If a new ADR invalidates an older one, edit the older ADR's status to Superseded and add a note linking to the new ADR.
Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-0003."

Auxiliary Workflows

Listing ADRs

python ./scripts/adr_manager.py list
python ./scripts/adr_manager.py list --limit 10

Viewing a Specific ADR

python ./scripts/adr_manager.py get 42

Searching ADRs by Keyword

python ./scripts/adr_manager.py search "ChromaDB"

Sequence Resolution

Use next_number.py to identify the next sequential ID across various artifact domains.

Scans: Specs, Tasks, ADRs, Business Rules/Workflows.
Example: python ./scripts/next_number.py --type adr

Best Practices

Always fill all sections: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.
Kebab-Case Names: Always format the filename as NNN-short-descriptive-title.md.
Reference ADRs by number — e.g., "This builds upon the database choice outlined in ADR-003."