claude-flow 3.50.0 → 3.51.0

package/.claude/proven-config.json

@@ -1,5 +1,5 @@
 {
-  "adoptedAt": 1790898945808,
+  "adoptedAt": 1790916839199,
   "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
   "manifest": {
     "schema": "ruflo.proven-config/v1",

package/.claude/settings.json

@@ -5,7 +5,8 @@
   "env": {
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
     "CLAUDE_FLOW_V3_ENABLED": "true",
-    "CLAUDE_FLOW_HOOKS_ENABLED": "true"
+    "CLAUDE_FLOW_HOOKS_ENABLED": "true",
+    "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1"
   },
   "permissions": {
     "allow": [
@@ -280,5 +281,13 @@
   },
   "enabledMcpjsonServers": [
     "claude-flow"
-  ]
+  ],
+  "enabledPlugins": {
+    "ruflo-mods@ruflo": true,
+    "ruflo-swarm@ruflo": true,
+    "ruflo-console@ruflo": true
+  },
+  "extraKnownMarketplaces": {
+    "ruflo": { "source": { "source": "github", "repo": "ruvnet/ruflo" } }
+  }
 }

package/.claude-plugin/marketplace.json

@@ -225,6 +225,11 @@
       "name": "ruflo-ruos",
       "source": "./plugins/ruflo-ruos",
       "description": "Run ruflo swarm agents on your own ruOS cloud desktops via the tenant-authenticated fleet MCP or per-tenant SSH; optional, removable"
+    },
+    {
+      "name": "ruflo-console",
+      "source": "./plugins/ruflo-console",
+      "description": "Early access: ruflo's cockpit as a Claude Code mod (function hooks) and the one /ruflo command for every ruflo mod \u2014 overview with health alerts, swarm topology, claims flow, federation map, plugin health, learning pipeline, MetaHarness radar, memory, cost gauge, agent timeline, approvals and events; a command palette for confirm-gated actions through the ruflo CLI; auto-opens where it docks; no network by default"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.50.0",
+  "version": "3.51.0",
   "workspaces": [
     "v3/@claude-flow/codex",
     "v3/@claude-flow/mcp",

package/v3/@claude-flow/cli/README.md

@@ -16,8 +16,6 @@
 
 # Ruflo
 
-[English](README.md) · [简体中文](README.zh-CN.md)
-
 **An agent meta-harness for Claude Code and Codex.**
 
 [![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 1,
-  "generation": 7,
-  "generatedAt": "2026-10-02T00:19:27.102Z",
-  "gitSha": "27982983",
+  "generation": 6,
+  "generatedAt": "2026-09-17T21:28:47.530Z",
+  "gitSha": "702d1461",
   "catalog": {
-    "agents": 176,
+    "agents": 167,
     "tools": 418,
     "skills": 34
   },

package/v3/@claude-flow/cli/dist/src/commands/catalog.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `ruflo catalog` — ADR-406 P0/P1 command inventory and canonical catalog.
+ *
+ * Interim home: ADR-406 §14 places these under `ruflo mods catalog`, but
+ * `commands/mods.ts` belongs to the install-fix lane (PR #3612) until it
+ * merges. This file moves there as a follow-up; the operations stay the same.
+ *
+ *   catalog generate [--check]   inventory + engine probe + deterministic catalog
+ *   catalog verify [--file]      schema, duplicate ids/names, digest parity
+ *   catalog engine               engine capability report only
+ *
+ * Reads command files; writes only the catalog and engine report under
+ * src/mods/command-registry/. Never touches a command file.
+ */
+import type { Command } from '../types.js';
+export declare const catalogCommand: Command;
+export default catalogCommand;
+//# sourceMappingURL=catalog.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/catalog.js

@@ -0,0 +1,89 @@
+/**
+ * `ruflo catalog` — ADR-406 P0/P1 command inventory and canonical catalog.
+ *
+ * Interim home: ADR-406 §14 places these under `ruflo mods catalog`, but
+ * `commands/mods.ts` belongs to the install-fix lane (PR #3612) until it
+ * merges. This file moves there as a follow-up; the operations stay the same.
+ *
+ *   catalog generate [--check]   inventory + engine probe + deterministic catalog
+ *   catalog verify [--file]      schema, duplicate ids/names, digest parity
+ *   catalog engine               engine capability report only
+ *
+ * Reads command files; writes only the catalog and engine report under
+ * src/mods/command-registry/. Never touches a command file.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { output } from '../output.js';
+import { CATALOG_RELATIVE_PATH, ENGINE_REPORT_RELATIVE_PATH, generate, serializeCatalog, summarize, verifyCatalog, writeCatalog, } from '../mods/command-registry/index.js';
+import { canonicalJson, sha256Hex } from '../mods/command-registry/index.js';
+import { writeFileSync } from 'node:fs';
+function engineFrom(flags) {
+    const explicit = typeof flags.engine === 'string' ? flags.engine : undefined;
+    const candidate = explicit ?? join(homedir(), '.local', 'bin', 'claude');
+    return existsSync(candidate) ? candidate : null;
+}
+function finish(data, ok, json, text) {
+    if (json)
+        output.writeln(JSON.stringify(data, null, 2));
+    else
+        output.writeln(text);
+    return { success: ok, exitCode: ok ? 0 : 1, data };
+}
+export const catalogCommand = {
+    name: 'catalog',
+    description: 'ADR-406 command inventory and canonical command catalog (generate, verify, engine report)',
+    options: [
+        { name: 'repo-root', type: 'string', description: 'Repository root (default: cwd)' },
+        { name: 'engine', type: 'string', description: 'Claude Code executable to probe (default ~/.local/bin/claude)' },
+        { name: 'check', type: 'boolean', description: 'generate: compare with the committed catalog instead of writing' },
+        { name: 'file', type: 'string', description: 'verify: catalog file to verify' },
+        { name: 'json', type: 'boolean', description: 'Machine-readable output' },
+    ],
+    examples: [
+        { command: 'ruflo catalog generate', description: 'Regenerate the catalog and engine report' },
+        { command: 'ruflo catalog generate --check', description: 'Fail if the committed catalog is stale' },
+        { command: 'ruflo catalog verify --file catalog.generated.json', description: 'Verify a copied catalog (parity)' },
+    ],
+    async action(ctx) {
+        const flags = ctx.flags;
+        const op = ctx.args[0] ?? 'generate';
+        const json = flags.json === true;
+        const root = resolve(String(flags.repoRoot ?? ctx.cwd ?? process.cwd()));
+        try {
+            if (op === 'verify') {
+                const file = resolve(String(flags.file ?? join(root, CATALOG_RELATIVE_PATH)));
+                const result = verifyCatalog(JSON.parse(readFileSync(file, 'utf8')));
+                return finish({ file, ...result }, result.valid, json, result.valid ? `catalog valid: ${file}` : `catalog INVALID:\n${result.errors.join('\n')}`);
+            }
+            if (op !== 'generate' && op !== 'engine') {
+                return finish({ error: `unknown operation ${op}` }, false, json, `unknown operation: ${op} (generate | verify | engine)`);
+            }
+            const result = generate({ repoRoot: root, engineExecutable: engineFrom(flags) });
+            if (op === 'engine')
+                return finish(result.engine, true, json, JSON.stringify(result.engine, null, 2));
+            const catalogPath = join(root, CATALOG_RELATIVE_PATH);
+            const summary = summarize(result);
+            if (flags.check === true) {
+                const committed = existsSync(catalogPath) ? readFileSync(catalogPath, 'utf8') : '';
+                const fresh = serializeCatalog(result.catalog);
+                const same = committed === fresh;
+                return finish({ catalogPath, upToDate: same, summary }, same, json, same ? 'catalog up to date' : `catalog is stale: run \`ruflo catalog generate\` (${catalogPath})`);
+            }
+            const previous = existsSync(catalogPath) ? sha256Hex(readFileSync(catalogPath)) : null;
+            const write = writeCatalog(catalogPath, result.catalog, previous);
+            // The engine report is host evidence (engine build, binary digest), kept
+            // beside the catalog but outside its digest, which must stay host-free.
+            writeFileSync(join(root, ENGINE_REPORT_RELATIVE_PATH), `${JSON.stringify(JSON.parse(canonicalJson(result.engine)), null, 2)}\n`);
+            return finish({ catalogPath, written: write.written, sha256: write.sha256, summary }, true, json, `${write.written ? 'wrote' : 'unchanged'} ${catalogPath}\n${JSON.stringify(summary, null, 2)}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            output.printError(message);
+            return { success: false, exitCode: 1, message };
+        }
+    },
+};
+export default catalogCommand;
+//# sourceMappingURL=catalog.js.map

package/v3/@claude-flow/cli/dist/src/commands/doctor.js

@@ -2308,15 +2308,20 @@ async function checkMetaharness() {
 }
 // ADR-404 — ruflo as a Claude Code mod (function hooks, early access). One
 // line in a bare `doctor`: whether the mod is enabled, can load (function
-// hooks on, not refused by allowManagedModsOnly) and has started; never a
-// failure, since the classic hooks are the default and the fallback.
-// `ruflo mods doctor` prints every finding.
+// hooks on, not refused by allowManagedModsOnly) and has started. Only an
+// opted-in project whose plugin Claude Code cannot resolve (stale ruflo
+// marketplace clone, nothing installed) fails: the classic hooks still run,
+// but the opt-in silently does nothing. `ruflo mods doctor` prints every finding.
 async function checkMods() {
     const { probeMods } = await import('../mods/probe.js');
     const findings = probeMods({ projectRoot: process.cwd() });
     const enabled = findings.find((f) => f.name === 'ruflo-mods plugin')?.status === 'pass';
     if (!enabled)
         return { name: 'ruflo mods (ADR-404)', status: 'pass', message: 'not enabled; classic hooks handle every event' };
+    const failures = findings.filter((f) => f.status === 'fail');
+    if (failures.length > 0) {
+        return { name: 'ruflo mods (ADR-404)', status: 'fail', message: failures.map((f) => `${f.name}: ${f.message}`).join('; '), fix: failures[0].fix ?? 'ruflo mods doctor' };
+    }
     const warnings = findings.filter((f) => f.status !== 'pass');
     return warnings.length === 0
         ? { name: 'ruflo mods (ADR-404)', status: 'pass', message: findings.find((f) => f.name === 'last mod start')?.message ?? 'enabled' }

package/v3/@claude-flow/cli/dist/src/commands/index.js

@@ -90,6 +90,9 @@ const commandLoaders = {
     spinner: () => import('./spinner.js'),
     // ruflo as a Claude Code mod: function hooks, early access (ADR-404)
     mods: () => import('./mods.js'),
+    // ADR-406 command catalog and mission control (interim homes until mods.ts follow-up)
+    catalog: () => import('./catalog.js'),
+    mission: () => import('./mission.js'),
     // Ruflo entries in Claude Code's companyAnnouncements startup rotation (ADR-319)
     announcements: () => import('./announcements.js'),
     // AGNTCY/Outshift runtime transport selection (ADR-324 §2) — optional,

package/v3/@claude-flow/cli/dist/src/commands/init.js

@@ -775,17 +775,18 @@ const initClaudeAction = async (ctx) => {
                 output.writeln(output.warning('  Embedding initialization skipped (run manually)'));
             }
         }
-        // ADR-404 — opt into the Claude Code mod path. Additive: the classic
-        // hooks just written stay the default and the fallback.
-        if (ctx.flags.mods === true) {
+        // ADR-404 (amended: mods default-on in init) — enable the ruflo mod
+        // plugins in the committed .claude/settings.json, then install them with
+        // claude. Additive: the classic hooks just written stay the fallback.
+        // --no-mods opts out; --no-plugin-install writes settings only.
+        if (ctx.flags.mods !== false) {
             output.writeln();
             try {
-                const { installMod } = await import('../mods/install.js');
-                const installed = installMod(ctx.cwd, 'local');
-                output.writeln(output.success(`  ✓ ruflo-mods enabled in ${installed.settingsFile} (early access; run "ruflo mods doctor")`));
+                const { applyMods } = await import('../mods/apply.js');
+                await applyMods(ctx.cwd, { scope: 'project', pluginInstall: ctx.flags.pluginInstall !== false && ctx.flags['plugin-install'] !== false, skipInTestEnv: true });
             }
             catch (err) {
-                output.writeln(output.warning(`  ruflo-mods not enabled: ${err instanceof Error ? err.message : String(err)}`));
+                output.writeln(output.warning(`  ruflo mods not enabled: ${err instanceof Error ? err.message : String(err)}`));
             }
         }
         if (!startDaemon && !startAll) {
@@ -1062,6 +1063,17 @@ const wizardCommand = {
                     output.printInfo(`  ... and ${result.warnings.length - 5} more`);
                 }
             }
+            // ADR-404 amendment — the wizard enables the mods as `ruflo init` does.
+            if (ctx.flags.mods !== false) {
+                output.writeln();
+                try {
+                    const { applyMods } = await import('../mods/apply.js');
+                    await applyMods(ctx.cwd, { scope: 'project', pluginInstall: ctx.flags.pluginInstall !== false && ctx.flags['plugin-install'] !== false, skipInTestEnv: true });
+                }
+                catch (err) {
+                    output.writeln(output.warning(`  ruflo mods not enabled: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            }
             // Initialize embeddings if enabled
             let embeddingsInitialized = false;
             if (enableEmbeddings) {
@@ -1322,14 +1334,27 @@ const upgradeCommand = {
         {
             name: 'settings',
             short: 's',
-            description: 'Merge new settings (Agent Teams, hooks) into existing settings.json',
+            description: 'Merge new settings (Agent Teams, hooks, ruflo mods) into existing settings.json',
             type: 'boolean',
             default: false,
         },
+        {
+            // ADR-404 amendment — the same merge + plugin install as `ruflo init`.
+            name: 'mods',
+            description: 'Merge the ruflo mod plugins into .claude/settings.json and install them (also implied by --add-missing and --settings; --no-mods to skip)',
+            type: 'boolean',
+        },
+        {
+            name: 'plugin-install',
+            description: 'With mods: run claude plugin install (--no-plugin-install to merge settings only)',
+            type: 'boolean',
+            default: true,
+        },
     ],
     action: async (ctx) => {
         const addMissing = (ctx.flags['add-missing'] || ctx.flags.addMissing);
         const upgradeSettings = (ctx.flags.settings);
+        const upgradeMods = ctx.flags.mods === true || (ctx.flags.mods !== false && (addMissing || upgradeSettings));
         output.writeln();
         output.writeln(output.bold('Upgrading RuFlo'));
         if (addMissing && upgradeSettings) {
@@ -1363,6 +1388,14 @@ const upgradeCommand = {
             }
             spinner.succeed('Upgrade complete!');
             output.writeln();
+            // ADR-404 amendment — merge the mod plugins without clobbering: only
+            // keys that are absent are added, and each is reported.
+            if (upgradeMods) {
+                const { applyMods, describeAdded } = await import('../mods/apply.js');
+                const mods = await applyMods(ctx.cwd, { scope: 'project', pluginInstall: ctx.flags.pluginInstall !== false && ctx.flags['plugin-install'] !== false, skipInTestEnv: true });
+                result.settingsUpdated = [...(result.settingsUpdated ?? []), ...describeAdded(mods.install.added)];
+                output.writeln();
+            }
             // Show what was updated
             if (result.updated.length > 0) {
                 output.printBox(result.updated.map(f => `✓ ${f}`).join('\n'), 'Updated (latest version)');
@@ -1514,11 +1547,17 @@ export const initCommand = {
             default: false,
         },
         {
-            // ADR-404 — Claude Code function hooks are early access; opt-in only.
+            // ADR-404 amendment — on by default; nothing loads where function hooks are off.
             name: 'mods',
-            description: 'Also enable the ruflo Claude Code mod (function hooks, early access); classic hooks stay as fallback',
+            description: 'Enable the ruflo mod plugins in .claude/settings.json (default on; --no-mods to skip); classic hooks stay as fallback',
             type: 'boolean',
-            default: false,
+            default: true,
+        },
+        {
+            name: 'plugin-install',
+            description: 'With mods: refresh the ruflo marketplace and claude plugin install the mods (--no-plugin-install to write settings only)',
+            type: 'boolean',
+            default: true,
         },
         {
             name: 'with-embeddings',

package/v3/@claude-flow/cli/dist/src/commands/mission.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `ruflo mission` — ADR-406 §19.7 mission operations from the CLI.
+ *
+ *   mission create  --objective <text> [--request-id <id>]
+ *   mission plan    --mission <id> --expected-revision <n> --plan-file <json> [--request-id <id>]
+ *   mission get     [--mission <id>]
+ *   mission events  --mission <id> [--after <seq>] [--limit <n>]
+ *   mission action  --mission <id> --expected-revision <n> --action <requestAuthorization|pause|cancel|admit|resume> [--reason <text>]
+ *
+ * Flags map one-to-one onto the raw input the MCP tools receive; the shared
+ * `MissionService` validates both. Output is JSON. A missing request id gets a
+ * fresh one: a new id is a new intentional request (ADR-406 §9); pass the same
+ * id to retry the same request safely.
+ */
+import type { Command } from '../types.js';
+import type { MissionPort } from '../mcp-tools/mission-tools.js';
+export type MissionPortFactoryCli = (projectRoot: string) => MissionPort;
+/** Test seam (London school): substitute the service the command talks to. */
+export declare function setMissionPortFactory(next: MissionPortFactoryCli | null): void;
+/** Raw operation input from flags; undefined fields are dropped so defaults apply. */
+export declare function inputFromFlags(op: string, flags: Record<string, unknown>, cwd: string): Record<string, unknown>;
+export declare const missionCommand: Command;
+export default missionCommand;
+//# sourceMappingURL=mission.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/mission.js

@@ -0,0 +1,116 @@
+/**
+ * `ruflo mission` — ADR-406 §19.7 mission operations from the CLI.
+ *
+ *   mission create  --objective <text> [--request-id <id>]
+ *   mission plan    --mission <id> --expected-revision <n> --plan-file <json> [--request-id <id>]
+ *   mission get     [--mission <id>]
+ *   mission events  --mission <id> [--after <seq>] [--limit <n>]
+ *   mission action  --mission <id> --expected-revision <n> --action <requestAuthorization|pause|cancel|admit|resume> [--reason <text>]
+ *
+ * Flags map one-to-one onto the raw input the MCP tools receive; the shared
+ * `MissionService` validates both. Output is JSON. A missing request id gets a
+ * fresh one: a new id is a new intentional request (ADR-406 §9); pass the same
+ * id to retry the same request safely.
+ */
+import { randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { output } from '../output.js';
+import { MissionService } from '../missions/service.js';
+const PLAN_FILE_MAX_BYTES = 256 * 1024;
+let factory = (projectRoot) => new MissionService({ projectRoot, channel: 'cli' });
+/** Test seam (London school): substitute the service the command talks to. */
+export function setMissionPortFactory(next) {
+    factory = next ?? ((projectRoot) => new MissionService({ projectRoot, channel: 'cli' }));
+}
+function int(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : Number.NaN;
+}
+function readPlanFile(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile())
+        throw new Error('plan-file must be a regular file');
+    if (stat.size > PLAN_FILE_MAX_BYTES)
+        throw new Error(`plan-file exceeds ${PLAN_FILE_MAX_BYTES} bytes`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** Raw operation input from flags; undefined fields are dropped so defaults apply. */
+export function inputFromFlags(op, flags, cwd) {
+    const raw = {};
+    const set = (key, value) => { if (value !== undefined)
+        raw[key] = value; };
+    const requestId = typeof flags.requestId === 'string' ? flags.requestId : randomUUID();
+    if (op === 'create') {
+        set('requestId', requestId);
+        set('objective', flags.objective);
+    }
+    else if (op === 'plan') {
+        set('requestId', requestId);
+        set('missionId', flags.mission);
+        set('expectedRevision', int(flags.expectedRevision));
+        if (typeof flags.planFile === 'string')
+            set('plan', readPlanFile(resolve(cwd, flags.planFile)));
+    }
+    else if (op === 'get') {
+        set('missionId', flags.mission);
+    }
+    else if (op === 'events') {
+        set('missionId', flags.mission);
+        set('afterSequence', int(flags.after));
+        set('limit', int(flags.limit));
+    }
+    else if (op === 'action') {
+        set('requestId', requestId);
+        set('missionId', flags.mission);
+        set('expectedRevision', int(flags.expectedRevision));
+        set('action', flags.action);
+        set('reason', flags.reason);
+    }
+    return raw;
+}
+export const missionCommand = {
+    name: 'mission',
+    description: 'ADR-406 mission control: create, plan, get, events, action (shared runtime with the mission_* MCP tools)',
+    options: [
+        { name: 'objective', type: 'string', description: 'create: mission objective' },
+        { name: 'mission', type: 'string', description: 'Mission id (msn_…)' },
+        { name: 'request-id', type: 'string', description: 'Idempotency key; reuse only to retry the same request' },
+        { name: 'expected-revision', type: 'number', description: 'Revision the request was prepared against' },
+        { name: 'plan-file', type: 'string', description: 'plan: JSON file with { tasks, acceptance, budget, scope }' },
+        { name: 'after', type: 'number', description: 'events: cursor (last sequence seen)' },
+        { name: 'limit', type: 'number', description: 'events: page size (max 500)' },
+        { name: 'action', type: 'string', description: 'action: requestAuthorization | pause | cancel | admit | resume' },
+        { name: 'reason', type: 'string', description: 'action: reason' },
+        { name: 'project-root', type: 'string', description: 'Project root (default: cwd)' },
+    ],
+    examples: [
+        { command: 'ruflo mission create --objective "Ship the report" --request-id r1', description: 'Create a draft mission' },
+        { command: 'ruflo mission plan --mission msn_… --expected-revision 1 --plan-file plan.json', description: 'Submit a plan' },
+        { command: 'ruflo mission events --mission msn_… --after 0', description: 'Read events from a cursor' },
+    ],
+    async action(ctx) {
+        const flags = ctx.flags;
+        const op = ctx.args[0] ?? 'get';
+        const root = resolve(String(flags.projectRoot ?? ctx.cwd ?? process.cwd()));
+        const ops = { create: 'create', plan: 'plan', get: 'get', events: 'events', action: 'requestAction' };
+        const method = ops[op];
+        if (!method) {
+            output.printError(`unknown mission operation: ${op} (create | plan | get | events | action)`);
+            return { success: false, exitCode: 1 };
+        }
+        let result;
+        try {
+            result = await factory(root)[method](inputFromFlags(op, flags, root));
+        }
+        catch (error) {
+            result = { ok: false, code: 'invalid-input', message: error instanceof Error ? error.message : String(error) };
+        }
+        output.writeln(JSON.stringify(result, null, 2));
+        return { success: result.ok, exitCode: result.ok ? 0 : result.code === 'revision-conflict' ? 3 : 1, data: result };
+    },
+};
+export default missionCommand;
+//# sourceMappingURL=mission.js.map

package/v3/@claude-flow/cli/dist/src/commands/mods.d.ts

@@ -2,7 +2,7 @@
  * `ruflo mods` — opt into running ruflo as a Claude Code mod (ADR-404,
  * Claude Code function hooks, early access).
  *
- * install/uninstall edit one settings file and record what they added;
+ * install/uninstall edit settings files and record what they added;
  * status/doctor report what can be known from outside a session; sync-policy
  * rewrites the policy projection the mod's tool check reads. Classic hooks
  * are never removed: they stay the default and the fallback.

package/v3/@claude-flow/cli/dist/src/commands/mods.js

@@ -2,14 +2,34 @@
  * `ruflo mods` — opt into running ruflo as a Claude Code mod (ADR-404,
  * Claude Code function hooks, early access).
  *
- * install/uninstall edit one settings file and record what they added;
+ * install/uninstall edit settings files and record what they added;
  * status/doctor report what can be known from outside a session; sync-policy
  * rewrites the policy projection the mod's tool check reads. Classic hooks
  * are never removed: they stay the default and the fallback.
  */
 import { output } from '../output.js';
-import { installMod, uninstallMod } from '../mods/install.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { directoryMarketplace, MARKETPLACE_NAME } from '../mods/install.js';
 import { probeMods } from '../mods/probe.js';
+import { applyMods, removeMods } from '../mods/apply.js';
+/**
+ * `--source local` / `--marketplace-path <dir>`: a ruflo checkout as a
+ * directory marketplace (dogfooding). It must be a ruflo marketplace.
+ */
+function localMarketplace(dir) {
+    const catalog = join(resolve(dir), '.claude-plugin', 'marketplace.json');
+    if (!existsSync(catalog))
+        return `${dir} has no .claude-plugin/marketplace.json`;
+    try {
+        if (JSON.parse(readFileSync(catalog, 'utf8')).name !== MARKETPLACE_NAME)
+            return `${catalog} is not the ${MARKETPLACE_NAME} marketplace`;
+    }
+    catch {
+        return `${catalog} is not JSON`;
+    }
+    return directoryMarketplace(dir);
+}
 function projectRoot(ctx) {
     return ctx.flags.projectRoot ?? ctx.flags['project-root'] ?? ctx.cwd ?? process.cwd();
 }
@@ -24,11 +44,15 @@ function printFindings(findings) {
 const rootOption = { name: 'project-root', description: 'Project root (default: current directory)', type: 'string' };
 const installSub = {
     name: 'install',
-    description: 'Enable the ruflo-mods plugin for this project (opt-in; classic hooks stay as fallback)',
+    description: 'Enable the ruflo mod plugins (ruflo-mods, ruflo-swarm, ruflo-console) for this project; classic hooks stay as fallback',
     options: [
         rootOption,
         { name: 'scope', description: 'local (.claude/settings.local.json, default) | project (.claude/settings.json)', type: 'string', default: 'local' },
-        { name: 'dry-run', description: 'Show the settings that would be written', type: 'boolean', default: false },
+        { name: 'dry-run', description: 'Show the settings that would be written and the claude commands that would run', type: 'boolean', default: false },
+        { name: 'plugin-install', description: 'Refresh the ruflo marketplace and run `claude plugin install` (--no-plugin-install to only write settings)', type: 'boolean', default: true },
+        { name: 'strict', description: 'Exit 1 when a required plugin could not be made loadable', type: 'boolean', default: false },
+        { name: 'source', description: 'github (ruvnet/ruflo, default) | local (a ruflo checkout as a directory marketplace: plugins load live from it)', type: 'string', default: 'github' },
+        { name: 'marketplace-path', description: 'With --source local: the ruflo checkout (default: the project root)', type: 'string' },
     ],
     action: async (ctx) => {
         const scope = ctx.flags.scope ?? 'local';
@@ -36,32 +60,49 @@ const installSub = {
             output.printError(`--scope must be local or project, got ${scope}`);
             return { success: false, exitCode: 1 };
         }
-        const root = projectRoot(ctx);
-        const result = installMod(root, scope, (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
-        if (result.dryRun) {
-            output.writeln(`Would write ${result.settingsFile}:`);
-            output.printJson(result.next);
-            return { success: true, data: result };
+        const source = ctx.flags.source ?? 'github';
+        const path = (ctx.flags.marketplacePath ?? ctx.flags['marketplace-path']);
+        if (source !== 'github' && source !== 'local') {
+            output.printError(`--source must be github or local, got ${source}`);
+            return { success: false, exitCode: 1 };
         }
-        await syncPolicy(root, true);
-        output.printSuccess(`ruflo-mods enabled in ${result.settingsFile}${result.backup ? ` (backup: ${result.backup})` : ''}`);
-        output.writeln('Restart Claude Code, then run /ruflo-mods in a session to see what the mod owns.');
-        output.writeln(output.dim('Early access: Claude Code loads it only where function hooks are on. Run `ruflo mods doctor`.'));
-        return { success: true, data: result };
+        let marketplace;
+        if (source === 'local' || path) {
+            const local = localMarketplace(path ?? projectRoot(ctx));
+            if (typeof local === 'string') {
+                output.printError(`--source local: ${local}`);
+                return { success: false, exitCode: 1 };
+            }
+            marketplace = local;
+        }
+        const result = await applyMods(projectRoot(ctx), {
+            scope: scope,
+            marketplace,
+            dryRun: ctx.flags.dryRun === true || ctx.flags['dry-run'] === true,
+            pluginInstall: ctx.flags.pluginInstall !== false && ctx.flags['plugin-install'] !== false,
+        });
+        if (result.install.dryRun)
+            return { success: true, data: result };
+        if (result.resolvable)
+            output.writeln('Restart Claude Code, then run /ruflo in a session to open the console (/ruflo mods shows what the mod owns). Check with: ruflo mods doctor');
+        const data = { ...result.install, resolvable: result.resolvable };
+        return result.resolvable || ctx.flags.strict !== true ? { success: true, data } : { success: false, exitCode: 1, data };
     },
 };
 const uninstallSub = {
     name: 'uninstall',
-    description: 'Remove what `ruflo mods install` added (classic hooks take every event back)',
+    description: 'Remove what `ruflo mods install` added, and claude plugin uninstall what it installed (classic hooks take every event back)',
     options: [rootOption, { name: 'dry-run', description: 'Show what would be removed', type: 'boolean', default: false }],
     action: async (ctx) => {
-        const result = uninstallMod(projectRoot(ctx), (ctx.flags.dryRun === true || ctx.flags['dry-run'] === true));
+        const result = await removeMods(projectRoot(ctx), { dryRun: ctx.flags.dryRun === true || ctx.flags['dry-run'] === true });
         if (!result.removed) {
             output.printWarning('No install record (.claude-flow/mods/install.json): nothing ruflo added to remove.');
             return { success: true, data: result };
         }
-        output.printSuccess(`${result.dryRun ? 'Would remove' : 'Removed'} ruflo-mods from ${result.settingsFile}`);
-        return { success: true, data: result };
+        output.printSuccess(`${result.dryRun ? 'Would remove' : 'Removed'} what ruflo mods added from ${result.settingsFiles.join(', ')}`);
+        if (result.uninstalled.length)
+            output.writeln(`claude plugin uninstall: ${result.uninstalled.join(', ')}`);
+        return { success: result.failed.length === 0, exitCode: result.failed.length ? 1 : 0, data: result };
     },
 };
 function findingsCommand(name, description) {
@@ -76,8 +117,8 @@ function findingsCommand(name, description) {
             else
                 printFindings(findings);
             const failed = findings.some((f) => f.status === 'fail');
-            // status reports; doctor gates (warnings are expected while early access is off).
-            return { success: !failed, exitCode: name === 'doctor' && failed ? 1 : 0, data: findings };
+            // status reports (exit 0); doctor gates on a failure (warnings are expected while early access is off).
+            return name === 'doctor' && failed ? { success: false, exitCode: 1, data: findings } : { success: true, data: findings };
         },
     };
 }
@@ -116,8 +157,11 @@ export const modsCommand = {
         syncPolicySub,
     ],
     examples: [
-        { command: 'ruflo mods install', description: 'Enable for this project (settings.local.json)' },
-        { command: 'ruflo mods doctor', description: 'Function hooks on? Refused by policy? Handshake supported?' },
+        { command: 'ruflo mods install', description: 'Enable the mod plugins for this checkout (settings.local.json) and install them with claude' },
+        { command: 'ruflo mods install --scope project', description: 'Same, in the committed settings.json (what ruflo init does)' },
+        { command: 'ruflo mods install --no-plugin-install', description: 'Only write settings; run no claude command' },
+        { command: 'ruflo mods install --source local', description: 'Dogfood: load the mods live from this ruflo checkout (directory marketplace)' },
+        { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy?' },
         { command: 'ruflo mods uninstall', description: 'Remove only what install added' },
     ],
     action: statusSub.action,