adr-index

ADR Index

Persists every ADR under */docs/adr/ or */docs/adrs/ to the adr-patterns namespace and every relationship (supersedes / amends / related / depends-on) to adr-edges. Handles both ADR formats found in the Ruflo monorepo:

• v3-style: # ADR-097: Title heading + **Status**: Proposed line
• plugin-style: YAML frontmatter (id: ADR-NNNN, status: Proposed)

Implementation is in scripts/import.mjs (one Bash call) rather than dozens of per-ADR MCP tool calls — same effective behavior, materially faster, dual-format-aware, and false-positive-resistant for issue numbers.

When to use

• After importing ADRs from another project
• When the AgentDB graph is out of sync with the on-disk ADR files
• Bootstrapping ADR tracking on an existing codebase

Steps

1. Run the importer:

   node plugins/ruflo-adr/scripts/import.mjs
   

   Optional env:

   • IMPORT_FORMAT=json — emit JSON instead of markdown
   • IMPORT_DRY_RUN=1 — parse + summarize, skip persistence
   • ADR_ROOT=/path — scan a different root (default: cwd)

2. Inspect the summary — total ADRs, stored count, by-status breakdown, edge counts, dangling refs, status mismatches.

3. Verify graph integrity (optional but recommended) via the sibling adr-verify skill, which runs scripts/verify.mjs and exits 1 on cycles.

4. Search semantically via mcp__plugin_ruflo-core_ruflo__memory_search against the populated namespace:

   memory_search --query "federation budget" --namespace adr-patterns
   

Storage shape

adr-patterns namespace, key <ADR-id>::<basename>, value (text):

<title> — <first paragraph of Context>

file: <relative path>
status: <Proposed|Accepted|Superseded|...>
date: <ISO date>
tags: <comma-separated>

adr-edges namespace, deterministic key <relation>:<FROM>-><TO>, value:

{ "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" }

Both ADR records and relationship edges are stored with explicit upsert semantics. Re-running adr-index refreshes changed metadata in place and does not create duplicate copies of an unchanged semantic edge.

False-positive guard

#1697 / commit abc123 / PR 1234 references inside ADR bodies are stripped before regex extraction so they don't get misread as ADR-1697 etc. See extractAdrRefs() in scripts/import.mjs.

What this skill cannot do

adr-index only ever adds/upserts. If an ADR file was deleted (or a relation line removed from a surviving file), the row it wrote stays forever — adr-verify won't catch it either, since an orphan has no dangling ref and forms no cycle. Use the sibling adr-reindex skill to reconcile a deletion (issue #2666).

Cross-references

• adr-create — produces the ADR files this skill consumes
• adr-review — runs over adr-patterns for compliance checks
• adr-verify (sibling skill) — runs scripts/verify.mjs for graph-integrity gating
• adr-reindex (sibling skill) — drop-and-rebuild reconcile for a deleted ADR file (this skill can only add, never remove)