richfrem/adr-management
plugins/dev-utils/skills/adr-management/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add richfrem/agent-plugins-skills adr-managementInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 29, 2026, 5:46 AM102.9s8 files scanned
SKILL.md
- name:
- adr-management
- plugin:
- adr-manager
- description:
- >
- allowed-tools:
- Bash, Read, Write
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
createsubcommand. 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
.mdfile 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
ProposedorAccepted. - If a new ADR invalidates an older one, edit the older ADR's status to
Supersededand 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."
Related Skills
richfrem/issue-worktree-agent
testing
VerifiedTrustedCommunity
Skill for creating and managing isolated git worktrees (`.worktrees/issue-NNN`) for issue execution branches. USE ONLY when setting up or cleaning up isolated git worktrees for specific issue execution. DO NOT USE for managing local task files (use `task-agent`) or escalating tasks to issues (use `github-issue-backlog-agent`).
4SKILL.mdUpdated Jul 29, 2026
richfrem/issue-pr-lifecycle-agent
data-ai
VerifiedTrustedCommunity
Skill for orchestrating the end-to-end GitHub issue lifecycle flow: Issue -> Worktree -> Implementation -> PR Creation -> Resolution Closure. USE ONLY when running or dry-running full lifecycle orchestration for resolving an issue with a PR. DO NOT USE for isolated worktree management only (use `issue-worktree-agent`) or logging issues (use `github-issue-agent`).
4SKILL.mdUpdated Jul 29, 2026
richfrem/github-issue-prioritizer
tools
VerifiedTrustedCommunity
Automatically ranks GitHub issues (P0-P3) based on friction tier, frequency, and blockages, synchronizing priority labels and GitHub Projects v2 custom fields.
4SKILL.mdUpdated Jul 29, 2026
richfrem/github-issue-backlog-agent
testing
VerifiedTrustedCommunity
Bridge skill for escalating ephemeral local task scratchpad items (`tasks/*.md`) into durable, taxonomy-validated, evidence-rich GitHub Issues. USE ONLY when promoting a single-session local task into durable repository backlog. DO NOT USE for managing local kanban boards (use `task-agent` instead) or directly querying/commenting on issues (use `github-issue-agent` instead).
4SKILL.mdUpdated Jul 29, 2026