claude-flow 3.74.1 → 3.75.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/.claude/helpers/auto-memory-hook.mjs +262 -81
  2. package/node_modules/@claude-flow/codex/README.md +38 -0
  3. package/node_modules/@claude-flow/codex/dist/generators/agents-md.d.ts +1 -0
  4. package/node_modules/@claude-flow/codex/dist/generators/agents-md.d.ts.map +1 -1
  5. package/node_modules/@claude-flow/codex/dist/generators/agents-md.js +4 -4
  6. package/node_modules/@claude-flow/codex/dist/generators/agents-md.js.map +1 -1
  7. package/node_modules/@claude-flow/codex/dist/generators/dual-instructions.d.ts +20 -0
  8. package/node_modules/@claude-flow/codex/dist/generators/dual-instructions.d.ts.map +1 -0
  9. package/node_modules/@claude-flow/codex/dist/generators/dual-instructions.js +104 -0
  10. package/node_modules/@claude-flow/codex/dist/generators/dual-instructions.js.map +1 -0
  11. package/node_modules/@claude-flow/codex/dist/generators/index.d.ts +2 -0
  12. package/node_modules/@claude-flow/codex/dist/generators/index.d.ts.map +1 -1
  13. package/node_modules/@claude-flow/codex/dist/generators/index.js +2 -0
  14. package/node_modules/@claude-flow/codex/dist/generators/index.js.map +1 -1
  15. package/node_modules/@claude-flow/codex/dist/generators/shared-instructions.d.ts +46 -0
  16. package/node_modules/@claude-flow/codex/dist/generators/shared-instructions.d.ts.map +1 -0
  17. package/node_modules/@claude-flow/codex/dist/generators/shared-instructions.js +162 -0
  18. package/node_modules/@claude-flow/codex/dist/generators/shared-instructions.js.map +1 -0
  19. package/node_modules/@claude-flow/codex/dist/index.d.ts +3 -3
  20. package/node_modules/@claude-flow/codex/dist/index.js +1 -1
  21. package/node_modules/@claude-flow/codex/dist/initializer.d.ts.map +1 -1
  22. package/node_modules/@claude-flow/codex/dist/initializer.js +16 -93
  23. package/node_modules/@claude-flow/codex/dist/initializer.js.map +1 -1
  24. package/node_modules/@claude-flow/codex/package.json +8 -6
  25. package/node_modules/@claude-flow/mcp/README.md +44 -0
  26. package/node_modules/@claude-flow/mcp/package.json +16 -4
  27. package/package.json +4 -4
  28. package/v3/@claude-flow/cli/catalog-manifest.json +3 -3
  29. package/v3/@claude-flow/cli/dist/src/autopilot-state.js +17 -8
  30. package/v3/@claude-flow/cli/dist/src/commands/agent.js +2 -1
  31. package/v3/@claude-flow/cli/dist/src/commands/init.js +28 -6
  32. package/v3/@claude-flow/cli/dist/src/commands/memory-backup.js +2 -1
  33. package/v3/@claude-flow/cli/dist/src/commands/memory-distill.js +2 -1
  34. package/v3/@claude-flow/cli/dist/src/commands/memory.js +47 -3
  35. package/v3/@claude-flow/cli/dist/src/commands/neural.js +6 -5
  36. package/v3/@claude-flow/cli/dist/src/commands/plugins-host.d.ts +13 -0
  37. package/v3/@claude-flow/cli/dist/src/commands/plugins-host.js +161 -0
  38. package/v3/@claude-flow/cli/dist/src/commands/plugins.js +3 -1
  39. package/v3/@claude-flow/cli/dist/src/commands/start-all.d.ts +28 -0
  40. package/v3/@claude-flow/cli/dist/src/commands/start-all.js +99 -0
  41. package/v3/@claude-flow/cli/dist/src/commands/start.d.ts +5 -1
  42. package/v3/@claude-flow/cli/dist/src/commands/start.js +17 -10
  43. package/v3/@claude-flow/cli/dist/src/commands/swarm.js +2 -1
  44. package/v3/@claude-flow/cli/dist/src/fs-secure.js +9 -2
  45. package/v3/@claude-flow/cli/dist/src/init/claudemd-generator.d.ts +15 -0
  46. package/v3/@claude-flow/cli/dist/src/init/claudemd-generator.js +64 -114
  47. package/v3/@claude-flow/cli/dist/src/init/dual-instructions.d.ts +29 -0
  48. package/v3/@claude-flow/cli/dist/src/init/dual-instructions.js +87 -0
  49. package/v3/@claude-flow/cli/dist/src/init/executor.js +96 -13
  50. package/v3/@claude-flow/cli/dist/src/init/index.d.ts +3 -1
  51. package/v3/@claude-flow/cli/dist/src/init/index.js +5 -1
  52. package/v3/@claude-flow/cli/dist/src/init/plugin-dedup.d.ts +61 -0
  53. package/v3/@claude-flow/cli/dist/src/init/plugin-dedup.js +130 -0
  54. package/v3/@claude-flow/cli/dist/src/init/shared-instructions.d.ts +46 -0
  55. package/v3/@claude-flow/cli/dist/src/init/shared-instructions.js +162 -0
  56. package/v3/@claude-flow/cli/dist/src/init/types.d.ts +33 -0
  57. package/v3/@claude-flow/cli/dist/src/init/types.js +3 -0
  58. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.d.ts +14 -0
  59. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js +48 -5
  60. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-hierarchical-inventory-tools.d.ts +15 -0
  61. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-hierarchical-inventory-tools.js +115 -0
  62. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-inventory-tools.d.ts +21 -0
  63. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-inventory-tools.js +152 -0
  64. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-tools.js +56 -7
  65. package/v3/@claude-flow/cli/dist/src/mcp-tools/aidefence-known-misses.d.ts +6 -0
  66. package/v3/@claude-flow/cli/dist/src/mcp-tools/aidefence-known-misses.js +23 -5
  67. package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js +21 -3
  68. package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.d.ts +29 -0
  69. package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js +239 -19
  70. package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.js +53 -5
  71. package/v3/@claude-flow/cli/dist/src/memory/embedding-config.d.ts +79 -0
  72. package/v3/@claude-flow/cli/dist/src/memory/embedding-config.js +250 -0
  73. package/v3/@claude-flow/cli/dist/src/memory/ewc-consolidation.js +2 -1
  74. package/v3/@claude-flow/cli/dist/src/memory/intelligence.d.ts +28 -2
  75. package/v3/@claude-flow/cli/dist/src/memory/intelligence.js +37 -7
  76. package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.d.ts +42 -0
  77. package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.js +267 -28
  78. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts +1 -1
  79. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js +47 -22
  80. package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.js +3 -2
  81. package/v3/@claude-flow/cli/dist/src/ruvector/task-embedder.d.ts +2 -1
  82. package/v3/@claude-flow/cli/dist/src/ruvector/task-embedder.js +7 -3
  83. package/v3/@claude-flow/cli/dist/src/services/daemon-autostart.d.ts +4 -6
  84. package/v3/@claude-flow/cli/dist/src/services/daemon-autostart.js +6 -46
  85. package/v3/@claude-flow/cli/dist/src/services/host-executable.d.ts +68 -0
  86. package/v3/@claude-flow/cli/dist/src/services/host-executable.js +175 -0
  87. package/v3/@claude-flow/cli/dist/src/services/host-plugin-manager.d.ts +137 -0
  88. package/v3/@claude-flow/cli/dist/src/services/host-plugin-manager.js +374 -0
  89. package/v3/@claude-flow/cli/dist/src/services/project-root.d.ts +37 -0
  90. package/v3/@claude-flow/cli/dist/src/services/project-root.js +122 -0
  91. package/v3/@claude-flow/cli/package.json +7 -7
@@ -0,0 +1,130 @@
1
+ /**
2
+ * #2640 — init defers to the installed ruflo Claude Code plugins.
3
+ *
4
+ * When `ruflo-core@ruflo` is installed for this project (and not switched off
5
+ * in `enabledPlugins`), the agents, commands and skills that the installed
6
+ * `*@ruflo` plugins ship are not copied into `.claude/` again, and the
7
+ * standalone `claude-flow` MCP server is not registered (the plugin provides
8
+ * one). `init --full` keeps copying everything.
9
+ *
10
+ * Read-only: only reads Claude Code's own records
11
+ * (`<config>/plugins/installed_plugins.json`, settings files) and the plugin
12
+ * install directories they point to. A missing or malformed record means
13
+ * "no plugin", i.e. today's behaviour.
14
+ */
15
+ import { readdirSync } from 'node:fs';
16
+ import { homedir } from 'node:os';
17
+ import { join } from 'node:path';
18
+ import { claudeConfigDir, installedState, nodeReadFs } from '../mods/plugin-resolve.js';
19
+ export const RUFLO_CORE_PLUGIN = 'ruflo-core@ruflo';
20
+ const MARKETPLACE_SUFFIX = '@ruflo';
21
+ const MAX_DEPTH = 6;
22
+ export const nodeDedupFs = {
23
+ ...nodeReadFs,
24
+ listDir: (p) => {
25
+ try {
26
+ return readdirSync(p, { withFileTypes: true }).map((e) => ({ name: e.name, isDirectory: e.isDirectory() }));
27
+ }
28
+ catch {
29
+ return [];
30
+ }
31
+ },
32
+ };
33
+ function readJson(fs, path) {
34
+ const text = fs.readText(path);
35
+ if (text === undefined)
36
+ return undefined;
37
+ try {
38
+ return JSON.parse(text);
39
+ }
40
+ catch {
41
+ return undefined;
42
+ }
43
+ }
44
+ function isRecord(v) {
45
+ return v !== null && typeof v === 'object' && !Array.isArray(v);
46
+ }
47
+ /** `enabledPlugins[id]` from the most specific settings file that sets it (local > project > user). */
48
+ function enabledSetting(projectRoot, configDir, id, fs) {
49
+ const files = [
50
+ join(projectRoot, '.claude', 'settings.local.json'),
51
+ join(projectRoot, '.claude', 'settings.json'),
52
+ join(configDir, 'settings.json'),
53
+ ];
54
+ for (const file of files) {
55
+ const settings = readJson(fs, file);
56
+ if (isRecord(settings) && isRecord(settings.enabledPlugins) && id in settings.enabledPlugins) {
57
+ return settings.enabledPlugins[id];
58
+ }
59
+ }
60
+ return undefined;
61
+ }
62
+ function collectMd(fs, dir, into, id, depth = 0) {
63
+ if (depth > MAX_DEPTH)
64
+ return;
65
+ for (const entry of fs.listDir(dir)) {
66
+ if (entry.isDirectory)
67
+ collectMd(fs, join(dir, entry.name), into, id, depth + 1);
68
+ else if (entry.name.endsWith('.md') && entry.name !== 'README.md' && !into.has(entry.name))
69
+ into.set(entry.name, id);
70
+ }
71
+ }
72
+ function collectSkills(fs, dir, into, id) {
73
+ for (const entry of fs.listDir(dir)) {
74
+ if (entry.isDirectory && fs.exists(join(dir, entry.name, 'SKILL.md')) && !into.has(entry.name))
75
+ into.set(entry.name, id);
76
+ }
77
+ }
78
+ /**
79
+ * The agents, commands and skills the installed ruflo plugins provide for
80
+ * this project, or `null` when `ruflo-core@ruflo` is not installed and
81
+ * enabled here (then init behaves exactly as before).
82
+ */
83
+ export function detectRufloPlugins(projectRoot, opts = {}) {
84
+ const fs = opts.fs ?? nodeDedupFs;
85
+ const configDir = opts.configDir ?? claudeConfigDir(opts.env ?? process.env, opts.home ?? homedir());
86
+ const active = (id) => installedState(projectRoot, configDir, id, fs).installed && enabledSetting(projectRoot, configDir, id, fs) !== false;
87
+ if (!active(RUFLO_CORE_PLUGIN))
88
+ return null;
89
+ const registry = readJson(fs, join(configDir, 'plugins', 'installed_plugins.json'));
90
+ const ids = isRecord(registry) && isRecord(registry.plugins)
91
+ ? Object.keys(registry.plugins).filter((id) => id.endsWith(MARKETPLACE_SUFFIX)).sort()
92
+ : [];
93
+ const provided = { plugins: [], agents: new Map(), commands: new Map(), skills: new Map() };
94
+ for (const id of ids) {
95
+ if (!active(id))
96
+ continue;
97
+ const { installPath } = installedState(projectRoot, configDir, id, fs);
98
+ if (!installPath)
99
+ continue;
100
+ provided.plugins.push(id);
101
+ collectMd(fs, join(installPath, 'agents'), provided.agents, id);
102
+ collectMd(fs, join(installPath, 'commands'), provided.commands, id);
103
+ collectSkills(fs, join(installPath, 'skills'), provided.skills, id);
104
+ }
105
+ return provided;
106
+ }
107
+ export function emptyDedupReport(provided) {
108
+ return { plugins: [...provided.plugins], skipped: { agents: [], commands: [], skills: [] }, mcpServerSkipped: false };
109
+ }
110
+ const shortName = (id) => id.replace(MARKETPLACE_SUFFIX, '');
111
+ /** Lines for the summary `ruflo init` prints. Empty when nothing was skipped. */
112
+ export function formatPluginDedupSummary(report) {
113
+ const { agents, commands, skills } = report.skipped;
114
+ if (!agents.length && !commands.length && !skills.length && !report.mcpServerSkipped)
115
+ return [];
116
+ const names = report.plugins.map(shortName);
117
+ const shown = names.length > 4 ? `${names.slice(0, 4).join(', ')} and ${names.length - 4} more` : names.join(', ');
118
+ const lines = [`Installed ruflo plugins already provide these, so init did not copy them (${shown}):`];
119
+ if (skills.length)
120
+ lines.push(` Skills: ${skills.length} (${skills.slice(0, 6).join(', ')}${skills.length > 6 ? ', …' : ''})`);
121
+ if (commands.length)
122
+ lines.push(` Commands: ${commands.length}`);
123
+ if (agents.length)
124
+ lines.push(` Agents: ${agents.length}`);
125
+ if (report.mcpServerSkipped)
126
+ lines.push(' MCP: standalone `claude-flow` server not registered (ruflo-core provides the MCP server)');
127
+ lines.push('Run `ruflo init --full` to copy everything anyway.');
128
+ return lines;
129
+ }
130
+ //# sourceMappingURL=plugin-dedup.js.map
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Shared Ruflo instruction sections (#2638).
3
+ *
4
+ * The host-neutral half of the project instructions: the text both Claude
5
+ * Code and Codex should read. In a dual project AGENTS.md carries these
6
+ * sections once, and CLAUDE.md pulls them in with Claude Code's `@AGENTS.md`
7
+ * import, adding only Claude-specific guidance.
8
+ *
9
+ * Canonical copy: v3/@claude-flow/codex/src/generators/shared-instructions.ts
10
+ * Mirror: v3/@claude-flow/cli/src/init/shared-instructions.ts
11
+ *
12
+ * The two files must stay byte-identical (a CLI test compares them). The CLI
13
+ * keeps a mirror instead of importing it because it pins a published
14
+ * @claude-flow/codex release, which cannot see unreleased exports; once the
15
+ * CLI pins a codex release that ships this module, the mirror can go.
16
+ *
17
+ * Pure: no imports, no I/O.
18
+ */
19
+ /**
20
+ * How the sections invoke the Ruflo CLI. The default is the codex generators'
21
+ * convention (unversioned, as in AGENTS.md); the CLI passes its own pinned-tag
22
+ * form so its single-host CLAUDE.md is unchanged.
23
+ */
24
+ export declare const DEFAULT_CLI = "npx @claude-flow/cli";
25
+ /** Rules both hosts follow. The Claude-only commit-trailer rule is kept by the CLI. */
26
+ export declare const SHARED_RULE_LINES: readonly string[];
27
+ /** Position of the Claude-only commit-trailer rule inside the single-host Rules list. */
28
+ export declare const CLAUDE_RULE_INSERT_AT = 6;
29
+ export declare function sharedRules(): string;
30
+ /** Swarm body shared by both hosts: init command, routing table, when to swarm. */
31
+ export declare function swarmRoutingBody(cli?: string): string;
32
+ export declare function sharedSwarmRouting(cli?: string): string;
33
+ export declare function sharedMemoryAndLearning(cli?: string): string;
34
+ export declare function sharedAgentTypes(): string;
35
+ export declare function sharedBuildAndTest(): string;
36
+ export declare function sharedCliQuickRef(cli?: string): string;
37
+ /**
38
+ * Every shared section, in order. AGENTS.md (dual mode) writes all of them;
39
+ * a CLAUDE.md that imports AGENTS.md must not repeat any of them.
40
+ */
41
+ export declare function generateSharedInstructions(cli?: string): string[];
42
+ /** Claude Code's import line. Must stand on its own line, outside a code block. */
43
+ export declare const AGENTS_MD_IMPORT = "@AGENTS.md";
44
+ /** True when the text already pulls AGENTS.md in through Claude Code's import syntax. */
45
+ export declare function importsAgentsMd(text: string): boolean;
46
+ //# sourceMappingURL=shared-instructions.d.ts.map
@@ -0,0 +1,162 @@
1
+ /**
2
+ * Shared Ruflo instruction sections (#2638).
3
+ *
4
+ * The host-neutral half of the project instructions: the text both Claude
5
+ * Code and Codex should read. In a dual project AGENTS.md carries these
6
+ * sections once, and CLAUDE.md pulls them in with Claude Code's `@AGENTS.md`
7
+ * import, adding only Claude-specific guidance.
8
+ *
9
+ * Canonical copy: v3/@claude-flow/codex/src/generators/shared-instructions.ts
10
+ * Mirror: v3/@claude-flow/cli/src/init/shared-instructions.ts
11
+ *
12
+ * The two files must stay byte-identical (a CLI test compares them). The CLI
13
+ * keeps a mirror instead of importing it because it pins a published
14
+ * @claude-flow/codex release, which cannot see unreleased exports; once the
15
+ * CLI pins a codex release that ships this module, the mirror can go.
16
+ *
17
+ * Pure: no imports, no I/O.
18
+ */
19
+ /**
20
+ * How the sections invoke the Ruflo CLI. The default is the codex generators'
21
+ * convention (unversioned, as in AGENTS.md); the CLI passes its own pinned-tag
22
+ * form so its single-host CLAUDE.md is unchanged.
23
+ */
24
+ export const DEFAULT_CLI = 'npx @claude-flow/cli';
25
+ /** Rules both hosts follow. The Claude-only commit-trailer rule is kept by the CLI. */
26
+ export const SHARED_RULE_LINES = [
27
+ '- Do what has been asked; nothing more, nothing less',
28
+ '- NEVER create files unless absolutely necessary — prefer editing existing files',
29
+ '- NEVER create documentation files unless explicitly requested',
30
+ '- NEVER save working files or tests to root — use `/src`, `/tests`, `/docs`, `/config`, `/scripts`',
31
+ '- ALWAYS read a file before editing it',
32
+ '- NEVER commit secrets, credentials, or .env files',
33
+ '- Keep files under 500 lines',
34
+ '- Validate input at system boundaries',
35
+ ];
36
+ /** Position of the Claude-only commit-trailer rule inside the single-host Rules list. */
37
+ export const CLAUDE_RULE_INSERT_AT = 6;
38
+ export function sharedRules() {
39
+ return `## Rules\n\n${SHARED_RULE_LINES.join('\n')}`;
40
+ }
41
+ /** Swarm body shared by both hosts: init command, routing table, when to swarm. */
42
+ export function swarmRoutingBody(cli = DEFAULT_CLI) {
43
+ return `\`\`\`bash
44
+ ${cli} swarm init --topology hierarchical --max-agents 8 --strategy specialized
45
+ \`\`\`
46
+
47
+ ### Agent Routing
48
+
49
+ | Task | Agents | Topology |
50
+ |------|--------|----------|
51
+ | Bug Fix | researcher, coder, tester | hierarchical |
52
+ | Feature | architect, coder, tester, reviewer | hierarchical |
53
+ | Refactor | architect, coder, reviewer | hierarchical |
54
+ | Performance | perf-engineer, coder | hierarchical |
55
+ | Security | security-architect, auditor | hierarchical |
56
+
57
+ ### When to Swarm
58
+ - **YES**: 3+ files, new features, cross-module refactoring, API changes, security, performance
59
+ - **NO**: single file edits, 1-2 line fixes, docs updates, config changes, questions`;
60
+ }
61
+ export function sharedSwarmRouting(cli = DEFAULT_CLI) {
62
+ return `## Swarm & Routing\n\n${swarmRoutingBody(cli)}`;
63
+ }
64
+ export function sharedMemoryAndLearning(cli = DEFAULT_CLI) {
65
+ return `## Memory & Learning
66
+
67
+ ### Before Any Task
68
+ \`\`\`bash
69
+ ${cli} memory search --query "[task keywords]" --namespace patterns
70
+ ${cli} hooks route --task "[task description]"
71
+ \`\`\`
72
+
73
+ ### After Success
74
+ \`\`\`bash
75
+ ${cli} memory store --namespace patterns --key "[name]" --value "[what worked]"
76
+ ${cli} hooks post-task --task-id "[id]" --success true --store-results true
77
+ \`\`\`
78
+
79
+ ### MCP Tools (use \`ToolSearch("keyword")\` to discover)
80
+
81
+ | Category | Key Tools |
82
+ |----------|-----------|
83
+ | **Memory** | \`memory_store\`, \`memory_search\`, \`memory_search_unified\` |
84
+ | **Bridge** | \`memory_import_claude\`, \`memory_bridge_status\` |
85
+ | **Swarm** | \`swarm_init\`, \`swarm_status\`, \`swarm_health\` |
86
+ | **Agents** | \`agent_spawn\`, \`agent_list\`, \`agent_status\` |
87
+ | **Hooks** | \`hooks_route\`, \`hooks_post-task\`, \`hooks_worker-dispatch\` |
88
+ | **Security** | \`aidefence_scan\`, \`aidefence_is_safe\`, \`aidefence_has_pii\` |
89
+ | **Hive-Mind** | \`hive-mind_init\`, \`hive-mind_consensus\`, \`hive-mind_spawn\` |
90
+
91
+ ### Background Workers
92
+
93
+ | Worker | When |
94
+ |--------|------|
95
+ | \`audit\` | After security changes |
96
+ | \`optimize\` | After performance work |
97
+ | \`testgaps\` | After adding features |
98
+ | \`map\` | Every 5+ file changes |
99
+ | \`document\` | After API changes |
100
+
101
+ \`\`\`bash
102
+ ${cli} hooks worker dispatch --trigger audit
103
+ \`\`\``;
104
+ }
105
+ export function sharedAgentTypes() {
106
+ return `## Agents
107
+
108
+ **Core**: \`coder\`, \`reviewer\`, \`tester\`, \`planner\`, \`researcher\`
109
+ **Architecture**: \`system-architect\`, \`backend-dev\`, \`mobile-dev\`
110
+ **Security**: \`security-architect\`, \`security-auditor\`
111
+ **Performance**: \`performance-engineer\`, \`perf-analyzer\`
112
+ **Coordination**: \`hierarchical-coordinator\`, \`mesh-coordinator\`, \`adaptive-coordinator\`
113
+ **GitHub**: \`pr-manager\`, \`code-review-swarm\`, \`issue-tracker\`, \`release-manager\`
114
+
115
+ Any string works as a custom agent type.`;
116
+ }
117
+ export function sharedBuildAndTest() {
118
+ return `## Build & Test
119
+
120
+ - ALWAYS run tests after code changes
121
+ - ALWAYS verify build succeeds before committing
122
+
123
+ \`\`\`bash
124
+ npm run build && npm test
125
+ \`\`\``;
126
+ }
127
+ export function sharedCliQuickRef(cli = DEFAULT_CLI) {
128
+ return `## CLI Quick Reference
129
+
130
+ \`\`\`bash
131
+ ${cli} init --wizard # Setup
132
+ ${cli} swarm init --v3-mode # Start swarm
133
+ ${cli} memory search --query "" # Vector search
134
+ ${cli} hooks route --task "" # Route to agent
135
+ ${cli} doctor --fix # Diagnostics
136
+ ${cli} security scan # Security scan
137
+ ${cli} performance benchmark # Benchmarks
138
+ \`\`\`
139
+
140
+ 26 commands, 140+ subcommands. Use \`--help\` on any command for details.`;
141
+ }
142
+ /**
143
+ * Every shared section, in order. AGENTS.md (dual mode) writes all of them;
144
+ * a CLAUDE.md that imports AGENTS.md must not repeat any of them.
145
+ */
146
+ export function generateSharedInstructions(cli = DEFAULT_CLI) {
147
+ return [
148
+ sharedRules(),
149
+ sharedSwarmRouting(cli),
150
+ sharedMemoryAndLearning(cli),
151
+ sharedAgentTypes(),
152
+ sharedBuildAndTest(),
153
+ sharedCliQuickRef(cli),
154
+ ];
155
+ }
156
+ /** Claude Code's import line. Must stand on its own line, outside a code block. */
157
+ export const AGENTS_MD_IMPORT = '@AGENTS.md';
158
+ /** True when the text already pulls AGENTS.md in through Claude Code's import syntax. */
159
+ export function importsAgentsMd(text) {
160
+ return text.split(/\r?\n/).some((line) => line.trim() === AGENTS_MD_IMPORT);
161
+ }
162
+ //# sourceMappingURL=shared-instructions.js.map
@@ -312,6 +312,20 @@ export interface InitOptions {
312
312
  * (--drop-risky-settings).
313
313
  */
314
314
  riskySettings?: 'stop' | 'keep' | 'drop';
315
+ /**
316
+ * #2638 — where the shared project instructions live. `claude-md` (default,
317
+ * single-host) writes the full CLAUDE.md. `agents-md` (set by `init --dual`)
318
+ * writes CLAUDE.md as `@AGENTS.md` plus Claude-only sections; AGENTS.md,
319
+ * written by the Codex pass, carries the shared sections.
320
+ */
321
+ instructionsSource?: 'claude-md' | 'agents-md';
322
+ /**
323
+ * #2640 — when the ruflo Claude Code plugins are installed (ruflo-core@ruflo
324
+ * enabled), skip the agents/commands/skills they already ship and the
325
+ * standalone `claude-flow` MCP server. On by default; `--full` turns it off.
326
+ * No effect when the plugins are absent.
327
+ */
328
+ deferToPlugins?: boolean;
315
329
  }
316
330
  /**
317
331
  * Default init options - full V3 setup
@@ -354,5 +368,24 @@ export interface InitResult {
354
368
  riskySettings?: string[];
355
369
  /** ADR-509 §2.3 — init stopped before writing anything because of riskySettings. */
356
370
  stoppedOnRiskySettings?: boolean;
371
+ /**
372
+ * #2638 — set when this run wrote CLAUDE.md in its `@AGENTS.md` import form.
373
+ * `fullForm` is the single-host CLAUDE.md to restore if AGENTS.md turns out
374
+ * not to carry the shared sections (see finalizeDualInstructions).
375
+ */
376
+ dualInstructions?: {
377
+ importForm: string;
378
+ fullForm: string;
379
+ };
380
+ /** #2640 — what init left to the installed ruflo plugins (absent when none are installed). */
381
+ pluginDedup?: {
382
+ plugins: string[];
383
+ skipped: {
384
+ agents: string[];
385
+ commands: string[];
386
+ skills: string[];
387
+ };
388
+ mcpServerSkipped: boolean;
389
+ };
357
390
  }
358
391
  //# sourceMappingURL=types.d.ts.map
@@ -46,6 +46,7 @@ export const DEFAULT_INIT_OPTIONS = {
46
46
  targetDir: process.cwd(),
47
47
  force: false,
48
48
  interactive: true,
49
+ deferToPlugins: true,
49
50
  components: {
50
51
  settings: true,
51
52
  skills: true,
@@ -231,6 +232,8 @@ export const MINIMAL_INIT_OPTIONS = {
231
232
  */
232
233
  export const FULL_INIT_OPTIONS = {
233
234
  ...DEFAULT_INIT_OPTIONS,
235
+ // #2640: --full copies everything, even what installed plugins provide.
236
+ deferToPlugins: false,
234
237
  components: {
235
238
  settings: true,
236
239
  skills: true,
@@ -5,6 +5,20 @@
5
5
  * Includes model routing integration for intelligent model selection.
6
6
  */
7
7
  import { type MCPTool } from './types.js';
8
+ /**
9
+ * #3215 — agent_spawn's `model` accepts an alias or an exact provider model id
10
+ * (`claude-opus-5-5`, `gpt-6-astra`, `openrouter/anthropic/claude-sonnet-5.5`,
11
+ * `qwen3.6:27b`). One pattern is shared by the input schema and the handler so
12
+ * the two cannot drift. It is anchored, starts with an alphanumeric (so a value
13
+ * cannot read as a CLI flag), and allows only `._:/@+-` besides alphanumerics:
14
+ * no whitespace and no shell metacharacters. The character class has no
15
+ * escapes, so it compiles the same under ajv's `u` flag and under the plain
16
+ * `new RegExp(pattern)` that @claude-flow/mcp's schema validator uses.
17
+ */
18
+ export declare const MODEL_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$";
19
+ export declare const MODEL_ID_MAX_LENGTH = 256;
20
+ /** Returns an error message for an invalid model value, or null when it is valid. */
21
+ export declare function modelIdError(value: unknown, label?: string): string | null;
8
22
  /** Live canonical registry members, excluding stale or duplicate swarm IDs. */
9
23
  export declare function getLiveAgentIds(agentIds: string[]): string[];
10
24
  export declare const AGENT_STATUSES: readonly ["idle", "busy", "terminated"];
@@ -22,6 +22,34 @@ const AGENT_FILE = 'store.json';
22
22
  // used here). agent_status / agent_list / agent_logs merge that store so a
23
23
  // hive-spawned worker is resolvable instead of returning `not_found`.
24
24
  const HIVE_AGENT_FILE = 'agents.json';
25
+ /** Model aliases that resolve to a tier label rather than an exact model id. */
26
+ const MODEL_ALIASES = ['haiku', 'sonnet', 'opus', 'opus-4.7', 'inherit'];
27
+ /**
28
+ * #3215 — agent_spawn's `model` accepts an alias or an exact provider model id
29
+ * (`claude-opus-5-5`, `gpt-6-astra`, `openrouter/anthropic/claude-sonnet-5.5`,
30
+ * `qwen3.6:27b`). One pattern is shared by the input schema and the handler so
31
+ * the two cannot drift. It is anchored, starts with an alphanumeric (so a value
32
+ * cannot read as a CLI flag), and allows only `._:/@+-` besides alphanumerics:
33
+ * no whitespace and no shell metacharacters. The character class has no
34
+ * escapes, so it compiles the same under ajv's `u` flag and under the plain
35
+ * `new RegExp(pattern)` that @claude-flow/mcp's schema validator uses.
36
+ */
37
+ export const MODEL_ID_PATTERN = '^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$';
38
+ export const MODEL_ID_MAX_LENGTH = 256;
39
+ const MODEL_ID_RE = new RegExp(MODEL_ID_PATTERN);
40
+ /** Returns an error message for an invalid model value, or null when it is valid. */
41
+ export function modelIdError(value, label = 'model') {
42
+ if (typeof value !== 'string' || value.length === 0) {
43
+ return `${label} must be a non-empty string`;
44
+ }
45
+ if (value.length > MODEL_ID_MAX_LENGTH) {
46
+ return `${label} exceeds ${MODEL_ID_MAX_LENGTH} characters`;
47
+ }
48
+ if (!MODEL_ID_RE.test(value)) {
49
+ return `${label} contains invalid characters (must start with a letter or digit; allowed: letters, digits, . _ : / @ + -)`;
50
+ }
51
+ return null;
52
+ }
25
53
  function getAgentDir() {
26
54
  return join(getProjectCwd(), STORAGE_DIR, AGENT_DIR);
27
55
  }
@@ -160,7 +188,7 @@ async function determineAgentModel(agentType, config, task) {
160
188
  // 1. Explicit model in config
161
189
  if (config.model) {
162
190
  const explicitModel = config.model;
163
- if (['haiku', 'sonnet', 'opus', 'opus-4.7', 'inherit'].includes(explicitModel)) {
191
+ if (MODEL_ALIASES.includes(explicitModel)) {
164
192
  return { model: explicitModel, routedBy: 'explicit' };
165
193
  }
166
194
  // #2962 — a non-alias model string (e.g. an Ollama tag like
@@ -265,8 +293,10 @@ export const agentTools = [
265
293
  domain: { type: 'string', description: 'Agent domain' },
266
294
  model: {
267
295
  type: 'string',
268
- enum: ['haiku', 'sonnet', 'opus', 'opus-4.7', 'inherit'],
269
- description: 'Claude model alias (haiku=fast/cheap, sonnet=balanced, opus=current Opus 4.8, opus-4.7=prior Opus pin)'
296
+ minLength: 1,
297
+ maxLength: MODEL_ID_MAX_LENGTH,
298
+ pattern: MODEL_ID_PATTERN,
299
+ description: 'Model alias or exact model id. Aliases: haiku=fast/cheap, sonnet=balanced, opus=current Opus 4.8, opus-4.7=prior Opus pin, inherit=the default model. Any other value is passed through unchanged as an exact model id (e.g. claude-opus-5-5, gpt-6-astra, openrouter/anthropic/claude-sonnet-5.5) and reported back as modelId. Letters, digits and . _ : / @ + - only, starting with a letter or digit.'
270
300
  },
271
301
  task: { type: 'string', description: 'Task description for intelligent model routing' },
272
302
  memoryBase: { type: 'string', description: 'Opt-in: base .rvf memory file to fork a per-agent Copy-On-Write branch from (agenticow). When set, the agent gets an isolated ~162-byte COW branch instead of a full copy — promote on success, discard on terminate. Requires the optional `agenticow` dep; degrades to a no-op when absent or when CLAUDE_FLOW_NO_COW_MEMORY=1.' },
@@ -307,10 +337,23 @@ export const agentTools = [
307
337
  name = vName.sanitized;
308
338
  }
309
339
  const config = input.config || {};
310
- // Add explicit model to config if provided
311
- if (input.model) {
340
+ // #3215 — validate an explicit model before it is stored or routed. The
341
+ // top-level field is checked even when empty (the schema rejects ''; null
342
+ // is treated as absent), and config.model is checked too: `agent spawn -m`
343
+ // sends the model there, where the input schema never sees it. A falsy
344
+ // config.model keeps its old meaning (no explicit model), matching
345
+ // determineAgentModel's check.
346
+ if (input.model !== undefined && input.model !== null) {
347
+ const err = modelIdError(input.model);
348
+ if (err)
349
+ return { success: false, error: `Input validation failed: ${err}` };
312
350
  config.model = input.model;
313
351
  }
352
+ else if (config.model) {
353
+ const err = modelIdError(config.model, 'config.model');
354
+ if (err)
355
+ return { success: false, error: `Input validation failed: ${err}` };
356
+ }
314
357
  // Get task from either top-level or config (CLI passes it in config.task)
315
358
  const task = input.task || config.task || undefined;
316
359
  // Determine model using ADR-026 3-tier routing logic
@@ -0,0 +1,15 @@
1
+ /**
2
+ * agentdb_hierarchical-list / agentdb_hierarchical-get (#4712).
3
+ *
4
+ * Read-only inventory over the persisted `tiered_memory` table behind
5
+ * agentdb_hierarchical-store. agentdb_hierarchical-recall ranks by relevance
6
+ * over a capped in-memory view, so it cannot enumerate what is stored or read
7
+ * an entry back by id; these tools can. Needs @claude-flow/memory >= 3.3.0.
8
+ *
9
+ * @module v3/cli/mcp-tools/agentdb-hierarchical-inventory-tools
10
+ */
11
+ import type { MCPTool } from './types.js';
12
+ export declare const agentdbHierarchicalList: MCPTool;
13
+ export declare const agentdbHierarchicalGet: MCPTool;
14
+ export declare const agentdbHierarchicalInventoryTools: MCPTool[];
15
+ //# sourceMappingURL=agentdb-hierarchical-inventory-tools.d.ts.map
@@ -0,0 +1,115 @@
1
+ /**
2
+ * agentdb_hierarchical-list / agentdb_hierarchical-get (#4712).
3
+ *
4
+ * Read-only inventory over the persisted `tiered_memory` table behind
5
+ * agentdb_hierarchical-store. agentdb_hierarchical-recall ranks by relevance
6
+ * over a capped in-memory view, so it cannot enumerate what is stored or read
7
+ * an entry back by id; these tools can. Needs @claude-flow/memory >= 3.3.0.
8
+ *
9
+ * @module v3/cli/mcp-tools/agentdb-hierarchical-inventory-tools
10
+ */
11
+ const TIERS = ['working', 'episodic', 'semantic'];
12
+ const STATUSES = ['active', 'expired', 'superseded', 'archived', 'all'];
13
+ const MAX_LIMIT = 1000;
14
+ const CURSOR_MAX_LENGTH = 2048;
15
+ const ID_MAX_LENGTH = 1000;
16
+ let bridgeModule = null;
17
+ async function getBridge() {
18
+ bridgeModule ??= await import('../memory/memory-bridge.js');
19
+ return bridgeModule;
20
+ }
21
+ const unavailable = { success: false, error: 'AgentDB bridge not available. Use memory_list/memory_retrieve instead.' };
22
+ function fail(error) {
23
+ return { success: false, code: 'invalid-argument', error };
24
+ }
25
+ function errorMessage(error) {
26
+ return error instanceof Error ? error.message.replace(/\/[^\s:]+\//g, '<path>/').slice(0, 500) : 'Internal error';
27
+ }
28
+ export const agentdbHierarchicalList = {
29
+ name: 'agentdb_hierarchical-list',
30
+ description: 'Page through every persisted hierarchical-memory entry (the tiered_memory table behind agentdb_hierarchical-store), newest first, filtered by tier and status. Use when you need a complete inventory or audit of stored facts: agentdb_hierarchical-recall is wrong for that because it ranks by query relevance over an in-memory view capped at 5,000 entries per tier. status: active (default) = currently valid; expired = validity window closed or not yet open; superseded = invalidated by a newer fact; archived = archived without a superseding id; all = everything, each labelled. Pass nextCursor back as cursor for the next page; the cursor is opaque and only valid for the same tier and status. totalEstimate is an exact count for all/superseded/archived and is omitted for active/expired, which need a full scan. Read-only; refuses on a volatile (non-persistent) store.',
31
+ inputSchema: {
32
+ type: 'object',
33
+ properties: {
34
+ tier: { type: 'string', enum: [...TIERS], description: 'Only entries in this tier. Omit for all tiers.' },
35
+ status: {
36
+ type: 'string',
37
+ enum: [...STATUSES],
38
+ default: 'active',
39
+ description: 'active = valid now; expired = window closed or not yet open; superseded = replaced by a newer fact; archived = archived without a superseding id; all = every row with its status.',
40
+ },
41
+ limit: { type: 'number', minimum: 1, maximum: MAX_LIMIT, default: 100, description: `Page size, clamped to 1..${MAX_LIMIT}.` },
42
+ cursor: {
43
+ type: 'string',
44
+ maxLength: CURSOR_MAX_LENGTH,
45
+ description: 'Opaque nextCursor from the previous page. Must be reused with the same tier and status; an altered or foreign cursor is rejected. Omit to start from the newest entry.',
46
+ },
47
+ },
48
+ },
49
+ handler: async (params) => {
50
+ try {
51
+ const tier = params.tier;
52
+ if (tier !== undefined && !(typeof tier === 'string' && TIERS.includes(tier))) {
53
+ return fail(`tier must be one of ${TIERS.join(', ')}`);
54
+ }
55
+ const status = params.status ?? 'active';
56
+ if (!(typeof status === 'string' && STATUSES.includes(status))) {
57
+ return fail(`status must be one of ${STATUSES.join(', ')}`);
58
+ }
59
+ const limit = params.limit;
60
+ if (limit !== undefined && (typeof limit !== 'number' || !Number.isFinite(limit))) {
61
+ return fail('limit must be a number');
62
+ }
63
+ const cursor = params.cursor;
64
+ if (cursor !== undefined && (typeof cursor !== 'string' || cursor.length === 0 || cursor.length > CURSOR_MAX_LENGTH)) {
65
+ return fail(`cursor must be a non-empty string of at most ${CURSOR_MAX_LENGTH} characters`);
66
+ }
67
+ const bridge = await getBridge();
68
+ const result = await bridge.bridgeHierarchicalList({
69
+ tier: tier,
70
+ status,
71
+ limit: limit === undefined ? undefined : Math.min(MAX_LIMIT, Math.max(1, Math.floor(limit))),
72
+ cursor: cursor,
73
+ });
74
+ return result ?? unavailable;
75
+ }
76
+ catch (error) {
77
+ return { success: false, error: errorMessage(error) };
78
+ }
79
+ },
80
+ };
81
+ export const agentdbHierarchicalGet = {
82
+ name: 'agentdb_hierarchical-get',
83
+ description: 'Read one persisted hierarchical-memory entry by its stable id (the id returned by agentdb_hierarchical-store or listed by agentdb_hierarchical-list) together with its status. Use when you hold an id and need that exact record: agentdb_hierarchical-recall is wrong for this because it matches query text, not ids, and memory_retrieve reads a different store. By default only an active entry is returned; set includeInactive=true to also read expired, superseded or archived history. found=false means no row with that id, or an inactive row without includeInactive. Read-only; refuses on a volatile (non-persistent) store.',
84
+ inputSchema: {
85
+ type: 'object',
86
+ properties: {
87
+ id: { type: 'string', minLength: 1, maxLength: ID_MAX_LENGTH, description: 'Stable entry id (e.g. tm_...). Keys are not accepted.' },
88
+ includeInactive: {
89
+ type: 'boolean',
90
+ default: false,
91
+ description: 'Also return expired, superseded or archived entries. Default false returns active entries only.',
92
+ },
93
+ },
94
+ required: ['id'],
95
+ },
96
+ handler: async (params) => {
97
+ try {
98
+ const id = params.id;
99
+ if (typeof id !== 'string' || id.length === 0 || id.length > ID_MAX_LENGTH) {
100
+ return fail(`id must be a non-empty string of at most ${ID_MAX_LENGTH} characters`);
101
+ }
102
+ if (params.includeInactive !== undefined && typeof params.includeInactive !== 'boolean') {
103
+ return fail('includeInactive must be a boolean');
104
+ }
105
+ const bridge = await getBridge();
106
+ const result = await bridge.bridgeHierarchicalGet({ id, includeInactive: params.includeInactive === true });
107
+ return result ?? unavailable;
108
+ }
109
+ catch (error) {
110
+ return { success: false, error: errorMessage(error) };
111
+ }
112
+ },
113
+ };
114
+ export const agentdbHierarchicalInventoryTools = [agentdbHierarchicalList, agentdbHierarchicalGet];
115
+ //# sourceMappingURL=agentdb-hierarchical-inventory-tools.js.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * agentdb_pattern-list / agentdb_skill-list / agentdb_skill-get /
3
+ * agentdb_hierarchical-stats (#4707).
4
+ *
5
+ * Read-only bindings over inventory APIs AgentDB already ships
6
+ * (ReasoningBank.listPatterns, SkillLibrary.listSkills/getSkill, agentdb >= 3.3.0)
7
+ * and the tiered store's counts (TieredMemoryStore.getTierStats/countPersisted).
8
+ * They go through the existing memory-bridge registry, so they read the same
9
+ * stores the write tools use. A controller or method the installed agentdb
10
+ * does not have comes back as `success: false, code: 'unsupported'`, never as
11
+ * an empty list.
12
+ *
13
+ * @module v3/cli/mcp-tools/agentdb-inventory-tools
14
+ */
15
+ import type { MCPTool } from './types.js';
16
+ export declare const agentdbPatternList: MCPTool;
17
+ export declare const agentdbSkillList: MCPTool;
18
+ export declare const agentdbSkillGet: MCPTool;
19
+ export declare const agentdbHierarchicalStats: MCPTool;
20
+ export declare const agentdbInventoryTools: MCPTool[];
21
+ //# sourceMappingURL=agentdb-inventory-tools.d.ts.map