npm package: @matthamlin/address
Description: A CLI for managing Architecture Decision Records (ADRs)
Author: Matt Hamlin
Latest version: 0.1.0

# Address (`ad`)

A CLI for managing Architecture Decision Records (ADRs) in your repository.

`ad` helps teams capture architectural decisions in a lightweight, git-friendly format so context does not get lost over time.

## Why Address?

- **Simple CLI workflow** for creating and evolving ADRs
- **Git-friendly storage** using JSONL in a local `.adr/` directory
- **Search + filtering** for quickly finding decisions
- **Versioned ADR updates** so decision history remains visible
- **Agent onboarding command** to append ADR guidance to `AGENTS.md` and `CLAUDE.md`

## Install

```bash
bun add @matthamlin/address
```

You can run the CLI as:

- `ad <command>` (if your shell resolves local bins)
- `bunx ad <command>` (recommended, explicit)

## Quick Start

```bash
# 1) Initialize ADR storage in the current repo
bunx ad init

# 2) Create your first ADR (interactive)
bunx ad new

# 3) List ADRs
bunx ad list

# 4) View one ADR
bunx ad show adr-1234abcd
```

## Command Reference

### `ad init`

Initialize an ADR repository in the current directory.

Creates `.adr/` with default files.

### `ad new` / `ad create`

Create an ADR.

- **Interactive mode** when running in a TTY
- **Non-interactive mode** (CI/scripts) via flags:

```bash
bunx ad new \
  --title="Use Bun for tooling" \
  --context="Need fast installs and script execution" \
  --decision="Standardize on Bun for package management and scripts" \
  --consequences="Faster CI and local workflows; requires Bun familiarity" \
  --status=accepted \
  --tags=tooling,build \
  --author="Platform Team"
```

Required in non-interactive mode:

- `--title`
- `--context`
- `--decision`
- `--consequences`

Optional:

- `--status` (`proposed|accepted|rejected|deprecated|superseded`)
- `--tags` (comma-separated)
- `--author`

### `ad list`

List ADRs, newest first.

Optional filters:

- `--status=<status>`
- `--tag=<tag>`

Examples:

```bash
bunx ad list --status=accepted
bunx ad list --tag=security
```

### `ad show <id>`

Display full ADR details including context, decision, consequences, version, timestamps, tags, and relationship fields.

### `ad update <id>`

Interactively update an ADR.

Behavior notes:

- Content/status/relationship changes increment `version`
- Tag-only updates do **not** increment `version`
- Some status-based update restrictions are enforced (for example, superseded ADRs are immutable)

### `ad delete <id>`

Delete an ADR after explicit confirmation.

### `ad search <query>`

Full-text search over ADR content (`title`, `context`, `decision`, `consequences`).

### `ad backup`

Create a snapshot backup of `.adr/adrs.jsonl`.

Backups are stored in `.adr/backups/` and rotated (up to 10 by default).

### `ad onboard`

Append ADR usage instructions to `AGENTS.md` and `CLAUDE.md` in the current directory (if present and not already documented).

Useful for making ADR workflows discoverable to AI coding agents.

### `ad help`

Show CLI help and usage summary.

## Global Options

- `--help`, `-h` — show help
- `--version` — show version

## ADR Status Values

- `proposed`
- `accepted`
- `rejected`
- `deprecated`
- `superseded`

## ADR Data Model

Each ADR includes:

- `id` (e.g. `adr-a1b2c3d4`)
- `title`
- `status`
- `context`
- `decision`
- `consequences`
- `version`
- `createdAt`
- `updatedAt`

Optional fields:

- `decidedAt`
- `tags`
- `author`
- `supersedes`
- `supersededBy`
- `relatedTo`
- `stakeholders`
- `metadata`

## Storage Layout

After `ad init`, the default structure is:

```txt
.adr/
  adrs.jsonl
  index.json
  config.json
  backups/
```

- `adrs.jsonl`: one JSON object per line (all ADRs)
- `index.json`: lookup/index metadata
- `config.json`: initialized storage config snapshot
- `backups/`: rotated backup files created by `ad backup`

## Best Practices

- Keep ADR titles short and specific
- Record trade-offs in **Consequences**, not just benefits
- Use tags for filtering (`security`, `data`, `api`, etc.)
- Prefer creating a new ADR + supersession when a decision fundamentally changes
- Commit `.adr/` to git so ADR history evolves with code history