@givolt/i3-composer-agent 1.0.0 → 1.0.1

package/rebrand/templates/README.md

@@ -11,25 +11,60 @@ Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osma
 The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
 `i3-composer-agent`. Skill IDs retain their upstream names.
 
-## 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.
+
+## 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
@@ -49,7 +84,9 @@ is maintained separately.
 
 ## Commands
 
-Hosts supporting Claude-compatible plugin commands load these workflows:
+Native CodeBuddy and Claude Code installations use short filenames such as
+`/spec`, `/plan`, `/build` and `/ship`. Hosts supporting Claude-compatible plugin
+commands load the same workflows under the plugin namespace:
 
 | Command | Description |
 | --- | --- |
@@ -71,7 +108,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 their original 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
+/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/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 retains
+the {{SKILL_COUNT}} 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
@@ -14,7 +25,7 @@ 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
+Start a new Codex session after registration. All {{SKILL_COUNT}} existing skills keep their
 original IDs. In CLI/IDE, use `/skills` or `$spec-driven-development`; in chat,
 explicitly request the relevant skill from i3 Composer Agent.
 

package/tests/installer.test.cjs

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