New to Claude Skills? Learn how to install them →

Get Claude Skills
ruvnet on GitHub

ADR Index

Free

Efficiently manage your ADRs and dependency graphs.

by ruvnet67.6k stars on ruvnet/ruflo
1 views
Updated Aug 10, 2026
Get this skill

Free · Opens the source repo

What ADR Index does

The ADR Index skill is designed to streamline the management of Architectural Decision Records (ADRs) within your projects. By utilizing a single Bash command, this skill allows you to import and rebuild the ADR index and dependency graph, significantly reducing the overhead associated with multiple tool calls. It supports both v3-style and plugin-style ADR formats, ensuring compatibility with various existing records in your codebase. This dual-format awareness helps maintain the integrity and usability of your ADRs while providing a faster and more efficient workflow.

When you run the import.mjs script, the skill processes ADRs located in specified directories, capturing their relationships such as supersedes, amends, and dependencies. Each ADR is stored in the adr-patterns namespace, and relationships are recorded in the adr-edges namespace, which allows for easy querying and retrieval of information. The skill also includes features to inspect the summary of imported ADRs, verify graph integrity, and search semantically, making it a comprehensive tool for managing architectural decisions.

This skill is particularly useful for teams that are integrating ADRs from other projects or those who need to bootstrap ADR tracking on existing codebases. It is also beneficial when the AgentDB graph is out of sync with the ADR files on disk. By ensuring that all ADRs and their relationships are accurately represented, teams can make informed architectural decisions based on a clear understanding of their project's history and dependencies.

However, it's important to note that the ADR Index skill only adds or updates records; it does not remove them. If an ADR or its relationships are deleted from the source, the skill will not reflect that change unless the adr-reindex skill is used. Users should be aware of this limitation when managing their ADRs to avoid confusion over stale records.

When to use it

Use this skill when importing ADRs from another project or when needing to sync the AgentDB graph with the current ADR files.

When not to use it

Avoid using this skill if you require the ability to remove ADRs or their relationships, as it only supports adding and updating records.

What you can build with it

Importing ADRs from another project

Quickly import ADRs from an external codebase to maintain consistency in architectural decisions.

Syncing ADRs with AgentDB

Ensure that the ADR records in your project are up to date with the current state of the AgentDB.

Bootstrapping ADR tracking

Easily set up ADR tracking on an existing codebase to improve documentation and decision-making.

How to install ADR Index

View source

1. Install with the skills CLI

npx skills add ruvnet/ruflo/adr-index --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by ruvnet

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)

Frequently asked questions about ADR Index

Similar skills

Markdown to HTML Conversion

Efficiently convert Markdown documents to HTML.

Code Tour

Create structured walkthroughs for codebases.

Acquire Codebase Knowledge

Streamline onboarding with comprehensive codebase documentation.

Documentation & Modernization

Streamline codebase documentation and modernization planning.

Azure Resource Visualizer

Generate architecture diagrams for Azure resources.

CLAUDE.md Improver

Optimize your CLAUDE.md files for better project context.