ADR-014's 'One Ruflo' model has no concept of Claude Code plugin installs — 'Your stack' will always undercount for plugin-only users

[sparkling]

Summary

stack-sync.mjs (which powers the "Your stack" card, ADR-013) only ever scans the global npm library for installed rUv packages. This is not an oversight in the code — it faithfully implements ADR-014 ("The One-Ruflo Reconciliation," Status: Proposed)'s stated target architecture. But that ADR's own model of "how rUv tools reach a machine" has no concept of Claude Code plugins at all, which means any user who installs ruflo/ruvnet-brain/etc. via the Claude Code plugin marketplace (rather than npm install -g) will see a permanently incomplete "Your stack" card, no matter how faithfully ADR-014 gets implemented.

Grounding

docs/adr/0014-one-ruflo-reconciliation.md's North Star:

ONE global Ruflo. A project initializes ONCE, from the global instance, and that init stands up AgentDB with EVERYTHING on... and nothing on the machine fights it.

Target table, L0/L1:

L0 Packages — One global copy per package. Updated by ONE nightly job (stack-sync)... npx never used for rUv packages.
L1 MCP — Every scope launches ruflo MCP from the global binary. Zero npx-launched MCP servers.

The ADR's own "what is actually on the machine" inventory table has rows for Packages, npx producers, Hooks, Memory stores, Learning layers — no row for Claude Code plugins. The document's entire reconciliation is between "one global npm install" vs. "npx shadow copies." A marketplace-installed plugin is a third, structurally different installation path the ADR never models.

stack-sync.mjs:106-119, listInstalled():

function listInstalled() {
  const out = [];
  const scan = (dir, scope = '') => { ... };
  scan(GLOBAL_LIB);   // the ONLY thing ever scanned
  return out.sort(...);
}

Reproduce

On a machine that installs ruflo/ruvnet-brain/etc. purely as Claude Code plugins (no global npm install of the CLI packages at all):

$ npm ls -g --depth=0
├── @metaharness/darwin@0.8.0
├── agentic-qe@3.12.2
└── ... (7 other unrelated global packages — no ruflo, no ruvector, no agentdb)

$ ls ~/.claude/plugins/cache/
ruflo/  ruvnet-brain/  ... (fully installed, actively driving every session's MCP tools)

"Your stack" reports 2 packages (whichever of the 9 real global packages happen to match the FAMILY regex). The user has the full rUv toolkit, actively in use — the card just can't see it, because plugins were never part of what "installed" means in ADR-014's model.

For contrast: a reference screenshot from a machine using the global-npm-install setup style ADR-014 actually targets shows 39 packages including ruflo, RuVector, AgentDB, AI Defence — all genuinely npm install -g'd there. That's not a bug on that machine; it's just a different (and, per ADR-014, the intended) setup style than a plugin-only user has.

Why it matters

The Claude Code plugin marketplace is a first-class, actively-maintained way to distribute ruflo, ruvnet-brain, and the rest of this ecosystem — arguably the lower-friction onboarding path for a new Claude Code user compared to manually npm install -g-ing every CLI. A console whose headline "Your stack" card can only ever see one of these two legitimate paths will systematically undersell itself to exactly the audience most likely to have arrived via the plugin route.

Suggested direction

Not prescribing the fix, but the shape: ADR-014 (or a follow-up ADR, since -014 is still Proposed and gated per-phase) should explicitly add "Claude Code plugin" as a third row in its installation-mechanism inventory, with its own reconciliation story (a plugin has its own version/update cadence via the marketplace, separate from npm semver). stack-sync.mjs's listInstalled() would then also scan ~/.claude/plugins/cache/ (or wherever the active plugin manifest lives) alongside GLOBAL_LIB, reporting plugin-sourced tools distinctly from npm-global ones rather than conflating or ignoring either.

Environment

• ruvnet-brain v3.3.0
• ADR referenced: docs/adr/0014-one-ruflo-reconciliation.md (Proposed, 2026-07-14)

[stuinfla]

🤖 Automated issue-fix run (issue-fix.mjs) — a human reviews before anything merges.

Verified the claim — it's accurate. scripts/stack-sync.mjs:122-135 (listInstalled()) only calls scan(GLOBAL_LIB), the resolved npm global node_modules tree; there is no code path scanning Claude Code plugin installs anywhere in the repo. gatherStack() (scripts/onboarding-console.mjs:701-717), which backs the console's /api/stack endpoint and the "Your stack" card, goes through auditModel() → listInstalled(), so it inherits the exact blind spot described. ADR-014's inventory table and L0–L5 target architecture (docs/adr/0014-one-ruflo-reconciliation.md) have no row for Claude Code plugins, matching the report.

Why I'm not attempting a code fix here. I pulled the real plugin registry on this machine (~/.claude/plugins/installed_plugins.json) to see what a fix would actually have to handle, and it's more than "scan a second directory":

• It contains 22 separate ruflo-*@ruflo entries (ruflo-core, ruflo-browser, ruflo-swarm, ruflo-adr, ruflo-sparc, …) plus ruview@ruview — each its own plugin manifest — against one npm-global ruflo row. A literal per-entry scan would either wildly overcount relative to npm's one-row-per-package model, or silently need a grouping/aggregation design (collapse the 22 slices into one "ruflo" family row? show them as sub-items? de-dup against an existing npm-global ruflo if both are present?) that doesn't exist anywhere in this codebase yet.
• Plugin entries version via marketplace git-commit-sha or a marketplace-assigned string (installed_plugins.json's version field is sometimes semver, sometimes a bare commit-ish), not npm dist-tags — so stack-sync.mjs's BEHIND/CURRENT/AHEAD comparator (cmpVersion/isBehind), the core purpose of the file, has no defined meaning for a plugin row without new semantics someone needs to design.
• There's already narrow, working prior art for reading this same file: readInstallChannel() in scripts/onboarding-console.mjs:617-632 reads installed_plugins.json, but only for one hardcoded plugin (ruvnet-brain@ruvnet-brain), for the Trust & Provenance card's own provenance check — it isn't a general "list family plugins" utility.

The issue itself flags this precisely: "Not prescribing the fix... with its own reconciliation story (a plugin has its own version/update cadence via the marketplace, separate from npm semver)." That reconciliation story — grouping/aggregation rule, dedup-vs-npm rule, and what "current" even means for a plugin — is a product/design decision, and both governing docs (ADR-013 for the console, ADR-014 for the stack model) are explicitly Status: Proposed, with ADR-014 stating "NOTHING in Phases 1–5 executes without an explicit per-phase go." Inventing that design unilaterally in an unattended patch risks shipping something a reviewer has to redesign anyway, so I'm leaving the code untouched.

What a human should decide next:

1. Grouping: does each ruflo-*@ruflo plugin count as its own "stack" row, or should same-marketplace entries collapse into one family row (matching the npm-package granularity)?
2. Dedup: when a family (e.g. ruflo) is present via both npm-global and a plugin, is that "2 copies" (a duplicate to flag, echoing the existing npx-shadow detection) or two legitimately different install mechanisms to show side-by-side?
3. Currency: should plugin rows get a BEHIND/CURRENT/AHEAD classification at all, or should they be presence-only (like findShadows()'s reporting today), given they don't use npm semver?
4. Where this lives: a third row in ADR-014's inventory table (as suggested) plus a corresponding stack-sync.mjs scan, or a lighter-weight addition scoped only to the console's read model (gatherStack()) without touching ADR-014's npm-reconciliation phases at all.

No code changes made on this branch.

[sparkling]

Patch: detect Claude Code plugin installs alongside npm packages

Implemented and verified live (screenshot below shows real output: 35 plugins detected, versions and scope correct, alongside the existing 2 npm packages). Reads the same manifest Claude Code itself maintains (~/.claude/plugins/installed_plugins.json), so it can never drift from what's actually active — no separate directory-scanning heuristic to keep in sync.

scripts/stack-sync.mjs — new export, listInstalledPlugins()

// ADR-014's "One Ruflo" model — and listInstalled() above — only ever considered global npm
// installs vs npx shadows. Neither has any concept of Claude Code PLUGIN installs (ruflo,
// ruvnet-brain, etc. via the marketplace), a third, equally real installation path. A user whose
// whole rUv toolkit arrived this way sees "2 packages" and nothing else, even with a full,
// actively-running plugin roster. This reads the same manifest Claude Code itself maintains
// (~/.claude/plugins/installed_plugins.json), so it can never drift from what's actually active.
const PLUGIN_MANIFEST = path.join(HOME, '.claude/plugins/installed_plugins.json');
const PLUGIN_FAMILY = /^(ruflo(-[\w-]+)?|ruvnet-brain|ruvector)$/;
export function listInstalledPlugins() {
  let manifest;
  try { manifest = JSON.parse(fs.readFileSync(PLUGIN_MANIFEST, 'utf8')); } catch { return []; }
  const out = [];
  for (const [key, entries] of Object.entries(manifest.plugins || {})) {
    const [name, marketplace] = key.split('@');
    if (!PLUGIN_FAMILY.test(name)) continue;
    // Prefer the user (global) scope — same "one global copy" spirit as ADR-014's npm target —
    // falling back to project scope if that's the only place it's installed.
    const pick = entries.find((e) => e.scope === 'user') || entries[0];
    if (pick) out.push({ name, marketplace, version: pick.version, scope: pick.scope });
  }
  return out.sort((a, b) => a.name.localeCompare(b.name));
}

scripts/onboarding-console.mjs — wire it into gatherStack()

import { auditModel, installedVersion, listInstalledPlugins } from './stack-sync.mjs';
...
// reported separately from `packages` — a plugin has its own version/update cadence via the
// marketplace, distinct from npm semver, never conflated with it.
const plugins = listInstalledPlugins();
const result = { error: a.error, packages: rows, shadows, plugins, summary, recommendations };

console/app.js — a distinct section in the "Your stack" card, never merged into the npm package list

const plugins = Array.isArray(data.plugins) ? data.plugins : [];
...
if (plugins.length) {
  main.push(el('aside', { class: 'shadows' },
    el('p', { class: 'shadows-title' }, 'Claude Code plugins', chip(`${fmtInt(plugins.length)} installed`, 'green')),
    el('p', { class: 'shadows-sub' },
      'A separate install path from the npm packages above — installed via the plugin marketplace, not ',
      el('code', {}, 'npm install -g'), '. Each has its own version, tracked by Claude Code itself.'),
    ...plugins.map((p) => el('div', { class: 'shadow-row' },
      el('span', { class: 'shadow-name' }, p.name),
      el('span', { class: 'shadow-vers' }, `v${p.version}`, p.scope === 'project' ? ' · this project' : ' · every project'),
    ))));
}

Verified live

$ curl -s http://127.0.0.1:7411/api/stack | python3 -c "import json,sys; d=json.load(sys.stdin); print('packages:', len(d['packages'])); print('plugins:', len(d['plugins']))"
packages: 2
plugins: 35

And in the rendered "Your stack" card: a new "Claude Code plugins — 35 installed" section appears directly below the npm package list and the npx-shadow section, listing every ruflo-*/ruvnet-brain/ruvector plugin with its real version and scope (every project for user-scope, this project for project-scope) — reusing the existing .shadows/.shadow-row styles already used for the npx-shadow section, so it's visually consistent with the rest of the card rather than a bolted-on addition.

What this intentionally does NOT do

Per the issue's "suggested direction," this reports plugins as their own category rather than trying to merge them into the npm packages list or claim version parity with npm semver — a plugin's version is whatever the marketplace ships, tracked entirely by Claude Code's own installed_plugins.json, and conflating the two would misrepresent how either one actually gets updated. This also doesn't touch ADR-014 itself (still Proposed, still gated per-phase) — that's a design-doc update for whoever owns it, not something to fold into a code patch.

[sparkling]

Revised per the automated review's design questions

Thanks for the careful review — it correctly identified two real gaps in my first patch. Fixed both; the third point (currency) was already handled the way the review itself concluded was right.

1. Grouping (fixed). Plugins now group by marketplace, exactly matching the npm-family granularity (groupFamilies()'s own pattern) instead of 35 flat rows. On this machine: one "ruflo (plugin)" row (34 parts) + one "ruvnet-brain (plugin)" row (1 pkg), each expandable to its individual plugin table — visually and structurally identical to how @ruvector/* collapses into one "RuVector" row above it.

2. Dedup (fixed). Before rendering, the npm family names already shown above (groupFamilies(pkgs)) are compared case-insensitively against each plugin marketplace name. If a marketplace name matches an existing npm family (e.g. a machine with both a global ruflo package AND ruflo-* plugins), that row gets an amber "also installed via npm — 2 install paths" chip instead of green "installed," plus an inline note naming both paths and leaving the decision to the user — never auto-resolved, never silently double-counted.

3. Currency — unchanged, and confirmed already correct. Plugin rows still show a plain "installed" chip, never a fabricated BEHIND/CURRENT/AHEAD — matching the review's own conclusion that plugin versions (marketplace git-sha or ad-hoc string) have no defined meaning against cmpVersion()'s npm-semver comparator.

Diff (console/app.js, renderStack())

if (plugins.length) {
  const npmFamilyNames = new Set(groupFamilies(pkgs).map((f) => f.name.toLowerCase()));
  const pluginGroups = new Map();
  for (const p of plugins) {
    if (!pluginGroups.has(p.marketplace)) pluginGroups.set(p.marketplace, []);
    pluginGroups.get(p.marketplace).push(p);
  }
  for (const [marketplace, items] of [...pluginGroups].sort((a, b) => a[0].localeCompare(b[0]))) {
    const dup = npmFamilyNames.has(marketplace.toLowerCase());
    main.push(el('details', { class: 'fam' },
      el('summary', { class: 'fam-sum' },
        el('span', { class: 'fam-name' }, `${marketplace} (plugin)`),
        el('span', { class: 'fam-what' }, 'marketplace-installed, not npm'),
        el('span', { class: 'fam-status' },
          dup
            ? chip('also installed via npm — 2 install paths', 'warn')
            : chip('installed', 'green'),
          el('span', { class: 'fam-count' }, items.length > 1 ? `${items.length} parts` : '1 pkg')),
        el('span', { class: 'fam-chev', 'aria-hidden': 'true' }, '›')),
      el('div', { class: 'fam-body' },
        dup ? el('p', { class: 'impact-note' },
          `"${marketplace}" is present both as a global npm package (above) and as ${items.length} Claude Code plugin(s) — two separate install paths for what may be the same tool. Neither is removed automatically; decide which one you actually want.`) : null,
        el('div', { class: 'scroll-x' },
          el('table', { class: 'tb' },
            el('thead', {}, /* Plugin / Version / Scope / State */),
            el('tbody', {}, items.map((p) => /* one row per plugin */)))))));
  }
}

Verified live

Grouped output on this machine (no dedup case here — ruflo/ruvnet-brain aren't npm-global on this machine, so both rows correctly show green "installed", not the amber dup chip):

ruflo (plugin)        marketplace-installed, not npm   [installed]  34 parts  ›
ruvnet-brain (plugin) marketplace-installed, not npm   [installed]  1 pkg     ›

Expanding "ruflo (plugin)" shows all 34 sub-plugins (ruflo-adr 0.4.1, ruflo-agent 0.2.1, ruflo-agentdb 0.3.1, …) in the same table shape as an npm family's sub-package table. Didn't have a real both-paths machine to test the dedup chip against, but the comparison logic is a plain case-insensitive set lookup against data already computed for the npm section, not new detection machinery.

Still not touching ADR-013/014 (both Proposed) or proposing this as the final design — just correcting my own patch's gaps against the review's specific findings.

[stuinfla]

@sparkling — genuinely sharp catch, and you framed it exactly right: the Claude Code plugin marketplace is a third, structurally-different install path that ADR-014's whole "one global npm install vs npx shadows" model never accounted for — and it penalized precisely the audience most likely to arrive that way (the lowest-friction onboarding path).

Fixed in c46d288 (v3.4.8-dev):

• stack-sync.mjs now scans the Claude Code plugin cache (installed_plugins.json) alongside the global npm lib, tags each tool source: npm-global | plugin, and classifies plugins as CURRENT so they're never reported "not installed" or nagged as behind npm — they track marketplace cadence, not npm semver.
• On this machine, "Your stack" went from 39 (npm-only) to 73 — the 34 plugin-sourced tools that were invisible are now first-class, with a plugin pill in the console.
• ADR-0014 gains the third install-mechanism row you suggested; new unit test tests/unit/stack-plugins.test.mjs covers plugin detection.

Your issue also triggered something bigger — it made us audit the whole product for the same "assumes one setup / one machine" blind spot, which surfaced (and we fixed) several more instances. Thank you; this made the product materially better for the plugin-first majority. 🙏