Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot

adr-verify — Claude Code skill: ADR graph integrity check

Reads the stored ADR graph back and flags dangling references, supersede cycles and status mismatches. Useful right after adr-index or as a CI gate.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add ruvnet/ruflo --skill adr-verify -a claude-code
Open on GitHub

What adr-verify does

The skill reads back what adr-index wrote into the adr-patterns and adr-edges memory namespaces, then reports three kinds of damage: an edge pointing at an ADR ID that isn't in the graph, a supersede cycle where two ADRs replace each other, and a row where an ADR is the source of a supersedes edge but its own status never became Superseded. That last one usually means the status update was missed while the successor ADR was promoted.

One command runs the checks: node plugins/ruflo-adr/scripts/verify.mjs. The exit code is 1 only when a cycle shows up; VERIFY_STRICT=1 fails the run on any issue at all, and VERIFY_FORMAT=json swaps the markdown report for JSON. Its tools are limited to Bash and two memory calls, so it reads the graph without touching files.

A blind spot remains: an adr-patterns row for an ADR deleted from disk with no edges in either direction passes every check. So if the ADR count in the report looks higher than the files you actually have, rerun adr-reindex rather than adr-verify. There is also nothing to verify before an import, since both namespaces are what adr-index fills.

What it helps with

  • catch an edge that points at a missing ADR ID
  • find supersede cycles before a release ships
  • spot ADRs whose status was never flipped to Superseded
  • fail the CI build on any graph issue
  • feed the report into another script as JSON

Example prompts for the agent

  • Run `node plugins/ruflo-adr/scripts/verify.mjs` and show me the ADR graph report.
  • Re-run the check with `VERIFY_STRICT=1` so CI fails on any issue, not just cycles.
  • Give me `VERIFY_FORMAT=json` output and list every supersede cycle.

How to install adr-verify

1Skills CLI (Vercel)

npx skills add ruvnet/ruflo --skill adr-verify -a claude-code

2Manually: put the files in place

~/.claude/skills/adr-verify/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adr-verify/

From the same set104

The whole set →
ruflo ruvnet This skill adds multi-agent orchestration, memory, routing, and MCP tools to a project. Use it for swarm tasks and multi-step workflows. Claude Code CX Codex Cursor +1 4,000installs Swarm Orchestration ruvnet Skill for managing agent swarms with parallel execution, dynamic topology, and automatic load balancing. Use when a single agent is not enough and you need to orchestrate specialists of different types. Claude Code CX Codex Cursor +1 2,100installs github-project-management ruvnet Turns issue triage and board upkeep into gh and ruv-swarm calls: labels, subtasks, duplicate lookup. Useful when the tracker holds more tickets than order. Claude Code CX Codex Cursor +1 1,400installs github-workflow-automation ruvnet Automates GitHub Actions with AI agent coordination. Generates optimised pipelines, manages pull requests, analyzes failed runs, and deploys updates with risk assessment. Claude Code CX Codex Cursor +1 1,300installs github-code-review ruvnet Runs a swarm of specialized AI agents to inspect GitHub pull requests for security, performance, and architecture issues. Claude Code CX Codex Cursor +1 1,300installs stream-chain ruvnet Chains sequential agent steps together using streaming JSON flow and provides ready-to-run pipelines. Claude Code CX Codex Cursor +1 1,200installs flow-nexus-swarm ruvnet Deploy cloud-based AI agent swarms and define event-driven workflows with message queues. Use it to coordinate tasks, inspect runs, and scale a swarm. Claude Code CX Codex Cursor +1 1,200installs performance-analysis ruvnet Detects bottlenecks in Claude Flow swarms, profiles agent operations, and generates reports with actionable optimization recommendations. Claude Code CX Codex Cursor +1 1,200installs

Similar

skill-review sanyuan0704 Audits Claude Code skills against best practices for structure, token efficiency, and trigger quality. Delivers prioritized fixes with exact line citations. Claude Code CX Codex Cursor +1 2,200installs google-drive-automation sanjay3290 Lets an agent read and write Google Drive files through two local scripts and standalone OAuth, without an MCP server. Claude Code CX Codex Cursor +1 909installs cli-anything-inkscape HKUDS Stateful command-line interface skill for editing vector graphics in Inkscape, tracking project state in JSON, and manipulating SVG documents. Claude Code CX Codex Cursor +1 599installs godot-nodes-scenes gamedev-skills Teaches the agent to build a Godot 4.7 project from nodes and scenes: reusable .tscn files, runtime instancing, autoload singletons, and node lookups that survive renames. Claude Code CX Codex Cursor +1 6,200installs setup-matt-pocock-skills Matt Pocock This skill configures a repository for Matt Pocock's engineering skills by setting its issue tracker, triage labels, and domain docs layout. Run it before using the other skills. Claude Code 1,052,851installs to-tickets Matt Pocock Turns a plan, spec, or conversation into small end-to-end tickets with explicit blockers. Use it to agree on the work breakdown before tickets go to a tracker. Claude Code 711,230installs writing-plans Jesse Vincent This skill turns requirements for a multi-step task into an implementation plan before code changes begin. It helps when another engineer needs exact files, interfaces, and checks. Claude Code CX Codex 282,859installs stitch-loop official google-labs-code Guides agents through iterative website creation with Stitch MCP. The agent reads the baton file, generates UI, integrates the page, and prepares tasks for the next run. Claude Code CX Codex Cursor +1 56,300installs

Questions about adr-verify

How do I install adr-verify in Claude Code?

Run npx skills add ruvnet/ruflo --skill adr-verify -a claude-code. The skill lands at ~/.claude/skills/adr-verify/SKILL.md.

What does adr-verify do?

It reads the adr-patterns and adr-edges namespaces after an import and surfaces dangling refs, supersede cycles and ADRs with a stale status. A detected cycle exits with code 1.

Does adr-verify need adr-index to run first?

Yes, in practice. Both namespaces it checks are filled by adr-index, so on a fresh checkout there is nothing to read back until the import has run.

Source text

SKILL.md · MIT 
---
name: adr-verify
description: Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / Unknown statuses; exit 1 on cycles
argument-hint: ""
allowed-tools: Bash mcp__plugin_ruflo-core_ruflo__memory_list mcp__plugin_ruflo-core_ruflo__memory_retrieve
---

# ADR Verify

Companion to `adr-index`. After import, reads the persisted graph and surfaces integrity issues:

- **Dangling refs** — edge points at an ADR ID that doesn't exist in `adr-patterns`. Common cause: the referenced ADR is in a sibling repo or got deleted.
- **Supersede cycles** — `ADR-A supersedes ADR-B` and `ADR-B supersedes ADR-A` (or longer cycles). Always data corruption.
- **Status mismatches** — an ADR is the source of a `supersedes` edge but its own status isn't `Superseded`. Usually a missed status update during a successor ADR's promotion.

**What this skill cannot catch:** an `adr-patterns` row for an ADR that was deleted from disk and has zero edges referencing it or from it — invisible to every check above (issue #2666). If the reported ADR count looks higher than what's actually on disk, run `adr-reindex`, not `adr-verify` again.

## When to use

- Right after `adr-index` to confirm the graph is healthy
- In CI as a fail-closed gate (`VERIFY_STRICT=1` exits 1 on any issue)
- Before publishing an ADR-related release

## Steps

```bash
node plugins/ruflo-adr/scripts/verify.mjs
```

Optional env:
- `VERIFY_FORMAT=json` — JSON instead of markdown
- `VERIFY_STRICT=1` — exit 1 on ANY issue (default: only on cycles)

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Graph healthy (or dangling refs / status mismatches present in non-strict mode) |
| `1` | Supersede cycle detected, OR strict mode + any issue present |

## Cross-references

- `adr-index` — populates the data this skill verifies
- `scripts/import.mjs` — has its own dry-run validation; this skill is the read-back companion
- `adr-reindex` — reconciles a deleted ADR that `adr-verify` cannot detect

© ruvnet · MIT · ruvnet/ruflo

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor