@mfjjs/ruflo-setup 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @mfjjs/ruflo-setup
+
+Cross-platform npm CLI to bootstrap a project with Ruflo on Windows and Linux.
+
+## What this project is
+
+`@mfjjs/ruflo-setup` replaces the old PowerShell-only bootstrap script with a Node-based CLI command:
+
+- Package name: `@mfjjs/ruflo-setup`
+- Command name: `ruflo-setup`
+- Platform support: Windows and Linux (plus macOS by default)
+
+## Project structure
+
+- `package.json`: npm metadata, scripts, and `bin` mapping
+- `bin/ruflo-setup.js`: executable entry file the shell runs
+- `src/cli.js`: command router and argument handling
+- `src/setup.js`: setup workflow (`init`, `.mcp.json`, template copy)
+- `src/hooks.js`: global `check-ruflo` hook install/status
+- `src/utils.js`: reusable filesystem and argument helpers
+- `templates/CLAUDE.md`: bundled template copied into target project
+- `claude-hooks/check-ruflo.cjs`: SessionStart hook payload
+- `tests/cli.test.mjs`: smoke tests for CLI behavior
+
+## What the command line calls
+
+After install/link, `ruflo-setup` resolves to your package `bin` entry:
+
+```json
+{
+	"bin": {
+		"ruflo-setup": "./bin/ruflo-setup.js"
+	}
+}
+```
+
+The shell shim launches `bin/ruflo-setup.js`, which imports `src/cli.js`, which dispatches to setup or hook subcommands.
+
+## How the CLI entry point works
+
+Flow:
+
+1. `ruflo-setup` is invoked.
+2. npm/pnpm command shim runs `bin/ruflo-setup.js`.
+3. `bin/ruflo-setup.js` forwards args to `runCli(...)`.
+4. `src/cli.js` parses command and flags.
+5. `src/setup.js` runs setup steps:
+	 - optional `npx ruflo@latest init --full`
+	 - writes platform-aware `.mcp.json`
+	 - copies `templates/CLAUDE.md`
+	 - installs global SessionStart hook (unless skipped)
+
+## Usage
+
+```bash
+# full setup
+ruflo-setup
+
+# non-interactive
+ruflo-setup --yes
+
+# preview only
+ruflo-setup --dry-run --skip-init
+
+# skip global hook install
+ruflo-setup --no-hooks
+
+# hook operations
+ruflo-setup hooks install
+ruflo-setup hooks status
+```
+
+## Local development with pnpm
+
+From this repository root (`setup-ruflo/`):
+
+```bash
+pnpm install
+pnpm test
+pnpm run test:cli
+```
+
+## Link locally so command works everywhere
+
+```bash
+# from setup-ruflo/
+pnpm link --global
+
+# now use from any folder
+ruflo-setup --dry-run --skip-init
+```
+
+This is the fast edit loop: change files in `src/`, rerun `ruflo-setup`, and behavior updates immediately without reinstall.
+
+## Simulate a real install (deploy-style testing)
+
+Create a tarball and install it into a clean test location.
+
+```bash
+# from setup-ruflo/
+pnpm pack
+
+# then in a clean temp folder
+pnpm add -g ./mfjjs-ruflo-setup-0.1.0.tgz
+ruflo-setup --dry-run --skip-init
+```
+
+This tests exactly what users get from a package install.
+
+## Global hook behavior
+
+`ruflo-setup` installs a global Claude SessionStart command hook that runs:
+
+- `claude-hooks/check-ruflo.cjs`
+
+It merges into existing global settings instead of replacing them, and creates a backup of the settings file before writing.
+
+## Legacy note
+
+`setup-ruflo.ps1` remains in the repository as historical reference, but the npm CLI is now the primary path.

package/bin/ruflo-setup.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+const exitCode = await runCli(process.argv.slice(2), process.cwd());
+process.exit(exitCode);

package/claude-hooks/check-ruflo.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * check-ruflo.cjs
+ * Global Claude Code SessionStart hook.
+ * Checks if the current project has Ruflo configured.
+ * If not, prints a notice that Claude sees as a <system-reminder>.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const cwd = process.cwd();
+const mcpJson = path.join(cwd, '.mcp.json');
+const claudeSettings = path.join(cwd, '.claude', 'settings.json');
+
+const isConfigured = fs.existsSync(mcpJson) || fs.existsSync(claudeSettings);
+
+if (!isConfigured) {
+  const msg =
+    '[RUFLO] This project is not configured with Ruflo + Claude Flow. ' +
+    'IMPORTANT: Before responding to anything else, tell the user this project is not configured with Ruflo + Claude Flow ' +
+    'and offer to set it up via /ruflo-setup.\n';
+  process.stdout.write(msg);
+}
+
+process.exit(0);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mfjjs/ruflo-setup",
+  "version": "0.1.0",
+  "description": "Cross-platform setup CLI for Ruflo + Claude Flow projects",
+  "type": "module",
+  "bin": {
+    "ruflo-setup": "./bin/ruflo-setup.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "claude-hooks"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "ruflo",
+    "claude-flow",
+    "cli",
+    "setup"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "lint": "node --check ./src/cli.js && node --check ./src/setup.js && node --check ./src/hooks.js && node --check ./src/utils.js && node --check ./bin/ruflo-setup.js",
+    "test": "node --test tests/cli.test.mjs",
+    "test:cli": "node ./bin/ruflo-setup.js --dry-run --skip-init --no-hooks --yes",
+    "pack:dry": "pnpm pack --dry-run"
+  }
+}

package/src/cli.js

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './utils.js';
+import { runSetup } from './setup.js';
+import { getGlobalHookStatus, installGlobalCheckRufloHook } from './hooks.js';
+
+function printHelp() {
+  process.stdout.write(`
+@mfjjs/ruflo-setup
+
+Usage:
+  ruflo-setup [options]
+  ruflo-setup hooks install [options]
+  ruflo-setup hooks status
+
+Options:
+  --force, -f      Overwrite existing config without prompt
+  --dry-run        Show actions without making changes
+  --yes, -y        Non-interactive yes for prompts
+  --no-hooks       Skip global hook installation during setup
+  --skip-init      Skip 'npx ruflo@latest init --full'
+  --verbose, -v    Extra output
+
+Examples:
+  ruflo-setup
+  ruflo-setup --dry-run --skip-init
+  ruflo-setup hooks status
+  ruflo-setup hooks install --dry-run
+`);
+}
+
+function packageRootFromModule() {
+  const filename = fileURLToPath(import.meta.url);
+  return path.join(path.dirname(filename), '..');
+}
+
+export async function runCli(argv, cwd) {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) {
+      printHelp();
+      return 0;
+    }
+
+    const packageRoot = packageRootFromModule();
+    const flags = parseArgs(argv);
+
+    if (flags.command === 'hooks') {
+      const subcommand = argv[1] || 'status';
+      if (subcommand === 'status') {
+        const status = getGlobalHookStatus({ packageRoot });
+        process.stdout.write(`Hook installed: ${status.installed ? 'yes' : 'no'}\n`);
+        process.stdout.write(`Settings path: ${status.settingsPath}\n`);
+        process.stdout.write(`Reason: ${status.reason}\n`);
+        process.stdout.write(`Command: ${status.hookCommand}\n`);
+        return status.installed ? 0 : 1;
+      }
+
+      if (subcommand === 'install') {
+        const result = installGlobalCheckRufloHook({ packageRoot, dryRun: flags.dryRun });
+        process.stdout.write(`${flags.dryRun ? '[DRY RUN] ' : ''}${result.inserted ? 'Hook installed' : 'Hook already present'}\n`);
+        process.stdout.write(`Settings path: ${result.settingsPath}\n`);
+        return 0;
+      }
+
+      process.stderr.write(`Unknown hooks subcommand: ${subcommand}\n`);
+      return 1;
+    }
+
+    await runSetup({
+      cwd,
+      packageRoot,
+      force: flags.force,
+      dryRun: flags.dryRun,
+      yes: flags.yes,
+      noHooks: flags.noHooks,
+      skipInit: flags.skipInit,
+      verbose: flags.verbose
+    });
+
+    return 0;
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    return 1;
+  }
+}

package/src/hooks.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readJsonSafe, writeJson } from './utils.js';
+
+function defaultGlobalClaudeSettingsPath() {
+  return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+function ensureSessionStartHook(settings, hookCommand) {
+  const next = settings;
+  if (!next.hooks || typeof next.hooks !== 'object') {
+    next.hooks = {};
+  }
+
+  if (!Array.isArray(next.hooks.SessionStart)) {
+    next.hooks.SessionStart = [];
+  }
+
+  const sessionStart = next.hooks.SessionStart;
+  if (sessionStart.length === 0) {
+    sessionStart.push({ hooks: [] });
+  }
+
+  const firstGroup = sessionStart[0];
+  if (!Array.isArray(firstGroup.hooks)) {
+    firstGroup.hooks = [];
+  }
+
+  const alreadyExists = firstGroup.hooks.some((h) => h && h.type === 'command' && h.command === hookCommand);
+  if (!alreadyExists) {
+    firstGroup.hooks.unshift({
+      type: 'command',
+      command: hookCommand,
+      timeout: 5000
+    });
+  }
+
+  return !alreadyExists;
+}
+
+export function installGlobalCheckRufloHook({
+  packageRoot,
+  dryRun = false,
+  globalSettingsPath
+}) {
+  const resolvedSettingsPath = globalSettingsPath || process.env.CLAUDE_SETTINGS_PATH || defaultGlobalClaudeSettingsPath();
+  const hookScriptPath = path.join(packageRoot, 'claude-hooks', 'check-ruflo.cjs');
+  const hookCommand = `node "${hookScriptPath}"`;
+
+  const exists = fs.existsSync(resolvedSettingsPath);
+  const settings = readJsonSafe(resolvedSettingsPath, {});
+
+  const inserted = ensureSessionStartHook(settings, hookCommand);
+
+  if (!dryRun) {
+    if (exists) {
+      const backupPath = `${resolvedSettingsPath}.bak`;
+      fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+      fs.copyFileSync(resolvedSettingsPath, backupPath);
+    }
+    writeJson(resolvedSettingsPath, settings);
+  }
+
+  return {
+    settingsPath: resolvedSettingsPath,
+    hookCommand,
+    inserted,
+    existed: exists
+  };
+}
+
+export function getGlobalHookStatus({ packageRoot, globalSettingsPath }) {
+  const resolvedSettingsPath = globalSettingsPath || process.env.CLAUDE_SETTINGS_PATH || defaultGlobalClaudeSettingsPath();
+  const hookScriptPath = path.join(packageRoot, 'claude-hooks', 'check-ruflo.cjs');
+  const hookCommand = `node "${hookScriptPath}"`;
+
+  if (!fs.existsSync(resolvedSettingsPath)) {
+    return {
+      installed: false,
+      reason: 'global settings file does not exist',
+      settingsPath: resolvedSettingsPath,
+      hookCommand
+    };
+  }
+
+  const settings = readJsonSafe(resolvedSettingsPath, {});
+  const sessionStart = settings?.hooks?.SessionStart;
+  if (!Array.isArray(sessionStart)) {
+    return {
+      installed: false,
+      reason: 'SessionStart hooks are missing',
+      settingsPath: resolvedSettingsPath,
+      hookCommand
+    };
+  }
+
+  const found = sessionStart.some((group) => Array.isArray(group?.hooks) && group.hooks.some((hook) => hook?.type === 'command' && hook?.command === hookCommand));
+
+  return {
+    installed: found,
+    reason: found ? 'hook found' : 'hook command not found in SessionStart hooks',
+    settingsPath: resolvedSettingsPath,
+    hookCommand
+  };
+}

package/src/setup.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { pathExists, copyFileSync, confirm, toPlatformMcpConfig, writeJson } from './utils.js';
+import { installGlobalCheckRufloHook } from './hooks.js';
+
+function logLine(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+function runNpxInit({ force, cwd, dryRun }) {
+  const args = ['ruflo@latest', 'init', '--full'];
+  if (force) {
+    args.push('--force');
+  }
+
+  if (dryRun) {
+    logLine(`  [DRY RUN] Would run: npx ${args.join(' ')}`);
+    return;
+  }
+
+  const result = spawnSync('npx', args, {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`ruflo init failed with exit code ${result.status}`);
+  }
+}
+
+function writeMcpJson({ cwd, dryRun }) {
+  const mcpPath = path.join(cwd, '.mcp.json');
+  const mcpConfig = toPlatformMcpConfig(process.platform);
+
+  if (dryRun) {
+    const action = pathExists(mcpPath) ? 'overwrite' : 'write';
+    logLine(`  [DRY RUN] Would ${action}: ${mcpPath}`);
+    return;
+  }
+
+  writeJson(mcpPath, mcpConfig);
+  logLine('  .mcp.json written for this platform.');
+}
+
+async function copyTemplateClaude({ cwd, force, dryRun, templatePath, yes }) {
+  const destination = path.join(cwd, 'CLAUDE.md');
+
+  if (pathExists(destination) && !force && !dryRun && !yes) {
+    logLine('  WARNING: CLAUDE.md already exists.');
+    const shouldOverwrite = await confirm('  Overwrite with template? [y/N] ');
+    if (!shouldOverwrite) {
+      logLine('  Skipped CLAUDE.md (kept existing).');
+      return;
+    }
+  }
+
+  if (dryRun) {
+    if (pathExists(destination)) {
+      logLine(`  [DRY RUN] Would overwrite: ${destination}`);
+    } else {
+      logLine(`  [DRY RUN] Would copy CLAUDE.md to: ${destination}`);
+    }
+    return;
+  }
+
+  copyFileSync(templatePath, destination);
+  if (pathExists(destination)) {
+    logLine('  CLAUDE.md copied from template.');
+  }
+}
+
+function installGlobalCommand({ packageRoot, dryRun }) {
+  const src = path.join(packageRoot, 'templates', 'ruflo-setup.md');
+  const dest = path.join(os.homedir(), '.claude', 'commands', 'ruflo-setup.md');
+
+  if (dryRun) {
+    logLine(`  [DRY RUN] Would write: ${dest}`);
+    return { dest };
+  }
+
+  copyFileSync(src, dest);
+  return { dest };
+}
+
+function isAlreadyConfigured(cwd) {
+  return pathExists(path.join(cwd, '.mcp.json')) || pathExists(path.join(cwd, '.claude', 'settings.json'));
+}
+
+export async function runSetup({
+  cwd,
+  packageRoot,
+  force = false,
+  dryRun = false,
+  skipInit = false,
+  noHooks = false,
+  yes = false,
+  verbose = false
+}) {
+  const templateClaude = path.join(packageRoot, 'templates', 'CLAUDE.md');
+
+  if (!fs.existsSync(templateClaude)) {
+    throw new Error(`Template CLAUDE.md not found at: ${templateClaude}`);
+  }
+
+  logLine('');
+  logLine('Ruflo Setup (npm CLI)');
+  logLine(`Target directory: ${cwd}`);
+  if (dryRun) {
+    logLine('[DRY RUN - no changes will be made]');
+  }
+  logLine('');
+
+  if (isAlreadyConfigured(cwd) && !force && !yes) {
+    logLine('WARNING: This project already has Ruflo configuration.');
+    const shouldOverwrite = await confirm('Overwrite existing configuration? [y/N] ');
+    if (!shouldOverwrite) {
+      logLine('Aborted. No changes made.');
+      return;
+    }
+  }
+
+  if (!skipInit) {
+    logLine('Step 1: Running npx ruflo@latest init --full ...');
+    runNpxInit({ force, cwd, dryRun });
+    if (!dryRun) {
+      logLine('  ruflo init completed.');
+    }
+    logLine('');
+  } else {
+    logLine('Step 1: Skipped ruflo init (--skip-init).');
+    logLine('');
+  }
+
+  logLine('Step 2: Writing platform-aware .mcp.json ...');
+  writeMcpJson({ cwd, dryRun });
+  logLine('');
+
+  logLine('Step 3: Copying template CLAUDE.md ...');
+  await copyTemplateClaude({ cwd, force, dryRun, templatePath: templateClaude, yes });
+  logLine('');
+
+  if (!noHooks) {
+    logLine('Step 4: Installing global SessionStart check-ruflo hook ...');
+    const hookResult = installGlobalCheckRufloHook({ packageRoot, dryRun });
+    if (hookResult.inserted) {
+      logLine(`  Hook installed in: ${hookResult.settingsPath}`);
+    } else {
+      logLine(`  Hook already present in: ${hookResult.settingsPath}`);
+    }
+    if (verbose) {
+      logLine(`  Hook command: ${hookResult.hookCommand}`);
+    }
+    logLine('');
+  } else {
+    logLine('Step 4: Skipped hook installation (--no-hooks).');
+    logLine('');
+  }
+
+  logLine('Step 5: Installing global /ruflo-setup command ...');
+  const commandResult = installGlobalCommand({ packageRoot, dryRun });
+  if (!dryRun) {
+    logLine(`  Command installed at: ${commandResult.dest}`);
+  }
+  logLine('');
+
+  if (dryRun) {
+    logLine('Dry run complete. No changes were made.');
+    return;
+  }
+
+  logLine('Setup complete!');
+  logLine('');
+  logLine('Next steps:');
+  logLine('  1. Edit CLAUDE.md for project-specific Build & Test commands');
+  logLine('  2. Run: claude');
+  logLine('  3. Verify hooks: ruflo-setup hooks status');
+}

package/src/utils.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+export function pathExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+export function readJsonSafe(filePath, fallbackValue = {}) {
+  if (!pathExists(filePath)) {
+    return fallbackValue;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallbackValue;
+  }
+}
+
+export function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function copyFileSync(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+export async function confirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const answer = await new Promise((resolve) => {
+    rl.question(question, resolve);
+  });
+
+  rl.close();
+  return /^[Yy]$/.test((answer || '').trim());
+}
+
+export function parseArgs(argv) {
+  const flags = {
+    force: false,
+    dryRun: false,
+    yes: false,
+    noHooks: false,
+    skipInit: false,
+    verbose: false,
+    command: 'setup'
+  };
+
+  const positional = [];
+  for (const item of argv) {
+    if (item === '--force' || item === '-f') flags.force = true;
+    else if (item === '--dry-run') flags.dryRun = true;
+    else if (item === '--yes' || item === '-y') flags.yes = true;
+    else if (item === '--no-hooks') flags.noHooks = true;
+    else if (item === '--skip-init') flags.skipInit = true;
+    else if (item === '--verbose' || item === '-v') flags.verbose = true;
+    else positional.push(item);
+  }
+
+  if (positional.length > 0) {
+    flags.command = positional[0];
+  }
+
+  return flags;
+}
+
+export function toPlatformMcpConfig(platform) {
+  const isWindows = platform === 'win32';
+  const command = isWindows ? 'cmd' : 'npx';
+  const npxArgs = ['-y'];
+
+  const makeArgs = (pkg, extraArgs) => {
+    if (isWindows) {
+      return ['/c', 'npx', ...npxArgs, pkg, ...extraArgs];
+    }
+    return [...npxArgs, pkg, ...extraArgs];
+  };
+
+  return {
+    mcpServers: {
+      'claude-flow': {
+        command,
+        args: makeArgs('@claude-flow/cli@latest', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false',
+          CLAUDE_FLOW_MODE: 'v3',
+          CLAUDE_FLOW_HOOKS_ENABLED: 'true',
+          CLAUDE_FLOW_TOPOLOGY: 'hierarchical-mesh',
+          CLAUDE_FLOW_MAX_AGENTS: '15',
+          CLAUDE_FLOW_MEMORY_BACKEND: 'hybrid'
+        },
+        autoStart: false
+      },
+      'ruv-swarm': {
+        command,
+        args: makeArgs('ruv-swarm', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false'
+        },
+        optional: true
+      },
+      'flow-nexus': {
+        command,
+        args: makeArgs('flow-nexus@latest', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false'
+        },
+        optional: true,
+        requiresAuth: true
+      }
+    }
+  };
+}

package/templates/CLAUDE.md

@@ -0,0 +1,99 @@
+# Claude Code Configuration - Claude Flow V3
+
+## Behavioral Rules (Always Enforced)
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless they're absolutely necessary for achieving your goal
+- ALWAYS prefer editing an existing file to creating a new one
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
+- NEVER save working files, text/mds, or tests to the root folder
+- Never continuously check status after spawning a swarm — wait for results
+- ALWAYS read a file before editing it
+- NEVER commit secrets, credentials, or .env files
+
+## File Organization
+
+- NEVER save to root folder — use the directories below
+- Use `/src` for source code files
+- Use `/tests` for test files
+- Use `/docs` for documentation and markdown files
+- Use `/config` for configuration files
+- Use `/scripts` for utility scripts
+- Use `/examples` for example code
+
+## Project Architecture
+
+- Follow Domain-Driven Design with bounded contexts
+- Keep files under 500 lines
+- Use typed interfaces for all public APIs
+- Prefer TDD London School (mock-first) for new code
+- Use event sourcing for state changes
+- Ensure input validation at system boundaries
+
+### Project Config
+
+- **Topology**: hierarchical-mesh
+- **Max Agents**: 15
+- **Memory**: hybrid
+- **HNSW**: Enabled
+- **Neural**: Enabled
+
+## Build & Test
+
+<!-- TODO: Replace with this project's actual build/test/lint commands -->
+```bash
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+- ALWAYS run tests after making code changes
+- ALWAYS verify build succeeds before committing
+
+## Security Rules
+
+- NEVER hardcode API keys, secrets, or credentials in source files
+- NEVER commit .env files or any file containing secrets
+- Always validate user input at system boundaries
+- Always sanitize file paths to prevent directory traversal
+- Run `npx ruflo@latest security scan` after security-related changes
+
+## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
+
+- All operations MUST be concurrent/parallel in a single message
+- Use Claude Code's Task tool for spawning agents, not just MCP
+- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
+- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL Bash commands in ONE message
+
+## Swarm Orchestration
+
+- MUST initialize the swarm using CLI tools when starting complex tasks
+- MUST spawn concurrent agents using Claude Code's Task tool
+- Never use CLI tools alone for execution — Task tool agents do the actual work
+- MUST call CLI tools AND Task tool in ONE message for complex work
+
+## Quick Setup
+
+```bash
+npx ruflo@latest init --full
+npx ruflo@latest daemon start
+npx ruflo@latest doctor --fix
+```
+
+## Claude Code vs CLI Tools
+
+- Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git
+- CLI tools handle coordination via Bash: swarm init, memory, hooks, routing
+- NEVER use CLI tools as a substitute for Task tool agents
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues

package/templates/ruflo-setup.md

@@ -0,0 +1,29 @@
+# /ruflo-setup
+
+Set up Ruflo + Claude Flow V3 in the current project directory.
+
+## What this does
+
+Runs `npx @mfjjs/ruflo-setup` which:
+
+1. Runs `npx ruflo@latest init --full` to install:
+   - `.claude/settings.json` with hooks, permissions, and Claude Flow config
+   - `.claude/helpers/` — hook-handler, statusline, auto-memory scripts
+   - `.claude/agents/` — 120+ agent definitions
+   - `.claude/skills/` — 30+ skill definitions
+   - `.claude/commands/` — slash commands
+2. Writes a platform-aware `.mcp.json` (MCP server registration for claude-flow, ruv-swarm, flow-nexus)
+3. Copies a template `CLAUDE.md` for the project
+4. Installs a global `SessionStart` hook in `~/.claude/settings.json` that warns when Ruflo is not configured
+
+## Instructions for Claude
+
+When the user runs /ruflo-setup:
+
+1. Confirm the current working directory with the user
+2. Check if `.mcp.json` already exists — if so, warn and ask before overwriting
+3. Run the setup CLI:
+   ```bash
+   npx @mfjjs/ruflo-setup
+   ```
+4. Report what was installed and remind the user to restart Claude Code to load the new MCP servers