π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ruflo-adr): one-shot import + verify scripts (v0.3.0) (#1758)
rUvcd0b66f0d41f
diff --git a/plugins/ruflo-adr/.claude-plugin/plugin.json b/plugins/ruflo-adr/.claude-plugin/plugin.jsonindex 4970514085..5619bfcfa2 100644--- a/plugins/ruflo-adr/.claude-plugin/plugin.json+++ b/plugins/ruflo-adr/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-adr","description": "ADR lifecycle management \u2014 create, index, supersede, check compliance, and link Architecture Decision Records to code via AgentDB hierarchical store + causal edges (supersedes/amends/depends-on/related)",- "version": "0.2.0",+ "version": "0.3.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-adr/scripts/import.mjs b/plugins/ruflo-adr/scripts/import.mjsnew file mode 100755index 0000000000..c89f4c8bb0--- /dev/null+++ b/plugins/ruflo-adr/scripts/import.mjs@@ -0,0 +1,273 @@+#!/usr/bin/env node+// One-shot ADR importer for the ruflo-adr plugin.+//+// Walks the working directory (or ADR_ROOT override), parses every ADR file+// under */docs/adr/ or */docs/adrs/, persists records to the `adr-patterns`+// namespace, persists causal edges to the `adr-edges` namespace, prints a+// summary with status counts + relationship breakdown + dangling-ref check.+//+// Handles two ADR formats:+// 1. v3-style: `# ADR-097: Title` heading + `**Status**: Proposed` line+// 2. plugin-style: YAML frontmatter (`status: Proposed`) at file head+//+// Usage:+// node scripts/import.mjs # markdown summary to stdout+// IMPORT_FORMAT=json node scripts/import.mjs # JSON summary+// IMPORT_DRY_RUN=1 node scripts/import.mjs # parse + summarize, skip memory_store+// ADR_ROOT=/path/to/repo node scripts/import.mjs # override scan root (default: cwd)+//+// Why a script, not raw MCP calls: 70+ ADRs Γ multiple memory_store calls each+// is hundreds of MCP round-trips. spawnSync over the CLI is materially faster+// and avoids shell-quoting pitfalls in the ADR titles.++import { readFileSync, readdirSync, statSync } from 'node:fs';+import { join, basename } from 'node:path';+import { spawnSync } from 'node:child_process';++const ROOT = process.env.ADR_ROOT || process.cwd();+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'v2', '.next', '.turbo', 'build']);++function findAdrs(dir, out = []) {+ let entries;+ try { entries = readdirSync(dir); } catch { return out; }+ for (const e of entries) {+ if (SKIP_DIRS.has(e)) continue;+ const p = join(dir, e);+ let st;+ try { st = statSync(p); } catch { continue; }+ if (st.isDirectory()) {+ findAdrs(p, out);+ } else if (e.endsWith('.md') && (p.includes('/docs/adr/') || p.includes('/docs/adrs/'))) {+ out.push(p);+ }+ }+ return out;+}++function parseAdr(path) {+ const text = readFileSync(path, 'utf-8');+ const id = parseId(path, text);+ const title = parseTitle(text);+ const status = parseStatus(text);+ const date = parseDate(text);+ const tags = parseTags(text);+ const context = parseContextFirstParagraph(text);+ const links = parseLinks(text, id);+ return { id, title, status, date, tags, context, links, file: path.replace(ROOT + '/', '') };+}++function parseId(path, text) {+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ const m = /^id:\s*(\S+)/m.exec(fm[1]);+ if (m) return m[1].toUpperCase();+ }+ const fname = basename(path, '.md');+ const m = /^(ADR-?\d+|\d{3,4})/i.exec(fname);+ if (m) {+ const raw = m[1];+ return raw.toUpperCase().startsWith('ADR') ? raw.toUpperCase().replace(/^ADR-?/, 'ADR-') : `ADR-${raw}`;+ }+ return fname;+}++function parseTitle(text) {+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ const m = /^title:\s*(.+)$/m.exec(fm[1]);+ if (m) return m[1].trim();+ }+ const m = /^#\s*(?:ADR-?\d+:?\s*)?(.+?)$/m.exec(text);+ return m ? m[1].trim() : '(untitled)';+}++function parseStatus(text) {+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ const m = /^status:\s*(.+)$/im.exec(fm[1]);+ if (m) return m[1].trim();+ }+ // Match `**Status**:` plus `**Status**:` with possible adornments.+ // Strip parenthetical qualifiers like "Proposed (v3.6.x)" -> "Proposed".+ const m = /^\*\*Status\*\*:\s*([A-Za-z][A-Za-z\- ]*?)(?:\s*\(.*?\))?\s*$/m.exec(text);+ return m ? m[1].trim() : 'Unknown';+}++function parseDate(text) {+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ const m = /^date:\s*(\S+)/m.exec(fm[1]);+ if (m) return m[1];+ }+ const m = /^\*\*Date\*\*:\s*(\S+)/m.exec(text);+ return m ? m[1] : '';+}++function parseTags(text) {+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ const m = /^tags:\s*\[([^\]]+)\]/m.exec(fm[1]);+ if (m) return m[1].split(',').map((s) => s.trim()).filter(Boolean);+ }+ const m = /^\*\*Tags\*\*:\s*(.+)$/m.exec(text);+ return m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : [];+}++function parseContextFirstParagraph(text) {+ const m = /^##\s*Context\s*$\s*([\s\S]+?)(?=^##\s|\Z)/m.exec(text);+ if (!m) return '';+ return m[1].trim().split(/\n\s*\n/)[0].replace(/\s+/g, ' ').slice(0, 400);+}++// Extract ADR-NNN references from a link line. CRITICAL: must distinguish ADR+// references from GitHub issue numbers (#1697 etc.) which the prior version+// false-positively captured as "ADR-1697". We only recognize bare numbers as+// ADR refs when they appear in a known ADR-link section AND they don't look+// like GitHub issues (no leading #, no leading "issue").+function parseLinks(text, selfId) {+ const out = [];+ // Frontmatter relationships+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);+ if (fm) {+ for (const [field, relation] of [+ ['supersedes', 'supersedes'],+ ['amended-by', 'amends'],+ ['amends', 'amends'],+ ['related', 'related'],+ ['depends-on', 'depends-on'],+ ]) {+ const re = new RegExp(`^${field}:\\s*\\[?([^\\]\\n]+)\\]?$`, 'mi');+ const m = re.exec(fm[1]);+ if (m) for (const ref of extractAdrRefs(m[1])) {+ if (relation === 'supersedes') out.push({ from: ref, to: selfId, relation });+ else out.push({ from: selfId, to: ref, relation });+ }+ }+ }+ // Body relationship lines+ const supersedes = /\*\*Supersedes\*\*:\s*(.+)$/m.exec(text);+ if (supersedes) for (const ref of extractAdrRefs(supersedes[1])) out.push({ from: ref, to: selfId, relation: 'supersedes' });+ const amended = /\*\*(?:Amended[ -]by|Amends)\*\*:\s*(.+)$/m.exec(text);+ if (amended) for (const ref of extractAdrRefs(amended[1])) out.push({ from: selfId, to: ref, relation: 'amends' });+ const related = /\*\*Related\*\*:\s*(.+)$/m.exec(text);+ if (related) for (const ref of extractAdrRefs(related[1])) out.push({ from: selfId, to: ref, relation: 'related' });+ const dependsOn = /\*\*Depends[ -]on\*\*:\s*(.+)$/m.exec(text);+ if (dependsOn) for (const ref of extractAdrRefs(dependsOn[1])) out.push({ from: selfId, to: ref, relation: 'depends-on' });+ return out;+}++function extractAdrRefs(s) {+ const refs = new Set();+ // Strip GitHub issue / commit references first to prevent false positives.+ const cleaned = s+ .replace(/#\d+/g, '') // #1697+ .replace(/issue[s]?\s*\d+/gi, '') // issue 1697+ .replace(/PR\s*\d+/gi, '') // PR 1234+ .replace(/commit\s*[`a-f0-9]+/gi, '') // commit `abc123`+ .replace(/`[^`]*`/g, ''); // any backtick-quoted span+ const re = /\bADR-?(\d+)\b/gi;+ let m;+ while ((m = re.exec(cleaned))) refs.add(`ADR-${m[1].padStart(3, '0').replace(/^0+(\d{3,})/, '$1')}`);+ return [...refs];+}++function memoryStore(namespace, key, value) {+ const r = spawnSync('npx', [+ '@claude-flow/cli@latest', 'memory', 'store',+ '--namespace', namespace,+ '--key', key,+ '--value', typeof value === 'string' ? value : JSON.stringify(value),+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });+ if (r.status !== 0) {+ if (/UNIQUE constraint/i.test(r.stderr || r.stdout || '')) return 'exists';+ return 'error: ' + (r.stderr || '').slice(0, 100);+ }+ return 'ok';+}++const dryRun = process.env.IMPORT_DRY_RUN === '1';+const fmt = process.env.IMPORT_FORMAT || 'markdown';++const files = findAdrs(ROOT);+const adrs = files.map(parseAdr);+const byId = new Map();+const allEdges = [];+for (const a of adrs) {+ byId.set(a.id, a);+ allEdges.push(...a.links);+}++let storedRecords = 0, storedEdges = 0;+const errors = [];+if (!dryRun) {+ for (const a of adrs) {+ const r = memoryStore('adr-patterns', `${a.id}::${basename(a.file, '.md')}`,+ `${a.title} β ${a.context || '(no context)'}\n\nfile: ${a.file}\nstatus: ${a.status}\ndate: ${a.date}\ntags: ${a.tags.join(',')}`);+ if (r === 'ok' || r === 'exists') storedRecords++;+ else errors.push(`${a.id} ${a.file}: ${r}`);+ }+ for (const e of allEdges) {+ const key = `${e.relation}:${e.from}->${e.to}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;+ const r = memoryStore('adr-edges', key, JSON.stringify({ ...e, capturedAt: new Date().toISOString() }));+ if (r === 'ok' || r === 'exists') storedEdges++;+ }+}++const danglingRefs = allEdges.filter((e) => !byId.has(e.to));+const supersededIds = new Set(allEdges.filter((x) => x.relation === 'supersedes').map((x) => x.from));+const statusMismatches = [];+for (const id of supersededIds) {+ const a = byId.get(id);+ if (a && !/superseded/i.test(a.status)) statusMismatches.push({ id, status: a.status, file: a.file });+}++const byStatus = {};+for (const a of adrs) {+ const k = (a.status || 'unknown').toLowerCase();+ byStatus[k] = (byStatus[k] || 0) + 1;+}+const byRelation = {};+for (const e of allEdges) byRelation[e.relation] = (byRelation[e.relation] || 0) + 1;+const bySource = {};+for (const a of adrs) {+ const src = a.file.split('/docs/')[0];+ bySource[src] = (bySource[src] || 0) + 1;+}++const result = {+ scannedRoot: ROOT,+ total: adrs.length,+ sourceDirs: Object.keys(bySource).length,+ storedRecords, storedEdges, dryRun,+ byStatus, byRelation, bySource,+ edges: allEdges.length,+ danglingRefs, statusMismatches, errors,+};++if (fmt === 'json') {+ console.log(JSON.stringify(result, null, 2));+ process.exit(0);+}++console.log('## ADR Index Summary');+console.log('');+console.log(`Total ADRs: **${result.total}** across ${result.sourceDirs} source dirs (root: ${ROOT})`);+console.log(`Records stored to \`adr-patterns\`: ${result.storedRecords}/${result.total}${dryRun ? ' (dry-run, skipped)' : ''}`);+console.log(`Edges stored to \`adr-edges\`: ${result.storedEdges}/${result.edges}${dryRun ? ' (dry-run, skipped)' : ''}`);+console.log('');+console.log('### By status');+for (const [k, n] of Object.entries(byStatus).sort((a, b) => b[1] - a[1])) console.log(`- ${k}: ${n}`);+console.log('');+console.log(`### Relationships: **${result.edges}** edges`);+for (const [k, n] of Object.entries(byRelation).sort((a, b) => b[1] - a[1])) console.log(`- ${k}: ${n}`);+console.log('');+console.log('### Issues found');+console.log(`- Dangling refs (edge β non-existent ADR): ${danglingRefs.length}`);+for (const d of danglingRefs.slice(0, 10)) console.log(` - ${d.relation} ${d.from} β ${d.to} (missing)`);+console.log(`- Status mismatches (superseded but not marked): ${statusMismatches.length}`);+for (const m of statusMismatches.slice(0, 10)) console.log(` - ${m.id} status='${m.status}' (${m.file})`);+console.log(`- Storage errors: ${errors.length}`);+for (const e of errors.slice(0, 5)) console.log(` - ${e}`);+console.log('');+console.log('### Source breakdown');+for (const [s, n] of Object.entries(bySource).sort((a, b) => b[1] - a[1]).slice(0, 12)) console.log(`- ${s}: ${n}`);diff --git a/plugins/ruflo-adr/scripts/smoke.sh b/plugins/ruflo-adr/scripts/smoke.shindex 348c31ca09..c44541c98c 100755--- a/plugins/ruflo-adr/scripts/smoke.sh+++ b/plugins/ruflo-adr/scripts/smoke.sh@@ -9,10 +9,10 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }# 1. plugin.json bump + new keywords-step "1. plugin.json declares 0.2.0 with new keywords"+step "1. plugin.json declares 0.3.0 with new keywords"v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)-if [[ "$v" != "0.2.0" ]]; then- bad "expected 0.2.0, got '$v'"+if [[ "$v" != "0.3.0" ]]; then+ bad "expected 0.3.0, got '$v'"elsemiss=""for k in lifecycle compliance causal-graph mcp; do@@ -21,10 +21,10 @@ else[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"fi-# 2. All 3 skills present with valid frontmatter-step "2. skills (adr-create, adr-index, adr-review) present with name/description/allowed-tools"+# 2. All 4 skills present with valid frontmatter+step "2. skills (adr-create, adr-index, adr-review, adr-verify) present with name/description/allowed-tools"miss=""-for s in adr-create adr-index adr-review; do+for s in adr-create adr-index adr-review adr-verify; dof="$ROOT/skills/$s/SKILL.md"[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }for k in 'name:' 'description:' 'allowed-tools:'; do@@ -85,5 +85,46 @@ for f in "$ROOT"/skills/*/SKILL.md; dodone[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"+# 11. import + verify scripts present, executable, parse cleanly+step "11. scripts/import.mjs and verify.mjs executable + syntax-clean"+miss=""+for s in import.mjs verify.mjs; do+ f="$ROOT/scripts/$s"+ [[ -x "$f" ]] || miss="$miss $s-not-executable"+ node --check "$f" 2>/dev/null || miss="$miss $s-syntax-error"+done+[[ -z "$miss" ]] && ok || bad "$miss"++# 12. import.mjs handles both ADR formats + has issue-number false-positive guard+step "12. import.mjs supports v3 + plugin formats and strips issue numbers"+F="$ROOT/scripts/import.mjs"+miss=""+grep -q "extractAdrRefs" "$F" || miss="$miss no-extractAdrRefs"+grep -q "frontmatter\|YAML\|^---" "$F" || miss="$miss no-frontmatter-handling"+grep -q "#\\\\d+\|issue\|PR\\\\s*\\\\d" "$F" || miss="$miss no-issue-strip"+grep -q '\*\*Status\*\*' "$F" || miss="$miss no-v3-status-pattern"+[[ -z "$miss" ]] && ok || bad "$miss"++# 13. verify.mjs reports cycles + dangling refs and exits 1 on cycles+step "13. verify.mjs detects cycles + has fail-closed exit"+F="$ROOT/scripts/verify.mjs"+miss=""+grep -q "cycles" "$F" || miss="$miss no-cycle-detection"+grep -q "danglingRefs" "$F" || miss="$miss no-dangling-detection"+grep -q "process.exit(1)" "$F" || miss="$miss no-fail-exit"+[[ -z "$miss" ]] && ok || bad "$miss"++# 14. adr-index skill references the script (not direct MCP loop)+step "14. adr-index skill calls scripts/import.mjs"+F="$ROOT/skills/adr-index/SKILL.md"+grep -q "scripts/import\.mjs\|import\.mjs" "$F" \+ && ok || bad "skill does not invoke import.mjs"++# 15. adr-verify skill references verify.mjs+step "15. adr-verify skill calls scripts/verify.mjs"+F="$ROOT/skills/adr-verify/SKILL.md"+grep -q "scripts/verify\.mjs\|verify\.mjs" "$F" \+ && ok || bad "skill does not invoke verify.mjs"+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"[[ $FAIL -eq 0 ]] || exit 1diff --git a/plugins/ruflo-adr/scripts/verify.mjs b/plugins/ruflo-adr/scripts/verify.mjsnew file mode 100755index 0000000000..a2cc171366--- /dev/null+++ b/plugins/ruflo-adr/scripts/verify.mjs@@ -0,0 +1,114 @@+#!/usr/bin/env node+// adr-verify β read the persisted adr-patterns + adr-edges namespaces, surface+// dangling refs, supersede cycles, and status mismatches.+//+// Companion to scripts/import.mjs. Run after import to validate graph integrity.+// Useful in CI: exits with code 1 if any issues found (gate on graph health).+//+// Usage:+// node scripts/verify.mjs # markdown report+// VERIFY_FORMAT=json node scripts/verify.mjs # JSON for chaining+// VERIFY_STRICT=1 node scripts/verify.mjs # exit 1 on ANY issue (default: only on cycles)++import { spawnSync } from 'node:child_process';++function memoryListJson(namespace) {+ const r = spawnSync('npx', [+ '@claude-flow/cli@latest', 'memory', 'list',+ '--namespace', namespace, '--format', 'json',+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });+ if (r.status !== 0) return [];+ const m = /\[[\s\S]*\]/.exec(r.stdout || '');+ if (!m) return [];+ try { return JSON.parse(m[0]); } catch { return []; }+}+function memoryRetrieve(namespace, key) {+ const r = spawnSync('npx', [+ '@claude-flow/cli@latest', 'memory', 'retrieve',+ '--namespace', namespace, '--key', key,+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });+ if (r.status !== 0) return null;+ // Strip ANSI / box-drawing+ const txt = (r.stdout || '').replace(/\x1b\[[0-9;]*m/g, '');+ return txt;+}++const patternEntries = memoryListJson('adr-patterns');+const edgeEntries = memoryListJson('adr-edges');++const adrIds = new Set(+ patternEntries.map((e) => (e.key || '').split('::')[0]).filter(Boolean)+);++// Parse edge values to recover {from, to, relation}+const edges = [];+for (const e of edgeEntries) {+ const k = e.key || '';+ // key format: relation:FROM->TO:timestamp-rand+ const m = /^(\w[\w-]*?):(\S+?)->(\S+?):/.exec(k);+ if (m) edges.push({ relation: m[1], from: m[2], to: m[3], key: k });+}++const danglingRefs = edges.filter((e) => !adrIds.has(e.to));+const danglingFroms = edges.filter((e) => !adrIds.has(e.from));++// Cycle detection on supersedes (cycle = data corruption β ADR can't supersede itself transitively)+const supersedesGraph = new Map();+for (const e of edges.filter((e) => e.relation === 'supersedes')) {+ if (!supersedesGraph.has(e.from)) supersedesGraph.set(e.from, []);+ supersedesGraph.get(e.from).push(e.to);+}+const cycles = [];+function findCycle(node, visited, stack) {+ if (stack.has(node)) {+ cycles.push([...stack, node].join(' β '));+ return;+ }+ if (visited.has(node)) return;+ visited.add(node);+ stack.add(node);+ for (const next of supersedesGraph.get(node) || []) {+ findCycle(next, visited, stack);+ }+ stack.delete(node);+}+for (const n of supersedesGraph.keys()) findCycle(n, new Set(), new Set());++const result = {+ adrCount: adrIds.size,+ edgeCount: edges.length,+ byRelation: edges.reduce((acc, e) => { acc[e.relation] = (acc[e.relation] || 0) + 1; return acc; }, {}),+ danglingRefs,+ danglingFroms,+ cycles: [...new Set(cycles)],+};++if (process.env.VERIFY_FORMAT === 'json') {+ console.log(JSON.stringify(result, null, 2));+} else {+ console.log('## ADR Graph Verification');+ console.log('');+ console.log(`| Metric | Value |`);+ console.log(`|---|---:|`);+ console.log(`| ADRs in adr-patterns | ${result.adrCount} |`);+ console.log(`| Edges in adr-edges | ${result.edgeCount} |`);+ for (const [k, n] of Object.entries(result.byRelation).sort((a, b) => b[1] - a[1])) {+ console.log(`| edges (${k}) | ${n} |`);+ }+ console.log(`| Dangling 'to' refs | ${result.danglingRefs.length} |`);+ console.log(`| Dangling 'from' refs | ${result.danglingFroms.length} |`);+ console.log(`| Supersede cycles | ${result.cycles.length} |`);+ if (result.danglingRefs.length) {+ console.log('\n### Sample dangling refs');+ for (const d of result.danglingRefs.slice(0, 8)) console.log(`- ${d.relation} ${d.from} β ${d.to} (missing)`);+ }+ if (result.cycles.length) {+ console.log('\n### Cycles (DATA CORRUPTION β fix immediately)');+ for (const c of result.cycles) console.log(`- ${c}`);+ }+}++const strict = process.env.VERIFY_STRICT === '1';+if (result.cycles.length || (strict && (result.danglingRefs.length || result.danglingFroms.length))) {+ process.exit(1);+}diff --git a/plugins/ruflo-adr/skills/adr-index/SKILL.md b/plugins/ruflo-adr/skills/adr-index/SKILL.mdindex c10553d5d8..a4a42b0f62 100644--- a/plugins/ruflo-adr/skills/adr-index/SKILL.md+++ b/plugins/ruflo-adr/skills/adr-index/SKILL.md@@ -1,66 +1,73 @@---name: adr-index-description: Build or rebuild the ADR index and dependency graph in AgentDB+description: 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)argument-hint: ""-allowed-tools: mcp__claude-flow__agentdb_hierarchical-store mcp__claude-flow__agentdb_hierarchical-query mcp__claude-flow__agentdb_causal-edge mcp__claude-flow__agentdb_causal-query mcp__claude-flow__memory_store mcp__claude-flow__memory_search Bash Read Grep Glob+allowed-tools: Bash mcp__claude-flow__memory_list mcp__claude-flow__memory_search---# ADR Index-Build or rebuild the full ADR index and dependency graph in AgentDB from the `docs/adr/` directory.+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, or when bootstrapping ADR tracking on an existing codebase that already has ADR files.+- 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. **Scan directory** -- `Glob` for `docs/adr/ADR-*.md` to find all ADR files. If no files found, report that no ADRs exist yet.--2. **Parse each ADR** -- `Read` each file and extract:- - **ID**: from the filename (e.g., `ADR-042` from `ADR-042-use-postgres.md`)- - **Title**: from the `# ADR-NNN: <Title>` heading- - **Status**: from the `**Status**:` line- - **Date**: from the `**Date**:` line- - **Tags**: from the `**Tags**:` line- - **Links**: from the `## Links` section (supersedes, amended-by, related)--3. **Store in AgentDB** -- For each ADR, call `mcp__claude-flow__agentdb_hierarchical-store` with:- - path: `adr/<adr-id>`- - value: `{ "id": "<id>", "title": "<title>", "status": "<status>", "date": "<date>", "tags": "<tags>", "file": "<filepath>" }`--4. **Build causal edges** -- For each ADR with links:- - "Supersedes ADR-XXX" -> `mcp__claude-flow__agentdb_causal-edge` with `from: ADR-XXX`, `to: <current>`, `relation: supersedes`- - "Amended by ADR-YYY" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-YYY`, `relation: amends`- - "Related: ADR-ZZZ" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-ZZZ`, `relation: related`- - "Depends on ADR-WWW" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-WWW`, `relation: depends-on`--5. **Store in memory** -- For each ADR, call `mcp__claude-flow__memory_store` with:- - namespace: `adr-patterns`- - key: `<adr-id>`- - value: `<title> β <first paragraph of Context section>`- This enables semantic search across ADRs.--6. **Verify graph** -- Call `mcp__claude-flow__agentdb_causal-query` to retrieve all edges and verify:- - No dangling references (edges pointing to non-existent ADRs)- - No circular supersedes chains- - All superseded ADRs have status "superseded"--7. **Report** -- Output a summary:+1. **Run the importer**:++ ```bash+ node plugins/ruflo-adr/scripts/import.mjs```- ## ADR Index Summary- Total ADRs: N- - Proposed: X- - Accepted: Y- - Deprecated: Z- - Superseded: W+ 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.- Relationships: M edges- - Supersedes: A- - Amends: B- - Depends-on: C- - Related: D+3. **Verify graph integrity** (optional but recommended) via the sibling `adr-verify` skill, which runs `scripts/verify.mjs` and exits 1 on cycles.- Issues found: (list any dangling refs or status mismatches)+4. **Search semantically** via `mcp__claude-flow__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, key `<relation>:<FROM>-><TO>:<timestamp-rand>`, value:++```json+{ "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" }+```++## 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`.++## 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 gatingdiff --git a/plugins/ruflo-adr/skills/adr-verify/SKILL.md b/plugins/ruflo-adr/skills/adr-verify/SKILL.mdnew file mode 100644index 0000000000..40b6afeea1--- /dev/null+++ b/plugins/ruflo-adr/skills/adr-verify/SKILL.md@@ -0,0 +1,42 @@+---+name: adr-verify+description: Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / status mismatches; exit 1 on cycles+argument-hint: ""+allowed-tools: Bash mcp__claude-flow__memory_list mcp__claude-flow__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.++## 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