@givolt/i3-composer-agent 1.0.1 → 2.0.0

package/rebrand/PREFIX-SPEC.md

@@ -0,0 +1,16 @@
+# i3 command and Skill identifiers
+
+The user approved applying the existing i3 naming convention on 2026-10-07.
+This supersedes the earlier preservation of unprefixed distribution identifiers.
+
+- `agent/source` keeps upstream files and identifiers unchanged. Changes live in `rebrand/`.
+- Branded Skill directories and YAML `name` fields use `i3-<upstream-id>`.
+- All three command directories use `i3-<upstream-stem>` filenames, retaining the existing `plan`/`planning` host mapping.
+- Native commands include `/i3-spec` and `/i3-build`; plugin commands include `/i3-composer-agent:i3-spec`.
+- Rewrite local references, hooks, routing fixtures and documentation together. Preserve external upstream links, attribution, and Skill frontmatter other than `name`.
+- Retain helper script filenames and executable permissions when their containing Skill directory is renamed.
+- Replay and validation accept only a complete reviewed source catalog or its mapped branded catalog. Replaying branded output is idempotent.
+- Installation migrates only legacy Skill/command paths listed in this package's prior installation manifest. Back up retired paths and support rollback. Unowned commands and skills remain in place.
+- Verify source tests, branded validation/tests, routing/hooks, packed CLI installation, migration, rollback and the actual project installation. IDE discovery and model execution require separate host verification.
+
+Release 2.0.0 applies this breaking identifier change. The user authorized publication on 2026-10-07. Publish and verify the reviewed new-version tarball; previously published tarballs remain immutable. The upstream baseline stays at 0.6.12.

package/rebrand/UNIFICATION-SPEC.md

@@ -8,7 +8,7 @@
 - `agent/source` 保留上游原始名称和源码，在 `rebrand/` 保存本项目的分发工具与转换规则。
 - 候选从 `agent/source` 创建，在候选中重放；`main` 保存经过验证的品牌快照。
 - GSD 仓库只读，不使用它的源码、分支或安装产物。
-- Skill ID、流程命令内容、Persona、参考文件和 MIT 来源署名保持既有契约。
+- 源码保留上游 Skill ID；品牌版按 PREFIX-SPEC.md 使用 i3- 前缀。流程内容、Persona、参考文件和 MIT 来源署名保持。
 - 本次完善源码同步和品牌重放；交互安装向导、Codex 命令适配及新的 npm 发布独立处理。
 
 ## 实现与命令
@@ -24,7 +24,7 @@
 1. 从干净上游源码及本项目规则能生成完整品牌包，重复重放不产生差异。
 2. 在 `agent/source` 上执行写入式重放必须失败且不修改源码。
 3. 记录上游新增 Skill/Command 后能生成相应清单和说明；删失或改写已记录 Skill ID 时校验失败。
-4. 上游的 25 个 Skill frontmatter、24 个非元 Skill、4 个 Persona、7 个共享参考保持原始内容；9 个流程只变品牌命名空间。
+4. 品牌版的 Skill name、目录和命令文件名统一使用 i3-；frontmatter 的其他字段、Persona、共享参考和流程契约保持。
 5. 本地候选通过完整测试，并从打包结果运行 CLI 与校验。
 6. 独立品牌仓库中的源/发行分支及远程关系正确；首次发布标签保持原来的 0.6.12 提交。
 

package/rebrand/VALIDATION.md

@@ -11,8 +11,8 @@
 
 ## 品牌候选
 
-- Skill、命令、Persona、references 和全部已记录普通运行文件与上游目录一致。
-- Skill frontmatter 的名称和字段内容保持；换行差异不作为字段变更。
+- Skill 和命令路径按 PREFIX-SPEC.md 映射为 i3- 名称；其余已记录运行文件保持目录一致。
+- Skill frontmatter 只改 name；逆向映射 name 后比较上游哈希，换行差异不作为字段变更。
 - 新增上游 Skill/Command 能进入目录、品牌说明和打包；缺失内容会失败。
 - 文字补丁失去匹配时必须失败，不能静默遗漏。
 - 重放后 --check 成功，完整 Node、路由与 hook 检查通过。

package/rebrand/VERSIONING.md

@@ -4,7 +4,7 @@
 
 | 信息 | 权威来源 | 当前发行值 |
 | --- | --- | --- |
-| i3 发行版本 | brand.json 的 releaseVersion | 1.0.1 |
+| i3 发行版本 | brand.json 的 releaseVersion | 2.0.0 |
 | 上游版本 | upstream.json 的 upstreamVersion | 0.6.12 |
 | 上游提交 | upstream.json 的 upstreamCommit | 1401c8b8030e023baeebb31781a6653fe8e93026 |
 
@@ -20,14 +20,16 @@ package.json 的 i3ComposerAgent 来源字段。package.template.json 不保存
 README、CLI 帮助和准备完成提示显示：
 
 ```text
-i3 Composer Agent v1.0.1
+i3 Composer Agent v2.0.0
 Based on agent-skills v0.6.12
 ```
 
-在上述例子中，--version 输出 1.0.1，保留脚本使用的单一版本格式。--dry-run 的 JSON
+在上述例子中，--version 输出 2.0.0，保留脚本使用的单一版本格式。--dry-run 的 JSON
 分别提供 version、upstreamVersion、upstreamCommit。
 
 已经发布的 @givolt/i3-composer-agent@0.6.12 及其 Git 标签作为历史记录保留。
 之前的 0.6.13 是未发布候选，新的独立版本候选替代它。
 1.0.0 已发布。1.0.1 用于修复安装向导遗漏，版本与发布已由用户确认。
+2.0.0 为命令和 Skill 的 i3- 前缀变更；使用者需要调整调用名，因此递增 major。
+用户于 2026-10-07 要求修改并授权发布；上游版本和提交保持不变。
 源码与打包验证不代表 npm 发布；发布仍按 MAINTENANCE.md 单独执行。

package/rebrand/apply.cjs

@@ -5,6 +5,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { validateCatalog, frontmatter } = require('./catalog.cjs');
+const { skillId, runtimePath, rewriteReferences } = require('./identifiers.cjs');
 const brand = require('./brand.json');
 const upstream = require('./upstream.json');
 const root = path.resolve(__dirname, '..');
@@ -20,7 +21,24 @@ if (mode === '--apply') {
     process.exit(1);
   }
 }
-const inventory = validateCatalog(root, upstream);
+const branded = fs.existsSync(path.join(root, 'skills', skillId(upstream.skills[0])));
+validateCatalog(root, upstream, { branded });
+const inventory = upstream;
+const renames = new Map();
+if (!branded) {
+  for (const id of inventory.skills) renames.set(`skills/${id}`, `skills/${skillId(id)}`);
+  for (const file of inventory.runtimeFiles.filter(file => /^(?:\.claude\/commands|\.gemini\/commands|commands)\/[^/]+\.(?:md|toml)$/.test(file))) renames.set(file, runtimePath(file));
+  for (const target of renames.values()) if (fs.existsSync(path.join(root, target))) throw new Error(`Brand destination already exists: ${target}`);
+}
+for (const id of inventory.skills) {
+  for (const file of [`evals/cases/${id}.json`, `evals/fixtures/${id}`]) {
+    if (fs.existsSync(path.join(root, file))) {
+      const target = runtimePath(file);
+      if (fs.existsSync(path.join(root, target))) throw new Error(`Brand destination already exists: ${target}`);
+      renames.set(file, target);
+    }
+  }
+}
 const packageFile = path.join(root, 'package.json');
 if (fs.existsSync(packageFile) && JSON.parse(fs.readFileSync(packageFile, 'utf8')).name !== brand.npmName) {
   console.error('Upstream package.json now exists; explicitly adapt the distribution overlay before replaying.');
@@ -30,6 +48,7 @@ const changes = new Map();
 function update(relative, content) {
   const file = path.join(root, relative);
   if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) changes.set(relative, content);
+  else changes.delete(relative);
 }
 function transform(content, relative) {
   const head = /^skills\/[^/]+\/SKILL\.md$/.test(relative) ? frontmatter(content) : '';
@@ -43,7 +62,7 @@ function transform(content, relative) {
     .replaceAll('addy-agent-skills', brand.name)
     .replaceAll('agent-skills@addy-agent-skills', `${brand.name}@${brand.name}`)
     .replaceAll('agent-skills@agent-skills', `${brand.name}@${brand.name}`)
-    .replaceAll('agent-skills:', `${brand.name}:`)
+    .replace(/(?<![\w-])agent-skills:/g, `${brand.name}:`)
     .replaceAll('/path/to/agent-skills', `/path/to/${brand.name}`)
     .replaceAll('./agent-skills', `./${brand.name}`)
     .replace(/(?<![\w/.-])agent-skills(?![\w-])/g, brand.name)
@@ -74,7 +93,9 @@ function transform(content, relative) {
       .replace(/\[[^\]]+\]\(https:\/\/github\.com\/addyosmani\/agent-skills\/issues\/(\d+)\)/g,
         (_, issue) => `[upstream agent-skills #${issue}](https://github.com/addyosmani/agent-skills/issues/${issue})`);
   }
-  return head + result;
+  const name = head.match(/^name:\s*([^\s]+)\s*$/m)?.[1];
+  const brandedHead = name && inventory.skills.includes(name) ? head.replace(/^name:.*$/m, `name: ${skillId(name)}`) : head;
+  return brandedHead + rewriteReferences(result, false, inventory, !relative.startsWith('scripts/'));
 }
 const skipDirectories = new Set(['.git', 'node_modules', 'rebrand', 'dist', 'tests', 'bin']);
 const skipFiles = new Set(['LICENSE', 'NOTICE.md', 'CHANGELOG.md', 'package.json', 'README.md', 'evals/README.md', 'evals/skill-impact.md', 'docs/comparison.md', 'scripts/validate-brand.cjs', 'scripts/lib/skill-lint.js', 'scripts/lib/skill-lint-test.js']);
@@ -83,7 +104,7 @@ function walk(directory, prefix = '') {
     const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
       if (!skipDirectories.has(entry.name) && !relative.startsWith('evals/results')) walk(path.join(directory, entry.name), relative);
-    } else if (entry.isFile() && !skipFiles.has(relative) && /\.(?:md|js|cjs|sh|toml|yml)$/.test(entry.name)) {
+    } else if (entry.isFile() && !skipFiles.has(relative) && /\.(?:md|js|cjs|sh|toml|yml|json|patch|diff)$/.test(entry.name)) {
       const original = fs.readFileSync(path.join(root, relative), 'utf8');
       update(relative, transform(original, relative));
     }
@@ -116,7 +137,7 @@ for (const relative of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plu
     manifest.interface.developerName = brand.maintainer;
     manifest.interface.shortDescription = 'Engineering workflow skills';
     manifest.interface.longDescription = `${brand.displayName} packages ${inventory.skills.length} engineering skills from Addy Osmani's Agent Skills, covering requirements, planning, implementation, testing, review, and shipping.`;
-    manifest.interface.defaultPrompt = manifest.interface.defaultPrompt.map(prompt => prompt.replaceAll('Agent Skills', brand.displayName));
+    manifest.interface.defaultPrompt = manifest.interface.defaultPrompt.map(prompt => rewriteReferences(prompt.replaceAll('Agent Skills', brand.displayName)));
   }
   update(relative, JSON.stringify(manifest, null, 2) + '\n');
 }
@@ -164,7 +185,8 @@ pkg.i3ComposerAgent.upstreamRepository = brand.upstream;
 update('package.json', JSON.stringify(pkg, null, 2) + '\n');
 update('NOTICE.md', fs.readFileSync(path.join(__dirname, 'NOTICE.md'), 'utf8'));
 function description(relative) {
-  const head = fs.readFileSync(path.join(root, relative), 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] || '';
+  const file = path.join(root, branded ? runtimePath(relative) : relative);
+  const head = fs.readFileSync(file, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] || '';
   return (head.match(/^description:\s*(.*)$/m)?.[1] || '').replace(/^["']|["']$/g, '').replaceAll('|', '\\|');
 }
 const values = {
@@ -173,8 +195,8 @@ const values = {
   SKILL_COUNT: inventory.skills.length,
   COMMAND_COUNT: inventory.commands.length,
   PERSONA_COUNT: inventory.personas.length,
-  SKILL_TABLE: inventory.skills.map(id => `| [${id}](skills/${id}/SKILL.md) | ${description(`skills/${id}/SKILL.md`)} |`).join('\n'),
-  COMMAND_TABLE: inventory.commands.map(id => `| /${brand.name}:${id} | ${description(`.claude/commands/${id}.md`)} |`).join('\n'),
+  SKILL_TABLE: inventory.skills.map(id => `| [${skillId(id)}](skills/${skillId(id)}/SKILL.md) | ${description(`skills/${id}/SKILL.md`)} |`).join('\n'),
+  COMMAND_TABLE: inventory.commands.map(id => `| /${brand.name}:${skillId(id)} | ${description(`.claude/commands/${id}.md`)} |`).join('\n'),
 };
 for (const [relative, template] of [
   ['README.md', 'README.md'], ['docs/codex-setup.md', 'codex-setup.md'], ['docs/codebuddy-setup.md', 'codebuddy-setup.md'],
@@ -190,5 +212,6 @@ if (mode === '--apply') for (const [relative, content] of changes) {
   fs.writeFileSync(path.join(root, relative), content);
 }
 if (mode === '--apply') fs.chmodSync(path.join(root, 'bin/i3-composer-agent.cjs'), 0o755);
-console.log(JSON.stringify({ mode, changedFiles: [...changes.keys()] }, null, 2));
-if (mode === '--check' && changes.size) process.exitCode = 1;
+if (mode === '--apply') for (const [source, target] of renames) fs.renameSync(path.join(root, source), path.join(root, target));
+console.log(JSON.stringify({ mode, changedFiles: [...changes.keys()], renamedPaths: Object.fromEntries(renames) }, null, 2));
+if (mode === '--check' && (changes.size || renames.size)) process.exitCode = 1;

package/rebrand/brand.json

@@ -9,5 +9,5 @@
   "repository": "https://github.com/49780522/i3-composer-agent",
   "sourceBranch": "agent/source",
   "releaseBranch": "main",
-  "releaseVersion": "1.0.1"
+  "releaseVersion": "2.0.0"
 }

package/rebrand/catalog.cjs

@@ -4,6 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const assert = require('node:assert/strict');
+const { skillId, runtimePath } = require('./identifiers.cjs');
 const runtimeRoots = ['skills', 'references', 'agents', 'commands', '.claude/commands', '.gemini/commands', 'hooks', '.claude-plugin', '.codex-plugin', '.agents/plugins'];
 const runtimeFiles = ['plugin.json', 'LICENSE'];
 
@@ -46,10 +47,23 @@ function catalog(root) {
   for (const name of runtimeFiles) if (fs.existsSync(path.join(root, name))) files.push(name);
   return describe(files, file => fs.readFileSync(path.join(root, file), 'utf8'));
 }
-function validateCatalog(root, expected) {
+function validateCatalog(root, expected, { branded = false } = {}) {
   const actual = catalog(root);
+  const mapped = branded ? {
+    ...expected,
+    skills: expected.skills.map(skillId),
+    commands: expected.commands.map(skillId),
+    runtimeFiles: expected.runtimeFiles.map(file => runtimePath(file, false, expected)).sort(),
+    skillFrontmatter: Object.fromEntries(expected.skills.map(id => {
+      const name = skillId(id);
+      const head = frontmatter(fs.readFileSync(path.join(root, 'skills', name, 'SKILL.md'), 'utf8'));
+      const normalized = head.replace(new RegExp(`^name:.*$`, 'm'), `name: ${id}`).replace(/\r\n/g, '\n');
+      actual.skillFrontmatter[name] = crypto.createHash('sha256').update(normalized).digest('hex');
+      return [name, expected.skillFrontmatter[id]];
+    })),
+  } : expected;
   for (const field of ['skills', 'commands', 'personas', 'references', 'runtimeFiles', 'skillFrontmatter']) {
-    assert.deepEqual(actual[field], expected[field], `upstream preservation failed: ${field}`);
+    assert.deepEqual(actual[field], mapped[field], `upstream preservation failed: ${field}`);
   }
   return actual;
 }

package/rebrand/fork-patches.json

@@ -1,4 +1,19 @@
 [
+  {
+    "file": "scripts/lib/skill-lint.js",
+    "from": "const SECTION_EXEMPT_SKILLS = {",
+    "to": "const SECTION_EXEMPT_SKILLS = {\n  'i3-using-agent-skills': 'Branded alias of the reviewed upstream meta-skill.',\n  'i3-idea-refine': 'Branded alias of the reviewed upstream legacy structure.',"
+  },
+  {
+    "file": "scripts/validate-artifact-paths.js",
+    "from": "function findViolations(relPath) {",
+    "to": "GUARDED_FILES.push(...GUARDED_FILES.filter(relative => /(?:^|\\/)commands\\//.test(relative)).map(relative => relative.replace(/(commands\\/)([^/]+)(\\.md|\\.toml)$/, '$1i3-$2$3')));\n\nfunction findViolations(relPath) {"
+  },
+  {
+    "file": "scripts/validate-commands.js",
+    "from": "  plan: 'planning',",
+    "to": "  plan: 'planning',\n  'i3-plan': 'i3-planning',"
+  },
   {
     "file": "scripts/validate-versions.js",
     "from": "const manifestPaths = [\n  \"plugin.json\",",

package/rebrand/identifiers.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const upstream = require('./upstream.json');
+const prefix = 'i3-';
+const skillId = id => prefix + id;
+const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function runtimePath(relative, reverse = false, inventory = upstream) {
+  const skills = new Map(inventory.skills.map(id => reverse ? [skillId(id), id] : [id, skillId(id)]));
+  relative = relative.replace(/^(skills|evals\/fixtures)\/([^/]+)(?=\/|$)/, (match, folder, id) => skills.has(id) ? `${folder}/${skills.get(id)}` : match);
+  relative = relative.replace(/^evals\/cases\/([^/]+)\.json$/, (match, id) => skills.has(id) ? `evals/cases/${skills.get(id)}.json` : match);
+  const commands = inventory.runtimeFiles.filter(file => /^(?:\.claude\/commands|\.gemini\/commands|commands)\/[^/]+\.(?:md|toml)$/.test(file));
+  for (const file of commands) {
+    const branded = file.replace(/([^/]+)\.(md|toml)$/, `${prefix}$1.$2`);
+    if (relative === (reverse ? branded : file)) return reverse ? file : branded;
+  }
+  return relative;
+}
+
+function rewriteReferences(content, reverse = false, inventory = upstream, commandReferences = true) {
+  const skills = new Map(inventory.skills.map(id => reverse ? [skillId(id), id] : [id, skillId(id)]));
+  const names = [...new Set([...inventory.commands, ...inventory.runtimeFiles.filter(file => /commands\/[^/]+\.toml$/.test(file)).map(file => file.split('/').at(-1).slice(0, -5))])];
+  const commands = new Map(names.map(id => reverse ? [prefix + id, id] : [id, prefix + id]));
+  const skillPattern = new RegExp(`(?<![\\w-])(${[...skills.keys()].map(escape).join('|')})(?![\\w-]|\\.(?:sh|py|js|cjs)\\b)`, 'g');
+  const commandPattern = [...commands.keys()].map(escape).join('|');
+  const slash = new RegExp(`(?<![\\w/.-])/(${commandPattern})(?![\\w-])`, 'g');
+  const filenames = new RegExp(`(commands/)(${commandPattern})\\.(md|toml)\\b`, 'g');
+  const namespace = new RegExp(`((?:agent-skills|i3-composer-agent|\\$\\{name\\}):)(${commandPattern})(?![\\w-])`, 'g');
+  // External links refer to the upstream repository's original paths.
+  return content.split(/(https?:\/\/[^\s)'"<>`]+)/g).map(part => {
+    if (/^https?:\/\//.test(part)) return part;
+    part = part.replace(skillPattern, match => skills.get(match));
+    if (!commandReferences) return part;
+    return part
+    .replace(slash, (_, id) => '/' + commands.get(id))
+    .replace(filenames, (_, folder, id, extension) => `${folder}${commands.get(id)}.${extension}`)
+    .replace(namespace, (_, scope, id) => scope + commands.get(id));
+  }).join('');
+}
+
+module.exports = { prefix, skillId, runtimePath, rewriteReferences };

package/rebrand/overlay/CHANGELOG.md

@@ -1,5 +1,22 @@
 # i3 Composer Agent changes
 
+## 2.0.0 — 2026-10-07
+
+Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
+
+### Changed
+
+- Commands and Skill IDs use the `i3-` prefix, such as `/i3-spec` and `$i3-spec-driven-development`.
+- Native upgrades back up and retire this package's manifest-owned unprefixed paths. Unowned entries remain in place; failed migrations roll back.
+- Local command references, hooks, routing fixtures and setup documentation follow the renamed identifiers.
+
+### Migration
+
+- Replace `/spec`, `/plan`, `/build` and other lifecycle calls with `/i3-spec`, `/i3-plan`, `/i3-build` and their prefixed equivalents. Plugin calls use `/i3-composer-agent:i3-<command>`.
+- Replace Skill calls such as `$spec-driven-development` with `$i3-spec-driven-development`.
+- Upgrade with `npx @givolt/i3-composer-agent@2.0.0 --codebuddy`, confirm replacement, then reload the host. The installer backs up manifest-owned legacy entries before retiring them.
+- Keep using the pinned 1.0.1 package if a consuming workflow needs the old identifiers. Existing published versions remain available.
+
 ## 1.0.1 — 2026-10-07
 
 Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.

package/rebrand/overlay/bin/i3-composer-agent.cjs

@@ -127,7 +127,7 @@ function prepare() {
   } else {
     console.log(`/plugin marketplace add ${quote(directory)}`);
     console.log(`/plugin install ${selector}`);
-    console.log(`Use /${name}:spec, /${name}:plan, /${name}:build, and /${name}:ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
+    console.log(`Use /${name}:i3-spec, /${name}:i3-plan, /${name}:i3-build, and /${name}:i3-ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
   }
 }
 async function main() {
@@ -180,7 +180,7 @@ async function main() {
   console.log(identity);
   for (const target of plan.targets) {
     console.log(`Installed ${target.agents.join(', ')} skills at ${target.skillsDirectory}`);
-    if (target.commandsDirectory) console.log(`Commands: /spec, /plan, /build, /ship (all ${fs.readdirSync(target.commandsDirectory).filter(file => file.endsWith('.md')).length} workflows) at ${target.commandsDirectory}`);
+    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.');

package/rebrand/overlay/bin/install.cjs

@@ -5,6 +5,7 @@ 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 root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
 const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
@@ -82,7 +83,19 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     }
     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 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' });
+        }
+      }
+    }
+    assets.push({ target, destination: destination(manifestFile), kind: 'manifest' });
     for (const asset of assets.slice(start)) {
       asset.base = target.base;
       asset.codebuddyCommand = asset.kind === 'command' && target.agents.includes('codebuddy');
@@ -120,9 +133,10 @@ 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, 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');
       } else {
         fs.cpSync(asset.source, asset.staged, { recursive: true, filter: file => {
           if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Package contains a symlink: ${file}`);
@@ -143,8 +157,10 @@ 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);
   } catch (error) {

package/rebrand/overlay/scripts/validate-brand.cjs

@@ -9,7 +9,7 @@ const brand = require('../rebrand/brand.json');
 const pkg = require('../package.json');
 const upstream = require('../rebrand/upstream.json');
 const { validateCatalog } = require('../rebrand/catalog.cjs');
-validateCatalog(root, upstream);
+validateCatalog(root, upstream, { branded: true });
 function json(relative) { return JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8')); }
 assert.equal(pkg.name, brand.npmName);
 assert.equal(pkg.version, brand.releaseVersion);
@@ -31,13 +31,13 @@ for (const relative of ['.claude-plugin/marketplace.json', '.agents/plugins/mark
 assert.ok(json('.codex-plugin/plugin.json').interface.shortDescription.length <= 30);
 const skills = fs.readdirSync(path.join(root, 'skills')).filter(name => fs.existsSync(path.join(root, 'skills', name, 'SKILL.md')));
 assert.equal(skills.length, upstream.skills.length, 'brand conversion must preserve the reviewed upstream skills');
-assert.ok(skills.includes('using-agent-skills'), 'meta-skill ID must remain stable');
+assert.ok(skills.includes('i3-using-agent-skills'), 'meta-skill ID must use the branded prefix');
 const commands = fs.readdirSync(path.join(root, '.claude/commands')).filter(name => name.endsWith('.md'));
 assert.equal(commands.length, upstream.commands.length, 'brand conversion must preserve the reviewed upstream commands');
 for (const command of commands) {
   const body = fs.readFileSync(path.join(root, '.claude/commands', command), 'utf8');
   assert.ok(!body.includes('agent-skills:'), `${command}: stale plugin namespace`);
-  for (const match of body.matchAll(/i3-composer-agent:([a-z-]+)/g)) assert.ok(skills.includes(match[1]), `${command}: unknown skill ${match[1]}`);
+  for (const match of body.matchAll(/(?<!\/)i3-composer-agent:([a-z0-9-]+)/g)) assert.ok(skills.includes(match[1]), `${command}: unknown skill ${match[1]}`);
 }
 for (const relative of pkg.i3ComposerAgent.pluginFiles) assert.ok(fs.existsSync(path.join(root, relative)), `bundle is missing ${relative}`);
 assert.match(fs.readFileSync(path.join(root, 'LICENSE'), 'utf8'), /Copyright \(c\) 2025 Addy Osmani/);

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

@@ -25,10 +25,10 @@ test('native CodeBuddy installation includes short commands, personas and usable
   assert.equal(fs.readdirSync(path.join(base, 'skills')).length, upstream.skills.length);
   assert.equal(fs.readdirSync(path.join(base, 'commands')).length, upstream.commands.length);
   assert.equal(fs.readdirSync(path.join(base, 'agents')).length, upstream.personas.length);
-  const command = fs.readFileSync(path.join(base, 'commands/spec.md'), 'utf8');
-  assert.match(command, /Invoke the spec-driven-development skill/);
+  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/ship.md'), 'utf8');
+  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')));
@@ -36,7 +36,7 @@ test('native CodeBuddy installation includes short commands, personas and usable
   assert.match(fs.readFileSync(path.join(base, 'i3-composer-agent-NOTICE.md'), 'utf8'), /Addy Osmani/);
   assert.equal(fs.existsSync(path.join(directory, 'AGENTS.md')), false);
   assert.equal(fs.existsSync(path.join(directory, 'i3-composer-agent')), false);
-  assert.match(result.stdout, /\/spec/);
+  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);
@@ -80,16 +80,64 @@ test('all copied Markdown reference links and stable skill frontmatter remain va
     }
   }
   visit(path.join(base, 'skills'));
-  for (const id of upstream.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/spec.md'), 'my custom command');
+  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);
@@ -98,7 +146,7 @@ test('existing assets are protected; confirmed replacement backs them up and pre
   assert.equal(result.status, 0, result.stderr);
   const backups = fs.readdirSync(base).filter(file => file.startsWith('.i3-composer-agent-backup-'));
   assert.equal(backups.length, 1);
-  assert.equal(fs.readFileSync(path.join(base, backups[0], 'commands/spec.md'), 'utf8'), 'my custom command');
+  assert.equal(fs.readFileSync(path.join(base, 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);
 });
@@ -133,7 +181,7 @@ test('the pinned tool catalog plans all project choices and rejects unsupported
 test('failed installation restores prior assets and removes all newly written files', t => {
   const directory = workspace(t);
   const { planInstallation, executeInstallation } = require('../bin/install.cjs');
-  const prior = path.join(directory, '.codebuddy/skills/api-and-interface-design');
+  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 });
@@ -146,7 +194,7 @@ test('failed installation restores prior assets and removes all newly written fi
   try { assert.throws(() => executeInstallation(plan, { force: true }), /simulated disk failure/); }
   finally { fs.renameSync = realRename; }
   assert.equal(fs.readFileSync(path.join(prior, 'custom.md'), 'utf8'), 'prior skill content');
-  assert.deepEqual(fs.readdirSync(path.dirname(prior)), ['api-and-interface-design']);
+  assert.deepEqual(fs.readdirSync(path.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);
 });
@@ -157,14 +205,14 @@ test('replacing a skill symlink backs up the link and leaves its external source
   fs.mkdirSync(external);
   fs.writeFileSync(path.join(external, 'custom.md'), 'external source');
   fs.mkdirSync(skills, { recursive: true });
-  fs.symlinkSync(external, path.join(skills, 'spec-driven-development'), 'dir');
+  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, 'spec-driven-development')).isSymbolicLink(), false);
+  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/spec-driven-development')).isSymbolicLink(), true);
+  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);

package/rebrand/templates/README.md

@@ -9,7 +9,7 @@ Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osma
 (MIT). See [NOTICE.md](NOTICE.md) for attribution.
 
 The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
-`i3-composer-agent`. Skill IDs retain their upstream names.
+`i3-composer-agent`. Commands and Skill IDs use the `i3-` prefix.
 
 ## Install with the wizard
 
@@ -49,6 +49,12 @@ under each tool configuration root. Unrelated settings are left in place.
 `npx -y` accepts npm's package download prompt; the package's own `--yes` flag
 accepts the explicit installation plan.
 
+Earlier native installations migrate their unprefixed Skill and command paths
+when those paths belong to this package's previous installation manifest.
+The migration preserves legacy paths in the backup directory. Unowned entries
+remain in place. Use `/i3-spec` in CodeBuddy or `$i3-spec-driven-development`
+in Codex after upgrading.
+
 ## Prepare the complete plugin
 
 For native plugin registration, including plugin hooks, explicitly prepare a
@@ -78,21 +84,21 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new session after enabling the plugin. Codex uses the existing Skill
-names, such as `$spec-driven-development`; lifecycle slash-command adaptation
+Start a new session after enabling the plugin. Codex uses the branded Skill
+names, such as `$i3-spec-driven-development`; lifecycle slash-command adaptation
 is maintained separately.
 
 ## Commands
 
 Native CodeBuddy and Claude Code installations use short filenames such as
-`/spec`, `/plan`, `/build` and `/ship`. Hosts supporting Claude-compatible plugin
+`/i3-spec`, `/i3-plan`, `/i3-build` and `/i3-ship`. Hosts supporting Claude-compatible plugin
 commands load the same workflows under the plugin namespace:
 
 | Command | Description |
 | --- | --- |
 {{COMMAND_TABLE}}
 
-`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
+`/i3-composer-agent:i3-build auto` runs the existing approved-plan workflow.
 
 ## Skills