@givolt/i3-composer-agent 1.0.0 → 1.0.1

package/rebrand/overlay/bin/i3-composer-agent.cjs

@@ -12,23 +12,35 @@ const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pk
 const help = `${identity}
 ${pkg.name}
 
-Prepare the complete i3 Composer Agent plugin, including shared references.
+Install engineering skills with a multi-tool installation wizard.
 
 Usage:
-  npx ${pkg.name} --codebuddy [--dir <directory>]
-  npx ${pkg.name} --codex [--dir <directory>]
-  npx ${pkg.name} --claude [--dir <directory>]
+  npx ${pkg.name}
+  npx ${pkg.name} --codebuddy
+  npx ${pkg.name} --agents codebuddy,codex --scope project --yes
+  npx ${pkg.name} --prepare --claude --dir <directory>
   npx ${pkg.name} --extract --dir <directory>
 
 Options:
-  --dir <directory>  Output directory (default: ./i3-composer-agent)
-  --dry-run         Show the planned bundle without writing files
-  --force           Replace an existing i3 bundle, preserving a backup
-  --version         Print the package version
-  --help            Show this help
+  --agents <ids>      Comma-separated tool IDs; multiple tools are supported
+  --codebuddy        Preselect CodeBuddy desktop IDE / CodeBuddy Code
+  --codex            Preselect Codex
+  --claude           Preselect Claude Code
+  --scope <scope>    project or global (or use --global / --local)
+  --project-dir <dir> Project installation root (default: current directory)
+  --yes              Confirm explicit noninteractive installation
+  --list-agents      List all supported tool directories
+  --prepare          Prepare a complete plugin for native plugin registration
+  --dir <directory>  Plugin output directory; implies --prepare
+  --dry-run          Show the installation or bundle plan without writing files
+  --force            Replace existing assets, preserving backups
+  --version          Print the package version
+  --help             Show this help
 
-Host flags prepare the bundle and print native registration commands.
-Execute those commands in the intended host to enable the plugin.
+The terminal wizard selects tools and scope, then installs native skill files.
+CodeBuddy and Claude Code also receive short lifecycle commands and personas.
+Other tools receive skills and references; command availability is host-specific.
+Use --prepare for complete plugins, including hooks and host registration.
 `;
 
 function quote(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
@@ -43,15 +55,14 @@ function realDestination(target) {
   }
   return path.join(fs.realpathSync(existing), ...suffix);
 }
-function main() {
-  if (!args.length || args.includes('--help')) { console.log(help); return; }
-  if (args.length === 1 && args[0] === '--version') { console.log(pkg.version); return; }
+function prepare() {
   let host;
   let directory = path.join(process.cwd(), name);
   let dryRun = false;
   let force = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+    if (arg === '--prepare') continue;
     if (['--codebuddy', '--codex', '--claude', '--extract'].includes(arg)) {
       if (host) throw new Error('Choose exactly one host flag or --extract.');
       host = arg.slice(2);
@@ -119,4 +130,61 @@ function main() {
     console.log(`Use /${name}:spec, /${name}:plan, /${name}:build, and /${name}:ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
   }
 }
-try { main(); } catch (error) { console.error(`${name}: ${error.message}`); process.exitCode = 1; }
+async function main() {
+  if (args.includes('--help') || (!args.length && !process.stdin.isTTY)) { console.log(help); return; }
+  if (args.length === 1 && args[0] === '--version') { console.log(pkg.version); return; }
+  if (args.some(arg => ['--extract', '--prepare', '--dir'].includes(arg))) { prepare(); return; }
+  const installer = require('./install.cjs');
+  if (args.length === 1 && args[0] === '--list-agents') {
+    for (const agent of installer.registry.agents) console.log(`${agent.id.padEnd(20)} ${agent.label}${agent.globalSkillsDir ? '' : ' (project only)'}`);
+    return;
+  }
+  const options = { agents: [], projectDir: process.cwd() };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (['--codebuddy', '--codex', '--claude'].includes(arg)) options.agents.push(arg.slice(2));
+    else if (['--agents', '--scope', '--project-dir'].includes(arg)) {
+      if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} requires a value.`);
+      const value = args[++i];
+      if (arg === '--agents') options.agents.push(value);
+      else if (arg === '--scope') { if (options.scope && options.scope !== value) throw new Error('Choose one installation scope.'); options.scope = value; }
+      else options.projectDir = path.resolve(value);
+    } else if (arg === '--global' || arg === '--local') {
+      const scope = arg === '--global' ? 'global' : 'project';
+      if (options.scope && options.scope !== scope) throw new Error('Choose one installation scope.');
+      options.scope = scope;
+    } else if (arg === '--yes') options.yes = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  options.agents = installer.selectAgents(options.agents);
+  if (process.stdin.isTTY && process.stdout.isTTY && !options.yes && !options.dryRun) {
+    const selection = await require('./wizard.cjs').choose(options, identity);
+    if (!selection) { console.log('Installation cancelled. No files changed.'); return; }
+    Object.assign(options, selection);
+  } else if (!options.agents.length || !options.scope || (!options.yes && !options.dryRun)) {
+    throw new Error('Use an interactive terminal, or specify --agents <ids> --scope project|global --yes.');
+  }
+  const plan = installer.planInstallation(options);
+  if (options.dryRun) {
+    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, mode: plan.mode, scope: plan.scope, agents: plan.agents, targets: plan.targets, conflicts: plan.conflicts }, null, 2));
+    return;
+  }
+  if (!options.yes) {
+    const confirmed = await require('./wizard.cjs').confirm(plan);
+    if (!confirmed) { console.log('Installation cancelled. No files changed.'); return; }
+    options.force = plan.conflicts.length > 0;
+  }
+  const backups = installer.executeInstallation(plan, { force: options.force });
+  console.log(identity);
+  for (const target of plan.targets) {
+    console.log(`Installed ${target.agents.join(', ')} skills at ${target.skillsDirectory}`);
+    if (target.commandsDirectory) console.log(`Commands: /spec, /plan, /build, /ship (all ${fs.readdirSync(target.commandsDirectory).filter(file => file.endsWith('.md')).length} workflows) at ${target.commandsDirectory}`);
+  }
+  for (const backup of backups) console.log(`Previous assets preserved at ${backup}`);
+  console.log('Reload the IDE window or start a new host session to discover installed files.');
+  if (plan.agents.some(id => !['codebuddy', 'claude-code'].includes(id))) console.log('These tools use the existing skill IDs; lifecycle slash-command support depends on the host.');
+  console.log('Native skill installation does not enable plugin hooks. Use --prepare for complete plugin registration.');
+}
+main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/rebrand/overlay/bin/install.cjs

@@ -0,0 +1,164 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const registry = require('./agent-targets.json');
+const root = path.resolve(__dirname, '..');
+const name = 'i3-composer-agent';
+const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
+function exists(file) {
+  try { fs.lstatSync(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+function selectAgents(values) {
+  const ids = [...new Set(values.flatMap(value => value.split(',')).map(id => aliases[id.trim()] || id.trim()).filter(Boolean))];
+  for (const id of ids) if (!registry.agents.some(agent => agent.id === id)) throw new Error(`Unknown tool: ${id}. Use --list-agents.`);
+  return ids;
+}
+function globalSkillsDir(agent, home, env) {
+  const config = agent.globalSkillsDir;
+  if (!config) throw new Error(`${agent.label} supports project installation only. Choose project scope or remove this tool.`);
+  let base = home;
+  if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
+    const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
+    if (alternative) return path.join(home, alternative);
+  }
+  return path.resolve(base, config.path);
+}
+// Resolve parent aliases while keeping a leaf symlink replaceable as a link.
+function destination(file) {
+  let parent = path.dirname(file);
+  const suffix = [path.basename(file)];
+  while (!exists(parent)) { suffix.unshift(path.basename(parent)); parent = path.dirname(parent); }
+  return path.join(fs.realpathSync(parent), ...suffix);
+}
+function checkDestination(file) {
+  const source = fs.realpathSync(root);
+  if (file === source || file.startsWith(source + path.sep) || source.startsWith(file + path.sep)) {
+    throw new Error('Installation destinations must be outside this package directory.');
+  }
+}
+function planInstallation({ agents, scope, projectDir = process.cwd(), home = os.homedir(), env = process.env }) {
+  agents = selectAgents(agents);
+  if (!agents.length) throw new Error('Choose at least one tool.');
+  if (!['project', 'global'].includes(scope)) throw new Error('Choose --scope project or --scope global.');
+  const targets = new Map();
+  for (const id of agents) {
+    const agent = registry.agents.find(item => item.id === id);
+    const skillsDirectory = destination(scope === 'project' ? path.resolve(projectDir, agent.projectSkillsDir) : globalSkillsDir(agent, home, env));
+    const base = path.dirname(skillsDirectory);
+    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, referencesDirectory: path.join(base, 'references'), base });
+    const target = targets.get(skillsDirectory);
+    target.agents.push(id);
+    if (['codebuddy', 'claude-code'].includes(id)) {
+      target.commandsDirectory = path.join(base, 'commands');
+      target.personasDirectory = path.join(base, 'agents');
+    }
+  }
+  const assets = [];
+  function addDirectory(sourceDirectory, destinationDirectory, kind) {
+    if (exists(destinationDirectory) && fs.lstatSync(destinationDirectory).isSymbolicLink()) {
+      throw new Error(`Installation directory is a symlink: ${destinationDirectory}. Choose its canonical location instead.`);
+    }
+    for (const entry of fs.readdirSync(path.join(root, sourceDirectory)).sort()) {
+      if (entry === '.DS_Store') continue;
+      assets.push({ source: path.join(root, sourceDirectory, entry), destination: destination(path.join(destinationDirectory, entry)), kind });
+    }
+  }
+  for (const target of targets.values()) {
+    const start = assets.length;
+    addDirectory('skills', target.skillsDirectory, 'skill');
+    addDirectory('references', target.referencesDirectory, 'reference');
+    if (target.commandsDirectory) {
+      addDirectory('.claude/commands', target.commandsDirectory, 'command');
+      addDirectory('agents', target.personasDirectory, 'persona');
+      const docs = path.join(target.base, 'docs');
+      if (exists(docs) && fs.lstatSync(docs).isSymbolicLink()) throw new Error(`Installation directory is a symlink: ${docs}.`);
+      assets.push({ source: path.join(root, 'docs/agents.md'), destination: destination(path.join(target.base, 'docs/agents.md')), kind: 'documentation' });
+    }
+    assets.push({ source: path.join(root, 'LICENSE'), destination: destination(path.join(target.base, `${name}-LICENSE`)), kind: 'attribution' });
+    assets.push({ source: path.join(root, 'NOTICE.md'), destination: destination(path.join(target.base, `${name}-NOTICE.md`)), kind: 'attribution' });
+    assets.push({ target, destination: destination(path.join(target.base, `.${name}.json`)), kind: 'manifest' });
+    for (const asset of assets.slice(start)) {
+      asset.base = target.base;
+      asset.codebuddyCommand = asset.kind === 'command' && target.agents.includes('codebuddy');
+    }
+  }
+  for (const asset of assets) { checkDestination(asset.destination); asset.existing = exists(asset.destination); }
+  return { mode: 'install', scope, agents, targets: [...targets.values()], assets, conflicts: assets.filter(asset => asset.existing).map(asset => asset.destination) };
+}
+function executeInstallation(plan, { force = false } = {}) {
+  if (plan.conflicts.length && !force) throw new Error('Existing installation assets require confirmation or --force; previous files will be backed up.');
+  const pkg = require('../package.json');
+  const contexts = new Map();
+  const createdDirectories = [];
+  const committed = [];
+  function mkdir(directory) {
+    if (exists(directory)) return;
+    mkdir(path.dirname(directory));
+    fs.mkdirSync(directory);
+    createdDirectories.push(directory);
+  }
+  function portable(file, markdown = false, codebuddyCommand = false) {
+    if (fs.statSync(file).isDirectory()) {
+      for (const entry of fs.readdirSync(file)) portable(path.join(file, entry), false, codebuddyCommand);
+    } else if (markdown || file.endsWith('.md')) {
+      let content = fs.readFileSync(file, 'utf8').replaceAll('i3-composer-agent:', '').replaceAll('agent-skills:', '');
+      if (codebuddyCommand) content = content.replaceAll('.claude/agents/', '.codebuddy/agents/');
+      fs.writeFileSync(file, content);
+    }
+  }
+  try {
+    // Stage every target before replacing the first installed asset.
+    for (const [index, asset] of plan.assets.entries()) {
+      if (!contexts.has(asset.base)) {
+        mkdir(asset.base);
+        contexts.set(asset.base, { staging: fs.mkdtempSync(path.join(asset.base, `.${name}-stage-`)), backup: path.join(asset.base, `.${name}-backup-${crypto.randomUUID()}`) });
+      }
+      const context = contexts.get(asset.base);
+      asset.staged = path.join(context.staging, String(index));
+      if (asset.kind === 'manifest') {
+        fs.writeFileSync(asset.staged, JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, scope: plan.scope, agents: asset.target.agents, assets: plan.assets.filter(item => item.base === asset.base).map(item => path.relative(asset.base, item.destination)) }, null, 2) + '\n');
+      } else {
+        fs.cpSync(asset.source, asset.staged, { recursive: true, filter: file => {
+          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Package contains a symlink: ${file}`);
+          return path.basename(file) !== '.DS_Store';
+        } });
+        portable(asset.staged, asset.source.endsWith('.md'), asset.codebuddyCommand);
+      }
+    }
+    for (const asset of plan.assets) {
+      const context = contexts.get(asset.base);
+      mkdir(path.dirname(asset.destination));
+      // A destination may have appeared since planning; never replace it implicitly.
+      if (exists(asset.destination) && !force) throw new Error(`Destination appeared during installation: ${asset.destination}. Retry with confirmed replacement.`);
+      const change = { destination: asset.destination, written: false };
+      if (exists(asset.destination)) {
+        change.backup = path.join(context.backup, path.relative(asset.base, asset.destination));
+        mkdir(path.dirname(change.backup));
+        fs.renameSync(asset.destination, change.backup);
+      }
+      committed.push(change);
+      fs.renameSync(asset.staged, asset.destination);
+      change.written = true;
+    }
+    return [...contexts.values()].map(context => context.backup).filter(exists);
+  } catch (error) {
+    for (const change of committed.reverse()) {
+      if (change.written) fs.rmSync(change.destination, { recursive: true, force: true });
+      if (change.backup) fs.renameSync(change.backup, change.destination);
+    }
+    throw error;
+  } finally {
+    for (const context of contexts.values()) fs.rmSync(context.staging, { recursive: true, force: true });
+    for (const directory of createdDirectories.reverse()) {
+      try { fs.rmdirSync(directory); }
+      catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+    }
+  }
+}
+module.exports = { registry, selectAgents, planInstallation, executeInstallation, exists };

package/rebrand/overlay/bin/skills-registry.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/rebrand/overlay/bin/wizard.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+const readline = require('node:readline');
+const { registry, selectAgents } = require('./install.cjs');
+
+async function session(action) {
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  terminal.on('close', () => { closed = true; });
+  terminal.on('SIGINT', () => terminal.close());
+  const ask = prompt => new Promise(resolve => {
+    if (closed) { resolve(null); return; }
+    const cancelled = () => resolve(null);
+    terminal.once('close', cancelled);
+    terminal.question(prompt, answer => {
+      terminal.off('close', cancelled);
+      resolve(answer.trim());
+    });
+  });
+  try { return await action(ask); }
+  finally { terminal.close(); }
+}
+async function choose(options, identity) {
+  console.log(identity);
+  console.log('\nChoose tools (multiple selections are supported):');
+  const entries = registry.agents.map((agent, index) => `${index + 1}. ${agent.label} [${agent.id}]${agent.globalSkillsDir ? '' : ' (project only)'}`);
+  for (let index = 0; index < entries.length; index += 2) console.log(entries[index].padEnd(49) + (entries[index + 1] || ''));
+  return session(async ask => {
+    let agents;
+    while (!agents) {
+      const input = await ask(`Select tools by number or ID, comma-separated${options.agents.length ? ` [${options.agents.join(',')}]` : ''} (q cancels): `);
+      if (input === null || ['q', 'cancel'].includes(input.toLowerCase())) return null;
+      try {
+        const values = input === 'all' ? registry.agents.map(agent => agent.id) : input ? input.split(',').map(value => {
+          const trimmed = value.trim();
+          return /^\d+$/.test(trimmed) ? registry.agents[Number(trimmed) - 1]?.id || trimmed : trimmed;
+        }) : options.agents;
+        agents = selectAgents(values);
+        if (!agents.length) { agents = undefined; console.log('Choose at least one tool.'); }
+      } catch (error) { console.log(error.message); }
+    }
+    let scope = options.scope;
+    while (!scope) {
+      const input = await ask('Installation scope: 1. Project (current project), 2. Global (all projects) [1] (q cancels): ');
+      if (input === null || ['q', 'cancel'].includes(input.toLowerCase())) return null;
+      if (['', '1', 'project'].includes(input)) scope = 'project';
+      else if (['2', 'global'].includes(input)) scope = 'global';
+      else console.log('Choose 1 (project) or 2 (global).');
+    }
+    return { agents, scope };
+  });
+}
+async function confirm(plan) {
+  console.log(`\nInstallation scope: ${plan.scope}`);
+  for (const target of plan.targets) {
+    console.log(`  ${target.agents.join(', ')}: ${target.skillsDirectory}`);
+    if (target.commandsDirectory) console.log(`  Commands: ${target.commandsDirectory}`);
+  }
+  if (plan.conflicts.length) console.log(`${plan.conflicts.length} existing assets will be preserved in backups before replacement.`);
+  console.log('Includes all skills and shared references. Plugin hooks require native plugin registration.');
+  return session(async ask => {
+    const answer = await ask('Install these files? [y/N]: ');
+    return answer !== null && ['y', 'yes'].includes(answer.toLowerCase());
+  });
+}
+module.exports = { choose, confirm };

package/rebrand/overlay/tests/installer.test.cjs

@@ -0,0 +1,193 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const root = path.resolve(__dirname, '..');
+const cli = path.join(root, 'bin/i3-composer-agent.cjs');
+const upstream = require('../rebrand/upstream.json');
+function workspace(t) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-agent-install-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  return fs.realpathSync(directory);
+}
+function run(directory, args) {
+  return spawnSync(process.execPath, [cli, ...args], { cwd: directory, encoding: 'utf8' });
+}
+test('native CodeBuddy installation includes short commands, personas and usable references', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--codebuddy', '--scope', 'project', '--yes']);
+  assert.equal(result.status, 0, result.stderr);
+  const base = path.join(directory, '.codebuddy');
+  assert.equal(fs.readdirSync(path.join(base, 'skills')).length, upstream.skills.length);
+  assert.equal(fs.readdirSync(path.join(base, 'commands')).length, upstream.commands.length);
+  assert.equal(fs.readdirSync(path.join(base, 'agents')).length, upstream.personas.length);
+  const command = fs.readFileSync(path.join(base, 'commands/spec.md'), 'utf8');
+  assert.match(command, /Invoke the spec-driven-development skill/);
+  assert.doesNotMatch(command, /i3-composer-agent:/);
+  const ship = fs.readFileSync(path.join(base, 'commands/ship.md'), 'utf8');
+  assert.match(ship, /\.codebuddy\/agents\//);
+  assert.doesNotMatch(ship, /\.claude\/agents\//);
+  assert.ok(fs.existsSync(path.join(base, 'references/definition-of-done.md')));
+  assert.equal(fs.readFileSync(path.join(base, 'i3-composer-agent-LICENSE'), 'utf8'), fs.readFileSync(path.join(root, 'LICENSE'), 'utf8'));
+  assert.match(fs.readFileSync(path.join(base, 'i3-composer-agent-NOTICE.md'), 'utf8'), /Addy Osmani/);
+  assert.equal(fs.existsSync(path.join(directory, 'AGENTS.md')), false);
+  assert.equal(fs.existsSync(path.join(directory, 'i3-composer-agent')), false);
+  assert.match(result.stdout, /\/spec/);
+});
+test('multiple tools retain their own destinations and share universal skills without duplicate work', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--agents', 'codebuddy,codex,cursor,claude-code', '--scope', 'project', '--yes']);
+  assert.equal(result.status, 0, result.stderr);
+  for (const base of ['.codebuddy', '.agents', '.claude']) {
+    assert.equal(fs.readdirSync(path.join(directory, base, 'skills')).length, upstream.skills.length);
+    assert.ok(fs.existsSync(path.join(directory, base, 'references/testing-patterns.md')));
+  }
+  const manifest = JSON.parse(fs.readFileSync(path.join(directory, '.agents/.i3-composer-agent.json')));
+  assert.deepEqual(manifest.agents.sort(), ['codex', 'cursor']);
+  assert.equal(fs.existsSync(path.join(directory, '.agents/commands')), false);
+});
+test('installation dry run describes scope and destinations without changing project files', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--agents', 'codebuddy,codex', '--scope', 'project', '--dry-run']);
+  assert.equal(result.status, 0, result.stderr);
+  const plan = JSON.parse(result.stdout);
+  assert.equal(plan.mode, 'install');
+  assert.equal(plan.scope, 'project');
+  assert.equal(plan.targets.length, 2);
+  assert.deepEqual(fs.readdirSync(directory), []);
+});
+test('all copied Markdown reference links and stable skill frontmatter remain valid', t => {
+  const directory = workspace(t);
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes']).status, 0);
+  const base = path.join(directory, '.codebuddy');
+  function visit(folder) {
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+      const file = path.join(folder, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name.endsWith('.md')) {
+        const content = fs.readFileSync(file, 'utf8');
+        for (const match of content.matchAll(/\]\(([^)]+)\)/g)) {
+          const relative = match[1].split('#')[0];
+          if (relative.includes('references/') && !/^[a-z]+:/i.test(relative)) {
+            assert.ok(fs.existsSync(path.resolve(path.dirname(file), relative)), `${file}: ${relative}`);
+          }
+        }
+      }
+    }
+  }
+  visit(path.join(base, 'skills'));
+  for (const id of upstream.skills) {
+    const head = content => content.match(/^---\r?\n[\s\S]*?\r?\n---/)[0];
+    assert.equal(head(fs.readFileSync(path.join(base, 'skills', id, 'SKILL.md'), 'utf8')), head(fs.readFileSync(path.join(root, 'skills', id, 'SKILL.md'), 'utf8')));
+  }
+});
+test('existing assets are protected; confirmed replacement backs them up and preserves unrelated settings', t => {
+  const directory = workspace(t);
+  const base = path.join(directory, '.codebuddy');
+  fs.mkdirSync(path.join(base, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(base, 'commands/spec.md'), 'my custom command');
+  fs.writeFileSync(path.join(base, 'settings.json'), '{"keep":"my settings"}\n');
+  const args = ['--codebuddy', '--scope', 'project', '--yes'];
+  assert.equal(run(directory, args).status, 1);
+  assert.equal(fs.existsSync(path.join(base, 'skills')), false);
+  const result = run(directory, [...args, '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  const backups = fs.readdirSync(base).filter(file => file.startsWith('.i3-composer-agent-backup-'));
+  assert.equal(backups.length, 1);
+  assert.equal(fs.readFileSync(path.join(base, backups[0], 'commands/spec.md'), 'utf8'), 'my custom command');
+  assert.equal(fs.readFileSync(path.join(base, 'settings.json'), 'utf8'), '{"keep":"my settings"}\n');
+  assert.equal(fs.existsSync(path.join(base, backups[0], 'settings.json')), false);
+});
+test('global installation uses injected home and config roots without touching the real user configuration', t => {
+  const directory = workspace(t);
+  const { planInstallation, executeInstallation } = require('../bin/install.cjs');
+  const plan = planInstallation({ agents: ['codebuddy', 'codex', 'claude-code', 'opencode'], scope: 'global', home: directory, env: { XDG_CONFIG_HOME: path.join(directory, 'config'), CLAUDE_CONFIG_DIR: path.join(directory, 'custom-claude') } });
+  assert.ok(plan.targets.every(target => target.skillsDirectory.startsWith(directory + path.sep)));
+  assert.ok(plan.targets.some(target => target.skillsDirectory === path.join(directory, 'custom-claude/skills')));
+  assert.ok(plan.targets.some(target => target.skillsDirectory === path.join(directory, 'config/opencode/skills')));
+  executeInstallation(plan);
+  for (const target of plan.targets) {
+    assert.equal(fs.readdirSync(target.skillsDirectory).length, upstream.skills.length);
+    assert.ok(fs.existsSync(path.join(target.referencesDirectory, 'definition-of-done.md')));
+  }
+});
+test('the pinned tool catalog plans all project choices and rejects unsupported global choices before writing', t => {
+  const directory = workspace(t);
+  const { registry, planInstallation } = require('../bin/install.cjs');
+  assert.equal(registry.agents.length, 79);
+  assert.equal(registry.commit, '48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e');
+  const plan = planInstallation({ agents: registry.agents.map(agent => agent.id), scope: 'project', projectDir: directory });
+  assert.equal(plan.agents.length, registry.agents.length);
+  assert.ok(plan.targets.length < plan.agents.length);
+  assert.equal(new Set(plan.assets.map(asset => asset.destination)).size, plan.assets.length);
+  for (const agent of registry.agents) {
+    if (agent.globalSkillsDir) assert.ok(planInstallation({ agents: [agent.id], scope: 'global', home: directory, env: {} }).targets[0].skillsDirectory.startsWith(directory + path.sep));
+    else assert.throws(() => planInstallation({ agents: [agent.id], scope: 'global', home: directory, env: {} }), /project installation only/);
+  }
+  assert.deepEqual(fs.readdirSync(directory), []);
+});
+test('failed installation restores prior assets and removes all newly written files', t => {
+  const directory = workspace(t);
+  const { planInstallation, executeInstallation } = require('../bin/install.cjs');
+  const prior = path.join(directory, '.codebuddy/skills/api-and-interface-design');
+  fs.mkdirSync(prior, { recursive: true });
+  fs.writeFileSync(path.join(prior, 'custom.md'), 'prior skill content');
+  const plan = planInstallation({ agents: ['codebuddy', 'codex'], scope: 'project', projectDir: directory });
+  const realRename = fs.renameSync;
+  let failed = false;
+  fs.renameSync = (source, destination) => {
+    if (!failed && destination === plan.assets[1].destination) { failed = true; throw new Error('simulated disk failure'); }
+    return realRename(source, destination);
+  };
+  try { assert.throws(() => executeInstallation(plan, { force: true }), /simulated disk failure/); }
+  finally { fs.renameSync = realRename; }
+  assert.equal(fs.readFileSync(path.join(prior, 'custom.md'), 'utf8'), 'prior skill content');
+  assert.deepEqual(fs.readdirSync(path.dirname(prior)), ['api-and-interface-design']);
+  assert.deepEqual(fs.readdirSync(path.join(directory, '.codebuddy')), ['skills']);
+  assert.equal(fs.existsSync(path.join(directory, '.agents')), false);
+});
+test('replacing a skill symlink backs up the link and leaves its external source untouched', t => {
+  const directory = workspace(t);
+  const external = path.join(directory, 'external-skill');
+  const skills = path.join(directory, '.codebuddy/skills');
+  fs.mkdirSync(external);
+  fs.writeFileSync(path.join(external, 'custom.md'), 'external source');
+  fs.mkdirSync(skills, { recursive: true });
+  fs.symlinkSync(external, path.join(skills, 'spec-driven-development'), 'dir');
+  const result = run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(fs.readdirSync(external), ['custom.md']);
+  assert.equal(fs.lstatSync(path.join(skills, 'spec-driven-development')).isSymbolicLink(), false);
+  const base = path.dirname(skills);
+  const backup = fs.readdirSync(base).find(file => file.startsWith('.i3-composer-agent-backup-'));
+  assert.equal(fs.lstatSync(path.join(base, backup, 'skills/spec-driven-development')).isSymbolicLink(), true);
+});
+test('package destinations, shared directory symlinks and ambiguous noninteractive flags fail without writes', t => {
+  const directory = workspace(t);
+  for (const args of [ ['--codebuddy'], ['--codebuddy', '--yes'], ['--agents', 'unknown', '--scope', 'project', '--yes'], ['--codebuddy', '--scope', 'invalid', '--yes'], ['--codebuddy', '--scope', 'project', '--global', '--yes'] ]) {
+    assert.equal(run(directory, args).status, 1);
+    assert.deepEqual(fs.readdirSync(directory), []);
+  }
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--project-dir', root]).status, 1);
+  fs.mkdirSync(path.join(directory, '.codebuddy'));
+  fs.symlinkSync(path.join(root, 'skills'), path.join(directory, '.codebuddy/skills'), 'dir');
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--force']).status, 1);
+  assert.deepEqual(fs.readdirSync(path.join(directory, '.codebuddy')), ['skills']);
+});
+test('explicit plugin preparation remains available and does not install native host files', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--prepare', '--codebuddy']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /\/plugin install/);
+  assert.equal(fs.existsSync(path.join(directory, 'i3-composer-agent/plugin.json')), true);
+  assert.equal(fs.existsSync(path.join(directory, '.codebuddy')), false);
+  const listing = run(directory, ['--list-agents']);
+  assert.equal(listing.status, 0, listing.stderr);
+  assert.equal(listing.stdout.trim().split('\n').length, 79);
+  assert.match(listing.stdout, /codebuddy/);
+  assert.match(listing.stdout, /windsurf/);
+});