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/next_number.py

View on GitHub
"""
Sequential Identifier Generator
====================================

Purpose:
    Scans artifact directories (Specs, Tasks, ADRs, Chronicles, BRs, BWs) to find
    the next available sequence number. Prevents ID collisions.

Layer: Investigate / Utils

Usage Examples:
    python ./scripts/next_number.py --type spec
    python ./scripts/next_number.py --type task

Supported Object Types:
    - None (Sequence output)

CLI Arguments:
    --type: Artifact type (spec, task, adr, chronicle, br, bw, all).
    --dir: Ad-hoc directory to scan for 4-digit numbers.

Input Files:
    - tasks/
    - ADRs/

Output:
    - Next available ID (e.g. "0045") to stdout.

Key Functions:
    get_next_number(): Returns next available number supporting gap filling.
    find_max_number(): Returns max number for artifact type.

Script Dependencies:
    os, re, sys, argparse, pathlib

Consumed by:
    - Manual workflow execution
Related:
    - None
"""
import os
import re
import subprocess
import sys
import argparse
from pathlib import Path

# Configuration: artifact types and their locations/patterns
ARTIFACT_TYPES = {
    "task": {
        "name": "Maintenance Task",
        "directory": "tasks",
        "pattern": r"^(\d{3})",
        "format": "{:03d}",
        "prefix": "",
        "search_subdirs": True  # Search backlog, in-progress, done, superseded
    },
    "spec": {
        "name": "Specification",
        "directory": "specs",
        "pattern": r"^(\d{3})",
        "format": "{:03d}",
        "prefix": "",
        "scan_type": "directory"
    },
    "adr": {
        "name": "Architecture Decision Record",
        "directory": "docs/ADRs",
        "pattern": r"^(\d{3})",
        "format": "{:03d}",
        "prefix": ""
    }
}


def find_max_number(artifact_type: str, project_root: Path) -> int:
    """Find the maximum existing number for an artifact type."""
    config = ARTIFACT_TYPES.get(artifact_type)
    if not config:
        return 0
    
    base_dir = project_root / config["directory"]
    pattern = re.compile(config["pattern"])
    max_num = 0
    
    if config.get("search_subdirs"):
        dirs_to_search = [base_dir / "backlog", base_dir / "todo", base_dir / "in-progress", base_dir / "done", base_dir / "superseded"]
    else:
        dirs_to_search = [base_dir]
    
    scan_dirs = config.get("scan_type") == "directory"

    for search_dir in dirs_to_search:
        if not search_dir.exists():
            continue
        for item in search_dir.iterdir():
            # Check for directory or file based on config
            if scan_dirs:
                is_valid = item.is_dir()
            else:
                is_valid = item.is_file() and item.suffix == ".md"

            if is_valid:
                match = pattern.match(item.name)
                if match:
                    num = int(match.group(1))
                    max_num = max(max_num, num)
    
    return max_num


def get_next_number(artifact_type: str, project_root: Path) -> str:
    """
    Get the next available number, filling gaps if they exist.
    """
    config = ARTIFACT_TYPES.get(artifact_type)
    if not config:
        raise ValueError(f"Unknown artifact type: {artifact_type}")
    
    base_dir = project_root / config["directory"]
    pattern = re.compile(config["pattern"])
    
    existing_numbers = set()
    
    if config.get("search_subdirs"):
        dirs_to_search = [base_dir / "backlog", base_dir / "todo", base_dir / "in-progress", base_dir / "done", base_dir / "superseded"]
    else:
        dirs_to_search = [base_dir]
    
    scan_dirs = config.get("scan_type") == "directory"

    for search_dir in dirs_to_search:
        if not search_dir.exists():
            continue
        for item in search_dir.iterdir():
             # Check for directory or file based on config
            if scan_dirs:
                is_valid = item.is_dir()
            else:
                is_valid = item.is_file() and item.suffix == ".md"

            if is_valid:
                match = pattern.match(item.name)
                if match:
                    existing_numbers.add(int(match.group(1)))
    
    # Find first unused number (gap filling)
    next_num = 1
    while next_num in existing_numbers:
        next_num += 1
    
    return config["format"].format(next_num)


def find_max_in_directory(directory: Path, pattern: str = r'(\d{3})', recursive: bool = True) -> int:
    """Find the maximum number in an arbitrary directory using a regex pattern."""
    if not directory.exists():
        return 0
    
    regex = re.compile(pattern)
    max_num = 0
    
    iterator = directory.rglob("*") if recursive else directory.iterdir()
    
    for file in iterator:
        if file.is_file():
            match = regex.search(file.name)
            if match:
                num = int(match.group(1))
                max_num = max(max_num, num)
    
    return max_num


def show_all(project_root: Path) -> None:
    """Show next numbers for all artifact types."""
    print("=" * 50)
    print("NEXT AVAILABLE NUMBERS")
    print("=" * 50)
    
    for type_key, config in ARTIFACT_TYPES.items():
        next_id = get_next_number(type_key, project_root)
        max_num = find_max_number(type_key, project_root)
        existing = max_num if max_num > 0 else "none"
        print(f"  {config['name']:30} : {next_id} (existing max: {existing})")


def _discover_project_root() -> Path:
    """Resolves the repo root via `git rev-parse --show-toplevel` — unlike a manual walk-up
    checking `(p / ".git").is_dir()`, this correctly resolves inside a git worktree too
    (a worktree's `.git` is a file, not a directory, so `.is_dir()` was always False there,
    silently skipping past the worktree to an unrelated ancestor or a wrong fallback)."""
    script_path = Path(__file__).resolve()
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            cwd=str(script_path.parent), capture_output=True, text=True, timeout=5
        )
        if result.returncode == 0:
            return Path(result.stdout.strip()).resolve()
    except (subprocess.SubprocessError, OSError):
        pass

    for p in [script_path] + list(script_path.parents):
        if (p / ".git").exists():
            return p
    return script_path.parents[2]


def main() -> None:
    """Parse CLI arguments and find next available number for artifact types or directories."""
    parser = argparse.ArgumentParser(
        description='Get next available number for artifact types or arbitrary directories.',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__
    )
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument('--type', '-t', 
                        choices=list(ARTIFACT_TYPES.keys()) + ['all'],
                        help='Artifact type')
    group.add_argument('--dir', '-d', help='Ad-hoc directory to scan for 4-digit numbers')
    
    parser.add_argument('--pattern', help=r'Regex pattern for --dir (default: (\d{3}))', default=r'(\d{3})')
    parser.add_argument('--recursive', action='store_true', help='Recursive scan for --dir')
    parser.add_argument('--json', action='store_true', help='Output as JSON')
    
    args = parser.parse_args()

    project_root = _discover_project_root()

    if args.type == 'all':
        show_all(project_root)
    elif args.type:
        next_num = get_next_number(args.type, project_root)
        if args.json:
            import json
            print(json.dumps({"type": args.type, "next": next_num}))
        else:
            print(next_num)
    elif args.dir:
        max_num = find_max_in_directory(Path(args.dir), args.pattern, args.recursive)
        next_num = f"{max_num + 1:04d}"
        if args.json:
            import json
            print(json.dumps({"directory": args.dir, "next": next_num}))
        else:
            print(next_num)


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