name: adr-index
description: Generate and validate the ADR index for this repo (docs/adr/*.md -> docs/adr/index.json). Use when updating ADRs, checking ADR metadata format, or keeping agent context small; enforce header/metadata rules and never append done-logs to AGENTS.md.

ADR Index

Workflow

1) Run the generator/validator:

python .codex/skills/adr-index/scripts/build_adr_index.py

2) Review the short summary output (ADR count + whether index.json changed).

ADR Rules (enforced by script)

• First line must be # ADR-YYYYMMDD-####-XXX: <title> (date, 4 digits, 3 random chars, non-empty title).
• Optional metadata lines within the first ~40 lines:
• Tags: a, b, c
• Status: Proposed | Accepted | Deprecated
• Date: YYYY-MM-DD
• TL;DR: one short sentence

Output

• Writes docs/adr/index.json with fields: id, title, tags[], status, date, tldr, path.
• Sorts by date desc, then id desc.
• Prints only a short summary line.

Guardrails

• Never append done-logs to AGENTS.md; decisions belong in ADRs.
• Ensure AGENTS.md includes the Documentation Workflow policy block below; add it if missing.

AGENTS.md Policy Block

## Documentation Workflow

The following terms are to be interpreted as described in RFC 2119:
“MUST”, “MUST NOT”, “SHOULD”, and “MAY”.

1. ADRs MUST be written in `docs/adr/*.md`.

2. When an ADR is added or modified, `docs/adr/index.json` MUST be updated accordingly.

3. The ADR index MUST be generated using the `adr-index` skill.

4. AGENTS.md MUST NOT accumulate completed work logs.
   Architectural decisions MUST be recorded in ADRs.
   AGENTS.md MAY contain only links to ADRs or brief summaries.