How do I install the Adr Index skill?

Run npx skillmds@latest add gabrielmoreira/adr-index in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Adr Index safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Adr Index?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Adr Index free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Adr Index?

gabrielmoreira (@gabrielmoreira) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Adr Index by gabrielmoreira — Agent Skill

Name: Adr Index
Rating: 4.2 (5 reviews)
Author: gabrielmoreira

File contents

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

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)
Inspect the summary — total ADRs, stored count, by-status breakdown, edge counts, dangling refs, status mismatches.
Verify graph integrity (optional but recommended) via the sibling adr-verify skill, which runs scripts/verify.mjs and exits 1 on cycles.
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)

---name: adr-indexdescription: Build or rebuild the ADR index + dependency graph by running scripts/import.mjs (handles v3-style and plugin-style ADR formats; one Bash call vs hundreds of MCP round-trips)--- # 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**: ```bash 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: ```json { "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

Adr Index