@givolt/i3-composer-agent 1.0.1 → 2.1.0

package/bin/install.cjs

@@ -5,8 +5,12 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const registry = require('./agent-targets.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; }
@@ -42,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.');
@@ -54,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');
     }
@@ -70,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');
@@ -80,36 +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' });
-    assets.push({ target, destination: destination(path.join(target.base, `.${name}.json`)), kind: 'manifest' });
+    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', 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 {
@@ -120,22 +165,31 @@ function executeInstallation(plan, { force = false } = {}) {
         contexts.set(asset.base, { staging: fs.mkdtempSync(path.join(asset.base, `.${name}-stage-`)), backup: path.join(asset.base, `.${name}-backup-${crypto.randomUUID()}`) });
       }
       const context = contexts.get(asset.base);
+      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, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, scope: plan.scope, agents: asset.target.agents, assets: plan.assets.filter(item => item.base === asset.base).map(item => path.relative(asset.base, item.destination)) }, null, 2) + '\n');
+        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));
@@ -143,18 +197,26 @@ function executeInstallation(plan, { force = false } = {}) {
         fs.renameSync(asset.destination, change.backup);
       }
       committed.push(change);
-      fs.renameSync(asset.staged, asset.destination);
-      change.written = true;
+      if (asset.kind !== 'legacy') {
+        fs.renameSync(asset.staged, asset.destination);
+        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/commands/{build.toml → i3-build.toml}

@@ -1,12 +1,12 @@
 description = "Implement tasks incrementally — build, test, verify, commit. Add \"auto\" to run the whole plan in one approved pass."
 
 prompt = """
-Invoke the incremental-implementation skill alongside test-driven-development.
+Invoke the i3-incremental-implementation skill alongside i3-test-driven-development.
 
 ## Modes
 
-- `/build` — implement the next pending task, then stop (careful, one slice at a time).
-- `/build auto` — generate the plan if needed, get a single approval, then implement every task without stopping between them.
+- `/i3-build` — implement the next pending task, then stop (careful, one slice at a time).
+- `/i3-build auto` — generate the plan if needed, get a single approval, then implement every task without stopping between them.
 
 The arguments select the mode. Treat `auto` (canonical) or `all` as autonomous mode; anything else (or empty) is the default single-task mode. Note: autonomous mode is not faster per task — it runs the same test-driven loop — it only removes the human stepping between tasks.
 
@@ -23,21 +23,21 @@ Pick the next pending task from the plan. Then:
 7. Commit with a descriptive message
 8. Mark the task complete and stop
 
-## Autonomous: the whole plan (`/build auto`)
+## Autonomous: the whole plan (`/i3-build auto`)
 
 Use this once a spec exists and you want to collapse plan + build into one run. It removes the manual stepping between tasks — not the verification. Every task still earns a passing test and its own commit.
 
-1. Require a spec. Look only for a spec at a known path: SPEC.md at the repo root, docs/SPEC.md, or a file under spec/. A README or arbitrary doc does NOT count. If none exists, stop and tell the user to run /spec first — do not invent requirements.
+1. Require a spec. Look only for a spec at a known path: SPEC.md at the repo root, docs/SPEC.md, or a file under spec/. A README or arbitrary doc does NOT count. If none exists, stop and tell the user to run /i3-spec first — do not invent requirements.
 2. Establish a clean baseline. Run `git status --porcelain`. If there are uncommitted changes outside the expected planning artifacts (SPEC.md, docs/SPEC.md, spec/*, tasks/plan.md, tasks/todo.md), stop and ask the user to commit, stash, or confirm how to handle them. Autonomous per-task commits must not absorb unrelated local work, or the clean-rollback guarantee breaks.
-3. Plan if needed. If there is no tasks/plan.md, invoke the planning-and-task-breakdown skill to generate one.
+3. Plan if needed. If there is no tasks/plan.md, invoke the i3-planning-and-task-breakdown skill to generate one.
 4. Single checkpoint. Present the full plan and wait for an unambiguous affirmative (e.g. "approve", "go", "yes"). Treat hedged responses ("looks reasonable", "I guess") as NOT approved. This is the only human gate — after approval, run autonomously. If you generated tasks/plan.md, commit it as a single preparatory commit now so it doesn't bleed into the first task's commit.
 5. Execute every task in dependency order. Use each task's declared dependencies; if they aren't explicit, execute in the order the plan lists them. For each task, run the full default loop above (RED → GREEN → regression → build → commit → mark complete). Stage only the files that task touched plus its task-status update — never `git add -A` blindly — and make one commit per task so any point is a clean rollback.
 6. Stop and ask the user (do not push through) when:
-   - a test can't be made to pass or the build breaks without an obvious fix → follow the debugging-and-error-recovery skill
+   - a test can't be made to pass or the build breaks without an obvious fix → follow the i3-debugging-and-error-recovery skill
    - the spec is ambiguous, or a task needs a decision the spec doesn't cover
-   - a task is high-risk or irreversible — auth/permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets, or anything you can't undo with `git revert` → follow the doubt-driven-development skill and get explicit sign-off before continuing
-   After the user resolves a blocker, they re-invoke /build auto — it resumes from the next pending task.
+   - a task is high-risk or irreversible — auth/permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets, or anything you can't undo with `git revert` → follow the i3-doubt-driven-development skill and get explicit sign-off before continuing
+   After the user resolves a blocker, they re-invoke /i3-build auto — it resumes from the next pending task.
 7. Summarize at the end: tasks completed, tests added, commits made, and anything skipped, flagged, or left for the user.
 
-If any step fails, follow the debugging-and-error-recovery skill.
+If any step fails, follow the i3-debugging-and-error-recovery skill.
 """

package/commands/{code-simplify.toml → i3-code-simplify.toml}

@@ -1,7 +1,7 @@
 description = "Simplify code for clarity and maintainability — reduce complexity without changing behavior"
 
 prompt = """
-Invoke the code-simplification skill.
+Invoke the i3-code-simplification skill.
 
 Simplify recently changed code (or the specified scope) while preserving exact behavior:
 
@@ -18,5 +18,5 @@ Simplify recently changed code (or the specified scope) while preserving exact b
 5. Apply each simplification incrementally — run tests after each change
 6. Verify all tests pass, the build succeeds, and the diff is clean
 
-If tests fail after a simplification, revert that change and reconsider. Use `code-review-and-quality` to review the result.
+If tests fail after a simplification, revert that change and reconsider. Use `i3-code-review-and-quality` to review the result.
 """

package/commands/{constraints.toml → i3-constraints.toml}

@@ -1,7 +1,7 @@
 description = "Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md"
 
 prompt = """
-Invoke the constraint-driven-development skill.
+Invoke the i3-constraint-driven-development skill.
 
 $ARGUMENTS
 
@@ -26,7 +26,7 @@ Default behaviour with no arguments: set up constraints for this repository.
 7. **Verify.** Run the constraints against the current branch. If anything fails that the user disagrees with, fix the constraint now rather than leaving a gate people will learn to ignore.
 
 Sub-commands:
-- `/constraints check` — run the current constraints against this branch and report
-- `/constraints guard` — inspect the diff for a weakened bar: lowered thresholds, skipped or deleted tests, new suppression comments, unfinished stubs, new exceptions
-- `/constraints ratchet` — record today's measured values as the floor that must not fall
+- `/i3-constraints check` — run the current constraints against this branch and report
+- `/i3-constraints guard` — inspect the diff for a weakened bar: lowered thresholds, skipped or deleted tests, new suppression comments, unfinished stubs, new exceptions
+- `/i3-constraints ratchet` — record today's measured values as the floor that must not fall
 """

package/commands/{planning.toml → i3-planning.toml}

@@ -1,7 +1,7 @@
 description = "Break work into small verifiable tasks with acceptance criteria and dependency ordering"
 
 prompt = """
-Invoke the planning-and-task-breakdown skill.
+Invoke the i3-planning-and-task-breakdown skill.
 
 Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then:
 

package/{.gemini/commands/review.toml → commands/i3-review.toml}

@@ -1,15 +1,15 @@
 description = "Conduct a five-axis code review — correctness, readability, architecture, security, performance"
 
 prompt = """
-Invoke the code-review-and-quality skill.
+Invoke the i3-code-review-and-quality skill.
 
 Review the current changes (staged or recent commits) across all five axes:
 
 1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
 2. **Readability** — Clear names? Straightforward logic? Well-organized?
 3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level?
-4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
-5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
+4. **Security** — Input validated? Secrets safe? Auth checked? (Use i3-security-and-hardening skill)
+5. **Performance** — No N+1 queries? No unbounded ops? (Use i3-performance-optimization skill)
 
 Categorize findings as Critical, Important, or Suggestion.
 Output a structured review with specific file:line references and fix recommendations.

package/commands/{ship.toml → i3-ship.toml}

@@ -1,9 +1,9 @@
 description = "Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision"
 
 prompt = """
-Invoke the shipping-and-launch skill.
+Invoke the i3-shipping-and-launch skill.
 
-`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here.
+`/i3-ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here.
 
 ## Phase A — Parallel fan-out
 
@@ -22,7 +22,7 @@ Constraints (from CLI's subagent model):
 - Do not let one persona delegate to another — keep the fan-out flat.
 - For richer multi-agent collaboration where teammates talk to each other instead of just reporting back, see `references/orchestration-patterns.md`.
 
-**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `agents/` or your global configuration, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of the CLI's scope priority table, so user-level definitions win by design.
+**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `agents/` or your global configuration, those take precedence over this plugin's versions — `/i3-ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of the CLI's scope priority table, so user-level definitions win by design.
 
 ## Phase B — Merge in main context
 
@@ -68,5 +68,5 @@ Produce a single output:
 2. Personas do not call each other. The main agent merges in Phase B.
 3. The rollback plan is mandatory before any GO decision.
 4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk.
-5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small.
+5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/i3-ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small.
 """

package/commands/{spec.toml → i3-spec.toml}

@@ -1,7 +1,7 @@
 description = "Start spec-driven development — write a structured specification before writing code"
 
 prompt = """
-Invoke the spec-driven-development skill.
+Invoke the i3-spec-driven-development skill.
 
 Begin by understanding what the user wants to build. Ask clarifying questions about:
 1. The objective and target users

package/{.gemini/commands/test.toml → commands/i3-test.toml}

@@ -1,7 +1,7 @@
 description = "Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern."
 
 prompt = """
-Invoke the test-driven-development skill.
+Invoke the i3-test-driven-development skill.
 
 For new features:
 1. Write tests that describe the expected behavior (they should FAIL)
@@ -15,5 +15,5 @@ For bug fixes (Prove-It pattern):
 4. Confirm the test passes
 5. Run the full test suite for regressions
 
-For browser-related issues, also invoke browser-testing-with-devtools to verify with Chrome DevTools MCP.
+For browser-related issues, also invoke i3-browser-testing-with-devtools to verify with Chrome DevTools MCP.
 """

package/commands/{webperf.toml → i3-webperf.toml}

@@ -1,7 +1,7 @@
 description = "Run a web performance audit via the web-performance-auditor persona"
 
 prompt = """
-/webperf targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output.
+/i3-webperf targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output.
 
 ## Determine the mode
 

package/docs/adoption-guide.md

@@ -28,44 +28,44 @@ A new project is the best-case scenario: there's no legacy behavior to preserve,
 ### Day 0 | Install and wire up
 
 1. Install the pack (`npx skills add /path/to/i3-composer-agent`, or the native integration for your tool, see [getting-started.md](getting-started.md)).
-2. If the host has no native skill router, load `using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. On hosts with native routing, install the individual skills and do not preload the meta-skill as always-on context.
-3. Add a short project rules file (`CLAUDE.md`, `.cursorrules`, etc.) with your stack, commands, and boundaries, `context-engineering` describes what belongs there.
+2. If the host has no native skill router, load `i3-using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. On hosts with native routing, install the individual skills and do not preload the meta-skill as always-on context.
+3. Add a short project rules file (`CLAUDE.md`, `.cursorrules`, etc.) with your stack, commands, and boundaries, `i3-context-engineering` describes what belongs there.
 
 ### Day 0 | Define before you build
 
 Run the lifecycle in order for the project's first real feature:
 
 ```
-/spec   →  SPEC.md            (spec-driven-development)
-/plan   →  tasks/plan.md      (planning-and-task-breakdown)
-/build  →  one slice at a time (incremental-implementation + test-driven-development)
-/review →  before every merge  (code-review-and-quality)
-/ship   →  when going live     (shipping-and-launch)
+/i3-spec   →  SPEC.md            (i3-spec-driven-development)
+/i3-plan   →  tasks/plan.md      (i3-planning-and-task-breakdown)
+/i3-build  →  one slice at a time (i3-incremental-implementation + i3-test-driven-development)
+/i3-review →  before every merge  (i3-code-review-and-quality)
+/i3-ship   →  when going live     (i3-shipping-and-launch)
 ```
 
-`/build auto` is a good fit for greenfield: you approve the plan once and every task still runs test-driven and commits individually. The spec and plan artifacts (`SPEC.md`, `tasks/`) are living documents, keep them in version control while the work is in flight. If the feature spans more than one session, those files are also the handoff, see [working across sessions](getting-started.md#working-across-sessions).
+`/i3-build auto` is a good fit for greenfield: you approve the plan once and every task still runs test-driven and commits individually. The spec and plan artifacts (`SPEC.md`, `tasks/`) are living documents, keep them in version control while the work is in flight. If the feature spans more than one session, those files are also the handoff, see [working across sessions](getting-started.md#working-across-sessions).
 
 ### From the start, treat these as always-on
 
-- **test-driven-development**, coverage debt is cheapest to avoid at zero.
-- **git-workflow-and-versioning**, atomic commits and ~100-line changes are habits, not retrofits.
-- **security-and-hardening**, auth, input validation, and secrets handling are structural; bolting them on later is a migration project.
-- **documentation-and-adrs**, the first architectural decisions are exactly the ones nobody will remember the _why_ of in two years. An ADR now prevents the brownfield archaeology described in Path B.
+- **i3-test-driven-development**, coverage debt is cheapest to avoid at zero.
+- **i3-git-workflow-and-versioning**, atomic commits and ~100-line changes are habits, not retrofits.
+- **i3-security-and-hardening**, auth, input validation, and secrets handling are structural; bolting them on later is a migration project.
+- **i3-documentation-and-adrs**, the first architectural decisions are exactly the ones nobody will remember the _why_ of in two years. An ADR now prevents the brownfield archaeology described in Path B.
 
 ### Add as the project grows
 
 | When                                | Load                                                          |
 | ----------------------------------- | ------------------------------------------------------------- |
-| First public API or module boundary | `api-and-interface-design`                                    |
-| First UI work                       | `frontend-ui-engineering` (+ `browser-testing-with-devtools`) |
-| First CI pipeline                   | `ci-cd-and-automation`                                        |
-| First production deploy             | `observability-and-instrumentation`, `shipping-and-launch`    |
-| Performance requirements appear     | `performance-optimization`                                    |
+| First public API or module boundary | `i3-api-and-interface-design`                                    |
+| First UI work                       | `i3-frontend-ui-engineering` (+ `i3-browser-testing-with-devtools`) |
+| First CI pipeline                   | `i3-ci-cd-and-automation`                                        |
+| First production deploy             | `i3-observability-and-instrumentation`, `i3-shipping-and-launch`    |
+| Performance requirements appear     | `i3-performance-optimization`                                    |
 
 ### Greenfield anti-patterns
 
-- **Skipping `/spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase.
-- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `using-agent-skills` route, but not both.
+- **Skipping `/i3-spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase.
+- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `i3-using-agent-skills` route, but not both.
 - **Deferring observability until "there's something to observe."** Instrument as you build, retrofitting structured logging is a Path B problem you're choosing to create.
 
 ---
@@ -78,38 +78,38 @@ In an established codebase, the risk profile inverts: the danger isn't building
 
 Goal: the agent understands the codebase before it modifies anything.
 
-1. **`context-engineering` first.** Write the project rules file describing the real conventions, the ones in the code, not the ones in the wiki. Include build/test commands, directory meaning, known landmines ("don't touch `legacy/billing`, it has no tests and three known workarounds").
-2. **`code-review-and-quality` on incoming changes.** Reviewing is zero-risk and immediately valuable: the five-axis review and its severity labels (which separate what blocks a merge, Critical and Required, from what doesn't) work on any PR regardless of the codebase's state.
-3. **`debugging-and-error-recovery` for the bugs you were fixing anyway.** The five-step triage (reproduce → localize → reduce → fix → guard) shines in unfamiliar code, and the "guard" step starts building the regression suite you don't have.
-4. **`doubt-driven-development` as a safety net.** Legacy code is exactly the "unfamiliar code, high cost of being wrong" scenario this skill targets. Adversarial fresh-context review of the agent's claims about how the legacy system works catches confident hallucinations before they become commits.
+1. **`i3-context-engineering` first.** Write the project rules file describing the real conventions, the ones in the code, not the ones in the wiki. Include build/test commands, directory meaning, known landmines ("don't touch `legacy/billing`, it has no tests and three known workarounds").
+2. **`i3-code-review-and-quality` on incoming changes.** Reviewing is zero-risk and immediately valuable: the five-axis review and its severity labels (which separate what blocks a merge, Critical and Required, from what doesn't) work on any PR regardless of the codebase's state.
+3. **`i3-debugging-and-error-recovery` for the bugs you were fixing anyway.** The five-step triage (reproduce → localize → reduce → fix → guard) shines in unfamiliar code, and the "guard" step starts building the regression suite you don't have.
+4. **`i3-doubt-driven-development` as a safety net.** Legacy code is exactly the "unfamiliar code, high cost of being wrong" scenario this skill targets. Adversarial fresh-context review of the agent's claims about how the legacy system works catches confident hallucinations before they become commits.
 
 ### Phase 2 | Tests before change
 
 Goal: every area the agent will touch gets a safety net first.
 
-- **`test-driven-development`, applied selectively.** Don't aim for global coverage; aim for coverage _where change is planned_. For untested legacy behavior, write characterization tests, tests that pin down what the code currently does, right or wrong, before any modification. The Beyonce Rule applies: if the agent liked a behavior enough to depend on it, it should have put a test on it.
-- **`code-simplification` on the worst hotspots.** Chesterton's Fence is the operative principle: the skill forces the agent to understand _why_ code exists before removing it. Behavior-preserving simplification plus characterization tests is the lowest-risk way to make legacy code changeable.
-- **`git-workflow-and-versioning` everywhere.** Small atomic commits matter _more_ in brownfield: when a change to old code breaks something subtle, a ~100-line commit is bisectable; a 2,000-line "modernization" commit is not.
+- **`i3-test-driven-development`, applied selectively.** Don't aim for global coverage; aim for coverage _where change is planned_. For untested legacy behavior, write characterization tests, tests that pin down what the code currently does, right or wrong, before any modification. The Beyonce Rule applies: if the agent liked a behavior enough to depend on it, it should have put a test on it.
+- **`i3-code-simplification` on the worst hotspots.** Chesterton's Fence is the operative principle: the skill forces the agent to understand _why_ code exists before removing it. Behavior-preserving simplification plus characterization tests is the lowest-risk way to make legacy code changeable.
+- **`i3-git-workflow-and-versioning` everywhere.** Small atomic commits matter _more_ in brownfield: when a change to old code breaks something subtle, a ~100-line commit is bisectable; a 2,000-line "modernization" commit is not.
 
 ### Phase 3 | New work runs the full lifecycle
 
 Goal: two-speed adoption, legacy code stays under the Phase 1–2 regime; **new features get the greenfield treatment**.
 
-- New feature in the old codebase? `/spec → /plan → /build → /review`. The spec's boundaries section is where you declare what legacy surface the feature may and may not touch.
-- **`api-and-interface-design` at the seams.** When new code must talk to old code, design the boundary contract-first. Hyrum's Law is not theoretical in a years-old codebase, someone depends on every observable behavior, including the bugs.
-- **`security-and-hardening` as an audit, then a gate.** Run it once across the existing attack surface (auth, input handling, dependencies, the dependency audit alone usually pays for the exercise), file what you find, then enforce it on new changes.
+- New feature in the old codebase? `/i3-spec → /i3-plan → /i3-build → /i3-review`. The spec's boundaries section is where you declare what legacy surface the feature may and may not touch.
+- **`i3-api-and-interface-design` at the seams.** When new code must talk to old code, design the boundary contract-first. Hyrum's Law is not theoretical in a years-old codebase, someone depends on every observable behavior, including the bugs.
+- **`i3-security-and-hardening` as an audit, then a gate.** Run it once across the existing attack surface (auth, input handling, dependencies, the dependency audit alone usually pays for the exercise), file what you find, then enforce it on new changes.
 
 ### Phase 4 | Pay down, deprecate, observe
 
-- **`deprecation-and-migration`** is the brownfield skill par excellence: code-as-liability, compulsory vs. advisory deprecation, and zombie-code removal give you a disciplined way to shrink the legacy surface instead of just wrapping it.
-- **`observability-and-instrumentation`** retrofitted along the paths you actually debug: structured logging and RED metrics on the top incident sources first.
-- **`performance-optimization`** when regressions matter, its measure-first rule prevents the classic legacy trap of optimizing code that was never the bottleneck.
+- **`i3-deprecation-and-migration`** is the brownfield skill par excellence: code-as-liability, compulsory vs. advisory deprecation, and zombie-code removal give you a disciplined way to shrink the legacy surface instead of just wrapping it.
+- **`i3-observability-and-instrumentation`** retrofitted along the paths you actually debug: structured logging and RED metrics on the top incident sources first.
+- **`i3-performance-optimization`** when regressions matter, its measure-first rule prevents the classic legacy trap of optimizing code that was never the bottleneck.
 
 ### Brownfield anti-patterns
 
 - **"Big bang" adoption.** Loading the full lifecycle onto a legacy codebase on day one produces specs for code that already exists and refactors without safety nets. Sequence it.
 - **Letting the agent refactor untested code.** No characterization tests, no refactor. This is the single most expensive shortcut in brownfield adoption.
-- **Skipping `context-engineering` because "the code is the documentation."** The agent will infer conventions from the worst file it happens to read. Tell it the real ones.
+- **Skipping `i3-context-engineering` because "the code is the documentation."** The agent will infer conventions from the worst file it happens to read. Tell it the real ones.
 - **Treating the legacy system's behavior as wrong by default.** Chesterton's Fence: the weird retry loop may be load-bearing. Understand, then change.
 - **Ratcheting nothing.** Adoption should make quality monotonically better: each phase adds a gate that doesn't come back off. If a month in you can't name what's now enforced that wasn't before, the rollout has stalled.
 
@@ -117,11 +117,11 @@ Goal: two-speed adoption, legacy code stays under the Phase 1–2 regime; **new
 
 ## The two paths converge
 
-Both end in the same steady state: `/spec → /plan → /build → /review → /ship` for new work, always-on TDD and git discipline, review gates before merge, and skills loaded by phase rather than in bulk. Greenfield gets there in days; brownfield gets there in a quarter, and the difference is exactly the safety nets (context, characterization tests, boundaries) that the old codebase never had.
+Both end in the same steady state: `/i3-spec → /i3-plan → /i3-build → /i3-review → /i3-ship` for new work, always-on TDD and git discipline, review gates before merge, and skills loaded by phase rather than in bulk. Greenfield gets there in days; brownfield gets there in a quarter, and the difference is exactly the safety nets (context, characterization tests, boundaries) that the old codebase never had.
 
 |                        | Greenfield                     | Brownfield                               |
 | ---------------------- | ------------------------------ | ---------------------------------------- |
-| First skill loaded     | Native router, or `using-agent-skills` + `/spec` | `context-engineering`                    |
+| First skill loaded     | Native router, or `i3-using-agent-skills` + `/i3-spec` | `i3-context-engineering`                    |
 | First value delivered  | Spec'd, tested first feature   | Zero-risk reviews and safer bug fixes    |
 | TDD posture            | Universal from commit one      | Selective: tests where change is planned |
 | Refactoring rule       | Rare (little to refactor)      | Characterization tests first, always     |