@givolt/i3-composer-agent 2.0.0 → 2.1.0

package/.agents/plugins/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
       "source": {
         "source": "local",

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "source": "./",
       "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",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "author": {
     "name": "Givolt"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "author": {
     "name": "Givolt"

package/README.md

@@ -1,13 +1,7 @@
-# i3 Composer Agent v2.0.0
-
-**Based on agent-skills v0.6.12**
+# i3 Composer Agent v2.1.0
 
 **Intelligence. Integration. Innovation.**
 
-Engineering skills, lifecycle commands, and specialist personas for AI coding agents.
-Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani
-(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`. Commands and Skill IDs use the `i3-` prefix.
 
@@ -19,40 +13,53 @@ Run in the project where you want to use the skills:
 npx @givolt/i3-composer-agent
 # Preselect a tool; the wizard still allows multiple selections:
 npx @givolt/i3-composer-agent --codebuddy
+npx @givolt/i3-composer-agent --workbuddy
 ```
 
 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).
+an installation summary, and confirmation. It offers 80 directory
+presets: the pinned [Vercel Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
+plus a native WorkBuddy preset.
 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 25 skills and shared references.
-CodeBuddy and Claude Code also receive 9 short command workflows
+CodeBuddy, WorkBuddy and Claude Code also receive 9 short command workflows
 and 4 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.
+once. A standard MIT license accompanies the shared references.
 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).
+[CodeBuddy setup](docs/codebuddy-setup.md), [WorkBuddy setup](docs/workbuddy-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 --workbuddy --scope project --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope global --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.
+CodeBuddy and WorkBuddy share one project installation under `.codebuddy/`.
+Existing `.workbuddy/` project settings are preserved. Global installations use
+separate `~/.codebuddy/` and `~/.workbuddy/` directories.
+
+Unchanged manifest-owned assets from the same version and scope are reused;
+adding a client merges its ID into the shared installation manifest. Modified
+files, unowned collisions and version upgrades require confirmation; use
+`--force` with noninteractive installs after reviewing the dry run.
+After successful installation, replaced files and installer-owned historical
+backups are removed. A failed installation restores the previous files.
 `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`
+The migration removes owned legacy paths after successful installation. Use
+`/i3-spec` in CodeBuddy or WorkBuddy, or `$i3-spec-driven-development`
 in Codex after upgrading.
 
 ## Prepare the complete plugin
@@ -90,7 +97,7 @@ is maintained separately.
 
 ## Commands
 
-Native CodeBuddy and Claude Code installations use short filenames such as
+Native CodeBuddy, WorkBuddy 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:
 
@@ -106,7 +113,8 @@ commands load the same workflows under the plugin namespace:
 | /i3-composer-agent:i3-test | Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. |
 | /i3-composer-agent:i3-webperf | Run a web performance audit via the web-performance-auditor persona |
 
-`/i3-composer-agent:i3-build auto` runs the existing approved-plan workflow.
+`/i3-build auto` runs the existing approved-plan workflow in native installations;
+plugin installations use `/i3-composer-agent:i3-build auto`.
 
 ## Skills
 
@@ -146,17 +154,6 @@ npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
 npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
 ```
 
-Explicit `--dir` retains the original plugin preparation behavior. Replacement
-preserves the previous i3 bundle as a backup. Repository-scoped
+Explicit `--dir` retains the plugin preparation behavior. Successful replacement
+removes the previous bundle and this plugin's historical backups. Repository-scoped
 AGENTS.md and CLAUDE.md are not copied into business projects.
-
-## Maintaining this fork
-
-This repository is independent of the GSD-based i3 Composer Work repository.
-`agent/source` retains upstream source and the `rebrand/` rules; `main` contains
-the validated branded distribution. Create release candidates from the source
-branch, replay branding, validate, then update the release branch.
-
-See [maintenance](rebrand/MAINTENANCE.md), [source PR workflow](rebrand/PR-WORKFLOW.md),
-[versioning](rebrand/VERSIONING.md), [changelog](CHANGELOG.md),
-and [validation contract](rebrand/VALIDATION.md).

package/bin/agent-targets.json

@@ -721,6 +721,17 @@
         "base": "home",
         "path": ".zencoder/skills"
       }
+    },
+    {
+      "id": "workbuddy",
+      "label": "WorkBuddy",
+      "projectSkillsDir": ".codebuddy/skills",
+      "globalSkillsDir": {
+        "base": "env",
+        "env": "WORKBUDDY_CONFIG_DIR",
+        "fallback": ".workbuddy",
+        "path": "skills"
+      }
     }
   ]
 }

package/bin/asset-fingerprint.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { nativeContent } = require('./native-content.cjs');
+
+// Compare the complete tree without following links. When asset is provided,
+// hash the source as it will be rendered by the native installer.
+function fingerprint(file, asset) {
+  const hash = crypto.createHash('sha256');
+  function visit(current, relative) {
+    let stat;
+    try { stat = fs.lstatSync(current); }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+      if (asset) throw new Error(`Package contains an unsupported file: ${current}`);
+      return false;
+    }
+    hash.update(JSON.stringify([relative, stat.isDirectory() ? 'directory' : 'file', stat.mode & 0o111]) + '\n');
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(current).sort()) {
+        if (asset && entry === '.DS_Store') continue;
+        if (!visit(path.join(current, entry), path.join(relative, entry))) return false;
+      }
+    } else {
+      const content = asset && current.endsWith('.md')
+        ? Buffer.from(nativeContent(fs.readFileSync(current, 'utf8'), asset))
+        : fs.readFileSync(current);
+      hash.update(String(content.length) + '\n');
+      hash.update(content);
+    }
+    return true;
+  }
+  return visit(file, '') ? hash.digest('hex') : undefined;
+}
+
+module.exports = { fingerprint };

package/bin/cleanup-backups.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function cleanupBackups(directory, prefix, belongs = () => true) {
+  // Installer backups have a v4 UUID suffix. Ignore lookalikes and symlinks.
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith(prefix) || !uuid.test(entry.name.slice(prefix.length))) continue;
+    const backup = path.join(directory, entry.name);
+    if (belongs(backup)) fs.rmSync(backup, { recursive: true });
+  }
+}
+
+module.exports = { cleanupBackups };

package/bin/i3-composer-agent.cjs

@@ -4,11 +4,12 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { cleanupBackups } = require('./cleanup-backups.cjs');
 const root = path.resolve(__dirname, '..');
 const pkg = require('../package.json');
 const name = 'i3-composer-agent';
 const args = process.argv.slice(2);
-const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pkg.i3ComposerAgent.upstreamVersion}`;
+const identity = `i3 Composer Agent v${pkg.version}`;
 const help = `${identity}
 ${pkg.name}
 
@@ -17,6 +18,8 @@ Install engineering skills with a multi-tool installation wizard.
 Usage:
   npx ${pkg.name}
   npx ${pkg.name} --codebuddy
+  npx ${pkg.name} --workbuddy
+  npx ${pkg.name} --agents codebuddy,workbuddy --scope project --yes
   npx ${pkg.name} --agents codebuddy,codex --scope project --yes
   npx ${pkg.name} --prepare --claude --dir <directory>
   npx ${pkg.name} --extract --dir <directory>
@@ -24,6 +27,7 @@ Usage:
 Options:
   --agents <ids>      Comma-separated tool IDs; multiple tools are supported
   --codebuddy        Preselect CodeBuddy desktop IDE / CodeBuddy Code
+  --workbuddy        Preselect WorkBuddy (shared project / independent global)
   --codex            Preselect Codex
   --claude           Preselect Claude Code
   --scope <scope>    project or global (or use --global / --local)
@@ -33,12 +37,12 @@ Options:
   --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
+  --force            Replace existing assets; remove old files after success
   --version          Print the package version
   --help             Show this help
 
 The terminal wizard selects tools and scope, then installs native skill files.
-CodeBuddy and Claude Code also receive short lifecycle commands and personas.
+CodeBuddy, WorkBuddy and Claude Code also receive short commands and personas.
 Other tools receive skills and references; command availability is host-specific.
 Use --prepare for complete plugins, including hooks and host registration.
 `;
@@ -63,6 +67,7 @@ function prepare() {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--prepare') continue;
+    if (arg === '--workbuddy') throw new Error('For native WorkBuddy installation, use --workbuddy --scope project|global --yes without --prepare or --dir.');
     if (['--codebuddy', '--codex', '--claude', '--extract'].includes(arg)) {
       if (host) throw new Error('Choose exactly one host flag or --extract.');
       host = arg.slice(2);
@@ -87,12 +92,13 @@ function prepare() {
     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, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    console.log(JSON.stringify({ name, version: pkg.version, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
     return;
   }
   fs.mkdirSync(path.dirname(directory), { recursive: true });
   const staging = fs.mkdtempSync(path.join(path.dirname(directory), `.${name}-`));
   let backup;
+  let completed = false;
   try {
     for (const relative of pkg.i3ComposerAgent.pluginFiles) {
       const source = path.join(root, relative);
@@ -113,10 +119,18 @@ function prepare() {
     }
     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 }); }
+    completed = true;
+  } finally {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+    if (completed) cleanupBackups(path.dirname(directory), `${path.basename(directory)}.backup-`, previous => {
+      const manifest = path.join(previous, 'plugin.json');
+      try {
+        return !fs.lstatSync(manifest).isSymbolicLink() && JSON.parse(fs.readFileSync(manifest, 'utf8')).name === name;
+      } catch { return false; }
+    });
+  }
   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:');
   const selector = `${name}@${name}`;
@@ -142,7 +156,7 @@ async function main() {
   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));
+    if (['--codebuddy', '--workbuddy', '--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];
@@ -168,7 +182,7 @@ async function main() {
   }
   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));
+    console.log(JSON.stringify({ name, version: pkg.version, mode: plan.mode, scope: plan.scope, agents: plan.agents, targets: plan.targets, conflicts: plan.conflicts, reused: plan.reused }, null, 2));
     return;
   }
   if (!options.yes) {
@@ -176,15 +190,16 @@ async function main() {
     if (!confirmed) { console.log('Installation cancelled. No files changed.'); return; }
     options.force = plan.conflicts.length > 0;
   }
-  const backups = installer.executeInstallation(plan, { force: options.force });
+  installer.executeInstallation(plan, { force: options.force });
   console.log(identity);
+  if (plan.reused.length) console.log(`Reused ${plan.reused.length} unchanged assets from the same package version.`);
   for (const target of plan.targets) {
     console.log(`Installed ${target.agents.join(', ')} skills at ${target.skillsDirectory}`);
     if (target.commandsDirectory) console.log(`Commands: /i3-spec, /i3-plan, /i3-build, /i3-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.');
+  if (plan.agents.some(id => !['codebuddy', 'workbuddy', '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.');
+  if (plan.agents.some(id => ['codebuddy', 'codex', 'claude-code'].includes(id))) console.log('For CodeBuddy, Codex or Claude Code plugin registration, use --prepare with the matching host flag.');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/bin/install.cjs

@@ -5,9 +5,12 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const registry = require('./agent-targets.json');
-const upstream = require('../rebrand/upstream.json');
+const { cleanupBackups } = require('./cleanup-backups.cjs');
+const { nativeContent } = require('./native-content.cjs');
+const { fingerprint } = require('./asset-fingerprint.cjs');
 const root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
+const version = require('../package.json').version;
 const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
 function exists(file) {
   try { fs.lstatSync(file); return true; }
@@ -43,6 +46,10 @@ function checkDestination(file) {
     throw new Error('Installation destinations must be outside this package directory.');
   }
 }
+function manifestContent(plan, asset) {
+  return JSON.stringify({ name, version, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
+    assets: plan.assets.filter(item => item.base === asset.base && item.kind !== 'legacy').map(item => path.relative(asset.base, item.destination)) }, null, 2) + '\n';
+}
 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.');
@@ -55,7 +62,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     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)) {
+    if (['codebuddy', 'workbuddy', 'claude-code'].includes(id)) {
       target.commandsDirectory = path.join(base, 'commands');
       target.personasDirectory = path.join(base, 'agents');
     }
@@ -71,6 +78,20 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     }
   }
   for (const target of targets.values()) {
+    const manifestFile = path.join(target.base, `.${name}.json`);
+    const previous = exists(manifestFile) && !fs.lstatSync(manifestFile).isSymbolicLink()
+      ? JSON.parse(fs.readFileSync(manifestFile, 'utf8')) : undefined;
+    const owned = previous?.name === name && Array.isArray(previous.assets);
+    const sameVersion = owned && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
+    if (owned && previous.scope === scope && Array.isArray(previous.agents)) {
+      const applicable = previous.agents.filter(id => {
+        const agent = registry.agents.find(item => item.id === id);
+        if (!agent || (scope === 'global' && !agent.globalSkillsDir)) return false;
+        const directory = scope === 'project' ? path.resolve(projectDir, agent.projectSkillsDir) : globalSkillsDir(agent, home, env);
+        return destination(directory) === target.skillsDirectory;
+      });
+      target.agents = [...new Set([...applicable, ...target.agents])];
+    }
     const start = assets.length;
     addDirectory('skills', target.skillsDirectory, 'skill');
     addDirectory('references', target.referencesDirectory, 'reference');
@@ -81,48 +102,59 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
       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' });
-    const manifestFile = path.join(target.base, `.${name}.json`);
-    if (exists(manifestFile)) {
-      const previous = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
-      if (previous.name === name && Array.isArray(previous.assets)) {
-        const legacy = upstream.skills.map(id => `skills/${id}`);
-        if (target.commandsDirectory) legacy.push(...upstream.commands.map(id => `commands/${id}.md`));
-        for (const relative of legacy) {
-          const file = destination(path.join(target.base, relative));
-          if (previous.assets.includes(relative) && exists(file)) assets.push({ destination: file, kind: 'legacy' });
-        }
+    const licenseDirectory = path.join(target.referencesDirectory, name);
+    if (exists(licenseDirectory) && fs.lstatSync(licenseDirectory).isSymbolicLink()) throw new Error(`Installation directory is a symlink: ${licenseDirectory}.`);
+    assets.push({ source: path.join(root, 'LICENSE'), destination: destination(path.join(licenseDirectory, 'LICENSE')), kind: 'attribution' });
+    if (owned) {
+      const legacy = fs.readdirSync(path.join(root, 'skills')).filter(id => id.startsWith('i3-')).map(id => `skills/${id.slice(3)}`);
+      if (target.commandsDirectory) legacy.push(...fs.readdirSync(path.join(root, '.claude/commands')).filter(file => file.startsWith('i3-') && file.endsWith('.md')).map(file => `commands/${file.slice(3)}`));
+      legacy.push(`${name}-LICENSE`, `${name}-NOTICE.md`);
+      for (const relative of legacy) {
+        const file = destination(path.join(target.base, relative));
+        if (previous.assets.includes(relative) && exists(file)) assets.push({ destination: file, kind: 'legacy' });
       }
     }
-    assets.push({ target, destination: destination(manifestFile), kind: 'manifest' });
+    assets.push({ target, destination: destination(manifestFile), kind: 'manifest', mergeable: sameVersion });
     for (const asset of assets.slice(start)) {
       asset.base = target.base;
-      asset.codebuddyCommand = asset.kind === 'command' && target.agents.includes('codebuddy');
+      asset.buddyCommand = asset.kind === 'command' && target.agents.some(id => ['codebuddy', 'workbuddy'].includes(id));
+      asset.scope = scope;
+      asset.personasDirectory = target.personasDirectory;
+      if (sameVersion && previous.assets.includes(path.relative(target.base, asset.destination)) && asset.source && exists(asset.destination)) {
+        asset.expectedFingerprint = fingerprint(asset.source, asset);
+        asset.reusable = fingerprint(asset.destination) === asset.expectedFingerprint;
+      }
     }
   }
   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) };
+  const plan = { mode: 'install', scope, agents, targets: [...targets.values()], assets };
+  for (const asset of assets.filter(item => item.kind === 'manifest' && item.mergeable)) {
+    asset.observedFingerprint = fingerprint(asset.destination);
+    asset.reusable = fs.readFileSync(asset.destination, 'utf8') === manifestContent(plan, asset);
+    if (asset.reusable) asset.expectedFingerprint = asset.observedFingerprint;
+  }
+  plan.conflicts = assets.filter(asset => asset.existing && !asset.reusable && !asset.mergeable).map(asset => asset.destination);
+  plan.reused = assets.filter(asset => asset.reusable).map(asset => asset.destination);
+  return plan;
 }
 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');
+  if (plan.conflicts.length && !force) throw new Error('Existing installation assets require confirmation or --force before replacement.');
   const contexts = new Map();
   const createdDirectories = [];
   const committed = [];
+  let completed = false;
+  let rolledBack = false;
   function mkdir(directory) {
     if (exists(directory)) return;
     mkdir(path.dirname(directory));
     fs.mkdirSync(directory);
     createdDirectories.push(directory);
   }
-  function portable(file, markdown = false, codebuddyCommand = false) {
+  function portable(file, asset, markdown = false) {
     if (fs.statSync(file).isDirectory()) {
-      for (const entry of fs.readdirSync(file)) portable(path.join(file, entry), false, codebuddyCommand);
+      for (const entry of fs.readdirSync(file)) portable(path.join(file, entry), asset);
     } 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);
+      fs.writeFileSync(file, nativeContent(fs.readFileSync(file, 'utf8'), asset));
     }
   }
   try {
@@ -136,20 +168,28 @@ function executeInstallation(plan, { force = false } = {}) {
       if (asset.kind === 'legacy') continue;
       asset.staged = path.join(context.staging, String(index));
       if (asset.kind === 'manifest') {
-        fs.writeFileSync(asset.staged, JSON.stringify({ name, version: pkg.version, entryPrefix: 'i3-', upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, scope: plan.scope, agents: asset.target.agents, assets: plan.assets.filter(item => item.base === asset.base && item.kind !== 'legacy').map(item => path.relative(asset.base, item.destination)) }, null, 2) + '\n');
+        fs.writeFileSync(asset.staged, manifestContent(plan, asset));
       } 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);
+        portable(asset.staged, asset, asset.source.endsWith('.md'));
       }
     }
     for (const asset of plan.assets) {
       const context = contexts.get(asset.base);
       mkdir(path.dirname(asset.destination));
+      if (asset.reusable) {
+        const unchanged = fingerprint(asset.destination) === asset.expectedFingerprint
+          && fingerprint(asset.staged) === asset.expectedFingerprint;
+        if (unchanged) continue;
+        if (!force) throw new Error(`Destination changed during installation: ${asset.destination}. Retry with confirmed replacement.`);
+      } else if (asset.mergeable) {
+        if (fingerprint(asset.destination) !== asset.observedFingerprint && !force) throw new Error(`Manifest changed during installation: ${asset.destination}. Retry with confirmed replacement.`);
+      }
       // 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.`);
+      if (exists(asset.destination) && !force && !asset.mergeable) 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));
@@ -162,15 +202,21 @@ function executeInstallation(plan, { force = false } = {}) {
         change.written = true;
       }
     }
-    return [...contexts.values()].map(context => context.backup).filter(exists);
+    completed = true;
+    return [];
   } 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);
     }
+    rolledBack = true;
     throw error;
   } finally {
     for (const context of contexts.values()) fs.rmSync(context.staging, { recursive: true, force: true });
+    for (const [base, context] of contexts) {
+      if (completed) cleanupBackups(base, `.${name}-backup-`);
+      else if (rolledBack) fs.rmSync(context.backup, { 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; }

package/bin/native-content.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Project commands are identical for both Buddy clients, including when the
+// other client is added later. Global commands use the selected profile path.
+function nativeContent(content, asset) {
+  content = content.replaceAll('i3-composer-agent:', '').replaceAll('agent-skills:', '');
+  if (!asset.buddyCommand) return content;
+  const projectPersonas = '.codebuddy/agents/';
+  const userPersonas = asset.scope === 'project'
+    ? "the current host's user-level agents directory"
+    : `\`${asset.personasDirectory.replaceAll('\\', '/')}/\``;
+  content = content.replaceAll('CLAUDE.md', 'CODEBUDDY.md')
+    .replaceAll('`~/.claude/agents/`', userPersonas)
+    .replaceAll('.claude/agents/', projectPersonas);
+  if (!asset.source.endsWith('i3-ship.md')) return content;
+  return content
+    .replace('Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command.',
+      'Use the host\'s native subagent capability to run three specialist personas concurrently. Issue all three calls together when the host supports parallel execution.')
+    .replace("In Claude Code, each call passes `subagent_type` matching the persona's `name` field:",
+      'Select the following persona names using the host\'s native subagent mechanism:')
+    .replace('In other harnesses without an Agent tool, invoke each persona\'s system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works.',
+      'If native subagents are unavailable, read each persona prompt from the installed agents directory, perform the three reviews sequentially, and retain the same merge phase.')
+    .replace(/Constraints \(from Claude Code's subagent model\):\n[\s\S]*?\n\n\*\*Persona resolution\.\*\*[^\n]*/,
+      `Constraints:\n- Each specialist reviews independently and returns a report to this session.\n- Specialists do not delegate to one another.\n- Follow the host's execution and permission limits.\n\n**Persona resolution.** Read installed persona prompts from \`${asset.scope === 'project' ? projectPersonas : asset.personasDirectory.replaceAll('\\', '/') + '/'}\`. For project installations, check ${userPersonas} for the current host's user-defined personas, and follow its native precedence rules.`)
+    .replace('The three Phase A personas run in parallel — never sequentially.',
+      'Run the three Phase A personas in parallel when native subagents are available; otherwise use the sequential fallback above.');
+}
+
+module.exports = { nativeContent };

package/bin/wizard.cjs

@@ -56,7 +56,8 @@ async function confirm(plan) {
     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.`);
+  if (plan.conflicts.length) console.log(`${plan.conflicts.length} existing assets will be replaced. Previous files are removed after successful installation.`);
+  if (plan.reused.length) console.log(`${plan.reused.length} unchanged assets from the same version will be reused.`);
   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]: ');

package/docs/antigravity-setup.md

@@ -45,7 +45,7 @@ agy plugin list
 
 ## Lifecycle Workflows and Command Compatibility
 
-Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/i3-build` and the other short wrappers are available. This is tracked in [upstream agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
+Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/i3-build` and the other short wrappers are available. This is tracked in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
 
 Use the native plugin skills directly while that importer limitation applies: