@givolt/i3-composer-agent 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+
+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
+    .replace('agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself',
+      'agents working on the i3 Composer Agent repository itself, derived from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills)')
+    .replace(/Agent Skills(?=\s+(?:specification|spec\b|format\b|standard\b))/g, standard)
+    .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}:`)
+    .replaceAll('/path/to/agent-skills', `/path/to/${brand.name}`)
+    .replaceAll('./agent-skills', `./${brand.name}`)
+    .replace(/(?<![\w/.-])agent-skills(?![\w-])/g, brand.name)
+    .replaceAll('Agent Skills', brand.displayName)
+    .replaceAll(standard, 'Agent Skills');
+  if (relative.startsWith('docs/')) {
+    result = result.split('\n').map(line => {
+      if (/^\s*git clone https:\/\/github\.com\/addyosmani\/agent-skills(?:\.git)?\s*$/.test(line)) {
+        return `${line.match(/^\s*/)[0]}npx ${brand.npmName} --extract --dir ./${brand.name}`;
+      }
+      if (/^\s*(?:npx |codex |copilot |cmd |agy |gemini |\/plugin )/.test(line)) {
+        return line.replaceAll('https://github.com/addyosmani/agent-skills.git', `/path/to/${brand.name}`)
+          .replaceAll('https://github.com/addyosmani/agent-skills', `/path/to/${brand.name}`)
+          .replaceAll('addyosmani/agent-skills', `/path/to/${brand.name}`);
+      }
+      return line;
+    }).join('\n');
+    result = result
+      .replace(/^cmd skills add \/path\/to\/i3-composer-agent@main[^\n]*$/gm,
+        '# Branch selectors apply to Git sources; prepared npm bundles have no Git history.')
+      .replaceAll('Clone the repository', 'Prepare the plugin bundle')
+      .replaceAll('Clone this repository', 'Prepare the plugin bundle')
+      .replaceAll('Install from the remote repository', 'Install from a prepared local bundle')
+      .replaceAll('npx skills add addyosmani/agent-skills', `npx skills add /path/to/${brand.name}`)
+      .replaceAll('plugin marketplace add addyosmani/agent-skills', `plugin marketplace add /path/to/${brand.name}`)
+      .replaceAll('~/.gemini/config/plugins/agent-skills/', `~/.gemini/config/plugins/${brand.name}/`)
+      .replaceAll('.cursor/rules/agent-skills.mdc', `.cursor/rules/${brand.name}.mdc`)
+      .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 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']);
+function walk(directory, prefix = '') {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    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)) {
+      const original = fs.readFileSync(path.join(root, relative), 'utf8');
+      update(relative, transform(original, relative));
+    }
+  }
+}
+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:**')) {
+  const note = `> **Upstream research:** This comparison is retained from Addy Osmani's \`agent-skills\` at commit \`${brand.upstreamCommit}\`. Its experiments describe the upstream project; they are not independent evaluations of ${brand.displayName}.\n\n`;
+  update(comparisonPath, comparison.replace('# How agent-skills compares\n\n', '# How agent-skills compares\n\n' + note));
+}
+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 };
+  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 ${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');
+}
+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: './' } : './';
+    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'],
+]) {
+  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

@@ -0,0 +1,13 @@
+{
+  "name": "i3-composer-agent",
+  "displayName": "i3 Composer Agent",
+  "npmName": "@givolt/i3-composer-agent",
+  "maintainer": "Givolt",
+  "upstream": "https://github.com/addyosmani/agent-skills",
+  "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\","
+  }
+]

package/rebrand/overlay/.github/workflows/test-plugin-install.yml

@@ -0,0 +1,177 @@
+name: Test Plugin Installation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate-skills:
+    name: Validate skill content
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Validate all skills
+        run: node scripts/validate-skills.js
+
+      - name: Test skill lint rules
+        run: node --test scripts/lib/skill-lint-test.js
+
+      - name: Validate manifest versions
+        run: node scripts/validate-versions.js
+
+      - name: Validate i3 Composer Agent identity and replay
+        run: |
+          node scripts/validate-brand.cjs
+          node rebrand/apply.cjs --check
+
+      - name: Test npm bundle CLI
+        run: node --test tests/*.test.cjs rebrand/tests/*.test.cjs
+
+      - name: Test manifest version validator
+        run: node --test scripts/validate-versions-test.js
+
+      - name: Test skill eval runner
+        run: node --test scripts/run-evals-test.js
+
+      - name: Run skill evals (trigger + routing)
+        run: node scripts/run-evals.js --min-rank1 95
+
+      - name: Validate references/ links in skills
+        run: node scripts/validate-reference-links.js
+
+      - name: Test reference-link validator
+        run: node --test scripts/validate-reference-links-test.js
+
+      - name: Test floor-guard reference
+        run: node --test scripts/floor-guard-reference-test.js
+
+      - name: Test session-start hook payload
+        run: bash hooks/session-start-test.sh
+
+  validate-commands:
+    name: Validate command parity and description sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Validate commands across all tool directories
+        run: node scripts/validate-commands.js
+
+      - name: Test command validator
+        run: node --test scripts/validate-commands-test.js
+
+      - name: Validate spec/plan/todo artifact paths
+        run: node scripts/validate-artifact-paths.js
+
+      - name: Test artifact-path validator
+        run: node --test scripts/validate-artifact-paths-test.js
+
+  # Ubuntu coverage stays in the existing jobs above, preserving their check names.
+  validate-platforms:
+    name: Validate tooling (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      - name: Test validators and eval runner
+        run: >-
+          node --test
+          scripts/lib/skill-lint-test.js
+          scripts/validate-versions-test.js
+          scripts/run-evals-test.js
+          scripts/validate-reference-links-test.js
+          scripts/validate-commands-test.js
+          scripts/validate-artifact-paths-test.js
+          scripts/floor-guard-reference-test.js
+          tests/*.test.cjs
+          rebrand/tests/*.test.cjs
+
+      - name: Validate all skills
+        run: node scripts/validate-skills.js
+
+      - name: Validate manifest versions
+        run: node scripts/validate-versions.js
+
+      - name: Validate references/ links in skills
+        run: node scripts/validate-reference-links.js
+
+      - name: Validate commands across all tool directories
+        run: node scripts/validate-commands.js
+
+      - name: Validate spec/plan/todo artifact paths
+        run: node scripts/validate-artifact-paths.js
+
+      - name: Run skill evals (trigger + routing)
+        run: node scripts/run-evals.js --min-rank1 95
+
+  test-hooks:
+    name: Hook regression tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Test sdd-cache hooks (stubbed curl, no network)
+        run: bash hooks/sdd-cache-test.sh
+
+      - name: Test simplify-ignore hook
+        run: bash hooks/simplify-ignore-test.sh
+
+  validate:
+    name: Validate plugin structure
+    needs: [validate-skills, validate-commands, validate-platforms]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate marketplace and plugin manifests
+        run: claude plugin validate .
+
+  test-install:
+    name: Test plugin installation
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Configure git to use HTTPS
+        run: git config --global url."https://github.com/".insteadOf "git@github.com:"
+
+      - name: Add marketplace
+        run: claude plugin marketplace add ./
+
+      - name: List marketplaces
+        run: claude plugin marketplace list
+
+      - name: Install plugin
+        run: claude plugin install i3-composer-agent@i3-composer-agent --scope user

package/rebrand/overlay/CHANGELOG.md

@@ -0,0 +1,23 @@
+# i3 Composer Agent changes
+
+## 1.0.0 — Unreleased
+
+Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
+
+### Changed
+
+- Start independent i3 release numbering. The upstream baseline remains 0.6.12; this replaces the unpublished 0.6.13 candidate.
+- Display the i3 release and upstream baseline together in the README, CLI help, and bundle preparation output. Keep --version machine-readable.
+- Include the upstream version, commit, and repository in package metadata.
+- Maintain source changes on agent/source, generate and validate a branded candidate, then update main in this independent repository.
+
+### Fixed
+
+- Preserve complete reviewed runtime assets when replaying branding, including newly approved upstream skills and commands.
+- Keep replay checks repeatable in npm bundles without repository CI files.
+- Preserve branded ignore rules and exclude Finder metadata from runtime preservation checks.
+
+## 0.6.12
+
+- Publish the first i3 Composer Agent npm distribution based on agent-skills 0.6.12.
+- Retain upstream skill IDs, command workflows, specialist personas, shared references, and MIT attribution.

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const root = path.resolve(__dirname, '..');
+const pkg = require('../package.json');
+const name = 'i3-composer-agent';
+const args = process.argv.slice(2);
+const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pkg.i3ComposerAgent.upstreamVersion}`;
+const help = `${identity}
+${pkg.name}
+
+Prepare the complete i3 Composer Agent plugin, including shared references.
+
+Usage:
+  npx ${pkg.name} --codebuddy [--dir <directory>]
+  npx ${pkg.name} --codex [--dir <directory>]
+  npx ${pkg.name} --claude [--dir <directory>]
+  npx ${pkg.name} --extract --dir <directory>
+
+Options:
+  --dir <directory>  Output directory (default: ./i3-composer-agent)
+  --dry-run         Show the planned bundle without writing files
+  --force           Replace an existing i3 bundle, preserving a backup
+  --version         Print the package version
+  --help            Show this help
+
+Host flags prepare the bundle and print native registration commands.
+Execute those commands in the intended host to enable the plugin.
+`;
+
+function quote(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
+function realDestination(target) {
+  let existing = target;
+  const suffix = [];
+  while (!fs.existsSync(existing)) {
+    suffix.unshift(path.basename(existing));
+    const parent = path.dirname(existing);
+    if (parent === existing) throw new Error(`Cannot resolve destination: ${target}`);
+    existing = parent;
+  }
+  return path.join(fs.realpathSync(existing), ...suffix);
+}
+function main() {
+  if (!args.length || args.includes('--help')) { console.log(help); return; }
+  if (args.length === 1 && args[0] === '--version') { console.log(pkg.version); return; }
+  let host;
+  let directory = path.join(process.cwd(), name);
+  let dryRun = false;
+  let force = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (['--codebuddy', '--codex', '--claude', '--extract'].includes(arg)) {
+      if (host) throw new Error('Choose exactly one host flag or --extract.');
+      host = arg.slice(2);
+    } else if (arg === '--dir') {
+      if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error('--dir requires a directory.');
+      directory = path.resolve(args[++i]);
+    } else if (arg === '--dry-run') dryRun = true;
+    else if (arg === '--force') force = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (!host) throw new Error('Choose --codebuddy, --codex, --claude, or --extract.');
+  directory = realDestination(directory);
+  const sourceRoot = fs.realpathSync(root);
+  if (directory === sourceRoot || directory.startsWith(sourceRoot + path.sep) || sourceRoot.startsWith(directory + path.sep)) {
+    throw new Error('The output directory must be outside this package directory.');
+  }
+  let exists = false;
+  try { fs.lstatSync(directory); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (exists) {
+    if (!force) throw new Error(`Output already exists: ${directory}. Choose a new directory or use --force for an i3 bundle.`);
+    const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'plugin.json'), 'utf8'));
+    if (manifest.name !== name) throw new Error('Refusing to replace a directory belonging to another plugin.');
+  }
+  if (dryRun) {
+    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    return;
+  }
+  fs.mkdirSync(path.dirname(directory), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(directory), `.${name}-`));
+  let backup;
+  try {
+    for (const relative of pkg.i3ComposerAgent.pluginFiles) {
+      const source = path.join(root, relative);
+      const destination = path.join(staging, relative);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.cpSync(source, destination, {
+        recursive: true,
+        filter: file => {
+          if (path.basename(file) === '.DS_Store') return false;
+          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Bundle contains a symlink: ${file}`);
+          return !/(?:^|[\\/])(?:results|node_modules|\.git)(?:[\\/]|$)/.test(path.relative(root, file));
+        },
+      });
+    }
+    if (exists) {
+      backup = `${directory}.backup-${crypto.randomUUID()}`;
+      fs.renameSync(directory, backup);
+    }
+    try { fs.renameSync(staging, directory); }
+    catch (error) { if (backup) fs.renameSync(backup, directory); throw error; }
+  } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
+  console.log(identity);
+  console.log(`Prepared ${name} at ${directory}`);
+  if (backup) console.log(`Previous bundle preserved at ${backup}`);
+  if (host === 'extract') return;
+  console.log('\nRegister and enable the plugin with these native commands:');
+  const selector = `${name}@${name}`;
+  if (host === 'codex') {
+    console.log(`codex plugin marketplace add ${quote(directory)}`);
+    console.log(`codex plugin add ${selector}`);
+    console.log('Start a new Codex session and invoke the existing skill names. Lifecycle slash-command adaptation is separate.');
+  } 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'}.`);
+  }
+}
+try { main(); } catch (error) { console.error(`${name}: ${error.message}`); process.exitCode = 1; }