mcpField
A
adr-index

adr-index

github.com/ruvnetDevelopment80.0k737 installsUpdated today
Repository

About adr-index

adr-index is a skill that stores repository ADR files and their relationships. It is for bootstrapping ADR tracking or bringing graph data in line with files, and recognizes two ADR formats used in the Ruflo monorepo while supporting dry runs and semantic search.

Key features

  1. 01Scan ADR files
  2. 02Parse two ADR formats
  3. 03Store ADRs and relationship edges
  4. 04Refresh records without duplicate edges
  5. 05Summarize statuses and dangling references
  6. 06Support dry runs and JSON output

Use cases

  1. 01Import ADRs from another project
  2. 02Fix drift between the AgentDB graph and files
  3. 03Bootstrap ADR tracking in an existing codebase
  4. 04Search imported ADRs semantically by topic

MCP support

The skill uses MCP memory_search for semantic search in the adr-patterns namespace; its import script persists ADR records and relationships.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ruvnet/ruflo --skill adr-index

After installing, type/adr-indexin Claude Code to confirm it loaded.

Details

From the project README

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)

Comments

Markdown supported