@givolt/i3-composer-agent 1.0.0 → 2.0.0

package/skills/{using-agent-skills → i3-using-agent-skills}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: using-agent-skills
+name: i3-using-agent-skills
 description: Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked.
 ---
 
@@ -16,30 +16,30 @@ When a task arrives, identify the development phase and apply the corresponding
 ```
 Task arrives
     │
-    ├── Don't know what you want yet? ──────→ interview-me
-    ├── Have a rough concept, need variants? → idea-refine
-    ├── New project/feature/change? ──→ spec-driven-development
-    ├── No quality bar written down? ──→ constraint-driven-development
-    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
-    ├── Implementing code? ────────────→ incremental-implementation
-    │   ├── UI work? ─────────────────→ frontend-ui-engineering
-    │   ├── API work? ────────────────→ api-and-interface-design
-    │   ├── Need better context? ─────→ context-engineering
-    │   ├── Need doc-verified code? ───→ source-driven-development
-    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
-    ├── Writing/running tests? ────────→ test-driven-development
-    │   └── Browser-based? ───────────→ browser-testing-with-devtools
-    ├── Something broke? ──────────────→ debugging-and-error-recovery
-    ├── Reviewing code? ───────────────→ code-review-and-quality
-    │   ├── Too complex? ─────────────→ code-simplification
-    │   ├── Security concerns? ───────→ security-and-hardening
-    │   └── Performance concerns? ────→ performance-optimization
-    ├── Committing/branching? ─────────→ git-workflow-and-versioning
-    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
-    ├── Deprecating/migrating? ────────→ deprecation-and-migration
-    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
-    ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation
-    └── Deploying/launching? ─────────→ shipping-and-launch
+    ├── Don't know what you want yet? ──────→ i3-interview-me
+    ├── Have a rough concept, need variants? → i3-idea-refine
+    ├── New project/feature/change? ──→ i3-spec-driven-development
+    ├── No quality bar written down? ──→ i3-constraint-driven-development
+    ├── Have a spec, need tasks? ──────→ i3-planning-and-task-breakdown
+    ├── Implementing code? ────────────→ i3-incremental-implementation
+    │   ├── UI work? ─────────────────→ i3-frontend-ui-engineering
+    │   ├── API work? ────────────────→ i3-api-and-interface-design
+    │   ├── Need better context? ─────→ i3-context-engineering
+    │   ├── Need doc-verified code? ───→ i3-source-driven-development
+    │   └── Stakes high / unfamiliar code? ──→ i3-doubt-driven-development
+    ├── Writing/running tests? ────────→ i3-test-driven-development
+    │   └── Browser-based? ───────────→ i3-browser-testing-with-devtools
+    ├── Something broke? ──────────────→ i3-debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ i3-code-review-and-quality
+    │   ├── Too complex? ─────────────→ i3-code-simplification
+    │   ├── Security concerns? ───────→ i3-security-and-hardening
+    │   └── Performance concerns? ────→ i3-performance-optimization
+    ├── Committing/branching? ─────────→ i3-git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ i3-ci-cd-and-automation
+    ├── Deprecating/migrating? ────────→ i3-deprecation-and-migration
+    ├── Writing docs/ADRs? ───────────→ i3-documentation-and-adrs
+    ├── Adding logs/metrics/alerts? ───→ i3-observability-and-instrumentation
+    └── Deploying/launching? ─────────→ i3-shipping-and-launch
 ```
 
 ## Core Operating Behaviors
@@ -134,59 +134,59 @@ These are the subtle errors that look like productivity but create problems:
 
 2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
 
-3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `code-simplification` → `shipping-and-launch` in sequence.
+3. **Multiple skills can apply.** A feature implementation might involve `i3-idea-refine` → `i3-spec-driven-development` → `i3-planning-and-task-breakdown` → `i3-incremental-implementation` → `i3-test-driven-development` → `i3-code-review-and-quality` → `i3-code-simplification` → `i3-shipping-and-launch` in sequence.
 
-4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `i3-spec-driven-development`.
 
 ## Lifecycle Sequence
 
 For a complete feature, the typical skill sequence is:
 
 ```
-1.  interview-me                → Extract what the user actually wants
-2.  idea-refine                 → Refine vague ideas
-3.  spec-driven-development     → Define what we're building
-4.  planning-and-task-breakdown → Break into verifiable chunks
-5.  context-engineering         → Load the right context
-6.  source-driven-development   → Verify against official docs
-7.  incremental-implementation  → Build slice by slice
-8.  observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
-9.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
-10. test-driven-development     → Prove each slice works
-11. code-review-and-quality     → Review before merge
-12. code-simplification         → Reduce unnecessary complexity while preserving behavior
-13. git-workflow-and-versioning → Clean commit history
-14. documentation-and-adrs      → Document decisions
-15. deprecation-and-migration   → Retire old systems and move users safely when needed
-16. shipping-and-launch         → Deploy safely
+1.  i3-interview-me                → Extract what the user actually wants
+2.  i3-idea-refine                 → Refine vague ideas
+3.  i3-spec-driven-development     → Define what we're building
+4.  i3-planning-and-task-breakdown → Break into verifiable chunks
+5.  i3-context-engineering         → Load the right context
+6.  i3-source-driven-development   → Verify against official docs
+7.  i3-incremental-implementation  → Build slice by slice
+8.  i3-observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
+9.  i3-doubt-driven-development    → Cross-examine non-trivial decisions in-flight
+10. i3-test-driven-development     → Prove each slice works
+11. i3-code-review-and-quality     → Review before merge
+12. i3-code-simplification         → Reduce unnecessary complexity while preserving behavior
+13. i3-git-workflow-and-versioning → Clean commit history
+14. i3-documentation-and-adrs      → Document decisions
+15. i3-deprecation-and-migration   → Retire old systems and move users safely when needed
+16. i3-shipping-and-launch         → Deploy safely
 ```
 
-Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+Not every task needs every skill. A bug fix might only need: `i3-debugging-and-error-recovery` → `i3-test-driven-development` → `i3-code-review-and-quality`.
 
 ## Quick Reference
 
 | Phase | Skill | One-Line Summary |
 |-------|-------|-----------------|
-| Define | interview-me | Surface what the user actually wants before any plan, spec, or code exists |
-| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
-| Define | spec-driven-development | Requirements and acceptance criteria before code |
-| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
-| Build | incremental-implementation | Thin vertical slices, test each before expanding |
-| Build | source-driven-development | Verify against official docs before implementing |
-| Build | doubt-driven-development | Adversarial fresh-context review of every non-trivial decision |
-| Build | context-engineering | Right context at the right time |
-| Build | frontend-ui-engineering | Production-quality UI with accessibility |
-| Build | api-and-interface-design | Stable interfaces with clear contracts |
-| Verify | test-driven-development | Failing test first, then make it pass |
-| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
-| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
-| Review | code-review-and-quality | Five-axis review with quality gates |
-| Review | code-simplification | Preserve behavior while reducing unnecessary complexity |
-| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
-| Review | performance-optimization | Measure first, optimize only what matters |
-| Ship | git-workflow-and-versioning | Atomic commits, clean history |
-| Ship | ci-cd-and-automation | Automated quality gates on every change |
-| Ship | deprecation-and-migration | Remove old systems and migrate users safely |
-| Ship | documentation-and-adrs | Document the why, not just the what |
-| Ship | observability-and-instrumentation | Structured logs, RED metrics, traces, symptom-based alerts |
-| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |
+| Define | i3-interview-me | Surface what the user actually wants before any plan, spec, or code exists |
+| Define | i3-idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | i3-spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | i3-planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | i3-incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | i3-source-driven-development | Verify against official docs before implementing |
+| Build | i3-doubt-driven-development | Adversarial fresh-context review of every non-trivial decision |
+| Build | i3-context-engineering | Right context at the right time |
+| Build | i3-frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | i3-api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | i3-test-driven-development | Failing test first, then make it pass |
+| Verify | i3-browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | i3-debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | i3-code-review-and-quality | Five-axis review with quality gates |
+| Review | i3-code-simplification | Preserve behavior while reducing unnecessary complexity |
+| Review | i3-security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | i3-performance-optimization | Measure first, optimize only what matters |
+| Ship | i3-git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | i3-ci-cd-and-automation | Automated quality gates on every change |
+| Ship | i3-deprecation-and-migration | Remove old systems and migrate users safely |
+| Ship | i3-documentation-and-adrs | Document the why, not just the what |
+| Ship | i3-observability-and-instrumentation | Structured logs, RED metrics, traces, symptom-based alerts |
+| Ship | i3-shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |

package/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/);
+});