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
@@ -5,19 +5,20 @@
5
5
  * Templates: minimal | standard | full | security | performance | solo
6
6
  * All templates use imperative rules and agent comms-first coordination.
7
7
  */
8
+ import { AGENTS_MD_IMPORT, CLAUDE_RULE_INSERT_AT, SHARED_RULE_LINES, DEFAULT_CLI, swarmRoutingBody, sharedAgentTypes, sharedBuildAndTest, sharedCliQuickRef, sharedMemoryAndLearning, } from './shared-instructions.js';
8
9
  // --- Section Generators ---
10
+ //
11
+ // #2638: sections both hosts share come from shared-instructions.ts (the
12
+ // mirror of the codex module that writes them into AGENTS.md). Everything
13
+ // left in this file is Claude-specific, or a template extra.
14
+ /** How this file's sections invoke the CLI (single-host CLAUDE.md form). */
15
+ const CLI = 'npx @claude-flow/cli@latest';
16
+ /** Claude-only: the Claude Code Bash tool suggests this trailer; Codex has its own commit rule. */
17
+ const CO_AUTHORED_BY_RULE = '- NEVER add a `Co-Authored-By` trailer to user commits unless this project\'s `.claude/settings.json` has `attribution.commit` set (#2078). The Claude Code Bash tool may suggest one in its default commit-message template — ignore it. `Co-Authored-By` is semantic authorship attribution under git/GitHub convention; the tool is the facilitator, not a co-author.';
9
18
  function behavioralRules() {
10
- return `## Rules
11
-
12
- - Do what has been asked; nothing more, nothing less
13
- - NEVER create files unless absolutely necessary — prefer editing existing files
14
- - NEVER create documentation files unless explicitly requested
15
- - NEVER save working files or tests to root — use \`/src\`, \`/tests\`, \`/docs\`, \`/config\`, \`/scripts\`
16
- - ALWAYS read a file before editing it
17
- - NEVER commit secrets, credentials, or .env files
18
- - NEVER add a \`Co-Authored-By\` trailer to user commits unless this project's \`.claude/settings.json\` has \`attribution.commit\` set (#2078). The Claude Code Bash tool may suggest one in its default commit-message template — ignore it. \`Co-Authored-By\` is semantic authorship attribution under git/GitHub convention; the tool is the facilitator, not a co-author.
19
- - Keep files under 500 lines
20
- - Validate input at system boundaries`;
19
+ const lines = [...SHARED_RULE_LINES];
20
+ lines.splice(CLAUDE_RULE_INSERT_AT, 0, CO_AUTHORED_BY_RULE);
21
+ return `## Rules\n\n${lines.join('\n')}`;
21
22
  }
22
23
  function policyGovernedWorkflow() {
23
24
  return `## Ruflo Capability Brain & Implementation Loop
@@ -109,110 +110,29 @@ SendMessage({ to: "researcher", summary: "Start", message: "[task context]" })
109
110
  - Do not poll repeatedly — agents message back or complete automatically
110
111
  - Give every writing agent an isolated worktree and a non-overlapping file scope`;
111
112
  }
112
- function swarmConfig(options) {
113
- return `## Swarm & Routing
114
-
115
- ### Config
113
+ function swarmRuntimeConfig(options) {
114
+ return `### Config
116
115
  - **Topology**: ${options.runtime.topology} (anti-drift)
117
116
  - **Max Agents**: ${options.runtime.maxAgents}
118
117
  - **Memory**: ${options.runtime.memoryBackend}
119
118
  - **HNSW**: ${options.runtime.enableHNSW ? 'Enabled' : 'Disabled'}
120
- - **Neural**: ${options.runtime.enableNeural ? 'Enabled' : 'Disabled'}
121
-
122
- \`\`\`bash
123
- npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
124
- \`\`\`
125
-
126
- ### Agent Routing
127
-
128
- | Task | Agents | Topology |
129
- |------|--------|----------|
130
- | Bug Fix | researcher, coder, tester | hierarchical |
131
- | Feature | architect, coder, tester, reviewer | hierarchical |
132
- | Refactor | architect, coder, reviewer | hierarchical |
133
- | Performance | perf-engineer, coder | hierarchical |
134
- | Security | security-architect, auditor | hierarchical |
135
-
136
- ### When to Swarm
137
- - **YES**: 3+ files, new features, cross-module refactoring, API changes, security, performance
138
- - **NO**: single file edits, 1-2 line fixes, docs updates, config changes, questions
139
-
140
- ### 3-Tier Model Routing
119
+ - **Neural**: ${options.runtime.enableNeural ? 'Enabled' : 'Disabled'}`;
120
+ }
121
+ /** Claude-only: the tiers map onto Claude Code's Agent tool `model` choices. */
122
+ const THREE_TIER_ROUTING = `### 3-Tier Model Routing
141
123
 
142
124
  | Tier | Handler | Use Cases |
143
125
  |------|---------|-----------|
144
126
  | 1 | Agent Booster (WASM) | Simple transforms — skip LLM, use Edit directly |
145
127
  | 2 | Haiku | Simple tasks, low complexity |
146
128
  | 3 | Sonnet/Opus | Architecture, security, complex reasoning |`;
129
+ function swarmConfig(options) {
130
+ return `## Swarm & Routing\n\n${swarmRuntimeConfig(options)}\n\n${swarmRoutingBody(CLI)}\n\n${THREE_TIER_ROUTING}`;
147
131
  }
148
- function memoryAndLearning() {
149
- return `## Memory & Learning
150
-
151
- ### Before Any Task
152
- \`\`\`bash
153
- npx @claude-flow/cli@latest memory search --query "[task keywords]" --namespace patterns
154
- npx @claude-flow/cli@latest hooks route --task "[task description]"
155
- \`\`\`
156
-
157
- ### After Success
158
- \`\`\`bash
159
- npx @claude-flow/cli@latest memory store --namespace patterns --key "[name]" --value "[what worked]"
160
- npx @claude-flow/cli@latest hooks post-task --task-id "[id]" --success true --store-results true
161
- \`\`\`
162
-
163
- ### MCP Tools (use \`ToolSearch("keyword")\` to discover)
164
-
165
- | Category | Key Tools |
166
- |----------|-----------|
167
- | **Memory** | \`memory_store\`, \`memory_search\`, \`memory_search_unified\` |
168
- | **Bridge** | \`memory_import_claude\`, \`memory_bridge_status\` |
169
- | **Swarm** | \`swarm_init\`, \`swarm_status\`, \`swarm_health\` |
170
- | **Agents** | \`agent_spawn\`, \`agent_list\`, \`agent_status\` |
171
- | **Hooks** | \`hooks_route\`, \`hooks_post-task\`, \`hooks_worker-dispatch\` |
172
- | **Security** | \`aidefence_scan\`, \`aidefence_is_safe\`, \`aidefence_has_pii\` |
173
- | **Hive-Mind** | \`hive-mind_init\`, \`hive-mind_consensus\`, \`hive-mind_spawn\` |
174
-
175
- ### Background Workers
176
-
177
- | Worker | When |
178
- |--------|------|
179
- | \`audit\` | After security changes |
180
- | \`optimize\` | After performance work |
181
- | \`testgaps\` | After adding features |
182
- | \`map\` | Every 5+ file changes |
183
- | \`document\` | After API changes |
184
-
185
- \`\`\`bash
186
- npx @claude-flow/cli@latest hooks worker dispatch --trigger audit
187
- \`\`\``;
188
- }
189
- function agentTypes() {
190
- return `## Agents
191
-
192
- **Core**: \`coder\`, \`reviewer\`, \`tester\`, \`planner\`, \`researcher\`
193
- **Architecture**: \`system-architect\`, \`backend-dev\`, \`mobile-dev\`
194
- **Security**: \`security-architect\`, \`security-auditor\`
195
- **Performance**: \`performance-engineer\`, \`perf-analyzer\`
196
- **Coordination**: \`hierarchical-coordinator\`, \`mesh-coordinator\`, \`adaptive-coordinator\`
197
- **GitHub**: \`pr-manager\`, \`code-review-swarm\`, \`issue-tracker\`, \`release-manager\`
198
-
199
- Any string works as a custom agent type.`;
200
- }
201
- function cliQuickRef() {
202
- return `## CLI Quick Reference
203
-
204
- \`\`\`bash
205
- npx @claude-flow/cli@latest init --wizard # Setup
206
- npx @claude-flow/cli@latest swarm init --v3-mode # Start swarm
207
- npx @claude-flow/cli@latest memory search --query "" # Vector search
208
- npx @claude-flow/cli@latest hooks route --task "" # Route to agent
209
- npx @claude-flow/cli@latest doctor --fix # Diagnostics
210
- npx @claude-flow/cli@latest security scan # Security scan
211
- npx @claude-flow/cli@latest performance benchmark # Benchmarks
212
- \`\`\`
213
-
214
- 26 commands, 140+ subcommands. Use \`--help\` on any command for details.`;
215
- }
132
+ const memoryAndLearning = () => sharedMemoryAndLearning(CLI);
133
+ const agentTypes = sharedAgentTypes;
134
+ const cliQuickRef = () => sharedCliQuickRef(CLI);
135
+ const buildAndTest = sharedBuildAndTest;
216
136
  function setupAndBoundary() {
217
137
  return `## Setup
218
138
 
@@ -228,16 +148,6 @@ npx ruflo@latest doctor --fix
228
148
 
229
149
  **Agent tool** handles execution (agents, files, code, git). **MCP tools** handle coordination (swarm, memory, hooks). **CLI** is the same via Bash.`;
230
150
  }
231
- function buildAndTest() {
232
- return `## Build & Test
233
-
234
- - ALWAYS run tests after code changes
235
- - ALWAYS verify build succeeds before committing
236
-
237
- \`\`\`bash
238
- npm run build && npm test
239
- \`\`\``;
240
- }
241
151
  function securitySection() {
242
152
  return `## Security
243
153
 
@@ -407,6 +317,46 @@ export function generateClaudeMd(options, template) {
407
317
  export function generateMinimalClaudeMd(options) {
408
318
  return generateClaudeMd(options, 'minimal');
409
319
  }
320
+ /**
321
+ * The shared sections, with the CLI invoked as `cli`. With the default (this
322
+ * file's form) they are what a CLAUDE.md importing AGENTS.md must not repeat;
323
+ * with `AGENTS_MD_CLI` they are exactly what the codex generator writes into
324
+ * AGENTS.md.
325
+ */
326
+ export function sharedSectionsForImport(cli = CLI) {
327
+ return [
328
+ `## Rules\n\n${SHARED_RULE_LINES.join('\n')}`,
329
+ `## Swarm & Routing\n\n${swarmRoutingBody(cli)}`,
330
+ sharedMemoryAndLearning(cli),
331
+ sharedAgentTypes(),
332
+ sharedBuildAndTest(),
333
+ sharedCliQuickRef(cli),
334
+ ];
335
+ }
336
+ /** How the codex generator writes the CLI invocation into AGENTS.md. */
337
+ export const AGENTS_MD_CLI = DEFAULT_CLI;
338
+ /**
339
+ * #2638 dual mode: CLAUDE.md imports AGENTS.md (which carries the shared
340
+ * sections) and keeps only what is Claude-specific, plus any template extras
341
+ * the shared set does not cover. Nothing here repeats a shared section.
342
+ */
343
+ export function generateDualClaudeMd(options, template) {
344
+ const tmpl = template ?? options.runtime.claudeMdTemplate ?? 'standard';
345
+ const sections = TEMPLATE_SECTIONS[tmpl] ?? TEMPLATE_SECTIONS.standard;
346
+ const shared = new Set(sharedSectionsForImport());
347
+ const body = sections.map((fn) => {
348
+ if (fn === behavioralRules)
349
+ return `## Claude Code Rules\n\n${CO_AUTHORED_BY_RULE}`;
350
+ if (fn === swarmConfig)
351
+ return `## Swarm Runtime & Model Routing\n\n${swarmRuntimeConfig(options)}\n\n${THREE_TIER_ROUTING}`;
352
+ const text = fn(options);
353
+ return shared.has(text) ? null : text;
354
+ }).filter((s) => s !== null).join('\n\n');
355
+ const header = `# Ruflo — Claude Code Configuration\n\n${AGENTS_MD_IMPORT}\n\n` +
356
+ '> Shared project instructions live in `AGENTS.md`, imported above; OpenAI Codex reads the same file. ' +
357
+ 'Edit shared rules there. This file holds only Claude Code–specific guidance.\n';
358
+ return `${header}\n${body}\n`;
359
+ }
410
360
  export const CLAUDE_MD_TEMPLATES = [
411
361
  { name: 'minimal', description: 'Lean start — rules, agent comms, swarm config, CLI ref (~80 lines)' },
412
362
  { name: 'standard', description: 'Recommended — adds memory, learning, agent types (~140 lines)' },
@@ -0,0 +1,29 @@
1
+ /**
2
+ * #2638 — dual-host instructions with one source.
3
+ *
4
+ * `init --dual` makes AGENTS.md the single source for the sections both hosts
5
+ * share. CLAUDE.md becomes Claude Code's `@AGENTS.md` import plus only the
6
+ * Claude-specific sections. Two steps:
7
+ *
8
+ * 1. writeDualClaudeMd (Claude pass) writes the import form, but only over a
9
+ * CLAUDE.md that is missing, already ours and unmodified, or --force.
10
+ * 2. finalizeDualInstructions (after the Codex pass) checks that AGENTS.md
11
+ * really carries every shared section. If it does not (Codex init failed,
12
+ * or an older @claude-flow/codex wrote the single-host AGENTS.md), the full
13
+ * single-host CLAUDE.md is written back, so nothing is lost.
14
+ */
15
+ import type { InitOptions, InitResult } from './types.js';
16
+ export declare const DUAL_MIGRATION_HINT: string;
17
+ /** Claude pass of `init --dual`: write CLAUDE.md as the AGENTS.md import form when it is safe to. */
18
+ export declare function writeDualClaudeMd(claudeMdPath: string, options: InitOptions, result: InitResult): void;
19
+ export interface DualFinalizeOutcome {
20
+ /** `import`: CLAUDE.md imports AGENTS.md. `restored`: full CLAUDE.md written back. `none`: nothing to do. */
21
+ action: 'import' | 'restored' | 'none';
22
+ message?: string;
23
+ }
24
+ /**
25
+ * After the Codex pass: keep the import form only when AGENTS.md carries every
26
+ * shared section verbatim. Never touches a CLAUDE.md this run did not write.
27
+ */
28
+ export declare function finalizeDualInstructions(targetDir: string, claudeResult: InitResult | undefined): DualFinalizeOutcome;
29
+ //# sourceMappingURL=dual-instructions.d.ts.map
@@ -0,0 +1,87 @@
1
+ /**
2
+ * #2638 — dual-host instructions with one source.
3
+ *
4
+ * `init --dual` makes AGENTS.md the single source for the sections both hosts
5
+ * share. CLAUDE.md becomes Claude Code's `@AGENTS.md` import plus only the
6
+ * Claude-specific sections. Two steps:
7
+ *
8
+ * 1. writeDualClaudeMd (Claude pass) writes the import form, but only over a
9
+ * CLAUDE.md that is missing, already ours and unmodified, or --force.
10
+ * 2. finalizeDualInstructions (after the Codex pass) checks that AGENTS.md
11
+ * really carries every shared section. If it does not (Codex init failed,
12
+ * or an older @claude-flow/codex wrote the single-host AGENTS.md), the full
13
+ * single-host CLAUDE.md is written back, so nothing is lost.
14
+ */
15
+ import * as fs from 'fs';
16
+ import * as path from 'path';
17
+ import { AGENTS_MD_CLI, generateClaudeMd, generateDualClaudeMd, sharedSectionsForImport } from './claudemd-generator.js';
18
+ import { importsAgentsMd } from './shared-instructions.js';
19
+ export const DUAL_MIGRATION_HINT = 'to share instructions with Codex, move your custom sections into AGENTS.md and replace the shared ones ' +
20
+ 'with a line `@AGENTS.md`, or re-run with --force (the current file is backed up to CLAUDE.md.pre-ruflo)';
21
+ function inferredTemplate(options) {
22
+ return (!options.components.commands && !options.components.agents) ? 'minimal' : undefined;
23
+ }
24
+ function backup(claudeMdPath, result) {
25
+ const base = `${claudeMdPath}.pre-ruflo`;
26
+ const target = fs.existsSync(base) ? `${base}.${Date.now()}` : base;
27
+ fs.copyFileSync(claudeMdPath, target);
28
+ result.created.files.push(path.basename(target));
29
+ }
30
+ /** Claude pass of `init --dual`: write CLAUDE.md as the AGENTS.md import form when it is safe to. */
31
+ export function writeDualClaudeMd(claudeMdPath, options, result) {
32
+ const template = inferredTemplate(options);
33
+ const fullForm = generateClaudeMd(options, template);
34
+ const importForm = generateDualClaudeMd(options, template);
35
+ if (fs.existsSync(claudeMdPath)) {
36
+ const existing = fs.readFileSync(claudeMdPath, 'utf-8');
37
+ if (existing === importForm || (importsAgentsMd(existing) && !options.force)) {
38
+ result.skipped.push('CLAUDE.md (already imports AGENTS.md)');
39
+ return;
40
+ }
41
+ const ours = existing === fullForm;
42
+ if (!ours && !options.force) {
43
+ result.skipped.push(`CLAUDE.md (has your own content; ${DUAL_MIGRATION_HINT})`);
44
+ return;
45
+ }
46
+ if (!ours)
47
+ backup(claudeMdPath, result);
48
+ }
49
+ fs.writeFileSync(claudeMdPath, importForm, 'utf-8');
50
+ result.created.files.push('CLAUDE.md (imports AGENTS.md)');
51
+ result.dualInstructions = { importForm, fullForm };
52
+ }
53
+ /**
54
+ * After the Codex pass: keep the import form only when AGENTS.md carries every
55
+ * shared section verbatim. Never touches a CLAUDE.md this run did not write.
56
+ */
57
+ export function finalizeDualInstructions(targetDir, claudeResult) {
58
+ const dual = claudeResult?.dualInstructions;
59
+ if (!dual)
60
+ return { action: 'none' };
61
+ const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
62
+ let current;
63
+ try {
64
+ current = fs.readFileSync(claudeMdPath, 'utf-8');
65
+ }
66
+ catch {
67
+ return { action: 'none' };
68
+ }
69
+ if (current !== dual.importForm)
70
+ return { action: 'none' };
71
+ let agentsMd = '';
72
+ try {
73
+ agentsMd = fs.readFileSync(path.join(targetDir, 'AGENTS.md'), 'utf-8');
74
+ }
75
+ catch { /* missing AGENTS.md: handled below */ }
76
+ const missing = sharedSectionsForImport(AGENTS_MD_CLI).filter((section) => !agentsMd.includes(section));
77
+ if (missing.length === 0) {
78
+ return { action: 'import', message: 'CLAUDE.md imports AGENTS.md (shared sections live once, in AGENTS.md)' };
79
+ }
80
+ fs.writeFileSync(claudeMdPath, dual.fullForm, 'utf-8');
81
+ return {
82
+ action: 'restored',
83
+ message: `AGENTS.md is missing ${missing.length} shared section(s) (Codex init failed, or an older @claude-flow/codex ran), ` +
84
+ 'so the full CLAUDE.md was kept instead of the @AGENTS.md import',
85
+ };
86
+ }
87
+ //# sourceMappingURL=dual-instructions.js.map
@@ -17,6 +17,8 @@ import { generateStatuslineScript } from './statusline-generator.js';
17
17
  import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHookHandler, generateIntelligenceStub, generateAutoMemoryHook, generateRufloHookCjs, } from './helpers-generator.js';
18
18
  import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
19
19
  import { generateClaudeMd } from './claudemd-generator.js';
20
+ import { writeDualClaudeMd } from './dual-instructions.js';
21
+ import { detectRufloPlugins, emptyDedupReport } from './plugin-dedup.js';
20
22
  import { recordMemoryPackagePath } from './memory-package-resolver.js';
21
23
  import { COMMONJS_COMPANION_HELPERS, ensureCommonJsCompanions } from './helper-companions.js';
22
24
  import { scanSettingsForRisk, formatRiskFindingsAsWarnings, RISKY_SETTINGS_HINT } from './settings-risk-scanner.js';
@@ -215,6 +217,13 @@ export async function executeInit(options) {
215
217
  replaceUntrustedHelpers(targetDir, gate, sourceHelpers, result);
216
218
  }
217
219
  }
220
+ // #2640: what the installed ruflo plugins already ship (null: none installed,
221
+ // or --full). Read-only detection; any doubt means "copy as before".
222
+ const c = options.components;
223
+ const provided = options.deferToPlugins && (c.mcp || c.skills || c.commands || c.agents)
224
+ ? detectRufloPlugins(targetDir)
225
+ : null;
226
+ const dedup = provided ? emptyDedupReport(provided) : undefined;
218
227
  try {
219
228
  // Create directory structure
220
229
  await createDirectories(targetDir, options, result);
@@ -224,20 +233,22 @@ export async function executeInit(options) {
224
233
  }
225
234
  // Generate and write .mcp.json
226
235
  if (options.components.mcp) {
227
- await writeMCPConfig(targetDir, options, result);
236
+ await writeMCPConfig(targetDir, options, result, dedup);
228
237
  }
229
238
  // Copy skills
230
239
  if (options.components.skills) {
231
- await copySkills(targetDir, options, result);
240
+ await copySkills(targetDir, options, result, provided, dedup);
232
241
  }
233
242
  // Copy commands
234
243
  if (options.components.commands) {
235
- await copyCommands(targetDir, options, result);
244
+ await copyCommands(targetDir, options, result, provided, dedup);
236
245
  }
237
246
  // Copy agents
238
247
  if (options.components.agents) {
239
- await copyAgents(targetDir, options, result);
248
+ await copyAgents(targetDir, options, result, provided, dedup);
240
249
  }
250
+ if (dedup)
251
+ result.pluginDedup = dedup;
241
252
  // Generate helpers
242
253
  if (options.components.helpers) {
243
254
  await writeHelpers(targetDir, options, result);
@@ -1022,7 +1033,7 @@ function normalizeProjectKey(p) {
1022
1033
  /**
1023
1034
  * Write .mcp.json
1024
1035
  */
1025
- async function writeMCPConfig(targetDir, options, result) {
1036
+ async function writeMCPConfig(targetDir, options, result, dedup) {
1026
1037
  const mcpPath = path.join(targetDir, '.mcp.json');
1027
1038
  if (fs.existsSync(mcpPath) && !options.force) {
1028
1039
  // #2369: an existing .mcp.json from a pre-rename install is the most
@@ -1065,6 +1076,16 @@ async function writeMCPConfig(targetDir, options, result) {
1065
1076
  return;
1066
1077
  }
1067
1078
  }
1079
+ // #2640: ruflo-core provides the ruflo MCP server. A second, standalone
1080
+ // `claude-flow` server against the same project is a second writer on the
1081
+ // same memory DB. Keep any other servers the preset asks for. Checked after
1082
+ // the guards above, so it is only reported when init would have written it.
1083
+ if (dedup && options.mcp.claudeFlow) {
1084
+ dedup.mcpServerSkipped = true;
1085
+ options = { ...options, mcp: { ...options.mcp, claudeFlow: false } };
1086
+ if (!options.mcp.ruvSwarm && !options.mcp.flowNexus)
1087
+ return;
1088
+ }
1068
1089
  const content = generateMCPJson(options);
1069
1090
  fs.writeFileSync(mcpPath, content, 'utf-8');
1070
1091
  result.created.files.push('.mcp.json');
@@ -1072,7 +1093,7 @@ async function writeMCPConfig(targetDir, options, result) {
1072
1093
  /**
1073
1094
  * Copy skills from source
1074
1095
  */
1075
- async function copySkills(targetDir, options, result) {
1096
+ async function copySkills(targetDir, options, result, provided = null, dedup) {
1076
1097
  const skillsConfig = options.skills;
1077
1098
  const targetSkillsDir = path.join(targetDir, '.claude', 'skills');
1078
1099
  // Determine which skills to copy
@@ -1109,6 +1130,10 @@ async function copySkills(targetDir, options, result) {
1109
1130
  }
1110
1131
  // Copy each skill
1111
1132
  for (const skillName of [...new Set(skillsToCopy)]) {
1133
+ if (provided?.skills.has(skillName)) {
1134
+ dedup?.skipped.skills.push(skillName);
1135
+ continue;
1136
+ }
1112
1137
  const sourcePath = path.join(sourceSkillsDir, skillName);
1113
1138
  const targetPath = path.join(targetSkillsDir, skillName);
1114
1139
  if (fs.existsSync(sourcePath)) {
@@ -1126,7 +1151,7 @@ async function copySkills(targetDir, options, result) {
1126
1151
  /**
1127
1152
  * Copy commands from source
1128
1153
  */
1129
- async function copyCommands(targetDir, options, result) {
1154
+ async function copyCommands(targetDir, options, result, provided = null, dedup) {
1130
1155
  const commandsConfig = options.commands;
1131
1156
  const targetCommandsDir = path.join(targetDir, '.claude', 'commands');
1132
1157
  // Determine which commands to copy
@@ -1189,7 +1214,19 @@ async function copyCommands(targetDir, options, result) {
1189
1214
  if (fs.existsSync(sourcePath)) {
1190
1215
  if (!fs.existsSync(targetPath) || options.force) {
1191
1216
  if (fs.statSync(sourcePath).isDirectory()) {
1192
- copyDirRecursive(sourcePath, targetPath);
1217
+ if (provided) {
1218
+ // #2640: leave out the commands an installed plugin already ships.
1219
+ const copied = copyDirSkipping(sourcePath, targetPath, provided.commands, dedup?.skipped.commands ?? []);
1220
+ if (copied === 0)
1221
+ continue;
1222
+ }
1223
+ else {
1224
+ copyDirRecursive(sourcePath, targetPath);
1225
+ }
1226
+ }
1227
+ else if (provided?.commands.has(path.basename(cmdName))) {
1228
+ dedup?.skipped.commands.push(cmdName);
1229
+ continue;
1193
1230
  }
1194
1231
  else {
1195
1232
  fs.copyFileSync(sourcePath, targetPath);
@@ -1206,7 +1243,7 @@ async function copyCommands(targetDir, options, result) {
1206
1243
  /**
1207
1244
  * Copy agents from source
1208
1245
  */
1209
- async function copyAgents(targetDir, options, result) {
1246
+ async function copyAgents(targetDir, options, result, provided = null, dedup) {
1210
1247
  const agentsConfig = options.agents;
1211
1248
  const targetAgentsDir = path.join(targetDir, '.claude', 'agents');
1212
1249
  // Determine which agents to copy
@@ -1252,9 +1289,18 @@ async function copyAgents(targetDir, options, result) {
1252
1289
  const targetPath = path.join(targetAgentsDir, agentCategory);
1253
1290
  if (fs.existsSync(sourcePath)) {
1254
1291
  if (!fs.existsSync(targetPath) || options.force) {
1255
- copyDirRecursive(sourcePath, targetPath);
1256
- // Count agent files (.md only — .yaml agents were migrated to .md)
1257
- const mdFiles = countFiles(sourcePath, '.md');
1292
+ let mdFiles;
1293
+ if (provided) {
1294
+ // #2640: leave out the agents an installed plugin already ships.
1295
+ mdFiles = copyDirSkipping(sourcePath, targetPath, provided.agents, dedup?.skipped.agents ?? []);
1296
+ if (mdFiles === 0)
1297
+ continue;
1298
+ }
1299
+ else {
1300
+ copyDirRecursive(sourcePath, targetPath);
1301
+ // Count agent files (.md only — .yaml agents were migrated to .md)
1302
+ mdFiles = countFiles(sourcePath, '.md');
1303
+ }
1258
1304
  result.summary.agentsCount += mdFiles;
1259
1305
  result.created.files.push(`.claude/agents/${agentCategory}`);
1260
1306
  }
@@ -2120,7 +2166,10 @@ npx ruflo@latest hooks worker dispatch --trigger optimize
2120
2166
  */
2121
2167
  async function writeClaudeMd(targetDir, options, result) {
2122
2168
  const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
2123
- if (fs.existsSync(claudeMdPath) && !options.force) {
2169
+ if (options.instructionsSource === 'agents-md') {
2170
+ writeDualClaudeMd(claudeMdPath, options, result);
2171
+ }
2172
+ else if (fs.existsSync(claudeMdPath) && !options.force) {
2124
2173
  result.skipped.push('CLAUDE.md');
2125
2174
  }
2126
2175
  else {
@@ -2249,6 +2298,40 @@ function copyDirRecursive(src, dest) {
2249
2298
  }
2250
2299
  }
2251
2300
  }
2301
+ /**
2302
+ * #2640: copy a bundle directory, leaving out every `.md` whose basename an
2303
+ * installed plugin provides. Returns the number of agent/command `.md` files
2304
+ * copied (README.md excluded); writes nothing at all when that is zero.
2305
+ */
2306
+ function copyDirSkipping(src, dest, provided, skipped) {
2307
+ const plan = [];
2308
+ let kept = 0;
2309
+ const walk = (from, to) => {
2310
+ for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
2311
+ const srcPath = path.join(from, entry.name);
2312
+ const destPath = path.join(to, entry.name);
2313
+ if (entry.isDirectory()) {
2314
+ walk(srcPath, destPath);
2315
+ }
2316
+ else if (entry.name.endsWith('.md') && provided.has(entry.name)) {
2317
+ skipped.push(entry.name.replace(/\.md$/, ''));
2318
+ }
2319
+ else {
2320
+ plan.push([srcPath, destPath]);
2321
+ if (entry.name.endsWith('.md') && entry.name !== 'README.md')
2322
+ kept++;
2323
+ }
2324
+ }
2325
+ };
2326
+ walk(src, dest);
2327
+ if (kept === 0)
2328
+ return 0;
2329
+ for (const [from, to] of plan) {
2330
+ fs.mkdirSync(path.dirname(to), { recursive: true });
2331
+ fs.copyFileSync(from, to);
2332
+ }
2333
+ return kept;
2334
+ }
2252
2335
  /**
2253
2336
  * Count files with extension in directory
2254
2337
  */
@@ -7,7 +7,9 @@ export { generateSettings, generateSettingsJson, } from './settings-generator.js
7
7
  export { generateMCPConfig, generateMCPJson, generateMCPCommands, } from './mcp-generator.js';
8
8
  export { generateStatuslineScript, generateStatuslineHook, } from './statusline-generator.js';
9
9
  export { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHelpers, generateWindowsDaemonManager, generateWindowsBatchWrapper, generateCrossPlatformSessionManager, } from './helpers-generator.js';
10
- export { generateClaudeMd, generateMinimalClaudeMd, CLAUDE_MD_TEMPLATES, } from './claudemd-generator.js';
10
+ export { generateClaudeMd, generateMinimalClaudeMd, generateDualClaudeMd, CLAUDE_MD_TEMPLATES, } from './claudemd-generator.js';
11
+ export { finalizeDualInstructions, type DualFinalizeOutcome } from './dual-instructions.js';
12
+ export { detectRufloPlugins, formatPluginDedupSummary, RUFLO_CORE_PLUGIN } from './plugin-dedup.js';
11
13
  export { executeInit, executeUpgrade, executeUpgradeWithMissing, default } from './executor.js';
12
14
  export type { UpgradeResult } from './executor.js';
13
15
  export { executeGrokInit } from './grok-generator.js';
@@ -9,7 +9,11 @@ export { generateSettings, generateSettingsJson, } from './settings-generator.js
9
9
  export { generateMCPConfig, generateMCPJson, generateMCPCommands, } from './mcp-generator.js';
10
10
  export { generateStatuslineScript, generateStatuslineHook, } from './statusline-generator.js';
11
11
  export { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHelpers, generateWindowsDaemonManager, generateWindowsBatchWrapper, generateCrossPlatformSessionManager, } from './helpers-generator.js';
12
- export { generateClaudeMd, generateMinimalClaudeMd, CLAUDE_MD_TEMPLATES, } from './claudemd-generator.js';
12
+ export { generateClaudeMd, generateMinimalClaudeMd, generateDualClaudeMd, CLAUDE_MD_TEMPLATES, } from './claudemd-generator.js';
13
+ // #2638 dual-host instructions (AGENTS.md is the single source)
14
+ export { finalizeDualInstructions } from './dual-instructions.js';
15
+ // #2640 init defers to installed ruflo plugins
16
+ export { detectRufloPlugins, formatPluginDedupSummary, RUFLO_CORE_PLUGIN } from './plugin-dedup.js';
13
17
  // Main executor
14
18
  export { executeInit, executeUpgrade, executeUpgradeWithMissing, default } from './executor.js';
15
19
  // Grok Build host (ADR-402)
@@ -0,0 +1,61 @@
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 { type ReadFs } from '../mods/plugin-resolve.js';
16
+ export declare const RUFLO_CORE_PLUGIN = "ruflo-core@ruflo";
17
+ export interface DirEntry {
18
+ name: string;
19
+ isDirectory: boolean;
20
+ }
21
+ /** Filesystem reads detection needs; injectable for tests. */
22
+ export interface DedupFs extends ReadFs {
23
+ listDir(path: string): DirEntry[];
24
+ }
25
+ export declare const nodeDedupFs: DedupFs;
26
+ /** What the installed plugins already provide, by the name Claude Code loads it under. */
27
+ export interface PluginProvided {
28
+ /** Installed `*@ruflo` plugin ids that contributed. */
29
+ plugins: string[];
30
+ /** agent / command basename (with `.md`) → plugin id */
31
+ agents: Map<string, string>;
32
+ commands: Map<string, string>;
33
+ /** skill directory name → plugin id */
34
+ skills: Map<string, string>;
35
+ }
36
+ export interface DetectOptions {
37
+ configDir?: string;
38
+ env?: NodeJS.ProcessEnv;
39
+ home?: string;
40
+ fs?: DedupFs;
41
+ }
42
+ /**
43
+ * The agents, commands and skills the installed ruflo plugins provide for
44
+ * this project, or `null` when `ruflo-core@ruflo` is not installed and
45
+ * enabled here (then init behaves exactly as before).
46
+ */
47
+ export declare function detectRufloPlugins(projectRoot: string, opts?: DetectOptions): PluginProvided | null;
48
+ /** Init's record of what it left to the plugins. */
49
+ export interface PluginDedupReport {
50
+ plugins: string[];
51
+ skipped: {
52
+ agents: string[];
53
+ commands: string[];
54
+ skills: string[];
55
+ };
56
+ mcpServerSkipped: boolean;
57
+ }
58
+ export declare function emptyDedupReport(provided: PluginProvided): PluginDedupReport;
59
+ /** Lines for the summary `ruflo init` prints. Empty when nothing was skipped. */
60
+ export declare function formatPluginDedupSummary(report: PluginDedupReport): string[];
61
+ //# sourceMappingURL=plugin-dedup.d.ts.map