create-harness-vibe-coding 0.7.2 → 0.8.0

package/src/generator.js

@@ -76,18 +76,12 @@ const EMPTY_DIRS = [
 export function harnessDest(file) {
   if (file === '.harness-version') return 'Harness/.harness-version';
   if (file === 'SETUP.md') return 'Harness/SETUP.md';
-  if (file === 'MEMORY.md') return 'Harness/MEMORY.md';
-  if (file.startsWith('scripts/')) return `Harness/${file}`;
-  if (file.startsWith('memory/')) return `Harness/${file}`;
-  if (file === 'docs/README.md') return 'Harness/README.md';
-  if (file.startsWith('docs/harness/')) return file.replace(/^docs\/harness\//, 'Harness/');
-  if (file.startsWith('docs/research/')) return file.replace(/^docs\/research\//, 'Harness/research/');
-  if (file.startsWith('docs/domain/')) return file.replace(/^docs\/domain\//, 'Harness/domain/');
-  if (file.startsWith('docs/features/')) return file.replace(/^docs\/features\//, 'Harness/features/');
-  if (file.startsWith('docs/workflows/')) return file.replace(/^docs\/workflows\//, 'Harness/workflows/');
-  if (file.startsWith('docs/tasks/')) return file.replace(/^docs\/tasks\//, 'Harness/tasks/');
-  return file;
-}
+  if (file === 'MEMORY.md') return 'Harness/MEMORY.md';
+  if (file.startsWith('scripts/')) return `Harness/${file}`;
+  if (file.startsWith('memory/')) return `Harness/${file}`;
+  if (file.startsWith('Harness/')) return file;
+  return file;
+}
 
 /**
  * Replace {{vars}} in file contents.
@@ -126,27 +120,39 @@ function normalizePath(filePath) {
 }
 
 export function getOptionalCatalog() {
-  if (!fs.existsSync(OPTIONAL_CATALOG)) {
-    return { skills: [], presets: {} };
-  }
+  if (!fs.existsSync(OPTIONAL_CATALOG)) {
+    return { skills: [], presets: {}, externalRecommendations: [] };
+  }
 
   return JSON.parse(fs.readFileSync(OPTIONAL_CATALOG, 'utf-8'));
 }
 
-function normalizeOptionList(value) {
+function normalizeOptionList(value) {
   const values = Array.isArray(value) ? value : [value];
   return values
     .filter(Boolean)
     .flatMap(item => String(item).split(','))
     .map(item => item.trim())
     .filter(Boolean);
-}
-
-function resolveOptionalSelection({ withOptions = [], withoutOptions = [], preset = undefined }) {
-  const catalog = getOptionalCatalog();
-  const skillsById = new Map(catalog.skills.map(skill => [skill.id, skill]));
-  const selected = [];
-  const errors = [];
+}
+
+function externalRecommendations(catalog) {
+  return Array.isArray(catalog.externalRecommendations)
+    ? catalog.externalRecommendations
+    : [];
+}
+
+function resolveOptionalSelection({
+  withOptions = [],
+  withoutOptions = [],
+  preset = undefined,
+  externalOptions = [],
+}) {
+  const catalog = getOptionalCatalog();
+  const skillsById = new Map(catalog.skills.map(skill => [skill.id, skill]));
+  const recommendationsById = new Map(externalRecommendations(catalog).map(item => [item.id, item]));
+  const selected = [];
+  const errors = [];
 
   if (preset) {
     if (!catalog.presets[preset]) {
@@ -165,37 +171,46 @@ function resolveOptionalSelection({ withOptions = [], withoutOptions = [], prese
       errors.push(`Unknown optional skill "${id}". Run --list-options to see available options.`);
     }
   }
-  for (const id of withoutIds) {
-    if (!skillsById.has(id)) {
-      errors.push(`Unknown optional skill in --without "${id}". Run --list-options to see available options.`);
-    }
-  }
-
-  const withoutSet = new Set(withoutIds);
-  const selectedIds = ids.filter(id => !withoutSet.has(id));
-
-  return {
-    catalog,
-    selectedSkills: errors.length ? [] : selectedIds.map(id => skillsById.get(id)),
-    errors,
-  };
-}
-
-function createCoreFileSpecs() {
-  const specs = walkFiles(TEMPLATES_DIR)
-    .map(file => normalizePath(file))
-    .sort()
-    .map(file => ({
-      dest: harnessDest(file),
-      src: path.join(TEMPLATES_DIR, ...file.split('/')),
-      type: 'common',
-    }));
-
-  specs.push({ dest: 'tests/.gitkeep', src: undefined, type: 'empty' });
-  return specs;
-}
-
-function createOptionalFileSpecs(selectedSkills) {
+  for (const id of withoutIds) {
+    if (!skillsById.has(id)) {
+      errors.push(`Unknown optional skill in --without "${id}". Run --list-options to see available options.`);
+    }
+  }
+
+  const recommendationIds = [...new Set(normalizeOptionList(externalOptions))];
+  for (const id of recommendationIds) {
+    if (!recommendationsById.has(id)) {
+      errors.push(`Unknown external recommendation "${id}". Run --list-options to see available options.`);
+    }
+  }
+
+  const withoutSet = new Set(withoutIds);
+  const selectedIds = ids.filter(id => !withoutSet.has(id));
+
+  return {
+    catalog,
+    selectedSkills: errors.length ? [] : selectedIds.map(id => skillsById.get(id)),
+    selectedRecommendations: errors.length ? [] : recommendationIds.map(id => recommendationsById.get(id)),
+    errors,
+  };
+}
+
+function createCoreFileSpecs() {
+  const specs = walkFiles(TEMPLATES_DIR)
+    .map(file => normalizePath(file))
+    .sort()
+    .map(file => ({
+      dest: harnessDest(file),
+      src: path.join(TEMPLATES_DIR, ...file.split('/')),
+      type: 'common',
+    }));
+
+  specs.push(...createCodexSkillMirrors(specs));
+  specs.push({ dest: 'tests/.gitkeep', src: undefined, type: 'empty' });
+  return specs;
+}
+
+function createOptionalFileSpecs(selectedSkills) {
   const specs = [];
 
   for (const skill of selectedSkills) {
@@ -208,12 +223,22 @@ function createOptionalFileSpecs(selectedSkills) {
           type: 'optional',
           skillId: skill.id,
         });
-      }
-    }
-  }
-
-  return specs;
-}
+      }
+    }
+  }
+
+  specs.push(...createCodexSkillMirrors(specs));
+  return specs;
+}
+
+function createCodexSkillMirrors(fileSpecs) {
+  return fileSpecs
+    .filter(spec => spec.dest.startsWith('.claude/skills/'))
+    .map(spec => ({
+      ...spec,
+      dest: spec.dest.replace(/^\.claude\/skills\//, '.agents/skills/'),
+    }));
+}
 
 function duplicateDests(fileSpecs) {
   const seen = new Set();
@@ -325,13 +350,13 @@ function nextBackupPath(destPath) {
   }
 }
 
-function registerOptionalContent(file, content, selectedSkills) {
+function registerOptionalContent(file, content, selectedSkills) {
   if (!selectedSkills.length) return content;
 
-  if (file === 'Harness/MEMORY.md') {
-    const lines = selectedSkills.map(skill => (
-      `- [${skill.id}](../.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Workflow: [workflows/${skill.id}.md](workflows/${skill.id}.md)`
-    ));
+  if (file === 'Harness/MEMORY.md') {
+    const lines = selectedSkills.map(skill => (
+      `- [${skill.id}](../.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Codex mirror: [${skill.id}](../.agents/skills/${skill.id}/SKILL.md). Workflow: [workflows/${skill.id}.md](workflows/${skill.id}.md)`
+    ));
     return content.replace(
       'Stack-specific skills can be added after the product shape is known.',
       `Installed optional skills:\n\n${lines.join('\n')}\n\nStack-specific skills can be added after the product shape is known.`,
@@ -345,8 +370,18 @@ function registerOptionalContent(file, content, selectedSkills) {
     return `${content.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
   }
 
-  return content;
-}
+  return content;
+}
+
+function registerExternalRecommendations(file, content, selectedRecommendations) {
+  if (!selectedRecommendations.length || file !== 'Harness/SETUP.md') return content;
+
+  const lines = selectedRecommendations.map(item => (
+    `- \`${item.id}\` - ${item.description} Recommendation only; not installed by this scaffold. Use the discovery/install hint: ${item.installHint}`
+  ));
+
+  return `${content.trimEnd()}\n\n## Selected External Recommendations\n\n${lines.join('\n')}\n`;
+}
 
 function registrationWarnings(plan, selectedSkills) {
   const warnings = [];
@@ -378,10 +413,11 @@ export function generate({
   targetDir,
   dryRun = false,
   onConflict = 'fail',
-  withOptions = [],
-  withoutOptions = [],
-  preset = undefined,
-}) {
+  withOptions = [],
+  withoutOptions = [],
+  preset = undefined,
+  externalOptions = [],
+}) {
   const created = [];
   const errors = [];
   const warnings = [];
@@ -394,7 +430,7 @@ export function generate({
     generatedTimestamp: new Date().toISOString(),
   };
 
-  const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset });
+  const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset, externalOptions });
   const fileSpecs = [
     ...createCoreFileSpecs(),
     ...createOptionalFileSpecs(optional.selectedSkills),
@@ -500,10 +536,11 @@ export function generate({
       }
       const spec = specsByDest.get(file);
       const destPath = path.join(resolvedDir, ...file.split('/'));
-      let content = spec.type === 'empty'
-        ? ''
-        : renderTemplate(spec.src, vars);
-      content = registerOptionalContent(file, content, optional.selectedSkills);
+      let content = spec.type === 'empty'
+        ? ''
+        : renderTemplate(spec.src, vars);
+      content = registerOptionalContent(file, content, optional.selectedSkills);
+      content = registerExternalRecommendations(file, content, optional.selectedRecommendations);
 
       fs.mkdirSync(path.dirname(destPath), { recursive: true });
       fs.writeFileSync(destPath, content, 'utf-8');
@@ -521,7 +558,8 @@ export function generate({
       }
       parsed.generator = vars.generatorVersion;
       parsed.generated = vars.generatedTimestamp;
-      parsed.options = optional.selectedSkills.map(s => s.id);
+      parsed.options = optional.selectedSkills.map(s => s.id);
+      parsed.externalRecommendations = optional.selectedRecommendations.map(item => item.id);
       parsed.autoCheck = true;
       parsed.checksums = computeChecksums(generatedFiles);
       // Build sources map from fileSpecs (all writable files, not just generatedFiles)

package/src/index.js

@@ -1,14 +1,17 @@
-#!/usr/bin/env node
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { askProjectName, askTargetDir } from './prompts.js';
-import { generate, getOptionalCatalog } from './generator.js';
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { askConflictPolicy, askOptionalSelections, askProjectName, askTargetDir } from './prompts.js';
+import { generate, getOptionalCatalog } from './generator.js';
 
 // ── CLI flags ──────────────────────────────────────────────
 const raw = process.argv.slice(2);
-const parsed = parseArgs(raw);
-const showHelp = parsed.flags.help || parsed.flags.h;
-const skipPrompts = parsed.flags.yes || parsed.flags.y;
+const parsed = parseArgs(raw);
+const showHelp = parsed.flags.help || parsed.flags.h;
+const skipPrompts = parsed.flags.yes || parsed.flags.y;
+const conflictPolicyProvided = parsed.flags.onConflict !== undefined;
 
 if (parsed.errors.length > 0) {
   for (const err of parsed.errors) {
@@ -33,11 +36,14 @@ if (showHelp) {
   console.log('    -h, --help                   Show this help');
   console.log('    --dry-run                    Print the planned writes without creating files');
   console.log('    --on-conflict <policy>       fail, skip, backup, or overwrite (default: fail)');
-  console.log('    --with <id,id>               Add optional local workflow skills');
-  console.log('    --without <id,id>            Remove optional workflow skills selected by --preset or --with');
-  console.log('    --preset <name>              Add a built-in optional workflow preset');
-  console.log('    --list-options               Print optional workflow skills and presets');
-  console.log('    --json                       Output machine-readable JSON (use with --dry-run for planning)');
+  console.log('    --with <id,id>               Add optional local workflow skills');
+  console.log('    --without <id,id>            Remove optional workflow skills selected by --preset or --with');
+  console.log('    --recommend <id,id>          Record recommendation-only external capabilities');
+  console.log('    --preset <name>              Add a built-in optional workflow preset');
+  console.log('    --list-options               Print optional workflow skills and presets');
+  console.log('    --json                       Output machine-readable JSON (use with --dry-run for planning)');
+  console.log('');
+  console.log('  Interactive mode offers checkbox selection for optional workflows and external recommendations.');
   console.log('');
   console.log('  Examples:');
   console.log('    npx create-harness-vibe-coding@latest');
@@ -66,10 +72,11 @@ const generationOptions = {
   dryRun: Boolean(parsed.flags.dryRun),
   onConflict: parsed.flags.onConflict || 'fail',
   withOptions: parsed.flags.with || [],
-  withoutOptions: parsed.flags.without || [],
-  preset: parsed.flags.preset,
-  json: Boolean(parsed.flags.json),
-};
+  withoutOptions: parsed.flags.without || [],
+  externalOptions: parsed.flags.recommend || [],
+  preset: parsed.flags.preset,
+  json: Boolean(parsed.flags.json),
+};
 
 const DEFAULT_NAME = 'my-vibe-project';
 
@@ -99,8 +106,8 @@ if (argName || skipPrompts) {
 
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
-  console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, tests/')}`);
+  console.log(`  Directory   ${pc.green(targetDir)}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, tests/')}`);
   if (generationOptions.dryRun) {
     console.log(`  Mode        ${pc.yellow('dry-run')}`);
   }
@@ -108,9 +115,12 @@ if (argName || skipPrompts) {
   if (generationOptions.withOptions.length > 0) {
     console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
   }
-  if (generationOptions.withoutOptions.length > 0) {
-    console.log(`  Without     ${pc.cyan(generationOptions.withoutOptions.join(','))}`);
-  }
+  if (generationOptions.withoutOptions.length > 0) {
+    console.log(`  Without     ${pc.cyan(generationOptions.withoutOptions.join(','))}`);
+  }
+  if (generationOptions.externalOptions.length > 0) {
+    console.log(`  Recommend   ${pc.cyan(generationOptions.externalOptions.join(','))}`);
+  }
   if (generationOptions.preset) {
     console.log(`  Preset      ${pc.cyan(generationOptions.preset)}`);
   }
@@ -131,19 +141,54 @@ if (argName || skipPrompts) {
     console.log(pc.dim(`  Project: ${projectName} (default)`));
   }
 
-  try {
-    targetDir = await askTargetDir(projectName);
-  } catch {
+  try {
+    targetDir = await askTargetDir(projectName);
+  } catch {
     targetDir = `./${projectName}`;
     console.log(pc.dim(`  Directory: ${targetDir} (default)`));
-  }
+  }
+
+  const scan = scanTarget(targetDir);
+  printScan(scan);
+
+  if (!generationOptions.dryRun && !conflictPolicyProvided && scan.needsConflictPolicy) {
+    try {
+      generationOptions.onConflict = await askConflictPolicy(scan);
+    } catch {
+      generationOptions.onConflict = 'skip';
+      console.log(pc.dim('  Conflicts: skip (preserve existing files default)'));
+    }
+  }
+
+  const optionFlagsProvided = generationOptions.withOptions.length > 0
+    || generationOptions.withoutOptions.length > 0
+    || generationOptions.externalOptions.length > 0
+    || generationOptions.preset;
+
+  if (!optionFlagsProvided) {
+    try {
+      const selected = await askOptionalSelections(getOptionalCatalog());
+      generationOptions.withOptions = selected.withOptions;
+      generationOptions.externalOptions = selected.externalOptions;
+    } catch {
+      generationOptions.withOptions = [];
+      generationOptions.externalOptions = [];
+      console.log(pc.dim('  Optional: none (default)'));
+    }
+  }
 
   console.log('');
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
-  console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, tests/')}`);
-  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
+  console.log(`  Directory   ${pc.green(targetDir)}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, tests/')}`);
+  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
+  if (generationOptions.withOptions.length > 0) {
+    console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
+  }
+  if (generationOptions.externalOptions.length > 0) {
+    console.log(`  Recommend   ${pc.cyan(generationOptions.externalOptions.join(','))}`);
+  }
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -204,10 +249,11 @@ function printResult(result, targetDir) {
 
     printWarnings(result);
 
-    console.log(pc.bold('Next steps:'));
-    console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
-    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
-    console.log(`  Tell Claude: "${pc.yellow('Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
+    console.log(pc.bold('Next steps:'));
+    console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
+    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
+    console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
+    console.log(`  Tell your agent: "${pc.yellow('Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
     console.log('');
     console.log(pc.dim('  Harness/SETUP.md is temporary. Delete it after initialization.'));
     console.log('');
@@ -259,10 +305,10 @@ function parseArgs(args) {
       flags.yes = true;
     } else if (arg === '--dry-run') {
       flags.dryRun = true;
-    } else if (arg === '--list-options') {
-      flags.listOptions = true;
-    } else if (arg === '--json') {
-      flags.json = true;
+    } else if (arg === '--list-options') {
+      flags.listOptions = true;
+    } else if (arg === '--json') {
+      flags.json = true;
     } else if (arg === '--on-conflict') {
       const parsedValue = readValue('--on-conflict', i);
       flags.onConflict = parsedValue.value;
@@ -281,9 +327,22 @@ function parseArgs(args) {
       if (parsedValue.value !== undefined) flags.without.push(parsedValue.value);
       i = parsedValue.nextIndex;
     } else if (arg.startsWith('--without=')) {
-      const value = readEqualsValue('--without', arg.slice('--without='.length));
-      if (value !== undefined) flags.without.push(value);
-    } else if (arg === '--preset') {
+      const value = readEqualsValue('--without', arg.slice('--without='.length));
+      if (value !== undefined) flags.without.push(value);
+    } else if (arg === '--recommend') {
+      const parsedValue = readValue('--recommend', i);
+      if (parsedValue.value !== undefined) {
+        if (!flags.recommend) flags.recommend = [];
+        flags.recommend.push(parsedValue.value);
+      }
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--recommend=')) {
+      const value = readEqualsValue('--recommend', arg.slice('--recommend='.length));
+      if (value !== undefined) {
+        if (!flags.recommend) flags.recommend = [];
+        flags.recommend.push(value);
+      }
+    } else if (arg === '--preset') {
       const parsedValue = readValue('--preset', i);
       flags.preset = parsedValue.value;
       i = parsedValue.nextIndex;
@@ -308,13 +367,21 @@ function printOptions() {
     console.log(`  ${pc.cyan(skill.id)} - ${skill.description}`);
   }
 
-  console.log('');
-  console.log(pc.bold('Presets:'));
-  for (const [name, skills] of Object.entries(catalog.presets)) {
-    console.log(`  ${pc.cyan(name)} - ${skills.join(', ')}`);
-  }
-  console.log('');
-}
+  console.log('');
+  console.log(pc.bold('Presets:'));
+  for (const [name, skills] of Object.entries(catalog.presets)) {
+    console.log(`  ${pc.cyan(name)} - ${skills.join(', ')}`);
+  }
+
+  if (catalog.externalRecommendations?.length) {
+    console.log('');
+    console.log(pc.bold('External recommendations:'));
+    for (const item of catalog.externalRecommendations) {
+      console.log(`  ${pc.cyan(item.id)} - ${item.description} (${item.installMode})`);
+    }
+  }
+  console.log('');
+}
 
 function printSummary(summary) {
   console.log(`  created     ${pc.green(summary.created)}`);
@@ -345,11 +412,54 @@ function printWarnings(result) {
   }
 }
 
-function printJsonResult(result) {
+function printJsonResult(result) {
   // Remove `created` array from output — it is already in the plan, avoid duplication
   const { created, ...rest } = result;
   console.log(JSON.stringify(rest, null, 2));
   if (!result.success) {
     process.exit(1);
   }
-}
+}
+
+function scanTarget(targetDir) {
+  const resolvedDir = path.resolve(process.cwd(), targetDir);
+  const exists = fs.existsSync(resolvedDir);
+  const isDirectory = exists && fs.statSync(resolvedDir).isDirectory();
+  const entries = isDirectory
+    ? fs.readdirSync(resolvedDir)
+    : [];
+  const hasHarness = isDirectory && fs.existsSync(path.join(resolvedDir, 'Harness'));
+
+  return {
+    resolvedDir,
+    exists,
+    isDirectory,
+    entries,
+    hasHarness,
+    hasClaude: isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md')),
+    hasAgents: isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md')),
+    hasAgentSkills: isDirectory && fs.existsSync(path.join(resolvedDir, '.agents')),
+    hasCodex: isDirectory && fs.existsSync(path.join(resolvedDir, '.codex')),
+    hasDocs: isDirectory && fs.existsSync(path.join(resolvedDir, 'docs')),
+    needsConflictPolicy: exists && (!isDirectory || entries.length > 0 || hasHarness),
+  };
+}
+
+function printScan(scan) {
+  if (!scan.exists) return;
+
+  console.log('');
+  console.log(pc.bold('Root scan:'));
+  console.log(`  Directory   ${pc.dim(scan.resolvedDir)}`);
+  if (!scan.isDirectory) {
+    console.log(`  Conflict    ${pc.yellow('target path exists and is not a directory')}`);
+    return;
+  }
+  console.log(`  Entries     ${pc.cyan(scan.entries.length)}`);
+  if (scan.hasHarness) console.log(`  Harness     ${pc.yellow('exists')}`);
+  if (scan.hasClaude) console.log(`  CLAUDE.md   ${pc.yellow('exists')}`);
+  if (scan.hasAgents) console.log(`  AGENTS.md   ${pc.yellow('exists')}`);
+  if (scan.hasAgentSkills) console.log(`  .agents/    ${pc.yellow('exists')}`);
+  if (scan.hasCodex) console.log(`  .codex/     ${pc.yellow('exists')}`);
+  if (scan.hasDocs) console.log(`  docs/       ${pc.dim('project-owned; Harness stays in Harness/')}`);
+}