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.

### ADR Detection Rule

If you make or rely on a decision that:
- introduces architectural constraints,
- involves trade-offs,
- or is not obvious from code alone,

you MUST pause and explicitly state:
"An ADR is required for this decision."