claude-flow-guidance-implementation 0.1.1 → 0.1.3

package/README.md

@@ -24,6 +24,19 @@ npm i -D claude-flow-guidance-implementation
 npx cf-guidance-impl init --target ~/source/my-project --install-deps
 ```
 
+Choose integration target mode explicitly when needed:
+
+```bash
+# default: both Claude + Codex wiring
+npx cf-guidance-impl init --target ~/source/my-project --target-mode both
+
+# Claude-only wiring (.claude hooks + settings merge)
+npx cf-guidance-impl init --target ~/source/my-project --target-mode claude
+
+# Codex-only wiring (.agents bridge + codex scripts)
+npx cf-guidance-impl init --target ~/source/my-project --target-mode codex
+```
+
 ## Quickstart
 
 ```bash
@@ -34,24 +47,47 @@ npx --yes -p claude-flow-guidance-implementation cf-guidance-impl init --target
 npx --yes -p claude-flow-guidance-implementation cf-guidance-impl verify --target ~/source/my-project
 ```
 
+## Package Runtime Mode (No Local Guidance Code)
+
+You can run guidance directly from `node_modules` and avoid committing copied guidance runtime files.
+
+Example `package.json` scripts in a target repo:
+
+```bash
+"guidance:analyze": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/analyze-guidance.js",
+"guidance:optimize": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-autopilot.js --once --apply --source manual",
+"guidance:ab-benchmark": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-ab-benchmark.js",
+"guidance:codex:status": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-codex-bridge.js status"
+```
+
+Project root resolution for scaffold scripts:
+- `GUIDANCE_PROJECT_DIR` (if set)
+- else `CLAUDE_PROJECT_DIR` (if set)
+- else current working directory (`process.cwd()`)
+
 ## CLI commands
 
 ```bash
-cf-guidance-impl init --target <repoPath> [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
-cf-guidance-impl install --target <repoPath> [--force] [--install-deps]
-cf-guidance-impl verify --target <repoPath>
+cf-guidance-impl init --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
+cf-guidance-impl install --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps]
+cf-guidance-impl verify --target <repoPath> [--target-mode both|claude|codex]
 ```
 
 ## What `init` does
 
 `cf-guidance-impl init` performs:
-1. `npx @claude-flow/cli@latest init --dual` in target repo (unless `--skip-cf-init`)
-2. installs scaffold runtime files (`scripts/`, `src/guidance/`, `.claude/helpers/hook-handler.cjs`, docs)
-3. merges target `package.json` scripts + guidance deps
-4. merges `.claude/settings.json` env and hook blocks
-5. appends Codex bridge sections to `.agents/config.toml` and `AGENTS.md`
-6. creates `CLAUDE.local.md` stub and updates `.gitignore`
-7. verifies wiring (unless `--no-verify`)
+1. runs `npx @claude-flow/cli@latest init` in target repo (unless `--skip-cf-init`)
+2. adds init flags by mode:
+   - `--target-mode both` + default dual -> `--dual`
+   - `--target-mode codex` -> `--codex`
+   - `--target-mode claude` -> no codex flag
+   - `--no-dual` only affects `both` mode (skips `--dual`)
+3. installs scaffold runtime files (`scripts/`, `src/guidance/`, `.claude/helpers/hook-handler.cjs`, docs)
+4. merges target `package.json` scripts + guidance deps (Codex scripts only for `both|codex`)
+5. merges `.claude/settings.json` env and hook blocks (only for `both|claude`)
+6. appends Codex bridge sections to `.agents/config.toml` and `AGENTS.md` (only for `both|codex`)
+7. creates `CLAUDE.local.md` stub and updates `.gitignore`
+8. verifies wiring for selected mode (unless `--no-verify`)
 
 ## Codex lifecycle integration
 

package/bin/cf-guidance-impl.mjs

@@ -9,9 +9,9 @@ const toolkitRoot = resolve(__dirname, '..');
 
 function usage() {
   console.log(`Usage:
-  cf-guidance-impl init --target <repoPath> [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
-  cf-guidance-impl install --target <repoPath> [--force] [--install-deps]
-  cf-guidance-impl verify --target <repoPath>
+  cf-guidance-impl init --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
+  cf-guidance-impl install --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps]
+  cf-guidance-impl verify --target <repoPath> [--target-mode both|claude|codex]
 `);
 }
 
@@ -34,6 +34,7 @@ async function main() {
   }
 
   const target = getFlagValue(args, '--target', process.cwd());
+  const targetMode = getFlagValue(args, '--target-mode', 'both');
   const force = hasFlag(args, '--force');
   const installDeps = hasFlag(args, '--install-deps');
 
@@ -41,6 +42,7 @@ async function main() {
     const result = initRepo({
       toolkitRoot,
       targetRepo: target,
+      targetMode,
       force,
       installDeps,
       dual: !hasFlag(args, '--no-dual'),
@@ -52,13 +54,19 @@ async function main() {
   }
 
   if (command === 'install') {
-    const result = installIntoRepo({ toolkitRoot, targetRepo: target, force, installDeps });
+    const result = installIntoRepo({
+      toolkitRoot,
+      targetRepo: target,
+      targetMode,
+      force,
+      installDeps,
+    });
     console.log(JSON.stringify(result, null, 2));
     return;
   }
 
   if (command === 'verify') {
-    const report = verifyRepo({ targetRepo: target });
+    const report = verifyRepo({ targetRepo: target, targetMode });
     console.log(JSON.stringify(report, null, 2));
     process.exit(report.passed ? 0 : 2);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-guidance-implementation",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Reusable guidance control-plane implementation kit for wiring @claude-flow/guidance into any repo",
   "type": "module",
   "private": false,

package/scaffold/scripts/analyze-guidance.js

@@ -12,7 +12,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const root = resolve(__dirname, '..');
+const root = resolve(process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd());
 
 // Import guidance modules
 const { analyze, autoOptimize, formatReport, formatBenchmark } = await import('@claude-flow/guidance/analyzer');

package/scaffold/scripts/guidance-ab-benchmark.js

@@ -7,7 +7,9 @@ import { abBenchmark } from '@claude-flow/guidance/analyzer';
 import { createSyntheticContentAwareExecutor } from '../src/guidance/content-aware-executor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 const guidanceDir = resolve(rootDir, '.claude-flow', 'guidance');
 const reportPath = resolve(guidanceDir, 'ab-benchmark-report.json');
 

package/scaffold/scripts/guidance-autopilot.js

@@ -19,7 +19,9 @@ import { createCompiler } from '@claude-flow/guidance/compiler';
 import { createSyntheticContentAwareExecutor } from '../src/guidance/content-aware-executor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 
 const DEFAULTS = {
   mode: 'once',

package/scaffold/scripts/guidance-codex-bridge.js

@@ -5,7 +5,9 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 
 const SUPPORTED_EVENTS = new Set([
   'pre-command',

package/scaffold/scripts/guidance-integrations.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from 'node:url';
 import { createGuidanceAdvancedRuntime } from '../src/guidance/advanced-runtime.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 
 function usage() {
   console.log(`Usage:

package/scaffold/scripts/guidance-runtime.js

@@ -5,7 +5,9 @@ import { fileURLToPath } from 'node:url';
 import { createGuidancePhase1Runtime } from '../src/guidance/phase1-runtime.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 
 function usage() {
   console.log(`Usage:

package/scaffold/scripts/scaffold-guidance.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from 'node:url';
 import { scaffold } from '@claude-flow/guidance/generators';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const rootDir = resolve(__dirname, '..');
+const rootDir = resolve(
+  process.env.GUIDANCE_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd()
+);
 const defaultOutputDir = resolve(rootDir, '.claude-flow', 'guidance', 'scaffold');
 
 function parseArg(flag) {

package/src/installer.mjs

@@ -64,6 +64,22 @@ function ensureDir(path) {
   mkdirSync(path, { recursive: true });
 }
 
+function normalizeTargetMode(value = 'both') {
+  const mode = String(value || 'both').trim().toLowerCase();
+  if (!['both', 'claude', 'codex'].includes(mode)) {
+    throw new Error(`Invalid target mode: ${value}. Use one of: both, claude, codex.`);
+  }
+  return mode;
+}
+
+function usesClaudeMode(mode) {
+  return mode === 'both' || mode === 'claude';
+}
+
+function usesCodexMode(mode) {
+  return mode === 'both' || mode === 'codex';
+}
+
 function readJson(path, fallback = {}) {
   if (!existsSync(path)) return fallback;
   try {
@@ -138,9 +154,16 @@ function appendBlockIfMissing(path, marker, block, fallback = '') {
   return true;
 }
 
-export function installIntoRepo({ toolkitRoot, targetRepo, force = false, installDeps = false }) {
+export function installIntoRepo({
+  toolkitRoot,
+  targetRepo,
+  force = false,
+  installDeps = false,
+  targetMode = 'both',
+}) {
   const target = resolve(targetRepo);
   const scaffold = resolve(toolkitRoot, 'scaffold');
+  const mode = normalizeTargetMode(targetMode);
 
   if (!existsSync(target)) {
     throw new Error(`Target repo does not exist: ${target}`);
@@ -171,6 +194,8 @@ export function installIntoRepo({ toolkitRoot, targetRepo, force = false, instal
   packageJson.type = packageJson.type || 'module';
   packageJson.scripts = packageJson.scripts || {};
   for (const [name, cmd] of Object.entries(GUIDANCE_PACKAGE_SCRIPTS)) {
+    const isCodexScript = name.startsWith('guidance:codex:');
+    if (isCodexScript && !usesCodexMode(mode)) continue;
     if (!(name in packageJson.scripts)) {
       packageJson.scripts[name] = cmd;
     }
@@ -185,35 +210,45 @@ export function installIntoRepo({ toolkitRoot, targetRepo, force = false, instal
 
   writeJson(packagePath, packageJson);
 
-  // Merge .claude/settings.json hooks and env.
-  const settingsPath = resolve(target, '.claude/settings.json');
-  const settings = readJson(settingsPath, {});
-  settings.env = settings.env || {};
-  for (const [key, value] of Object.entries(GUIDANCE_ENV_DEFAULTS)) {
-    if (!(key in settings.env)) settings.env[key] = value;
-  }
-
-  settings.hooks = settings.hooks || {};
-  for (const [event, blocks] of Object.entries(GUIDANCE_HOOKS_DEFAULTS)) {
-    settings.hooks[event] = mergeHookBlocks(settings.hooks[event], blocks);
-  }
+  let settingsPath = null;
+  if (usesClaudeMode(mode)) {
+    // Merge .claude/settings.json hooks and env.
+    settingsPath = resolve(target, '.claude/settings.json');
+    const settings = readJson(settingsPath, {});
+    settings.env = settings.env || {};
+    for (const [key, value] of Object.entries(GUIDANCE_ENV_DEFAULTS)) {
+      if (!(key in settings.env)) settings.env[key] = value;
+    }
 
-  writeJson(settingsPath, settings);
+    settings.hooks = settings.hooks || {};
+    for (const [event, blocks] of Object.entries(GUIDANCE_HOOKS_DEFAULTS)) {
+      settings.hooks[event] = mergeHookBlocks(settings.hooks[event], blocks);
+    }
 
-  const agentsConfigPath = resolve(target, '.agents/config.toml');
-  const codexConfigAdded = appendBlockIfMissing(
-    agentsConfigPath,
-    '[guidance_codex]',
-    GUIDANCE_CODEX_CONFIG_BLOCK
-  );
+    writeJson(settingsPath, settings);
+  }
 
-  const agentsDocPath = resolve(target, 'AGENTS.md');
-  const codexAgentsDocAdded = appendBlockIfMissing(
-    agentsDocPath,
-    '## Guidance Lifecycle Wiring (Codex)',
-    GUIDANCE_CODEX_AGENTS_BLOCK,
-    '# Project\n\n'
-  );
+  let agentsConfigPath = null;
+  let agentsDocPath = null;
+  let codexConfigAdded = false;
+  let codexAgentsDocAdded = false;
+
+  if (usesCodexMode(mode)) {
+    agentsConfigPath = resolve(target, '.agents/config.toml');
+    codexConfigAdded = appendBlockIfMissing(
+      agentsConfigPath,
+      '[guidance_codex]',
+      GUIDANCE_CODEX_CONFIG_BLOCK
+    );
+
+    agentsDocPath = resolve(target, 'AGENTS.md');
+    codexAgentsDocAdded = appendBlockIfMissing(
+      agentsDocPath,
+      '## Guidance Lifecycle Wiring (Codex)',
+      GUIDANCE_CODEX_AGENTS_BLOCK,
+      '# Project\n\n'
+    );
+  }
 
   // Ensure local guidance file and gitignore entries.
   writeMissingStub(
@@ -232,6 +267,7 @@ export function installIntoRepo({ toolkitRoot, targetRepo, force = false, instal
 
   const summary = {
     target,
+    targetMode: mode,
     copiedFrom: relative(target, scaffold),
     filesInstalled: [
       '.claude/helpers/hook-handler.cjs',
@@ -270,18 +306,24 @@ export function installIntoRepo({ toolkitRoot, targetRepo, force = false, instal
   return summary;
 }
 
-export function verifyRepo({ targetRepo }) {
+export function verifyRepo({ targetRepo, targetMode = 'both' }) {
   const target = resolve(targetRepo);
+  const mode = normalizeTargetMode(targetMode);
   const requiredFiles = [
     '.claude/helpers/hook-handler.cjs',
     'scripts/guidance-integrations.js',
     'scripts/guidance-runtime.js',
-    'scripts/guidance-codex-bridge.js',
     'src/guidance/phase1-runtime.js',
-    '.claude/settings.json',
     'package.json',
   ];
 
+  if (usesCodexMode(mode)) {
+    requiredFiles.push('scripts/guidance-codex-bridge.js');
+    requiredFiles.push('.agents/config.toml');
+    requiredFiles.push('AGENTS.md');
+  }
+  if (usesClaudeMode(mode)) requiredFiles.push('.claude/settings.json');
+
   const checks = [];
   for (const relPath of requiredFiles) {
     const full = resolve(target, relPath);
@@ -293,9 +335,10 @@ export function verifyRepo({ targetRepo }) {
     '.claude/helpers/hook-handler.cjs',
     'scripts/guidance-integrations.js',
     'scripts/guidance-runtime.js',
-    'scripts/guidance-codex-bridge.js',
   ];
 
+  if (usesCodexMode(mode)) checkFiles.push('scripts/guidance-codex-bridge.js');
+
   for (const relPath of checkFiles) {
     const full = resolve(target, relPath);
     if (!existsSync(full)) {
@@ -311,29 +354,36 @@ export function verifyRepo({ targetRepo }) {
   }
 
   const smokeInput = '{"tool_input":{"command":"git status"}}';
-  const smoke = run(
-    'bash',
-    [
-      '-lc',
-      `printf '%s' '${smokeInput}' | node .claude/helpers/hook-handler.cjs pre-bash`,
-    ],
-    target
-  );
+  let smoke = { status: 0, stdout: '', stderr: '' };
+  if (usesClaudeMode(mode)) {
+    smoke = run(
+      'bash',
+      [
+        '-lc',
+        `printf '%s' '${smokeInput}' | node .claude/helpers/hook-handler.cjs pre-bash`,
+      ],
+      target
+    );
+  }
 
-  const smokeCodex = run(
-    'node',
-    ['scripts/guidance-codex-bridge.js', 'status', '--skip-cf-hooks'],
-    target
-  );
+  let smokeCodex = { status: 0, stdout: '', stderr: '' };
+  if (usesCodexMode(mode)) {
+    smokeCodex = run(
+      'node',
+      ['scripts/guidance-codex-bridge.js', 'status', '--skip-cf-hooks'],
+      target
+    );
+  }
 
   const passed =
     checks.every((check) => check.exists) &&
     syntaxChecks.every((check) => check.ok) &&
-    smoke.status === 0 &&
-    smokeCodex.status === 0;
+    (!usesClaudeMode(mode) || smoke.status === 0) &&
+    (!usesCodexMode(mode) || smokeCodex.status === 0);
 
   return {
     target,
+    targetMode: mode,
     passed,
     files: checks,
     syntaxChecks,
@@ -355,11 +405,13 @@ export function initRepo({
   targetRepo,
   force = false,
   installDeps = false,
+  targetMode = 'both',
   dual = true,
   skipCfInit = false,
   verify = true,
 }) {
   const target = resolve(targetRepo);
+  const mode = normalizeTargetMode(targetMode);
   if (!existsSync(target)) {
     throw new Error(`Target repo does not exist: ${target}`);
   }
@@ -371,7 +423,11 @@ export function initRepo({
 
   if (!skipCfInit) {
     const initArgs = ['@claude-flow/cli@latest', 'init'];
-    if (dual) initArgs.push('--dual');
+    if (mode === 'both') {
+      if (dual) initArgs.push('--dual');
+    } else if (mode === 'codex') {
+      initArgs.push('--codex');
+    }
 
     const initResult = run('npx', initArgs, target);
     claudeFlowInit = {
@@ -394,11 +450,12 @@ export function initRepo({
     targetRepo: target,
     force,
     installDeps,
+    targetMode: mode,
   });
 
   let verifyReport = null;
   if (verify) {
-    verifyReport = verifyRepo({ targetRepo: target });
+    verifyReport = verifyRepo({ targetRepo: target, targetMode: mode });
     if (!verifyReport.passed) {
       throw new Error(
         `Guidance wiring verification failed in ${target}. Run cf-guidance-impl verify --target ${target} for details.`
@@ -408,6 +465,7 @@ export function initRepo({
 
   return {
     target,
+    targetMode: mode,
     claudeFlowInit,
     install,
     verify: verifyReport,