---
name: adr-management
description: >
  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.
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:**
```bash
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:
```bash
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
```bash
python ./scripts/adr_manager.py list
python ./scripts/adr_manager.py list --limit 10
```

### Viewing a Specific ADR
```bash
python ./scripts/adr_manager.py get 42
```

### Searching ADRs by Keyword
```bash
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
1. **Always fill all sections**: Never leave an ADR blank. Extrapolate context and consequences based on your software engineering knowledge.
2. **Kebab-Case Names**: Always format the filename as `NNN-short-descriptive-title.md`.
3. **Reference ADRs by number** — e.g., "This builds upon the database choice outlined in ADR-003."