Skip to content

richfrem/agent-plugins-skills / plugins/dev-utils/.apm/skills/managing-adrs

managing-adrs

Verified

Scaffolds, lists, searches, and manages Architecture Decision Records (ADRs) to record permanent institutional memory.

scripts/adr_manager.py

View on GitHub
#!/usr/bin/env python
"""
adr_manager.py — Architecture Decision Record Manager
======================================================

Purpose:
    Create, list, search, and view ADRs. Uses next_number.py for
    auto-incrementing IDs and the ADR template for scaffolding.

Layer: 
    Plugin / ADR-Manager

Usage Examples:
    python./scripts/adr_manager.py create "Title" --context "..." --decision "..." --consequences "..."
    python./scripts/adr_manager.py list [--limit N]
    python./scripts/adr_manager.py get N
    python./scripts/adr_manager.py search "query"

Supported Object Types:
    - Architecture Decision Records (ADR)

CLI Arguments:
    create <title>          Create a new ADR with specified metadata fields
    list [--limit <N>]      List existing ADRs with optional result count limit
    get <number>            View a specific ADR fully by its numeric ID
    search <query>          Search ADR bodies using exact matching keywords

Key Input Dependencies:
    - templates/adr-template.md

Output:
    - ADRs/<NNN>_<title>.md

Key Functions:
    create_adr(title, ...)  Scaffolds a new decision log using auto-increment IDs
    list_adrs()             Renders index list ordered ascending by serial ID
    get_adr(n)              Loads detailed record for exact matched record ID

Script Dependencies:
    - next_number.py (sibling script helper indexer)

Consumed by:
    - ADR Management Skill orchestration workflows
"""

import os
import sys
import re
import argparse
from pathlib import Path
from datetime import datetime

SCRIPT_DIR = Path(__file__).parent.resolve()
PLUGIN_ROOT = SCRIPT_DIR.parent  # scripts/ → skill root (managing-adrs/)

# Import next_number from sibling script
sys.path.insert(0, str(SCRIPT_DIR))
try:
    from next_number import get_next_number, ARTIFACT_TYPES
except ImportError:
    print("❌ next_number.py not found in plugin scripts/")
    sys.exit(1)


def _find_project_root() -> Path:
    """Walk up from PLUGIN_ROOT to find the project root."""
    p = PLUGIN_ROOT
    for _ in range(10):
        if (p / ".git").exists() or (p / ".agent").exists():
            return p
        p = p.parent
    return Path.cwd()

def _find_adr_dir(project_root: Path) -> Path:
    """Auto-detects the project's ADR directory convention: prefers docs/ADRs/
    if it already exists (matches next_number.py's ARTIFACT_TYPES["adr"]["directory"]),
    otherwise falls back to a bare ADRs/ at the project root — so this tool works
    correctly whichever convention the target project already uses."""
    docs_adrs = project_root / "docs" / "ADRs"
    if docs_adrs.exists():
        return docs_adrs
    return project_root / "ADRs"

PROJECT_ROOT = _find_project_root()
ADR_DIR = _find_adr_dir(PROJECT_ROOT)
TEMPLATE_PATH = PLUGIN_ROOT / "assets" / "templates" / "adr-template.md"


def create_adr(title: str, context: str = "", decision: str = "", 
               consequences: str = "", alternatives: str = "", status: str = "Proposed") -> Path:
    """Create a new ADR from template."""
    ADR_DIR.mkdir(parents=True, exist_ok=True)

    next_num = get_next_number("adr", PROJECT_ROOT)
    filename = f"{next_num}_{title.lower().replace(' ', '_').replace('-', '_')}.md"
    filepath = ADR_DIR / filename

    # Load template
    if TEMPLATE_PATH.exists():
        content = TEMPLATE_PATH.read_text(encoding='utf-8')
    else:
        content = "# ADR-NNNN: [Title]\n\n## Status\n[Status]\n\n## Context\n[Context]\n\n## Decision\n[Decision]\n\n## Consequences\n[Consequences]\n\n## Alternatives Considered\n[Alternatives]\n"

    # Fill template
    content = content.replace("NNNN", next_num)
    content = content.replace("[Title]", title)
    content = content.replace("[Proposed | Accepted | Deprecated | Superseded]", status)
    content = content.replace("[What is the issue or situation that needs to be addressed?]", context or "TBD")
    content = content.replace("[What is the change that we're proposing and/or doing?]", decision or "TBD")
    content = content.replace("[What becomes easier or harder as a result of this decision?]", consequences or "TBD")
    content = content.replace("[What other options were evaluated?]", alternatives or "N/A")

    filepath.write_text(content, encoding='utf-8')
    print(f"✅ Created ADR-{next_num}: {title}")
    print(f"   Path: {filepath}")
    return filepath


def list_adrs(limit: int | None = None) -> None:
    """List ADRs sorted by number."""
    if not ADR_DIR.exists():
        print("📂 No ADRs directory found.")
        return

    adrs = sorted([f for f in ADR_DIR.iterdir() if f.suffix == '.md'], key=lambda f: f.name)
    if limit:
        adrs = adrs[-limit:]

    if not adrs:
        print("📂 No ADRs found.")
        return

    print(f"\n📋 Architecture Decision Records ({len(adrs)}):\n")
    for adr in adrs:
        # Extract title from first line
        try:
            first_line = adr.read_text(encoding='utf-8').split('\n')[0]
            title = first_line.lstrip('# ').strip()
        except:
            title = adr.stem
        print(f"  {adr.name:40} {title}")


def get_adr(number: int) -> None:
    """Get a specific ADR by number."""
    if not ADR_DIR.exists():
        print("❌ No ADRs directory.")
        return

    pattern = re.compile(rf"^{number:03d}")
    for f in ADR_DIR.iterdir():
        if f.suffix == '.md' and pattern.match(f.name):
            print(f.read_text(encoding='utf-8'))
            return
    print(f"❌ ADR-{number:03d} not found.")


def search_adrs(query: str) -> None:
    """Search ADRs by keyword."""
    if not ADR_DIR.exists():
        print("📂 No ADRs directory.")
        return

    query_lower = query.lower()
    results = []
    for f in sorted(ADR_DIR.iterdir()):
        if f.suffix != '.md':
            continue
        try:
            content = f.read_text(encoding='utf-8')
            if query_lower in content.lower():
                first_line = content.split('\n')[0].lstrip('# ').strip()
                results.append((f.name, first_line))
        except:
            continue

    if not results:
        print(f"❌ No ADRs matching '{query}'")
    else:
        print(f"\n🔍 {len(results)} ADR(s) matching '{query}':\n")
        for name, title in results:
            print(f"  {name:40} {title}")


def main() -> None:
    """Parse CLI arguments and execute ADR management commands (create, list, get)."""
    parser = argparse.ArgumentParser(description="Architecture Decision Record Manager")
    subparsers = parser.add_subparsers(dest="command")

    create_p = subparsers.add_parser("create", help="Create new ADR")
    create_p.add_argument("title", help="ADR title")
    create_p.add_argument("--context", default="", help="Context/problem statement")
    create_p.add_argument("--decision", default="", help="Decision made")
    create_p.add_argument("--consequences", default="", help="Consequences")
    create_p.add_argument("--alternatives", default="", help="Alternatives considered")
    create_p.add_argument("--status", default="Proposed", help="Status (default: Proposed)")

    list_p = subparsers.add_parser("list", help="List ADRs")
    list_p.add_argument("--limit", type=int, help="Show only last N ADRs")

    get_p = subparsers.add_parser("get", help="View specific ADR")
    get_p.add_argument("number", type=int, help="ADR number")

    search_p = subparsers.add_parser("search", help="Search ADRs by keyword")
    search_p.add_argument("query", help="Search query")

    args = parser.parse_args()

    if not args.command:
        parser.print_help()
        return

    if args.command == "create":
        create_adr(args.title, args.context, args.decision, args.consequences, args.alternatives, args.status)
    elif args.command == "list":
        list_adrs(args.limit)
    elif args.command == "get":
        get_adr(args.number)
    elif args.command == "search":
        search_adrs(args.query)


if __name__ == "__main__":
    main()
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall