create-harness-vibe-coding 0.8.16 → 0.8.18

package/src/generator.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
@@ -70,9 +71,45 @@ const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
 const OPTIONAL_DIR = path.resolve(__dirname, '..', 'templates', 'optional');
 const OPTIONAL_CATALOG = path.join(OPTIONAL_DIR, 'catalog.json');
 const VALID_CONFLICT_POLICIES = new Set(['fail', 'skip', 'backup', 'overwrite']);
+const VALID_INSTALL_SCOPES = new Set(['project', 'global']);
+const RETIRED_OPTION_MESSAGES = new Map([
+  ['browser-e2e', 'Optional workflow "browser-e2e" has been retired; wf-browser is built in by default. Use /wf-browser, $wf-browser, or /skills wf-browser instead.'],
+]);
 const EMPTY_DIRS = [
   'tests',
 ];
+const GLOBAL_RUNTIME_EXCLUDE = [
+  /^Harness\/PROGRESS\.md$/,
+  /^Harness\/tasks\//,
+  /^Harness\/research\//,
+  /^Harness\/project\//,
+];
+const GLOBAL_PROJECT_STATE_INCLUDE = [
+  /^Harness\/\.harness-version$/,
+  /^Harness\/PROGRESS\.md$/,
+  /^Harness\/settings\.json$/,
+  /^Harness\/tasks\//,
+  /^Harness\/memory\//,
+  /^Harness\/research\//,
+  /^Harness\/project\//,
+];
+
+const GLOBAL_PROJECT_TEMPLATE_DESTS = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  'Harness/README.md',
+  'Harness/MEMORY.md',
+  'Harness/settings.json',
+  'Harness/specs/guides/SETUP.md',
+];
+
+const PROJECT_USER_STATE_PATTERNS = [
+  'Harness/PROGRESS.md',
+  'Harness/tasks/**',
+  'Harness/memory/**',
+  'Harness/research/**',
+  'Harness/project/**',
+];
 
 export function harnessDest(file) {
   if (file === '.harness-version') return 'Harness/.harness-version';
@@ -120,6 +157,262 @@ function normalizePath(filePath) {
   return filePath.replace(/\\/g, '/');
 }
 
+function comparablePath(filePath) {
+  const resolved = path.resolve(filePath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function containsPath(parent, child) {
+  const rel = path.relative(comparablePath(parent), comparablePath(child));
+  return rel === '' || (rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function pathsOverlap(a, b) {
+  return containsPath(a, b) || containsPath(b, a);
+}
+
+function defaultGlobalDir() {
+  return process.env.HARNESS_GLOBAL_HOME
+    || path.join(os.homedir(), '.harness', 'create-harness-vibe-coding');
+}
+
+function defaultHostGlobalRoots(hostGlobalDir = undefined) {
+  if (hostGlobalDir || process.env.HARNESS_HOST_GLOBAL_HOME) {
+    const base = path.resolve(process.cwd(), hostGlobalDir || process.env.HARNESS_HOST_GLOBAL_HOME);
+    return {
+      claude: path.join(base, 'claude'),
+      codex: path.join(base, 'codex'),
+      opencode: path.join(base, 'opencode'),
+    };
+  }
+
+  return {
+    claude: process.env.CLAUDE_HOME || path.join(os.homedir(), '.claude'),
+    codex: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+    opencode: process.env.OPENCODE_CONFIG_HOME || path.join(os.homedir(), '.config', 'opencode'),
+  };
+}
+
+function isGlobalRuntimeDest(dest) {
+  return !GLOBAL_RUNTIME_EXCLUDE.some(pattern => pattern.test(dest));
+}
+
+function isGlobalProjectStateDest(dest) {
+  return GLOBAL_PROJECT_STATE_INCLUDE.some(pattern => pattern.test(dest));
+}
+
+function renderInlineTemplate(content, vars) {
+  let rendered = content;
+  for (const [key, value] of Object.entries(vars)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, value);
+  }
+  return rendered;
+}
+
+function virtualSpec(dest, content) {
+  return {
+    dest,
+    type: 'virtual',
+    content,
+  };
+}
+
+function mapHostSpec(spec, fromPrefix, toPrefix = '') {
+  return {
+    ...spec,
+    dest: `${toPrefix}${spec.dest.slice(fromPrefix.length)}`,
+    projectDest: spec.dest,
+  };
+}
+
+function mapExactHostSpec(spec, dest) {
+  return {
+    ...spec,
+    dest,
+    projectDest: spec.dest,
+  };
+}
+
+function createHostGlobalFileSpecs(allFileSpecs) {
+  const byDest = new Map(allFileSpecs.map(spec => [spec.dest, spec]));
+  const claude = [];
+  const codex = [];
+  const opencode = [];
+
+  for (const spec of allFileSpecs) {
+    if (spec.dest.startsWith('.claude/commands/')) claude.push(mapHostSpec(spec, '.claude/'));
+    if (spec.dest.startsWith('.claude/skills/')) claude.push(mapHostSpec(spec, '.claude/'));
+    if (spec.dest.startsWith('.claude/agents/')) claude.push(mapHostSpec(spec, '.claude/'));
+    if (spec.dest.startsWith('.claude/rules/')) claude.push(mapHostSpec(spec, '.claude/'));
+    if (spec.dest.startsWith('.agents/skills/')) codex.push(mapHostSpec(spec, '.agents/'));
+    if (spec.dest.startsWith('.opencode/commands/')) opencode.push(mapHostSpec(spec, '.opencode/'));
+    if (spec.dest.startsWith('.opencode/agents/')) opencode.push(mapHostSpec(spec, '.opencode/'));
+    if (spec.dest.startsWith('.opencode/plugins/')) opencode.push(mapHostSpec(spec, '.opencode/'));
+  }
+
+  const claudeSettings = byDest.get('.claude/settings.json');
+  if (claudeSettings) claude.push(mapExactHostSpec(claudeSettings, 'settings.json'));
+
+  const codexConfig = byDest.get('.codex/config.toml');
+  if (codexConfig) codex.push(mapExactHostSpec(codexConfig, 'config.toml'));
+  const codexHooks = byDest.get('.codex/hooks.json');
+  if (codexHooks) codex.push(mapExactHostSpec(codexHooks, 'hooks.json'));
+
+  const opencodeConfig = byDest.get('opencode.json');
+  if (opencodeConfig) opencode.push(mapExactHostSpec(opencodeConfig, 'opencode.json'));
+
+  return { claude, codex, opencode };
+}
+
+function createHostGlobalPlans(allFileSpecs, hostGlobalDir = undefined) {
+  const roots = defaultHostGlobalRoots(hostGlobalDir);
+  const specs = createHostGlobalFileSpecs(allFileSpecs);
+  return Object.entries(specs).map(([host, fileSpecs]) => ({
+    host,
+    root: roots[host],
+    fileSpecs,
+    specsByDest: new Map(fileSpecs.map(spec => [spec.dest, spec])),
+    plan: createPlan(roots[host], fileSpecs),
+    candidateSet: new Set(fileSpecs.map(spec => spec.dest)),
+  }));
+}
+
+function createOwnershipClasses({ resolvedGlobalDir, hostPlans }) {
+  const hostGlobalTemplates = {};
+  for (const hostPlan of hostPlans || []) {
+    hostGlobalTemplates[hostPlan.host] = {
+      root: normalizePath(hostPlan.root),
+      paths: hostPlan.fileSpecs.map(spec => spec.dest).sort(),
+    };
+  }
+
+  return {
+    projectUserState: [...PROJECT_USER_STATE_PATTERNS],
+    projectTemplateBridge: [...GLOBAL_PROJECT_TEMPLATE_DESTS],
+    globalRuntimeTemplate: resolvedGlobalDir ? normalizePath(resolvedGlobalDir) : null,
+    hostGlobalTemplates,
+    userOwnedProtection: 'Existing non-Harness files at Harness-interest paths are preserved or surfaced as conflicts; generated project template files follow the selected conflict policy.',
+  };
+}
+
+function createGlobalProjectBridgeSpecs({ globalDir }) {
+  const globalPath = normalizePath(globalDir);
+  return [
+    virtualSpec('CLAUDE.md', `# CLAUDE.md
+
+This project uses a global Harness runtime at \`${globalPath}\`.
+
+Project-local state is authoritative:
+
+- Tasks: \`Harness/tasks/\`
+- Active pointer: \`Harness/PROGRESS.md\`
+- Project memory: \`Harness/MEMORY.md\` and \`Harness/memory/\`
+- Project settings: \`Harness/settings.json\`
+
+Load global workflow docs, command surfaces, agents, and scripts from \`${globalPath}\`.
+Project settings override global settings. Do not store project task state in the global runtime. Do not store secrets or raw transcripts in project or global memory/settings.
+`),
+    virtualSpec('AGENTS.md', `# AGENTS.md
+
+Read \`CLAUDE.md\` first. This project uses the global Harness runtime at \`${globalPath}\`.
+
+Keep task capsules, project memory, and project settings under local \`Harness/\`; use the global runtime only for shared framework docs, commands, skills, agents, settings defaults, and scripts.
+`),
+    virtualSpec('Harness/README.md', `# {{projectName}} - Project Harness State
+
+This project is bound to a global Harness runtime at \`${globalPath}\`.
+
+Project-local files:
+
+- \`Harness/PROGRESS.md\` - active task pointer and task index.
+- \`Harness/tasks/\` - task capsules; always project-local.
+- \`Harness/MEMORY.md\` and \`Harness/memory/\` - project memory.
+- \`Harness/settings.json\` - project settings and overrides.
+- \`Harness/research/\` and \`Harness/project/\` - project facts.
+
+Global runtime files:
+
+- \`${globalPath}/Harness/README.md\` - shared Harness router.
+- \`${globalPath}/Harness/MEMORY.md\` and \`${globalPath}/Harness/memory/\` - global memory and resource index.
+- \`${globalPath}/Harness/settings.json\` - global settings defaults.
+- \`${globalPath}/.claude/\`, \`${globalPath}/.agents/\`, \`${globalPath}/.opencode/\` - shared runtime command, skill, and agent surfaces.
+
+Never discover task context from the global runtime. Resume work from local \`Harness/PROGRESS.md\` and local task \`STATE.json\`.
+Project settings override global settings. Existing user-authored files are preserved unless the user explicitly chooses an overwrite-capable conflict policy.
+`),
+    virtualSpec('Harness/MEMORY.md', `# MEMORY.md - {{projectName}} Project Memory
+
+Project memory lives here and under \`Harness/memory/\`.
+
+Global memory lives under \`${globalPath}/Harness/memory/\` and is only for cross-project lessons and preferences.
+
+Project settings live in \`Harness/settings.json\`; global settings defaults live in \`${globalPath}/Harness/settings.json\`. Project settings win.
+
+Rules:
+
+- Keep project-specific decisions, task evidence, and repo facts in this project.
+- Keep reusable cross-project lessons in global memory only when safe and non-secret.
+- Never store project task state, secrets, raw transcripts, or private project facts in global memory/settings.
+`),
+    virtualSpec('Harness/specs/guides/SETUP.md', `# SETUP.md - {{projectName}} Global Harness Bridge
+
+This project uses a global Harness runtime at \`${globalPath}\`.
+
+Read the full setup guide from \`${globalPath}/Harness/specs/guides/SETUP.md\`.
+
+Project-local state remains authoritative:
+
+- \`Harness/PROGRESS.md\`
+- \`Harness/tasks/\`
+- \`Harness/memory/\`
+- \`Harness/settings.json\`
+- \`Harness/research/\`
+- \`Harness/project/\`
+
+Run validators and shared scripts from the global runtime unless this project later installs a full project-local Harness runtime.
+Project settings override global settings. Existing user-authored files at Harness-interest paths are preserved or surfaced for review; generated project template files follow the selected conflict policy.
+`),
+  ];
+}
+
+function installMetadata({ installScope, resolvedGlobalDir, hostPlans = [] }) {
+  if (installScope !== 'global') return { installScope: 'project' };
+  return {
+    installScope: 'global',
+    globalDir: normalizePath(resolvedGlobalDir),
+    copyMode: 'copy',
+    projectState: {
+      tasks: 'Harness/tasks/',
+      progress: 'Harness/PROGRESS.md',
+      memory: 'Harness/memory/',
+      settings: 'Harness/settings.json',
+      research: 'Harness/research/',
+      project: 'Harness/project/',
+    },
+    memoryScopes: {
+      project: 'Harness/memory/',
+      global: `${normalizePath(resolvedGlobalDir)}/Harness/memory/`,
+    },
+    settingsScopes: {
+      precedence: ['project', 'global'],
+      project: 'Harness/settings.json',
+      global: `${normalizePath(resolvedGlobalDir)}/Harness/settings.json`,
+      secretsPolicy: 'never store secrets in project/global settings or memory',
+    },
+    hostGlobal: {
+      copyMode: 'copy',
+      targets: Object.fromEntries(hostPlans.map(hostPlan => [
+        hostPlan.host,
+        {
+          root: normalizePath(hostPlan.root),
+          files: hostPlan.fileSpecs.map(spec => spec.dest).sort(),
+        },
+      ])),
+    },
+    ownershipClasses: createOwnershipClasses({ resolvedGlobalDir, hostPlans }),
+  };
+}
+
 export function getOptionalCatalog() {
   if (!fs.existsSync(OPTIONAL_CATALOG)) {
     return { skills: [], presets: {}, externalRecommendations: [] };
@@ -154,6 +447,7 @@ function resolveOptionalSelection({
   const recommendationsById = new Map(externalRecommendations(catalog).map(item => [item.id, item]));
   const selected = [];
   const errors = [];
+  const warnings = [];
 
   if (preset) {
     if (!catalog.presets[preset]) {
@@ -168,12 +462,16 @@ function resolveOptionalSelection({
   const ids = [...new Set(selected)];
   const withoutIds = [...new Set(normalizeOptionList(withoutOptions))];
   for (const id of ids) {
-    if (!skillsById.has(id)) {
+    if (RETIRED_OPTION_MESSAGES.has(id)) {
+      warnings.push(RETIRED_OPTION_MESSAGES.get(id));
+    } else if (!skillsById.has(id)) {
       errors.push(`Unknown optional skill "${id}". Run --list-options to see available options.`);
     }
   }
   for (const id of withoutIds) {
-    if (!skillsById.has(id)) {
+    if (RETIRED_OPTION_MESSAGES.has(id)) {
+      warnings.push(`Optional workflow "${id}" is retired and built in/no-op for --without.`);
+    } else if (!skillsById.has(id)) {
       errors.push(`Unknown optional skill in --without "${id}". Run --list-options to see available options.`);
     }
   }
@@ -186,13 +484,14 @@ function resolveOptionalSelection({
   }
 
   const withoutSet = new Set(withoutIds);
-  const selectedIds = ids.filter(id => !withoutSet.has(id));
+  const selectedIds = ids.filter(id => !withoutSet.has(id) && !RETIRED_OPTION_MESSAGES.has(id));
 
   return {
     catalog,
     selectedSkills: errors.length ? [] : selectedIds.map(id => skillsById.get(id)),
     selectedRecommendations: errors.length ? [] : recommendationIds.map(id => recommendationsById.get(id)),
     errors,
+    warnings,
   };
 }
 
@@ -278,7 +577,7 @@ function symlinkInChain(rootDir, absPath) {
   return null;
 }
 
-function createPlan(resolvedDir, fileSpecs) {
+function createPlan(resolvedDir, fileSpecs, { includeEmptyDirs = true } = {}) {
   const plan = {
     create: [],
     skip: [],
@@ -299,8 +598,10 @@ function createPlan(resolvedDir, fileSpecs) {
       dir = path.posix.dirname(dir);
     }
   }
-  for (const dir of EMPTY_DIRS) {
-    dirSet.add(dir);
+  if (includeEmptyDirs) {
+    for (const dir of EMPTY_DIRS) {
+      dirSet.add(dir);
+    }
   }
 
   for (const dir of [...dirSet].sort()) {
@@ -350,7 +651,7 @@ function readOwnershipManifest() {
  *
  * Manifest-present: candidate set = manifest.frameworkOwned paths UNION the
  * selected optional skills' manifest.optionalOwned paths. This includes optional
- * skill paths like browser-e2e (fixing the bug where same-name user files at
+ * skill paths like ui-ux-review (fixing the bug where same-name user files at
  * optional-skill paths were clobbered).
  *
  * Manifest-absent (null): candidate set = all fileSpec dests (the exact set of
@@ -405,20 +706,33 @@ export function isHarnessOwnedContent(content) {
 /**
  * Returns true if an existing on-disk file is a Harness-interest candidate path
  * (per the manifest-first candidate set) that was NOT authored by this scaffold
- * (candidate path + no ownership marker). Such user-authored files are preserved
- * (skip) regardless of the conflict policy, mirroring the updater safety rule.
+ * (candidate path + no ownership marker + no matching template content).
+ * Such user-authored files are preserved (skip) regardless of the conflict policy,
+ * mirroring the updater safety rule.
+ *
+ * Ownership is determined by content marker first, then by exact template content
+ * match (for JSON/TOML configs without markers). Manifest declaration alone does
+ * NOT grant ownership — a user file at a manifest path without marker is still
+ * user-owned.
  */
-function existingCandidateIsUserOwned(dest, destPath, candidateSet) {
+function existingCandidateIsUserOwned(dest, destPath, candidateSet, srcPath = null) {
   if (!candidateSet.has(dest)) return false;
   try {
     const content = fs.readFileSync(destPath, 'utf-8');
-    return !isHarnessOwnedContent(content);
+    // Harness content marker present → Harness-owned
+    if (isHarnessOwnedContent(content)) return false;
+    // Same content as template source → Harness-generated → Harness-owned
+    if (srcPath && fs.existsSync(srcPath)) {
+      const templateContent = fs.readFileSync(srcPath, 'utf-8');
+      if (content === templateContent) return false;
+    }
+    return true; // user-owned: no marker, not template content
   } catch {
     return false;
   }
 }
 
-function addFileActions(plan, fileSpecs, resolvedDir, onConflict, candidateSet) {
+function addFileActions(plan, fileSpecs, resolvedDir, onConflict, candidateSet, specsByDest = null) {
   for (const { dest: file } of fileSpecs) {
     const destPath = path.join(resolvedDir, ...file.split('/'));
 
@@ -436,15 +750,20 @@ function addFileActions(plan, fileSpecs, resolvedDir, onConflict, candidateSet)
       continue;
     }
 
+    // Look up the template source path for content comparison
+    const spec = specsByDest ? specsByDest.get(file) : null;
+    const srcPath = spec && spec.type !== 'empty' && spec.type !== 'virtual' ? spec.src : null;
+
     // G4 guard: a non-Harness same-name candidate (any Harness-interest path
     // — agent/command/skill/optional-skill/script per the manifest-first
     // candidate set — without an ownership marker) must NEVER be overwritten.
     // Under overwrite/backup/skip it is preserved via plan.skip; under fail it
     // is blocked via plan.conflict so the collision surfaces (matching the fail
-    // branch below). Only Harness-owned files (marker present) reach the normal
-    // policy switch. Mirrors the wf-update-check.mjs safety rule; see
-    // existingCandidateIsUserOwned / isHarnessOwnedContent above.
-    if (existingCandidateIsUserOwned(file, destPath, candidateSet)) {
+    // branch below). Only Harness-owned files (marker present or template
+    // content match) reach the normal policy switch. Mirrors the
+    // wf-update-check.mjs safety rule; see existingCandidateIsUserOwned /
+    // isHarnessOwnedContent above.
+    if (existingCandidateIsUserOwned(file, destPath, candidateSet, srcPath)) {
       if (onConflict === 'fail') {
         plan.conflict.push(file);
       } else {
@@ -477,6 +796,14 @@ function createSummary(plan, { noWrites = false } = {}) {
   };
 }
 
+function createHostSummary(hostPlans, options = {}) {
+  return hostPlans.map(hostPlan => ({
+    host: hostPlan.host,
+    root: normalizePath(hostPlan.root),
+    summary: createSummary(hostPlan.plan, options),
+  }));
+}
+
 function nextBackupPath(destPath) {
   const first = `${destPath}.harness-backup`;
   if (!fs.existsSync(first)) {
@@ -493,7 +820,6 @@ function nextBackupPath(destPath) {
 
 function registerOptionalContent(file, content, selectedSkills) {
   if (!selectedSkills.length) return content;
-  const hasBrowserE2e = selectedSkills.some(skill => skill.id === 'browser-e2e');
 
   if (file === 'Harness/MEMORY.md') {
     const lines = selectedSkills.map(skill => (
@@ -509,25 +835,7 @@ function registerOptionalContent(file, content, selectedSkills) {
     const lines = selectedSkills.map(skill => (
       `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
     ));
-    let next = content;
-    if (hasBrowserE2e) {
-      next = next.replace(
-        '| Optional workflow installed |',
-        '| Browser E2E testing or automation | /wf-browser, $wf-browser, browser, e2e, web automation, screenshot verify, page test, browser test, Playwright, CDP | [workflows/browser-e2e.md](workflows/browser-e2e.md), [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) | UI/API contract, CLI commands, screenshots, traces, validation matrix |\n| Optional workflow installed |',
-      );
-      next = next.replace(
-        '| `/wf-readme [task]` |',
-        '| `/wf-browser [task]` | `$wf-browser [task]` | Optional browser automation/E2E workflow when `browser-e2e` is installed |\n| `/wf-readme [task]` |',
-      );
-    }
-    return `${next.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
-  }
-
-  if ((file === '.claude/commands/wf-help.md' || file === '.opencode/commands/wf-help.md') && hasBrowserE2e) {
-    return content.replace(
-      '| `/wf-readme <task>` |',
-      '| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |\n| `/wf-readme <task>` |',
-    );
+    return `${content.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
   }
 
   return content;
@@ -572,6 +880,103 @@ function registrationWarnings(plan, selectedSkills) {
   return warnings;
 }
 
+function writeGeneratedPlan({
+  plan,
+  fileSpecs,
+  specsByDest,
+  resolvedDir,
+  vars,
+  optional,
+  metadata,
+  createdPrefix = '',
+}) {
+  const created = [];
+  const generatedFiles = [];
+
+  for (const dir of plan.mkdir) {
+    const dirPath = dir === './'
+      ? resolvedDir
+      : path.join(resolvedDir, ...dir.slice(0, -1).split('/'));
+    const __slMkdir = symlinkInChain(resolvedDir, dirPath);
+    if (__slMkdir) throw new Error(`Cannot create directory ${createdPrefix}${dir}: symlinked directory in path (${__slMkdir})`);
+    fs.mkdirSync(dirPath, { recursive: true });
+    created.push(`${createdPrefix}${dir === './' ? './ (directory)' : `${dir} (directory)`}`);
+  }
+
+  for (const file of plan.backup) {
+    const destPath = path.join(resolvedDir, ...file.split('/'));
+    const __slBackup = symlinkInChain(resolvedDir, destPath);
+    if (__slBackup) throw new Error(`Cannot backup ${createdPrefix}${file}: symlinked directory in path (${__slBackup})`);
+    if (fs.existsSync(destPath)) {
+      try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot backup ${createdPrefix}${file}: ${e.message}`); }
+    }
+    fs.renameSync(destPath, nextBackupPath(destPath));
+  }
+
+  const writableFiles = [
+    ...plan.create,
+    ...plan.overwrite,
+    ...plan.backup,
+  ];
+
+  const HARNESS_VERSION_DEST = 'Harness/.harness-version';
+  let harnessVersionSpec = null;
+
+  for (const file of writableFiles) {
+    if (file === HARNESS_VERSION_DEST) {
+      harnessVersionSpec = specsByDest.get(file);
+      continue;
+    }
+    const spec = specsByDest.get(file);
+    const destPath = path.join(resolvedDir, ...file.split('/'));
+    const __slWrite = symlinkInChain(resolvedDir, destPath);
+    if (__slWrite) throw new Error(`Cannot create/overwrite ${createdPrefix}${file}: symlinked directory in path (${__slWrite})`);
+    if (fs.existsSync(destPath)) {
+      try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot create/overwrite ${createdPrefix}${file}: ${e.message}`); }
+    }
+    let content = spec.type === 'empty'
+      ? ''
+      : spec.type === 'virtual'
+        ? renderInlineTemplate(spec.content, vars)
+        : 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');
+    created.push(`${createdPrefix}${file}`);
+    generatedFiles.push({ dest: file, content });
+  }
+
+  if (harnessVersionSpec) {
+    const rendered = renderTemplate(harnessVersionSpec.src, vars);
+    let parsed;
+    try {
+      parsed = JSON.parse(rendered);
+    } catch {
+      parsed = {};
+    }
+    parsed.generator = vars.generatorVersion;
+    parsed.generated = vars.generatedTimestamp;
+    parsed.options = optional.selectedSkills.map(s => s.id);
+    parsed.externalRecommendations = optional.selectedRecommendations.map(item => item.id);
+    parsed.autoCheck = true;
+    Object.assign(parsed, metadata);
+    parsed.checksums = computeChecksums(generatedFiles);
+    const allWritableSpecs = writableFiles
+      .map(f => specsByDest.get(f))
+      .filter(Boolean);
+    parsed.sources = computeSources(allWritableSpecs);
+    const hvContent = JSON.stringify(parsed, null, 2) + '\n';
+    const hvDestPath = path.join(resolvedDir, ...HARNESS_VERSION_DEST.split('/'));
+    fs.mkdirSync(path.dirname(hvDestPath), { recursive: true });
+    fs.writeFileSync(hvDestPath, hvContent, 'utf-8');
+    created.push(`${createdPrefix}${HARNESS_VERSION_DEST}`);
+  }
+
+  return { created, generatedFiles };
+}
+
 export function generate({
   projectName,
   targetDir,
@@ -581,6 +986,9 @@ export function generate({
   withoutOptions = [],
   preset = undefined,
   externalOptions = [],
+  installScope = 'project',
+  globalDir = undefined,
+  hostGlobalDir = undefined,
 }) {
   const created = [];
   const errors = [];
@@ -588,6 +996,10 @@ export function generate({
 
   // Resolve targetDir relative to cwd
   const resolvedDir = path.resolve(process.cwd(), targetDir);
+  const normalizedInstallScope = String(installScope || 'project').trim().toLowerCase();
+  const resolvedGlobalDir = normalizedInstallScope === 'global'
+    ? path.resolve(process.cwd(), globalDir || defaultGlobalDir())
+    : undefined;
   const vars = {
     projectName,
     generatorVersion: pkg.version,
@@ -595,19 +1007,97 @@ export function generate({
   };
 
   const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset, externalOptions });
-  const fileSpecs = [
+  warnings.push(...optional.warnings);
+  const allFileSpecs = [
     ...createCoreFileSpecs(),
     ...createOptionalFileSpecs(optional.selectedSkills),
   ];
+  const fileSpecs = normalizedInstallScope === 'global'
+    ? [
+      ...createGlobalProjectBridgeSpecs({ globalDir: resolvedGlobalDir }),
+      ...allFileSpecs.filter(spec => isGlobalProjectStateDest(spec.dest)),
+    ]
+    : allFileSpecs;
   const specsByDest = new Map(fileSpecs.map(spec => [spec.dest, spec]));
-  const plan = createPlan(resolvedDir, fileSpecs);
+  const plan = createPlan(resolvedDir, fileSpecs, { includeEmptyDirs: normalizedInstallScope !== 'global' });
+  const globalFileSpecs = normalizedInstallScope === 'global'
+    ? allFileSpecs.filter(spec => isGlobalRuntimeDest(spec.dest))
+    : [];
+  const globalSpecsByDest = new Map(globalFileSpecs.map(spec => [spec.dest, spec]));
+  const globalPlan = normalizedInstallScope === 'global'
+    ? createPlan(resolvedGlobalDir, globalFileSpecs)
+    : undefined;
+  const hostPlans = normalizedInstallScope === 'global'
+    ? createHostGlobalPlans(allFileSpecs, hostGlobalDir)
+    : [];
   const duplicateDestinations = duplicateDests(fileSpecs);
+  const duplicateHostDestinations = hostPlans
+    .flatMap(hostPlan => duplicateDests(hostPlan.fileSpecs).map(dest => `${hostPlan.host}:${dest}`));
   const candidateSet = buildHarnessInterestCandidateSet(
     readOwnershipManifest(),
-    fileSpecs,
+    allFileSpecs,
     optional.selectedSkills,
   );
 
+  if (!VALID_INSTALL_SCOPES.has(normalizedInstallScope)) {
+    errors.push(`Unknown install scope "${installScope}". Use project or global.`);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
+      summary: createSummary(plan, { noWrites: true }),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan, { noWrites: true }) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans, { noWrites: true }) } : {}),
+      warnings,
+      installScope: normalizedInstallScope,
+      ...(resolvedGlobalDir ? { globalDir: normalizePath(resolvedGlobalDir) } : {}),
+    };
+  }
+
+  if (resolvedGlobalDir && pathsOverlap(resolvedDir, resolvedGlobalDir)) {
+    errors.push('Global install directory must be outside the target project and must not contain the target project.');
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
+      summary: createSummary(plan, { noWrites: true }),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan, { noWrites: true }), globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans, { noWrites: true }) } : {}),
+      warnings,
+      installScope: normalizedInstallScope,
+    };
+  }
+
+  for (const hostPlan of hostPlans) {
+    if (pathsOverlap(resolvedDir, hostPlan.root)) {
+      errors.push(`Host-global ${hostPlan.host} directory must be outside the target project.`);
+    }
+    if (resolvedGlobalDir && pathsOverlap(resolvedGlobalDir, hostPlan.root)) {
+      errors.push(`Host-global ${hostPlan.host} directory must be outside the global runtime directory.`);
+    }
+  }
+  if (errors.length > 0) {
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
+      summary: createSummary(plan, { noWrites: true }),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan, { noWrites: true }), globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans, { noWrites: true }) } : {}),
+      warnings,
+      installScope: normalizedInstallScope,
+    };
+  }
+
   if (!VALID_CONFLICT_POLICIES.has(onConflict)) {
     errors.push(`Unknown conflict policy "${onConflict}". Use fail, skip, backup, or overwrite.`);
     return {
@@ -643,9 +1133,34 @@ export function generate({
       warnings,
     };
   }
+  if (duplicateHostDestinations.length > 0) {
+    errors.push(`Generation stopped because duplicate host-global destination(s) were found: ${duplicateHostDestinations.join(', ')}`);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
+      summary: createSummary(plan, { noWrites: true }),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan, { noWrites: true }) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans, { noWrites: true }) } : {}),
+      warnings,
+      installScope: normalizedInstallScope,
+    };
+  }
 
-  addFileActions(plan, fileSpecs, resolvedDir, onConflict, candidateSet);
+  addFileActions(plan, fileSpecs, resolvedDir, onConflict, candidateSet, specsByDest);
+  if (globalPlan) {
+    addFileActions(globalPlan, globalFileSpecs, resolvedGlobalDir, onConflict, candidateSet, globalSpecsByDest);
+  }
+  for (const hostPlan of hostPlans) {
+    addFileActions(hostPlan.plan, hostPlan.fileSpecs, hostPlan.root, onConflict, hostPlan.candidateSet, hostPlan.specsByDest);
+  }
   warnings.push(...registrationWarnings(plan, optional.selectedSkills));
+  if (globalPlan) {
+    warnings.push('Global install scope selected: shared runtime assets are written to the global directory and copied into Claude Code, Codex, and OpenCode host-global surfaces; Harness/tasks and Harness/PROGRESS.md remain project-local.');
+  }
 
   if (dryRun) {
     return {
@@ -653,14 +1168,30 @@ export function generate({
       created,
       errors,
       plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
       summary: createSummary(plan),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan), globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans) } : {}),
+      ...(globalPlan ? { ownershipClasses: createOwnershipClasses({ resolvedGlobalDir, hostPlans }) } : {}),
       warnings,
       dryRun: true,
+      installScope: normalizedInstallScope,
     };
   }
 
-  if (plan.conflict.length > 0) {
-    errors.push(`Generation stopped because ${plan.conflict.length} file conflict(s) were found: ${plan.conflict.join(', ')}`);
+  const globalConflictCount = globalPlan?.conflict.length || 0;
+  const hostConflicts = hostPlans.flatMap(hostPlan => hostPlan.plan.conflict.map(file => `${hostPlan.host}:${file}`));
+  if (plan.conflict.length > 0 || globalConflictCount > 0 || hostConflicts.length > 0) {
+    if (plan.conflict.length > 0) {
+      errors.push(`Generation stopped because ${plan.conflict.length} file conflict(s) were found: ${plan.conflict.join(', ')}`);
+    }
+    if (globalConflictCount > 0) {
+      errors.push(`Generation stopped because ${globalConflictCount} global file conflict(s) were found: ${globalPlan.conflict.join(', ')}`);
+    }
+    if (hostConflicts.length > 0) {
+      errors.push(`Generation stopped because ${hostConflicts.length} host-global file conflict(s) were found: ${hostConflicts.join(', ')}`);
+    }
     if (plan.conflict.includes('CLAUDE.md')) {
       errors.push('CLAUDE.md already exists. It is the root agent entry contract; ask the user to confirm refactoring or merging it with the Harness entry contract before editing, backing up, or overwriting.');
     }
@@ -669,92 +1200,58 @@ export function generate({
       created,
       errors,
       plan,
+      ...(globalPlan ? { globalPlan } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
       summary: createSummary(plan, { noWrites: true }),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan, { noWrites: true }), globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans, { noWrites: true }) } : {}),
       warnings,
+      installScope: normalizedInstallScope,
     };
   }
 
   try {
-    for (const dir of plan.mkdir) {
-      const dirPath = dir === './'
-        ? resolvedDir
-        : path.join(resolvedDir, ...dir.slice(0, -1).split('/'));
-      const __slMkdir = symlinkInChain(resolvedDir, dirPath);
-      if (__slMkdir) throw new Error(`Cannot create directory ${dir}: symlinked directory in path (${__slMkdir})`);
-      fs.mkdirSync(dirPath, { recursive: true });
-      created.push(dir === './' ? './ (directory)' : `${dir} (directory)`);
-    }
-
-    for (const file of plan.backup) {
-      const destPath = path.join(resolvedDir, ...file.split('/'));
-      const __slBackup = symlinkInChain(resolvedDir, destPath);
-      if (__slBackup) throw new Error(`Cannot backup ${file}: symlinked directory in path (${__slBackup})`);
-      // Symlink safety: never rename or follow symlinks to avoid path traversal
-      if (fs.existsSync(destPath)) {
-        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot backup ${file}: ${e.message}`); }
-      }
-      fs.renameSync(destPath, nextBackupPath(destPath));
+    const metadata = installMetadata({ installScope: normalizedInstallScope, resolvedGlobalDir, hostPlans });
+    const projectWrite = writeGeneratedPlan({
+      plan,
+      fileSpecs,
+      specsByDest,
+      resolvedDir,
+      vars,
+      optional,
+      metadata,
+    });
+    created.push(...projectWrite.created);
+
+    let globalCreated = [];
+    let hostCreated = [];
+    if (globalPlan) {
+      const globalWrite = writeGeneratedPlan({
+        plan: globalPlan,
+        fileSpecs: globalFileSpecs,
+        specsByDest: globalSpecsByDest,
+        resolvedDir: resolvedGlobalDir,
+        vars,
+        optional,
+        metadata,
+        createdPrefix: 'global:',
+      });
+      created.push(...globalWrite.created);
+      globalCreated = globalWrite.created;
     }
-
-    const writableFiles = [
-      ...plan.create,
-      ...plan.overwrite,
-      ...plan.backup,
-    ];
-
-    const generatedFiles = [];
-    const HARNESS_VERSION_DEST = 'Harness/.harness-version';
-    let harnessVersionSpec = null;
-
-    for (const file of writableFiles) {
-      if (file === HARNESS_VERSION_DEST) {
-        harnessVersionSpec = specsByDest.get(file);
-        continue;
-      }
-      const spec = specsByDest.get(file);
-      const destPath = path.join(resolvedDir, ...file.split('/'));
-      const __slWrite = symlinkInChain(resolvedDir, destPath);
-      if (__slWrite) throw new Error(`Cannot create/overwrite ${file}: symlinked directory in path (${__slWrite})`);
-      // Symlink safety: reject symlinks before writing to prevent path traversal outside workspace
-      if (fs.existsSync(destPath)) {
-        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot create/overwrite ${file}: ${e.message}`); }
-      }
-      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');
-      created.push(file);
-      generatedFiles.push({ dest: file, content });
-    }
-
-    if (harnessVersionSpec) {
-      const rendered = renderTemplate(harnessVersionSpec.src, vars);
-      let parsed;
-      try {
-        parsed = JSON.parse(rendered);
-      } catch {
-        parsed = {};
-      }
-      parsed.generator = vars.generatorVersion;
-      parsed.generated = vars.generatedTimestamp;
-      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)
-      const allWritableSpecs = writableFiles
-        .map(f => specsByDest.get(f))
-        .filter(Boolean);
-      parsed.sources = computeSources(allWritableSpecs);
-      const hvContent = JSON.stringify(parsed, null, 2) + '\n';
-      const hvDestPath = path.join(resolvedDir, ...HARNESS_VERSION_DEST.split('/'));
-      fs.mkdirSync(path.dirname(hvDestPath), { recursive: true });
-      fs.writeFileSync(hvDestPath, hvContent, 'utf-8');
-      created.push(HARNESS_VERSION_DEST);
+    for (const hostPlan of hostPlans) {
+      const hostWrite = writeGeneratedPlan({
+        plan: hostPlan.plan,
+        fileSpecs: hostPlan.fileSpecs,
+        specsByDest: hostPlan.specsByDest,
+        resolvedDir: hostPlan.root,
+        vars,
+        optional,
+        metadata,
+        createdPrefix: `host:${hostPlan.host}:`,
+      });
+      created.push(...hostWrite.created);
+      hostCreated.push(...hostWrite.created);
     }
 
     return {
@@ -762,8 +1259,13 @@ export function generate({
       created,
       errors,
       plan,
+      ...(globalPlan ? { globalPlan, globalCreated, globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })), hostCreated } : {}),
       summary: createSummary(plan),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans), ownershipClasses: createOwnershipClasses({ resolvedGlobalDir, hostPlans }) } : {}),
       warnings,
+      installScope: normalizedInstallScope,
     };
 
   } catch (err) {
@@ -773,8 +1275,13 @@ export function generate({
       created,
       errors,
       plan,
+      ...(globalPlan ? { globalPlan, globalDir: normalizePath(resolvedGlobalDir) } : {}),
+      ...(hostPlans.length ? { hostPlans: hostPlans.map(hostPlan => ({ host: hostPlan.host, root: normalizePath(hostPlan.root), plan: hostPlan.plan })) } : {}),
       summary: createSummary(plan),
+      ...(globalPlan ? { globalSummary: createSummary(globalPlan) } : {}),
+      ...(hostPlans.length ? { hostSummary: createHostSummary(hostPlans) } : {}),
       warnings,
+      installScope: normalizedInstallScope,
     };
   }
 }