@givolt/i3-composer-agent 1.0.0 → 2.0.0

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

@@ -0,0 +1,241 @@
+'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/i3-spec.md'), 'utf8');
+  assert.match(command, /Invoke the i3-spec-driven-development skill/);
+  assert.doesNotMatch(command, /i3-composer-agent:/);
+  const ship = fs.readFileSync(path.join(base, 'commands/i3-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, /\/i3-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.map(id => `i3-${id}`)) {
+    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')));
+  }
+});
+function legacyInstallation(directory) {
+  const base = path.join(directory, '.codebuddy');
+  fs.mkdirSync(path.join(base, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(base, 'skills/spec-driven-development'), { recursive: true });
+  fs.writeFileSync(path.join(base, 'commands/spec.md'), 'original owned command');
+  fs.writeFileSync(path.join(base, 'skills/spec-driven-development/SKILL.md'), 'original owned Skill');
+  fs.writeFileSync(path.join(base, 'commands/build.md'), 'unowned custom command');
+  fs.writeFileSync(path.join(base, '.i3-composer-agent.json'), JSON.stringify({ name: 'i3-composer-agent', version: '1.0.1', assets: ['commands/spec.md', 'skills/spec-driven-development'] }));
+  return base;
+}
+test('prefix migration retires only owned legacy paths and preserves their backups', t => {
+  const directory = workspace(t);
+  const base = legacyInstallation(directory);
+  const args = ['--codebuddy', '--scope', 'project', '--yes'];
+  assert.equal(run(directory, args).status, 1);
+  assert.equal(fs.readFileSync(path.join(base, 'commands/spec.md'), 'utf8'), 'original owned command');
+  const result = run(directory, [...args, '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.existsSync(path.join(base, 'commands/spec.md')), false);
+  assert.equal(fs.existsSync(path.join(base, 'skills/spec-driven-development')), false);
+  assert.ok(fs.existsSync(path.join(base, 'commands/i3-spec.md')));
+  assert.match(fs.readFileSync(path.join(base, 'skills/i3-spec-driven-development/SKILL.md'), 'utf8'), /^name: i3-spec-driven-development$/m);
+  assert.equal(fs.readFileSync(path.join(base, 'commands/build.md'), 'utf8'), 'unowned custom command');
+  const backup = fs.readdirSync(base).find(file => file.startsWith('.i3-composer-agent-backup-'));
+  assert.equal(fs.readFileSync(path.join(base, backup, 'commands/spec.md'), 'utf8'), 'original owned command');
+  assert.equal(fs.readFileSync(path.join(base, backup, 'skills/spec-driven-development/SKILL.md'), 'utf8'), 'original owned Skill');
+  const manifest = JSON.parse(fs.readFileSync(path.join(base, '.i3-composer-agent.json'), 'utf8'));
+  assert.equal(manifest.entryPrefix, 'i3-');
+  assert.ok(!manifest.assets.includes('commands/spec.md'));
+});
+test('a failure after retiring legacy paths rolls the migration back', t => {
+  const directory = workspace(t);
+  const base = legacyInstallation(directory);
+  const before = fs.readFileSync(path.join(base, '.i3-composer-agent.json'), 'utf8');
+  const { planInstallation, executeInstallation } = require('../bin/install.cjs');
+  const plan = planInstallation({ agents: ['codebuddy'], scope: 'project', projectDir: directory });
+  const realRename = fs.renameSync;
+  fs.renameSync = (source, destination) => {
+    if (destination === path.join(base, '.i3-composer-agent.json') && source.includes('-stage-')) throw new Error('simulated manifest failure');
+    return realRename(source, destination);
+  };
+  try { assert.throws(() => executeInstallation(plan, { force: true }), /simulated manifest failure/); }
+  finally { fs.renameSync = realRename; }
+  assert.equal(fs.readFileSync(path.join(base, '.i3-composer-agent.json'), 'utf8'), before);
+  assert.equal(fs.readFileSync(path.join(base, 'commands/spec.md'), 'utf8'), 'original owned command');
+  assert.equal(fs.readFileSync(path.join(base, 'skills/spec-driven-development/SKILL.md'), 'utf8'), 'original owned Skill');
+  assert.equal(fs.existsSync(path.join(base, 'commands/i3-spec.md')), false);
+});
+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/i3-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/i3-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/i3-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)), ['i3-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, 'i3-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, 'i3-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/i3-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/);
+});

package/rebrand/templates/README.md

@@ -9,27 +9,68 @@ Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osma
 (MIT). See [NOTICE.md](NOTICE.md) for attribution.
 
 The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
-`i3-composer-agent`. Skill IDs retain their upstream names.
+`i3-composer-agent`. Commands and Skill IDs use the `i3-` prefix.
 
-## Prepare the complete plugin
+## Install with the wizard
 
-Run in the project where you want to prepare the plugin:
+Run in the project where you want to use the skills:
 
 ```bash
+npx @givolt/i3-composer-agent
+# Preselect a tool; the wizard still allows multiple selections:
 npx @givolt/i3-composer-agent --codebuddy
-# Other hosts:
-npx @givolt/i3-composer-agent --codex
-npx @givolt/i3-composer-agent --claude
 ```
 
-The command prepares a persistent `./i3-composer-agent/` directory containing
-{{SKILL_COUNT}} skills, {{COMMAND_COUNT}} commands, {{PERSONA_COUNT}} personas,
-and shared references. It prints native registration commands; run those in
-the selected host to enable the plugin. Preparing files does not select a host
-installation scope. See [CodeBuddy setup](docs/codebuddy-setup.md) and
-[Codex setup](docs/codex-setup.md).
+The interactive terminal wizard offers multiple tools, project or global scope,
+an installation summary, and confirmation. Its 79 tool directory presets come
+from the pinned [Vercel Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts).
+Choose by tool ID or comma-separated menu numbers. Use `--list-agents` to list
+the choices. Directory presets are not an execution test of every host.
+
+Every selected tool receives all {{SKILL_COUNT}} skills and shared references.
+CodeBuddy and Claude Code also receive {{COMMAND_COUNT}} short command workflows
+and {{PERSONA_COUNT}} persona files. Other tools use their native skill support;
+short lifecycle commands depend on the host. Shared destinations are installed
+once. License and attribution files accompany each native installation.
+Reload the IDE window or start a new session after installation. See
+[CodeBuddy setup](docs/codebuddy-setup.md) and [Codex setup](docs/codex-setup.md).
+
+For an explicit installation without prompts:
+
+```bash
+npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --claude --scope global --yes
+npx @givolt/i3-composer-agent --codebuddy --scope project --dry-run
+```
+
+Existing assets require confirmation; use `--force` with noninteractive installs.
+Replacement preserves previous files in a `.i3-composer-agent-backup-*` directory
+under each tool configuration root. Unrelated settings are left in place.
+`npx -y` accepts npm's package download prompt; the package's own `--yes` flag
+accepts the explicit installation plan.
+
+Earlier native installations migrate their unprefixed Skill and command paths
+when those paths belong to this package's previous installation manifest.
+The migration preserves legacy paths in the backup directory. Unowned entries
+remain in place. Use `/i3-spec` in CodeBuddy or `$i3-spec-driven-development`
+in Codex after upgrading.
+
+## Prepare the complete plugin
+
+For native plugin registration, including plugin hooks, explicitly prepare a
+persistent `./i3-composer-agent/` bundle:
+
+```bash
+npx @givolt/i3-composer-agent --prepare --codebuddy
+npx @givolt/i3-composer-agent --prepare --codex
+npx @givolt/i3-composer-agent --prepare --claude
+```
+
+The bundle includes skills, commands, personas, hooks and references. Run the
+registration commands printed by the CLI in the intended host. This preparation
+mode does not install native skills or choose the host plugin manager's scope.
 
-CodeBuddy / Claude Code:
+CodeBuddy Code (terminal) / Claude Code:
 
 ```text
 /plugin marketplace add ./i3-composer-agent
@@ -43,19 +84,21 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new session after enabling the plugin. Codex uses the existing Skill
-names, such as `$spec-driven-development`; lifecycle slash-command adaptation
+Start a new session after enabling the plugin. Codex uses the branded Skill
+names, such as `$i3-spec-driven-development`; lifecycle slash-command adaptation
 is maintained separately.
 
 ## Commands
 
-Hosts supporting Claude-compatible plugin commands load these workflows:
+Native CodeBuddy and Claude Code installations use short filenames such as
+`/i3-spec`, `/i3-plan`, `/i3-build` and `/i3-ship`. Hosts supporting Claude-compatible plugin
+commands load the same workflows under the plugin namespace:
 
 | Command | Description |
 | --- | --- |
 {{COMMAND_TABLE}}
 
-`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
+`/i3-composer-agent:i3-build auto` runs the existing approved-plan workflow.
 
 ## Skills
 
@@ -71,7 +114,8 @@ npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
 npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
 ```
 
-Replacement preserves the previous i3 bundle as a backup. Repository-scoped
+Explicit `--dir` retains the original plugin preparation behavior. Replacement
+preserves the previous i3 bundle as a backup. Repository-scoped
 AGENTS.md and CLAUDE.md are not copied into business projects.
 
 ## Maintaining this fork

package/rebrand/templates/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 {{SKILL_COUNT}} skills with `i3-` IDs.
+- `.codebuddy/references/` — shared checklists used by skill-relative links.
+- `.codebuddy/commands/` — all {{COMMAND_COUNT}} existing lifecycle workflows.
+- `.codebuddy/agents/` — all {{PERSONA_COUNT}} 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
+/i3-spec
+/i3-plan
+/i3-build
+/i3-build auto
+/i3-review
+/i3-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,28 +62,28 @@ 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.
 
 ```text
-/i3-composer-agent:spec
-/i3-composer-agent:plan
-/i3-composer-agent:build
-/i3-composer-agent:build auto
-/i3-composer-agent:review
-/i3-composer-agent:ship
+/i3-composer-agent:i3-spec
+/i3-composer-agent:i3-plan
+/i3-composer-agent:i3-build
+/i3-composer-agent:i3-build auto
+/i3-composer-agent:i3-review
+/i3-composer-agent:i3-ship
 ```
 
-Skill IDs, persona names, artifact paths, and workflow gates retain their
-upstream behavior. The plugin namespace changes to `i3-composer-agent`.
+Skill IDs and command filenames use `i3-`. Persona names, artifact paths,
+and workflow gates retain their upstream behavior. The plugin namespace is
+`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/rebrand/templates/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 installs
+the {{SKILL_COUNT}} skills with `i3-` 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
@@ -14,20 +25,20 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new Codex session after registration. All 25 existing skills keep their
-original IDs. In CLI/IDE, use `/skills` or `$spec-driven-development`; in chat,
+Start a new Codex session after registration. All {{SKILL_COUNT}} skills use
+`i3-` IDs. In CLI/IDE, use `/skills` or `$i3-spec-driven-development`; in chat,
 explicitly request the relevant skill from i3 Composer Agent.
 
 The adapter in `.codex-plugin/plugin.json` points at the unchanged `skills/`
 layout. Shared checklists remain under `references/`, so skill-relative links
 resolve inside the complete plugin bundle.
 
-The short lifecycle commands (`/spec`, `/plan`, `/build`, `/ship`) remain
+The short lifecycle commands (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-ship`) remain
 available in hosts that load the Claude-compatible command manifest. Codex
 lifecycle-command adaptation is separate from this brand conversion. Native
 Codex `/plan` switches planning mode; it is not the plugin's planning wrapper.
 
-Do not preload `using-agent-skills/SKILL.md` into always-on context: Codex routes
+Do not preload `i3-using-agent-skills/SKILL.md` into always-on context: Codex routes
 skills natively. The meta-skill can remain installed and explicitly invoked.
 
 For local source testing, replace `./i3-composer-agent` above with the absolute

package/rebrand/tests/pipeline.test.cjs

@@ -8,6 +8,8 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const root = path.resolve(__dirname, '../..');
 const baselineVersion = require('../upstream.json').upstreamVersion;
+const upstream = require('../upstream.json');
+const { runtimePath, rewriteReferences } = require('../identifiers.cjs');
 
 function run(directory, executable, args) {
   return spawnSync(executable, args, { cwd: directory, encoding: 'utf8' });
@@ -24,6 +26,19 @@ function fixture(t, branch = 'release/test-candidate') {
   for (const name of ['skills', 'references', 'agents', 'commands', '.claude', '.gemini', '.claude-plugin', '.codex-plugin', '.agents', 'hooks', 'docs', 'scripts', 'evals', 'rebrand', 'LICENSE', 'plugin.json', 'README.md']) {
     fs.cpSync(path.join(root, name), path.join(directory, name), { recursive: true, filter: file => !file.includes(`${path.sep}results${path.sep}`) });
   }
+  function restore(folder) {
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+      if (entry.name === 'rebrand') continue;
+      const file = path.join(folder, entry.name);
+      if (entry.isDirectory()) restore(file);
+      else if (/\.(?:md|js|cjs|sh|toml|json|yml|patch|diff)$/.test(entry.name)) fs.writeFileSync(file, rewriteReferences(fs.readFileSync(file, 'utf8'), true));
+    }
+  }
+  restore(directory);
+  for (const source of [...upstream.skills.map(id => `skills/${id}`), ...upstream.skills.map(id => `evals/cases/${id}.json`), ...upstream.skills.map(id => `evals/fixtures/${id}`), ...upstream.runtimeFiles.filter(file => /commands\/[^/]+\.(md|toml)$/.test(file))]) {
+    const branded = runtimePath(source);
+    if (fs.existsSync(path.join(directory, branded))) fs.renameSync(path.join(directory, branded), path.join(directory, source));
+  }
   // Model an upstream source checkout, including when this suite runs in a packed branded bundle.
   for (const name of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']) {
     const file = path.join(directory, name);
@@ -57,9 +72,62 @@ test('a source checkout generates a complete, repeatable branded distribution',
   const brand = JSON.parse(fs.readFileSync(path.join(directory, 'rebrand/brand.json'), 'utf8'));
   assert.equal(pkg.version, brand.releaseVersion);
   assert.equal(fs.existsSync(path.join(directory, 'bin/i3-composer-agent.cjs')), true);
-  assert.equal(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  const validation = node(directory, 'scripts/validate-brand.cjs');
+  assert.equal(validation.status, 0, validation.stdout + validation.stderr);
+  const complete = run(directory, 'npm', ['run', 'validate']);
+  assert.equal(complete.status, 0, complete.stdout + complete.stderr);
+  const routing = node(directory, 'scripts/run-evals.js', ['--min-rank1', '95']);
+  assert.equal(routing.status, 0, routing.stdout + routing.stderr);
+  const check = node(directory, 'rebrand/apply.cjs', ['--check']);
+  assert.equal(check.status, 0, check.stdout + check.stderr);
+});
+
+test('branded commands and skills use i3 identifiers with working local references', t => {
+  const directory = fixture(t);
+  record(directory);
+  apply(directory);
+  const skill = 'i3-spec-driven-development';
+  const file = path.join(directory, 'skills', skill, 'SKILL.md');
+  assert.ok(fs.existsSync(file), 'branded Skill directory must use i3-');
+  assert.match(fs.readFileSync(file, 'utf8'), /^name: i3-spec-driven-development$/m);
+  assert.equal(fs.existsSync(path.join(directory, 'skills/spec-driven-development')), false);
+  const command = fs.readFileSync(path.join(directory, '.claude/commands/i3-spec.md'), 'utf8');
+  assert.match(command, /i3-composer-agent:i3-spec-driven-development/);
+  assert.equal(fs.existsSync(path.join(directory, '.claude/commands/spec.md')), false);
+  const helper = 'skills/i3-idea-refine/scripts/idea-refine.sh';
+  assert.ok(fs.statSync(path.join(directory, helper)).mode & 0o111, 'helper execution permissions must survive renaming');
+  assert.ok(fs.readFileSync(path.join(directory, 'skills/i3-idea-refine/SKILL.md'), 'utf8').includes(helper), 'helper reference must resolve to its retained filename');
+  for (const commands of ['commands', '.gemini/commands']) {
+    assert.ok(fs.existsSync(path.join(directory, commands, 'i3-planning.toml')));
+  }
+  const hook = fs.readFileSync(path.join(directory, 'hooks/session-start.sh'), 'utf8');
+  assert.match(hook, /i3-using-agent-skills\/SKILL\.md/);
+  assert.equal(node(directory, 'scripts/validate-commands.js').status, 0);
+  const readme = fs.readFileSync(path.join(directory, 'README.md'), 'utf8');
+  assert.match(readme, /\/i3-spec/);
+  assert.match(readme, /skills\/i3-spec-driven-development\/SKILL\.md/);
   const check = node(directory, 'rebrand/apply.cjs', ['--check']);
   assert.equal(check.status, 0, check.stdout + check.stderr);
+  apply(directory);
+  assert.equal(fs.existsSync(path.join(directory, 'skills/i3-i3-spec-driven-development')), false);
+});
+
+test('generated native installer preserves references and migrates legacy identifiers safely', t => {
+  const directory = fixture(t);
+  record(directory);
+  apply(directory);
+  const result = run(directory, process.execPath, ['--test', 'tests/installer.test.cjs']);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('identifier rewriting preserves upstream URLs and avoids repeated prefixes', () => {
+  const content = 'Use spec-driven-development and /spec. https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md';
+  const expected = 'Use i3-spec-driven-development and /i3-spec. https://github.com/addyosmani/agent-skills/blob/main/skills/spec-driven-development/SKILL.md';
+  assert.equal(rewriteReferences(content), expected);
+  assert.equal(rewriteReferences(expected), expected);
+  assert.equal(rewriteReferences(expected, true), content);
+  assert.equal(rewriteReferences('Save specs/auth/spec.md; use .claude/commands/spec.md.'), 'Save specs/auth/spec.md; use .claude/commands/i3-spec.md.');
+  assert.equal(rewriteReferences('skills/idea-refine/scripts/idea-refine.sh'), 'skills/i3-idea-refine/scripts/idea-refine.sh');
 });
 
 test('brand fixes advance independently while preserving upstream provenance', t => {
@@ -132,9 +200,9 @@ test('missing files and altered skill identifiers fail preservation validation',
   const directory = fixture(t);
   record(directory);
   apply(directory);
-  const file = path.join(directory, 'skills/using-agent-skills/SKILL.md');
+  const file = path.join(directory, 'skills/i3-using-agent-skills/SKILL.md');
   const original = fs.readFileSync(file, 'utf8');
-  fs.writeFileSync(file, original.replace('name: using-agent-skills', 'name: renamed-meta-skill'));
+  fs.writeFileSync(file, original.replace('name: i3-using-agent-skills', 'name: renamed-meta-skill'));
   assert.notEqual(node(directory, 'scripts/validate-brand.cjs').status, 0);
   fs.writeFileSync(file, original);
   fs.rmSync(file);

package/references/accessibility-checklist.md

@@ -1,6 +1,6 @@
 # Accessibility Checklist
 
-Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `i3-frontend-ui-engineering` skill.
 
 ## Table of Contents