@givolt/i3-composer-agent 1.0.0 → 1.0.1

package/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/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/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/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/docs/codebuddy-setup.md

@@ -1,12 +1,60 @@
 # Using i3 Composer Agent with CodeBuddy
 
-Prepare the complete plugin inside the project where you want to use it:
+## Desktop IDE installation
+
+Run inside your business project:
 
 ```bash
 npx @givolt/i3-composer-agent --codebuddy
 ```
 
-In the CodeBuddy chat, register the prepared directory and install the plugin:
+The terminal wizard preselects CodeBuddy, still allows multiple tools, and asks
+for project or global scope before installing. Project scope writes these paths:
+
+- `.codebuddy/skills/` — all 25 skills with their original IDs.
+- `.codebuddy/references/` — shared checklists used by skill-relative links.
+- `.codebuddy/commands/` — all 9 existing lifecycle workflows.
+- `.codebuddy/agents/` — all 4 persona definitions.
+
+Global scope uses the same layout under `~/.codebuddy/`. Existing assets require
+confirmed replacement and are preserved in backup directories. Settings are
+not replaced. Reload the CodeBuddy window or start a new chat, then inspect
+the Skills list and type `/` to inspect the command menu.
+
+```text
+/spec
+/plan
+/build
+/build auto
+/review
+/ship
+```
+
+The command wrappers reference installed skill IDs without the plugin namespace.
+Their workflow content and approval gates are retained. File installation does
+not itself prove that the IDE has discovered or executed every workflow.
+
+For multiple tools or a noninteractive installation:
+
+```bash
+npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --codebuddy --scope global --yes
+```
+
+CodeBuddy documents [IDE skills](https://www.codebuddy.cn/docs/ide/Features/Skills)
+and [IDE custom commands](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands).
+The directory layout follows its [configuration directory reference](https://www.codebuddy.cn/docs/cli/codebuddy-dir).
+
+## CodeBuddy Code native plugin registration
+
+For the terminal CodeBuddy Code plugin manager, explicitly prepare the full
+plugin instead of native skill installation:
+
+```bash
+npx @givolt/i3-composer-agent --prepare --codebuddy
+```
+
+In CodeBuddy Code, register the prepared directory and install the plugin:
 
 ```text
 /plugin marketplace add ./i3-composer-agent
@@ -14,10 +62,10 @@ In the CodeBuddy chat, register the prepared directory and install the plugin:
 ```
 
 Use the absolute directory printed by the CLI if CodeBuddy has a different
-working directory. Choose the intended installation scope in CodeBuddy's native
+working directory. Choose the intended installation scope in CodeBuddy Code's native
 plugin manager. Reload plugins or start a new session after installation.
 
-CodeBuddy supports the existing `.claude-plugin/plugin.json` compatibility
+CodeBuddy Code supports the existing `.claude-plugin/plugin.json` compatibility
 manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
 original lifecycle commands and their workflow content.
 
@@ -33,9 +81,8 @@ original lifecycle commands and their workflow content.
 Skill IDs, persona names, artifact paths, and workflow gates retain their
 upstream behavior. The plugin namespace changes to `i3-composer-agent`.
 
-The bundle includes all skills and shared `references/`. Installing individual
-skills is a different distribution method and does not install the command
-wrappers or persona definitions.
+The prepared plugin includes all skills, personas, commands, hooks and shared
+`references/`. Native skill installation above does not enable plugin hooks.
 
-The CLI prepares files and prints registration commands. Actual host discovery
+In this explicit mode the CLI prepares files and prints registration commands. Actual host discovery
 and model execution should be verified after registering the plugin.

package/docs/codex-setup.md

@@ -1,12 +1,23 @@
 # Using i3 Composer Agent with Codex
 
-Prepare the complete plugin inside the project where you want to use it:
+For the multi-tool native skill wizard, run in your project:
 
 ```bash
 npx @givolt/i3-composer-agent --codex
 ```
 
-The CLI copies a persistent `./i3-composer-agent/` bundle and prints these
+Choose project or global scope. Native installation uses `.agents/skills/`
+or `~/.agents/skills/`, plus the sibling `references/` directory. It retains
+the 25 original skill IDs. This mode does not add short lifecycle
+slash commands or enable plugin hooks.
+
+For complete plugin registration, prepare a persistent bundle explicitly:
+
+```bash
+npx @givolt/i3-composer-agent --prepare --codex
+```
+
+This mode copies a persistent `./i3-composer-agent/` bundle and prints these
 native registration commands. Run them to enable the plugin:
 
 ```bash

package/package.json

@@ -82,7 +82,7 @@
     "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
     "upstreamRepository": "https://github.com/addyosmani/agent-skills"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/49780522/i3-composer-agent.git"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "homepage": "https://github.com/49780522/i3-composer-agent",
   "repository": "https://github.com/49780522/i3-composer-agent"

package/rebrand/INSTALLATION-SPEC.md

@@ -0,0 +1,46 @@
+# Installation wizard correction
+
+The published 1.0.0 CLI prepares plugin files but does not implement the
+installation wizard previously described to the user. Restore the promised
+installation flow, including the user's confirmed multiple-tool selection and
+CodeBuddy desktop IDE target.
+
+## Acceptance contract
+
+- Running the package in an interactive terminal opens a tool multi-select,
+  project/global scope selection, destination summary, and confirmation.
+- Host flags preselect tools rather than silently preparing a plugin. The tool
+  catalog preserves the installation paths from the pinned Vercel Skills CLI
+  registry; CodeBuddy, Codex, Claude Code, Cursor and other tools remain choices.
+- Native installation copies all skills and their shared references. CodeBuddy
+  and Claude Code also receive the nine existing command workflows and personas.
+  Portable command references use the installed stable skill IDs.
+- Shared destinations are installed once when several tools use the same path.
+- Existing assets require confirmed replacement and are retained in backups.
+  Unrelated settings and project files are untouched. Failed installation rolls
+  back completed writes; cancellation and dry runs write nothing.
+- `--prepare`, `--extract`, and existing explicit `--dir` calls retain complete
+  plugin preparation. Plain `--version` remains machine-readable.
+- Noninteractive installation requires explicit tools, scope and `--yes`;
+  replacement additionally requires `--force`.
+- Packaging tests exercise the shipped CLI; a real terminal session verifies
+  the wizard. File discovery and actual model execution are separate evidence.
+
+## Implementation and verification
+
+Keep upstream content unchanged on `agent/source`; all fork changes live under
+`rebrand/`. Distribution modules and tests are replayed from `rebrand/overlay/`.
+Use Node.js built-ins and the existing `node:test` conventions. No new runtime
+dependency is required. Keep the upstream baseline at 0.6.12 and the release
+version at 1.0.0 during development. Recommend and obtain the user's approval
+for a new release version before changing it or publishing.
+
+On 2026-10-07 the user accepted the recommended 1.0.1 correction release and
+authorized publication. The upstream baseline remains 0.6.12.
+
+Slices: first prove native multi-tool installation fails on the published CLI;
+then implement directory planning and copying; then add the interactive flow;
+finally verify conflicts, rollback, package extraction and terminal execution.
+
+Commands: `node --test tests/installer.test.cjs`, `npm test`, `npm run validate`,
+`npm run rebrand:check`, and `npm pack` in a generated branded candidate.

package/rebrand/MAINTENANCE.md

@@ -97,7 +97,8 @@ npm pack --pack-destination ../releases/next
 
 ## 发布及验收
 
-维护流程与安装能力分开验收。当前 npm CLI 准备文件并打印宿主注册命令；
+维护流程与安装能力分开验收。默认 npm CLI 使用多工具安装向导；`--prepare`
+保留完整插件准备和宿主注册提示。两种模式分别验收，不把准备文件等同于安装。
 实际宿主安装范围、启用、命令执行以及交互向导仍需各自验证。
 Codex 的生命周期斜杠命令适配是独立工作，已有 Skill ID 不因维护流程改名。
 

package/rebrand/NOTICE.md

@@ -5,5 +5,10 @@ i3 Composer Agent is a branded distribution of
 The initial distribution is based on upstream commit `1401c8b` (version 0.6.12).
 
 The original MIT license and copyright notice are preserved in LICENSE.
-Givolt maintains the branding, npm distribution, and bundle preparation CLI.
+Givolt maintains the branding, npm distribution, and installation CLI.
 The original skill IDs, command workflows, and persona definitions are retained.
+
+The tool installation directory presets in `bin/agent-targets.json` are adapted
+from Vercel's [Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
+at commit `48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e`. Copyright (c) 2026
+Vercel, Inc. Its MIT license is retained in `bin/skills-registry.LICENSE`.

package/rebrand/VALIDATION.md

@@ -26,3 +26,7 @@
 源或包校验不等于 registry 发布，也不等于实际宿主启用和模型执行。
 英文确定性 TF-IDF 路由分数不能代替中文或真实模型行为验收。
 安装向导、宿主范围、升级和移除沿用安装遗漏审计的独立验收项。
+
+交互安装修复必须覆盖多工具选择、项目/全局目录、共享 references、命令与
+Persona 文件、冲突保护、备份、失败回滚和取消不写入。对打包后的 CLI 运行
+真实终端向导，不能用 bundle 准备测试代替；安装文件也不等于 IDE 或模型验收。

package/rebrand/VERSIONING.md

@@ -2,9 +2,9 @@
 
 本规则已经用户确认，仅适用于 i3 Composer Agent 仓库。
 
-| 信息 | 权威来源 | 本次确认值 |
+| 信息 | 权威来源 | 当前发行值 |
 | --- | --- | --- |
-| i3 发行版本 | brand.json 的 releaseVersion | 1.0.0 |
+| i3 发行版本 | brand.json 的 releaseVersion | 1.0.1 |
 | 上游版本 | upstream.json 的 upstreamVersion | 0.6.12 |
 | 上游提交 | upstream.json 的 upstreamCommit | 1401c8b8030e023baeebb31781a6653fe8e93026 |
 
@@ -20,13 +20,14 @@ package.json 的 i3ComposerAgent 来源字段。package.template.json 不保存
 README、CLI 帮助和准备完成提示显示：
 
 ```text
-i3 Composer Agent v1.0.0
+i3 Composer Agent v1.0.1
 Based on agent-skills v0.6.12
 ```
 
-在上述例子中，--version 输出 1.0.0，保留脚本使用的单一版本格式。--dry-run 的 JSON
+在上述例子中，--version 输出 1.0.1，保留脚本使用的单一版本格式。--dry-run 的 JSON
 分别提供 version、upstreamVersion、upstreamCommit。
 
 已经发布的 @givolt/i3-composer-agent@0.6.12 及其 Git 标签作为历史记录保留。
 之前的 0.6.13 是未发布候选，新的独立版本候选替代它。
-1.0.0 的源码与打包验证不代表 npm 发布；发布仍按 MAINTENANCE.md 单独执行。
+1.0.0 已发布。1.0.1 用于修复安装向导遗漏，版本与发布已由用户确认。
+源码与打包验证不代表 npm 发布；发布仍按 MAINTENANCE.md 单独执行。

package/rebrand/brand.json

@@ -9,5 +9,5 @@
   "repository": "https://github.com/49780522/i3-composer-agent",
   "sourceBranch": "agent/source",
   "releaseBranch": "main",
-  "releaseVersion": "1.0.0"
+  "releaseVersion": "1.0.1"
 }