@mfjjs/ruflo-setup 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.1.5](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.4...v0.1.5) (2026-03-11)
+
+
+### Features
+
+* **cli:** update commands to use pnpm instead of npx for installation and initialization ([5d7e482](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/5d7e482beaae9b3adfdf2a4c6ea478e8cf6774cb))
+* **setup:** enhance pnpm installation instructions and ensure availability checks ([b89cccc](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/b89cccc978b7e439c6544195c7d480bb95ef07af))
+
+### [0.1.4](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.3...v0.1.4) (2026-03-11)
+
+
+### Features
+
+* **hooks:** enhance hook status reporting with matched command and source info ([faca4f7](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/faca4f77a26581a2262548753fb15ca8ee9d4773))
+
 ### [0.1.3](https://gitlab.mfj.local:8022/mario/setup-ruflo/compare/v0.1.2...v0.1.3) (2026-03-11)
 
 

package/README.md

@@ -10,6 +10,31 @@ Cross-platform npm CLI to bootstrap a project with Ruflo on Windows and Linux.
 - Command name: `ruflo-setup`
 - Platform support: Windows and Linux (plus macOS by default)
 
+## Requirements
+
+- Node.js 20+
+- pnpm available on PATH
+
+Quickest pnpm install by platform:
+
+```bash
+# Windows (recommended)
+winget install -e --id pnpm.pnpm
+
+# macOS (recommended)
+brew install pnpm
+
+# Linux (recommended)
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+Alternative (all platforms with recent Node.js):
+
+```bash
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
 ## Project structure
 
 - `package.json`: npm metadata, scripts, and `bin` mapping
@@ -45,7 +70,7 @@ Flow:
 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`
+	 - optional `pnpm add -g ruflo@latest` then `ruflo init --full`
 	 - writes platform-aware `.mcp.json`
 	 - copies `templates/CLAUDE.md`
 	 - installs global SessionStart hook (unless skipped)
@@ -114,7 +139,3 @@ This tests exactly what users get from a package install.
 - `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfjjs/ruflo-setup",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Cross-platform setup CLI for Ruflo + Claude Flow projects",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,99 +1,104 @@
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
-import { parseArgs } from './utils.js';
-import { runSetup } from './setup.js';
-import { getGlobalHookStatus, installGlobalCheckRufloHook } from './hooks.js';
-
-const require = createRequire(import.meta.url);
-
-function printVersion() {
-  const { version } = require('../package.json');
-  process.stdout.write(`${version}\n`);
-}
-
-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'
-  --version, -v    Print version and exit
-  --verbose        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('--version') || argv.includes('-v')) {
-      printVersion();
-      return 0;
-    }
-
-    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;
-  }
-}
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { parseArgs } from './utils.js';
+import { runSetup } from './setup.js';
+import { getGlobalHookStatus, installGlobalCheckRufloHook } from './hooks.js';
+
+const require = createRequire(import.meta.url);
+
+function printVersion() {
+  const { version } = require('../package.json');
+  process.stdout.write(`${version}\n`);
+}
+
+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 'pnpm add -g ruflo@latest && ruflo init --full'
+  --version, -v    Print version and exit
+  --verbose        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('--version') || argv.includes('-v')) {
+      printVersion();
+      return 0;
+    }
+
+    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`);
+        if (status.matchedHookPointingTo) {
+          process.stdout.write(`${status.matchedHookPointingTo}\n`);
+        }
+        process.stdout.write(`Settings path: ${status.settingsPath}\n`);
+        process.stdout.write(`Reason: ${status.reason}\n`);
+        if (status.matchedHookCommand) {
+          process.stdout.write(`Matched command: ${status.matchedHookCommand}\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

@@ -1,109 +1,198 @@
-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 newHook = { type: 'command', command: hookCommand, timeout: 5000 };
-  const existingIndex = firstGroup.hooks.findIndex(
-    (h) => h && h.type === 'command' && typeof h.command === 'string' && h.command.includes('check-ruflo.cjs')
-  );
-
-  if (existingIndex !== -1) {
-    const unchanged = firstGroup.hooks[existingIndex].command === hookCommand;
-    firstGroup.hooks[existingIndex] = newHook;
-    return unchanged ? false : true;
-  }
-
-  firstGroup.hooks.unshift(newHook);
-  return true;
-}
-
-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' && typeof hook?.command === 'string' && hook.command.includes('check-ruflo.cjs')));
-
-  return {
-    installed: found,
-    reason: found ? 'hook found' : 'hook command not found in SessionStart hooks',
-    settingsPath: resolvedSettingsPath,
-    hookCommand
-  };
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readJsonSafe, writeJson } from './utils.js';
+
+const CHECK_RUFLO_HOOK_FILENAME = 'check-ruflo.cjs';
+
+function defaultGlobalClaudeSettingsPath() {
+  return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+function hasCheckRufloHookFilename(command) {
+  if (typeof command !== 'string') return false;
+  return /check-ruflo\.cjs(?=["'\s]|$)/i.test(command);
+}
+
+function extractHookScriptPath(command) {
+  if (typeof command !== 'string') return null;
+  const quoted = command.match(/["']([^"']*check-ruflo\.cjs)["']/i);
+  if (quoted) return quoted[1];
+  const bare = command.match(/([^\s"']*check-ruflo\.cjs)/i);
+  return bare ? bare[1] : null;
+}
+
+function inferHookSourceInfo(command, packageRoot) {
+  const scriptPath = extractHookScriptPath(command);
+  const normalizedScriptPath = scriptPath ? scriptPath.replace(/\\/g, '/').toLowerCase() : '';
+  const normalizedPath = scriptPath ? scriptPath.replace(/\\/g, '/') : '';
+  const normalizedPackageRoot = packageRoot ? packageRoot.replace(/\\/g, '/').toLowerCase() : '';
+
+  let source = 'unknown';
+  let packageRef = null;
+  let storeType = null;
+
+  if (normalizedScriptPath.includes('/_npx/')) {
+    source = 'npm/npx cache install';
+    storeType = 'npm/npx cache';
+    const m = normalizedPath.match(/_npx\/[^/]+\/node_modules\/((?:@[^/]+\/)?[^/]+)\/claude-hooks/i);
+    if (m) packageRef = m[1];
+  } else if (normalizedScriptPath.includes('/.pnpm/')) {
+    source = 'pnpm store install';
+    // scoped package: @scope+pkg@version
+    const pnpmScoped = normalizedPath.match(/\/\.pnpm\/((@[^/+]+)\+([^/@]+)@([^/]+))\//i);
+    if (pnpmScoped) {
+      packageRef = `${pnpmScoped[2]}/${pnpmScoped[3]}@${pnpmScoped[4]}`;
+    } else {
+      // unscoped: pkg@version
+      const pnpmUnscoped = normalizedPath.match(/\/\.pnpm\/([^/@+]+)@([^/]+)\//i);
+      if (pnpmUnscoped) packageRef = `${pnpmUnscoped[1]}@${pnpmUnscoped[2]}`;
+    }
+    storeType = normalizedScriptPath.includes('/pnpm/global/') ? 'pnpm global store' : 'pnpm store';
+  } else if (normalizedScriptPath.includes('/node_modules/')) {
+    source = 'node_modules install';
+    storeType = 'npm global';
+    const m = normalizedPath.match(/node_modules\/((?:@[^/]+\/)?[^/]+)\/claude-hooks/i);
+    if (m) packageRef = m[1];
+  }
+
+  const isCurrentPackagePath = Boolean(
+    normalizedScriptPath && normalizedPackageRoot && normalizedScriptPath.startsWith(normalizedPackageRoot)
+  );
+
+  const versionMatch = command.match(/@mfjjs[+/\\]ruflo-setup@(\d+\.\d+\.\d+(?:[-+][^\\/"'\s]+)?)/i);
+
+  const pointingTo = packageRef && storeType
+    ? `hook pointing to ${packageRef} from ${storeType}`
+    : packageRef
+      ? `hook pointing to ${packageRef}`
+      : null;
+
+  return {
+    scriptPath,
+    source,
+    isCurrentPackagePath,
+    inferredVersion: versionMatch ? versionMatch[1] : null,
+    packageRef,
+    pointingTo
+  };
+}
+
+function findCheckRufloHook(sessionStart) {
+  if (!Array.isArray(sessionStart)) return null;
+  for (let gi = 0; gi < sessionStart.length; gi += 1) {
+    const group = sessionStart[gi];
+    if (!Array.isArray(group?.hooks)) continue;
+    for (let hi = 0; hi < group.hooks.length; hi += 1) {
+      const hook = group.hooks[hi];
+      if (hasCheckRufloHookFilename(hook?.command)) {
+        return { hook, groupIndex: gi, hookIndex: hi, command: hook.command };
+      }
+    }
+  }
+  return null;
+}
+
+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 newHook = { type: 'command', command: hookCommand, timeout: 5000 };
+  const existingIndex = firstGroup.hooks.findIndex((h) => hasCheckRufloHookFilename(h?.command));
+
+  if (existingIndex !== -1) {
+    const unchanged = firstGroup.hooks[existingIndex].command === hookCommand;
+    firstGroup.hooks[existingIndex] = newHook;
+    return unchanged ? false : true;
+  }
+
+  firstGroup.hooks.unshift(newHook);
+  return true;
+}
+
+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 foundHook = findCheckRufloHook(sessionStart);
+  const found = Boolean(foundHook);
+  const sourceInfo = foundHook ? inferHookSourceInfo(foundHook.command, packageRoot) : null;
+
+  return {
+    installed: found,
+    reason: found ? `hook found by filename ${CHECK_RUFLO_HOOK_FILENAME}` : `hook command with filename ${CHECK_RUFLO_HOOK_FILENAME} not found in SessionStart hooks`,
+    settingsPath: resolvedSettingsPath,
+    hookCommand,
+    matchedHookCommand: foundHook?.command || null,
+    matchedHookSource: sourceInfo?.source || null,
+    matchedHookPointingTo: sourceInfo?.pointingTo || null
+  };
+}

package/src/setup.js

@@ -8,25 +8,88 @@ function logLine(message) {
   process.stdout.write(`${message}\n`);
 }
 
-function runNpxInit({ force, cwd, dryRun }) {
-  const args = ['ruflo@latest', 'init', '--full'];
+function getPnpmInstallSuggestions(platform) {
+  if (platform === 'win32') {
+    return [
+      'winget install -e --id pnpm.pnpm',
+      'corepack enable && corepack prepare pnpm@latest --activate',
+      'npm install -g pnpm'
+    ];
+  }
+
+  if (platform === 'darwin') {
+    return [
+      'brew install pnpm',
+      'corepack enable && corepack prepare pnpm@latest --activate',
+      'npm install -g pnpm'
+    ];
+  }
+
+  return [
+    'curl -fsSL https://get.pnpm.io/install.sh | sh -',
+    'corepack enable && corepack prepare pnpm@latest --activate',
+    'npm install -g pnpm'
+  ];
+}
+
+function ensurePnpmAvailable() {
+  const check = spawnSync('pnpm', ['--version'], {
+    stdio: 'ignore',
+    shell: process.platform === 'win32'
+  });
+
+  if (check.status === 0 && !check.error) {
+    return;
+  }
+
+  const platformLabel = process.platform === 'win32'
+    ? 'Windows'
+    : process.platform === 'darwin'
+      ? 'macOS'
+      : 'Linux';
+  const suggestions = getPnpmInstallSuggestions(process.platform)
+    .map((command) => `  - ${command}`)
+    .join('\n');
+
+  throw new Error(
+    `pnpm is required but was not found in PATH.\n` +
+    `Install pnpm, then re-run ruflo-setup.\n` +
+    `Quick install options for ${platformLabel}:\n${suggestions}`
+  );
+}
+
+function runPnpmInit({ force, cwd, dryRun }) {
+  const initArgs = ['init', '--full'];
   if (force) {
-    args.push('--force');
+    initArgs.push('--force');
   }
 
   if (dryRun) {
-    logLine(`  [DRY RUN] Would run: npx ${args.join(' ')}`);
+    logLine(`  [DRY RUN] Would run: pnpm add -g ruflo@latest`);
+    logLine(`  [DRY RUN] Would run: ruflo ${initArgs.join(' ')}`);
     return;
   }
 
-  const result = spawnSync('npx', args, {
+  ensurePnpmAvailable();
+
+  const install = spawnSync('pnpm', ['add', '-g', 'ruflo@latest'], {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (install.status !== 0) {
+    throw new Error(`pnpm add -g ruflo@latest failed with exit code ${install.status}`);
+  }
+
+  const run = spawnSync('ruflo', initArgs, {
     cwd,
     stdio: 'inherit',
     shell: process.platform === 'win32'
   });
 
-  if (result.status !== 0) {
-    throw new Error(`ruflo init failed with exit code ${result.status}`);
+  if (run.status !== 0) {
+    throw new Error(`ruflo init failed with exit code ${run.status}`);
   }
 }
 
@@ -89,8 +152,8 @@ export async function runSetup({
   }
 
   if (!skipInit) {
-    logLine('Step 1: Running npx ruflo@latest init --full ...');
-    runNpxInit({ force, cwd, dryRun });
+    logLine('Step 1: Running pnpm add -g ruflo@latest && ruflo init --full ...');
+    runPnpmInit({ force, cwd, dryRun });
     if (!dryRun) {
       logLine('  ruflo init completed.');
     }

package/src/utils.js

@@ -72,14 +72,11 @@ export function parseArgs(argv) {
 
 export function toPlatformMcpConfig(platform) {
   const isWindows = platform === 'win32';
-  const command = isWindows ? 'cmd' : 'npx';
-  const npxArgs = ['-y'];
+  const command = isWindows ? 'cmd' : 'pnpm';
+  const pnpmArgs = isWindows ? ['/c', 'pnpm', 'dlx'] : ['dlx'];
 
   const makeArgs = (pkg, extraArgs) => {
-    if (isWindows) {
-      return ['/c', 'npx', ...npxArgs, pkg, ...extraArgs];
-    }
-    return [...npxArgs, pkg, ...extraArgs];
+    return [...pnpmArgs, pkg, ...extraArgs];
   };
 
   return {

package/templates/ruflo-setup.md

@@ -2,11 +2,36 @@
 
 Set up Ruflo + Claude Flow V3 in the current project directory.
 
+## Requirements
+
+- Node.js 20+
+- pnpm installed and available on PATH
+
+Quickest pnpm install by platform:
+
+```bash
+# Windows (recommended)
+winget install -e --id pnpm.pnpm
+
+# macOS (recommended)
+brew install pnpm
+
+# Linux (recommended)
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+Alternative (all platforms with recent Node.js):
+
+```bash
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
 ## What this does
 
-Runs `npx @mfjjs/ruflo-setup` which:
+Runs `pnpm add -g @mfjjs/ruflo-setup` then `ruflo-setup` which:
 
-1. Runs `npx ruflo@latest init --full` to install:
+1. Runs `pnpm add -g ruflo@latest` then `ruflo 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
@@ -23,6 +48,7 @@ When the user runs /ruflo-setup:
 2. Check if `.mcp.json` already exists — if so, warn and ask before overwriting
 3. Run the setup CLI:
    ```bash
-   npx @mfjjs/ruflo-setup
+   pnpm add -g @mfjjs/ruflo-setup
+   ruflo-setup
    ```
 4. Report what was installed and remind the user to restart Claude Code to load the new MCP servers