@givolt/i3-composer-agent 0.6.12 → 1.0.0

package/rebrand/MAINTENANCE.md

@@ -1,51 +1,112 @@
-# Maintaining i3 Composer Agent
+# i3 Composer Agent 仓库维护
 
-The product and plugin ID is `i3-composer-agent`; the npm package is
-`@givolt/i3-composer-agent`. The separate GSD-based project is maintained in its
-own repository and is outside this conversion.
+本指南只适用于 Agent 仓库；GSD / i3 Composer Work 是另一个独立仓库。
+这里借鉴其维护方式，不复用其源码、安装产物或 Git 分支。
 
-`brand.json` records the identity and upstream baseline. `apply.cjs` replays the
-brand substitutions and marketplace normalization; `templates/` holds the
-branded installation pages. Preserve LICENSE, NOTICE, upstream URLs, historical
-eval reports, the upstream comparison, and the skill ID `using-agent-skills`.
-References to the independent Agent Skills specification retain that name.
+## 仓库和分支
 
-## Source and release workflow
+- 品牌仓库：`https://github.com/49780522/i3-composer-agent`（Private）。
+- `origin` 指向品牌仓库；`upstream` 指向 `https://github.com/addyosmani/agent-skills.git`。
+- `agent/source`：原始上游源码与名称，加本项目 `rebrand/` 工具和规则。
+- `main`：经过重放与验证的品牌快照；npm 身份为 `@givolt/i3-composer-agent`。
+- `i3-composer-agent-v0.6.12`：已经发布的首次包所对应的原始品牌提交。
 
-Keep the upstream source on `i3/source`, with its original names. Perform source
-updates there. Start release candidates from the current branded branch, bringing
-in the upstream changes while retaining the npm CLI and `rebrand/` files, then
-replay the brand transformation. A fresh checkout of `i3/source` alone does not
-contain the distribution tools.
-Keep the original upstream remote until a dedicated fork repository is created;
-do not push branded changes to `addyosmani/agent-skills`.
+源码工作树为 `/Users/howard/Workspace/composer-skills-source/agent-source`；
+品牌工作树为 `/Users/howard/Workspace/composer-skills-source/agent-skills`。
+旧的 Agent 本地 `i3/source` 分支已改为 `agent/source`，避免与 GSD 分支名称混淆。
+
+## 获取源码
+
+```bash
+git clone https://github.com/49780522/i3-composer-agent.git
+cd i3-composer-agent
+git remote add upstream https://github.com/addyosmani/agent-skills.git
+git fetch upstream --tags
+git worktree add --track -b agent/source ../agent-source origin/agent/source
+```
+
+源分支没有发行用的根 package.json。包入口、发行测试和配置由
+`rebrand/overlay/`、`package.template.json` 在品牌候选中生成。
+
+## 同步上游
+
+1. 在 Agent 源工作树获取上游，选择并审查一个明确的版本或提交。
+2. 从 `agent/source` 创建维护分支，合并该 ref 并解决源码冲突。
+3. 从同一 ref 记录上游目录和 Skill frontmatter；审查记录中的新增、删除和描述变化。
+4. 调整文字补丁、分发 overlay 和品牌模板；源码分支保持原始名称。
+5. 运行源验证，提交维护分支，通过 PR 合入 `agent/source`。
+6. 从更新后的源分支创建独立品牌候选工作树，重放、验证和打包。
+7. 将验证过的品牌快照通过发行 PR 更新 `main`；npm 发布单独执行。
+
+源维护阶段示例（把示例分支和 ref 替换为实际选定值）：
+
+```bash
+cd /Users/howard/Workspace/composer-skills-source/agent-source
+git fetch upstream --tags
+git switch -c sync/upstream-next agent/source
+git merge --no-commit --no-ff upstream/main
+# 审查并处理源码冲突后：
+node rebrand/record-upstream.cjs upstream/main
+node --test scripts/*-test.js scripts/lib/*-test.js rebrand/tests/*.test.cjs
+```
+
+记录工具读取 Git 对象中的上游文件，写入 `upstream.json` 和 `brand.json` 的基线。
+它不会把任意本地新增文件认定为上游。发布版本由 `brand.json.releaseVersion`
+控制，与 `upstream.json.upstreamVersion` 分开；按实际更改递增，保持六份清单一致。
+
+品牌版本从 `1.0.0` 开始使用独立编号；本次仅修改 i3，上游基线保留为 `0.6.12`。
+之后的当前基线以 `upstream.json` 记录为准。
+仅修改 i3 的修复或分发规则时，只递增品牌版本；上游版本和提交保持原值。
+README、CLI 帮助和准备完成提示同时显示这两个版本；`--version` 保留单一品牌版本输出。
+具体规则与历史版本处理见 [VERSIONING.md](VERSIONING.md)。
+
+## 创建品牌候选
+
+从源分支创建候选，每次换一个分支名和独立目录：
 
 ```bash
-node rebrand/apply.cjs --apply
-node rebrand/apply.cjs --check
+cd /Users/howard/Workspace/composer-skills-source/agent-skills
+git fetch origin
+git worktree add -b release/agent-next ../agent-candidate origin/agent/source
+cd ../agent-candidate
+bash rebrand/rebrand.sh --apply
+bash rebrand/rebrand.sh --check
 npm run validate
 npm test
 node scripts/run-evals.js --min-rank1 95
 bash hooks/session-start-test.sh
 bash hooks/sdd-cache-test.sh
 bash hooks/simplify-ignore-test.sh
-npm pack --pack-destination /path/to/release-directory
+mkdir -p ../releases/next
+npm pack --pack-destination ../releases/next
 ```
 
-The transform is idempotent. The check exits with a failure when another replay
-would change files. Keep package.json and all plugin manifest versions in sync.
-Inspect the tarball and test its CLI in an isolated directory before publishing.
+在打包前先创建输出目录。对 tarball 重新解包，验证 CLI、完整文件目录及宿主清单。
+源码分支上执行 `--apply` 会在写入前失败；不得把未经重放的源分支直接更新到 `main`。
+源 PR 与发行 PR 的边界见 [PR-WORKFLOW.md](PR-WORKFLOW.md)。
+
+## 审查重放规则
+
+- `fork-patches.json`：明确的文字补丁，源文本不再匹配时失败，要求人工适配。
+- `overlay/`：本项目的 npm CLI、发行测试、品牌校验和发行 CI；上游相关文件改变时需合并审查。
+- `templates/`：品牌 README 和安装指南；上游对应说明改变时同步模板。
+- 目录数量、Skill 表、命令表和插件描述由已记录的目录生成，不固定为 25/9。
+- Skill frontmatter 保留原文；校验比较换行规范化后的哈希，兼容 LF/CRLF 检出。
+- LICENSE、NOTICE、真实上游链接、历史评估说明和标准名称保留。
+- 如果上游新增根 package.json，重放会失败，先适配分发配置和依赖再继续。
+
+## 发布及验收
 
-The CLI prepares a self-contained plugin directory and prints native host
-registration commands. It does not write business-project AGENTS.md, change
-existing plugin settings, or register lifecycle slash commands in Codex.
+维护流程与安装能力分开验收。当前 npm CLI 准备文件并打印宿主注册命令；
+实际宿主安装范围、启用、命令执行以及交互向导仍需各自验证。
+Codex 的生命周期斜杠命令适配是独立工作，已有 Skill ID 不因维护流程改名。
 
-Publishing is a separate step after the package is reviewed:
+发布审核通过后，发布已经测过的 tarball，先使用试用标签，完成 registry 安装验证后再更新 latest：
 
 ```bash
-npm publish /path/to/givolt-i3-composer-agent-0.6.12.tgz --access public
+npm publish /absolute/path/to/reviewed-package.tgz --access public --tag next
+npm dist-tag add @givolt/i3-composer-agent@<reviewed-version> latest
 ```
 
-Verify the registry version, integrity, and a fresh registry install after
-publication. A local tarball test does not prove registry publication or actual
-model execution of a command.
+每个已发布包名和版本只用一次。GitHub Actions 与 GSD 品牌仓库一样先保持关闭，
+适配并验证 CI 后再启用。当前验证范围见 [VALIDATION.md](VALIDATION.md)。

package/rebrand/NOTICE.md

@@ -0,0 +1,9 @@
+# Attribution
+
+i3 Composer Agent is a branded distribution of
+[Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani.
+The initial distribution is based on upstream commit `1401c8b` (version 0.6.12).
+
+The original MIT license and copyright notice are preserved in LICENSE.
+Givolt maintains the branding, npm distribution, and bundle preparation CLI.
+The original skill IDs, command workflows, and persona definitions are retained.

package/rebrand/PR-WORKFLOW.md

@@ -0,0 +1,34 @@
+# Agent 源码与发行 PR
+
+此流程只操作 49780522/i3-composer-agent。GSD 仓库只是维护方法的参考。
+
+源码、修复和重放规则的 PR 以 `agent/source` 为 base，从该分支创建维护分支。
+保持上游文件的原始名称；本项目分发工具放在 `rebrand/`。
+
+```bash
+git fetch origin
+git worktree add -b fix/my-change ../agent-fix origin/agent/source
+cd ../agent-fix
+node --test scripts/*-test.js scripts/lib/*-test.js rebrand/tests/*.test.cjs
+```
+
+修改重放规则后，从维护提交另建品牌候选并执行 MAINTENANCE.md 中的完整验证。
+审查和暂存本次文件后提交，再推送并创建源码 PR：
+
+```bash
+git push -u origin fix/my-change
+gh pr create --base agent/source --head fix/my-change
+```
+
+源码 PR 合入后，从最新 `agent/source` 建立候选，重放、验证、打包并提交品牌内容。
+发行 PR 以 `main` 为 base；head 必须包含验证后的品牌快照。
+
+当 main 和源候选历史产生合并冲突时，从 main 创建发行 PR 分支，合入已验证的
+品牌候选并审查冲突。最终跟踪文件树必须与验证过的候选一致，然后提交：
+
+```bash
+git diff --cached <validated-candidate-commit>
+```
+
+上述差异应为空。若合并中需要实际代码调整，重新验证调整后的发行内容和 tarball。
+不要把原始 agent/source 直接作为发行 PR 的 head；不向 upstream 推送品牌提交。

package/rebrand/UNIFICATION-SPEC.md

@@ -0,0 +1,33 @@
+# Agent 项目维护流程统一
+
+用户已确认借鉴 GSD 项目维护方式，并要求项目互相独立。本规范只约束 Agent 仓库。
+
+## 目标与边界
+
+- `upstream` 指向 addyosmani/agent-skills；`origin` 指向私有品牌仓库 49780522/i3-composer-agent。
+- `agent/source` 保留上游原始名称和源码，在 `rebrand/` 保存本项目的分发工具与转换规则。
+- 候选从 `agent/source` 创建，在候选中重放；`main` 保存经过验证的品牌快照。
+- GSD 仓库只读，不使用它的源码、分支或安装产物。
+- Skill ID、流程命令内容、Persona、参考文件和 MIT 来源署名保持既有契约。
+- 本次完善源码同步和品牌重放；交互安装向导、Codex 命令适配及新的 npm 发布独立处理。
+
+## 实现与命令
+
+转换入口保持 Node.js 20+ 和零依赖：`node rebrand/apply.cjs --apply|--check`；另提供与 GSD 相同形式的 `bash rebrand/rebrand.sh` 入口。
+
+上游基线由 `node rebrand/record-upstream.cjs <明确的 ref>` 从 Git 对象记录；源码分支上运行 `node --test rebrand/tests/*.test.cjs`。候选执行 `npm run validate`、`npm test` 和既有路由/hook 检查。
+
+代码沿用 CommonJS、Node 内置 fs/path/assert。分发专属文件放在 `rebrand/overlay/`，发行包配置由模板生成，不把 branded README 或清单混入源码分支。
+
+## 验收条件
+
+1. 从干净上游源码及本项目规则能生成完整品牌包，重复重放不产生差异。
+2. 在 `agent/source` 上执行写入式重放必须失败且不修改源码。
+3. 记录上游新增 Skill/Command 后能生成相应清单和说明；删失或改写已记录 Skill ID 时校验失败。
+4. 上游的 25 个 Skill frontmatter、24 个非元 Skill、4 个 Persona、7 个共享参考保持原始内容；9 个流程只变品牌命名空间。
+5. 本地候选通过完整测试，并从打包结果运行 CLI 与校验。
+6. 独立品牌仓库中的源/发行分支及远程关系正确；首次发布标签保持原来的 0.6.12 提交。
+
+## 执行顺序
+
+先为源到品牌的重放、源码保护、目录增长与完整性写失败测试；实现工具及模板生成；验证真实上游归档；提交源分支；生成并审查品牌候选；最后建立远程并同步分支。

package/rebrand/VALIDATION.md

@@ -0,0 +1,28 @@
+# Agent 维护流程验收合同
+
+本合同对应 UNIFICATION-SPEC.md；完整执行记录写入每次的审计或发布目录。
+
+## 源维护
+
+- 上游 ref 是明确的 Git 提交；目录与 frontmatter 从该 ref 的对象记录。
+- `agent/source` 的上游文件保留原始名称与内容；本项目新增文件限定在 rebrand/。
+- 重放在源码分支上写入前失败。
+- 重放规则改变时，运行 rebrand/tests/pipeline.test.cjs 并验证源候选到品牌的完整路径。
+
+## 品牌候选
+
+- Skill、命令、Persona、references 和全部已记录普通运行文件与上游目录一致。
+- Skill frontmatter 的名称和字段内容保持；换行差异不作为字段变更。
+- 新增上游 Skill/Command 能进入目录、品牌说明和打包；缺失内容会失败。
+- 文字补丁失去匹配时必须失败，不能静默遗漏。
+- 重放后 --check 成功，完整 Node、路由与 hook 检查通过。
+- npm package、插件和市场身份一致；六份版本一致。
+- 品牌修复能独立递增发行版本，保留上游目录记录原文；包来源元数据与该记录一致。
+- README、CLI 帮助和准备提示显示品牌版本与上游基线；--version 保持单一品牌版本输出。
+- 打包后从压缩包重新验证完整布局、CLI 和宿主清单。
+
+## 证据边界
+
+源或包校验不等于 registry 发布，也不等于实际宿主启用和模型执行。
+英文确定性 TF-IDF 路由分数不能代替中文或真实模型行为验收。
+安装向导、宿主范围、升级和移除沿用安装遗漏审计的独立验收项。

package/rebrand/VERSIONING.md

@@ -0,0 +1,32 @@
+# i3 Composer Agent 版本规则
+
+本规则已经用户确认，仅适用于 i3 Composer Agent 仓库。
+
+| 信息 | 权威来源 | 本次确认值 |
+| --- | --- | --- |
+| i3 发行版本 | brand.json 的 releaseVersion | 1.0.0 |
+| 上游版本 | upstream.json 的 upstreamVersion | 0.6.12 |
+| 上游提交 | upstream.json 的 upstreamCommit | 1401c8b8030e023baeebb31781a6653fe8e93026 |
+
+品牌版本采用独立的 major.minor.patch 编号。1.0.0 是这套编号的起点；
+兼容的 i3 修复递增 patch，兼容的新功能递增 minor，需要使用者调整用法的变更递增 major。
+实际同步上游并审查选定提交后，才用 record-upstream.cjs 更新上游版本与提交。
+上游版本变动不自动决定品牌版本；品牌版本根据本次发行的实际变化确定。
+
+重放将品牌版本写入 npm 包和插件清单，把上游版本、提交及仓库写入
+package.json 的 i3ComposerAgent 来源字段。package.template.json 不保存发行版本，
+发行版本统一由 brand.json 生成。
+
+README、CLI 帮助和准备完成提示显示：
+
+```text
+i3 Composer Agent v1.0.0
+Based on agent-skills v0.6.12
+```
+
+在上述例子中，--version 输出 1.0.0，保留脚本使用的单一版本格式。--dry-run 的 JSON
+分别提供 version、upstreamVersion、upstreamCommit。
+
+已经发布的 @givolt/i3-composer-agent@0.6.12 及其 Git 标签作为历史记录保留。
+之前的 0.6.13 是未发布候选，新的独立版本候选替代它。
+1.0.0 的源码与打包验证不代表 npm 发布；发布仍按 MAINTENANCE.md 单独执行。

package/rebrand/apply.cjs

@@ -3,19 +3,37 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { validateCatalog, frontmatter } = require('./catalog.cjs');
 const brand = require('./brand.json');
+const upstream = require('./upstream.json');
 const root = path.resolve(__dirname, '..');
 const mode = process.argv[2];
 if (!['--apply', '--check'].includes(mode)) {
   console.error('Usage: node rebrand/apply.cjs --apply | --check');
   process.exit(1);
 }
+if (mode === '--apply') {
+  const branch = spawnSync('git', ['-C', root, 'branch', '--show-current'], { encoding: 'utf8' });
+  if (branch.status === 0 && branch.stdout.trim() === brand.sourceBranch) {
+    console.error(`Refusing to transform the source branch ${brand.sourceBranch}; create a release candidate first.`);
+    process.exit(1);
+  }
+}
+const inventory = validateCatalog(root, upstream);
+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.');
+  process.exit(1);
+}
 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);
 }
 function transform(content, relative) {
+  const head = /^skills\/[^/]+\/SKILL\.md$/.test(relative) ? frontmatter(content) : '';
+  content = content.slice(head.length);
   // Agent Skills is also the name of an independent specification.
   const standard = '__I3_AGENT_SKILLS_STANDARD__';
   let result = content
@@ -56,10 +74,10 @@ 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 result;
+  return head + result;
 }
 const skipDirectories = new Set(['.git', 'node_modules', 'rebrand', 'dist', 'tests', 'bin']);
-const skipFiles = new Set(['LICENSE', 'NOTICE.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']);
+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']);
 function walk(directory, prefix = '') {
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -72,6 +90,13 @@ function walk(directory, prefix = '') {
   }
 }
 walk(root);
+for (const patch of require('./fork-patches.json')) {
+  if (path.isAbsolute(patch.file) || patch.file.split(/[\\/]/).includes('..')) throw new Error('Patch must stay inside this Agent repository.');
+  const original = (changes.get(patch.file) ?? fs.readFileSync(path.join(root, patch.file), 'utf8')).replace(/\r\n/g, '\n');
+  if (original.includes(patch.to)) continue;
+  if (!original.includes(patch.from)) throw new Error(`Upstream changed ${patch.file}; review the fork patch before proceeding.`);
+  update(patch.file, original.replace(patch.from, patch.to));
+}
 const comparisonPath = 'docs/comparison.md';
 const comparison = fs.readFileSync(path.join(root, comparisonPath), 'utf8');
 if (!comparison.includes('> **Upstream research:**')) {
@@ -81,15 +106,16 @@ if (!comparison.includes('> **Upstream research:**')) {
 for (const relative of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']) {
   const manifest = JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8'));
   manifest.name = brand.name;
+  manifest.version = brand.releaseVersion;
   manifest.description = brand.description;
   if (manifest.author) manifest.author = { name: brand.maintainer };
-  delete manifest.homepage;
-  delete manifest.repository;
+  manifest.homepage = brand.repository;
+  manifest.repository = brand.repository;
   if (manifest.interface) {
     manifest.interface.displayName = brand.displayName;
     manifest.interface.developerName = brand.maintainer;
     manifest.interface.shortDescription = 'Engineering workflow skills';
-    manifest.interface.longDescription = `${brand.displayName} packages 25 engineering skills from Addy Osmani's Agent Skills, covering requirements, planning, implementation, testing, review, and shipping.`;
+    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));
   }
   update(relative, JSON.stringify(manifest, null, 2) + '\n');
@@ -97,25 +123,72 @@ for (const relative of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plu
 for (const relative of ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) {
   const manifest = JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8'));
   manifest.name = brand.name;
+  if (manifest.version) manifest.version = brand.releaseVersion;
   if (manifest.description) manifest.description = brand.description;
   if (manifest.owner) manifest.owner = { name: brand.maintainer };
   if (manifest.interface) manifest.interface.displayName = brand.displayName;
   for (const plugin of manifest.plugins) {
     plugin.name = brand.name;
+    plugin.version = brand.releaseVersion;
     plugin.description = brand.description;
     plugin.source = relative.startsWith('.agents/') ? { source: 'local', path: './' } : './';
-    delete plugin.homepage;
+    plugin.homepage = brand.repository;
   }
   update(relative, JSON.stringify(manifest, null, 2) + '\n');
 }
+function overlay(directory, prefix = '') {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (relative === '.github' && !fs.existsSync(path.join(root, '.github'))) continue;
+    if (entry.isDirectory()) overlay(path.join(directory, entry.name), relative);
+    else if (entry.isFile()) update(relative, fs.readFileSync(path.join(directory, entry.name), 'utf8'));
+    else throw new Error(`Unsupported distribution overlay entry: ${relative}`);
+  }
+}
+overlay(path.join(__dirname, 'overlay'));
+const ignoreFile = path.join(root, '.gitignore');
+if (fs.existsSync(ignoreFile)) {
+  const original = fs.readFileSync(ignoreFile, 'utf8');
+  const entries = new Set(original.split(/\r?\n/));
+  const missing = ['dist/', '*.tgz', `${brand.name}/`].filter(entry => !entries.has(entry));
+  if (missing.length) update('.gitignore', original.replace(/\n?$/, '\n') + missing.join('\n') + '\n');
+}
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.template.json'), 'utf8'));
+pkg.name = brand.npmName;
+pkg.version = brand.releaseVersion;
+pkg.repository = { type: 'git', url: brand.repository + '.git' };
+pkg.homepage = brand.repository + '#readme';
+pkg.i3ComposerAgent.upstreamVersion = upstream.upstreamVersion;
+pkg.i3ComposerAgent.upstreamCommit = upstream.upstreamCommit;
+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] || '';
+  return (head.match(/^description:\s*(.*)$/m)?.[1] || '').replace(/^["']|["']$/g, '').replaceAll('|', '\\|');
+}
+const values = {
+  RELEASE_VERSION: brand.releaseVersion,
+  UPSTREAM_VERSION: upstream.upstreamVersion,
+  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'),
+};
 for (const [relative, template] of [
   ['README.md', 'README.md'], ['docs/codex-setup.md', 'codex-setup.md'], ['docs/codebuddy-setup.md', 'codebuddy-setup.md'],
 ]) {
-  update(relative, fs.readFileSync(path.join(__dirname, 'templates', template), 'utf8'));
+  const content = fs.readFileSync(path.join(__dirname, 'templates', template), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+    if (!(key in values)) throw new Error(`Unknown template variable: ${key}`);
+    return values[key];
+  });
+  update(relative, content);
 }
 if (mode === '--apply') for (const [relative, content] of changes) {
   fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true });
   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;

package/rebrand/brand.json

@@ -4,6 +4,10 @@
   "npmName": "@givolt/i3-composer-agent",
   "maintainer": "Givolt",
   "upstream": "https://github.com/addyosmani/agent-skills",
-  "upstreamCommit": "1401c8b",
-  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship."
+  "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "repository": "https://github.com/49780522/i3-composer-agent",
+  "sourceBranch": "agent/source",
+  "releaseBranch": "main",
+  "releaseVersion": "1.0.0"
 }

package/rebrand/catalog.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const assert = require('node:assert/strict');
+const runtimeRoots = ['skills', 'references', 'agents', 'commands', '.claude/commands', '.gemini/commands', 'hooks', '.claude-plugin', '.codex-plugin', '.agents/plugins'];
+const runtimeFiles = ['plugin.json', 'LICENSE'];
+
+function frontmatter(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/);
+  assert.ok(match, 'Skill must have YAML frontmatter');
+  return match[0];
+}
+function describe(files, read) {
+  files = files.filter(file => path.basename(file) !== '.DS_Store');
+  const select = pattern => files.filter(name => pattern.test(name)).sort();
+  const skillFiles = select(/^skills\/[^/]+\/SKILL\.md$/);
+  const skillFrontmatter = {};
+  for (const file of skillFiles) {
+    const id = file.split('/')[1];
+    const head = frontmatter(read(file));
+    const name = head.match(/^name:\s*["']?([^\s"']+)["']?\s*$/m)?.[1];
+    assert.equal(name, id, `${file}: unstable skill identifier`);
+    skillFrontmatter[id] = crypto.createHash('sha256').update(head.replace(/\r\n/g, '\n')).digest('hex');
+  }
+  return {
+    skills: skillFiles.map(file => file.split('/')[1]),
+    commands: select(/^\.claude\/commands\/[^/]+\.md$/).map(file => path.basename(file, '.md')),
+    personas: select(/^agents\/[^/]+\.md$/).map(file => path.basename(file, '.md')),
+    references: select(/^references\/[^/]+\.md$/),
+    runtimeFiles: files.filter(file => runtimeFiles.includes(file) || runtimeRoots.some(root => file.startsWith(root + '/'))).sort(),
+    skillFrontmatter,
+  };
+}
+function catalog(root) {
+  const files = [];
+  function walk(directory, prefix) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const relative = `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) walk(path.join(directory, entry.name), relative);
+      else if (entry.isFile()) files.push(relative);
+    }
+  }
+  for (const name of runtimeRoots) if (fs.existsSync(path.join(root, name))) walk(path.join(root, name), name);
+  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) {
+  const actual = catalog(root);
+  for (const field of ['skills', 'commands', 'personas', 'references', 'runtimeFiles', 'skillFrontmatter']) {
+    assert.deepEqual(actual[field], expected[field], `upstream preservation failed: ${field}`);
+  }
+  return actual;
+}
+module.exports = { runtimeRoots, runtimeFiles, frontmatter, describe, catalog, validateCatalog };

package/rebrand/fork-patches.json

@@ -0,0 +1,12 @@
+[
+  {
+    "file": "scripts/validate-versions.js",
+    "from": "const manifestPaths = [\n  \"plugin.json\",",
+    "to": "const manifestPaths = [\n  \"package.json\",\n  \"plugin.json\","
+  },
+  {
+    "file": "scripts/validate-versions-test.js",
+    "from": "const manifestPaths = [\n  \"plugin.json\",",
+    "to": "const manifestPaths = [\n  \"package.json\",\n  \"plugin.json\","
+  }
+]