@givolt/i3-composer-agent 0.6.12 → 1.0.1

package/bin/i3-composer-agent.cjs

@@ -8,25 +8,39 @@ const root = path.resolve(__dirname, '..');
 const pkg = require('../package.json');
 const name = 'i3-composer-agent';
 const args = process.argv.slice(2);
-const help = `${pkg.name} v${pkg.version}
+const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pkg.i3ComposerAgent.upstreamVersion}`;
+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("'", "'\\''") + "'"; }
@@ -41,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);
@@ -74,7 +87,7 @@ function main() {
     if (manifest.name !== name) throw new Error('Refusing to replace a directory belonging to another plugin.');
   }
   if (dryRun) {
-    console.log(JSON.stringify({ name, version: pkg.version, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
     return;
   }
   fs.mkdirSync(path.dirname(directory), { recursive: true });
@@ -101,7 +114,8 @@ function main() {
     try { fs.renameSync(staging, directory); }
     catch (error) { if (backup) fs.renameSync(backup, directory); throw error; }
   } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
-  console.log(`Prepared ${name} v${pkg.version} at ${directory}`);
+  console.log(identity);
+  console.log(`Prepared ${name} at ${directory}`);
   if (backup) console.log(`Previous bundle preserved at ${backup}`);
   if (host === 'extract') return;
   console.log('\nRegister and enable the plugin with these native commands:');
@@ -116,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/antigravity-setup.md

@@ -18,7 +18,7 @@ agy plugin install /path/to/i3-composer-agent
 
 1. Prepare the plugin bundle:
    ```bash
-npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+   npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
    ```
 2. Install the plugin using `agy`:
    ```bash

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/docs/comparison.md

@@ -6,7 +6,7 @@
 
 # How agent-skills compares
 
-> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
+> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b8030e023baeebb31781a6653fe8e93026`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
 
 People often ask how **agent-skills** relates to the two other "skills for coding agents" collections they hear about most: **Superpowers** (Jesse Vincent / obra) and **Matt Pocock's skills**. All three are good, share a lot of DNA, and are worth learning from. This page is an honest map of how they are *shaped* differently, so you can pick the one that fits how you work, or borrow across all three.
 

package/package.json

@@ -1,33 +1,91 @@
 {
   "name": "@givolt/i3-composer-agent",
-  "version": "0.6.12",
   "description": "i3 Composer Agent: production-grade engineering skills and lifecycle commands for AI coding agents.",
   "license": "MIT",
   "author": "Givolt",
-  "contributors": [{ "name": "Addy Osmani" }],
-  "bin": { "i3-composer-agent": "bin/i3-composer-agent.cjs" },
-  "engines": { "node": ">=20" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "contributors": [
+    {
+      "name": "Addy Osmani"
+    }
+  ],
+  "bin": {
+    "i3-composer-agent": "bin/i3-composer-agent.cjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "files": [
-    "bin/", "skills/", "references/", "agents/", "commands/",
-    ".claude/commands/", ".gemini/commands/", ".claude-plugin/",
-    ".codex-plugin/", ".agents/plugins/", "hooks/", "docs/",
-    "scripts/", "evals/", "rebrand/", "tests/", "plugin.json", "NOTICE.md"
+    "bin/",
+    "skills/",
+    "references/",
+    "agents/",
+    "commands/",
+    ".claude/commands/",
+    ".gemini/commands/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".agents/plugins/",
+    "hooks/",
+    "docs/",
+    "scripts/",
+    "evals/",
+    "rebrand/",
+    "tests/",
+    "plugin.json",
+    "NOTICE.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "rebrand": "node rebrand/apply.cjs --apply",
     "rebrand:check": "node rebrand/apply.cjs --check",
     "validate": "node scripts/validate-brand.cjs && node scripts/validate-skills.js && node scripts/validate-versions.js && node scripts/validate-commands.js && node scripts/validate-reference-links.js && node scripts/validate-artifact-paths.js",
-    "test": "node --test scripts/*-test.js scripts/lib/*-test.js tests/*.test.cjs",
+    "test": "node --test scripts/*-test.js scripts/lib/*-test.js tests/*.test.cjs rebrand/tests/*.test.cjs",
     "prepack": "npm run validate"
   },
-  "keywords": ["i3-composer", "agent-skills", "codebuddy", "codex", "claude-code"],
+  "keywords": [
+    "i3-composer",
+    "agent-skills",
+    "codebuddy",
+    "codex",
+    "claude-code"
+  ],
   "i3ComposerAgent": {
     "pluginFiles": [
-      "bin", "skills", "references", "agents", "commands", ".claude/commands",
-      ".gemini/commands", ".claude-plugin", ".codex-plugin", ".agents/plugins",
-      "hooks", "docs", "scripts", "evals", "rebrand", "tests", "plugin.json",
-      "package.json", "README.md", "LICENSE", "NOTICE.md"
-    ]
-  }
+      "bin",
+      "skills",
+      "references",
+      "agents",
+      "commands",
+      ".claude/commands",
+      ".gemini/commands",
+      ".claude-plugin",
+      ".codex-plugin",
+      ".agents/plugins",
+      "hooks",
+      "docs",
+      "scripts",
+      "evals",
+      "rebrand",
+      "tests",
+      "plugin.json",
+      "package.json",
+      "README.md",
+      "LICENSE",
+      "NOTICE.md",
+      "CHANGELOG.md"
+    ],
+    "upstreamVersion": "0.6.12",
+    "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
+    "upstreamRepository": "https://github.com/addyosmani/agent-skills"
+  },
+  "version": "1.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/49780522/i3-composer-agent.git"
+  },
+  "homepage": "https://github.com/49780522/i3-composer-agent#readme"
 }