@givolt/i3-composer-agent 0.6.12 → 1.0.0

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; }

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const root = path.resolve(__dirname, '..');
+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);
+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);
+assert.equal(brand.upstreamCommit, upstream.upstreamCommit);
+assert.equal(pkg.i3ComposerAgent.upstreamVersion, upstream.upstreamVersion);
+assert.equal(pkg.i3ComposerAgent.upstreamCommit, upstream.upstreamCommit);
+assert.equal(pkg.i3ComposerAgent.upstreamRepository, brand.upstream);
+assert.equal(Object.keys(pkg.bin).length, 1, 'npx must resolve one executable');
+assert.ok(fs.existsSync(path.join(root, pkg.bin[brand.name])));
+for (const relative of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']) {
+  assert.equal(json(relative).name, brand.name, `${relative}: inconsistent plugin identity`);
+}
+for (const relative of ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) {
+  const marketplace = json(relative);
+  assert.equal(marketplace.name, brand.name);
+  assert.equal(marketplace.plugins[0].name, brand.name);
+  assert.ok(marketplace.plugins[0].source === './' || marketplace.plugins[0].source.path === './', 'marketplace must load this distribution');
+}
+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');
+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 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/);
+console.log('Brand identity, package entrypoint, reviewed upstream catalog, and attribution are consistent.');

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

@@ -0,0 +1,85 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const root = path.resolve(__dirname, '..');
+const upstream = require('../rebrand/upstream.json');
+const cli = path.join(root, 'bin/i3-composer-agent.cjs');
+function run(args) { return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8' }); }
+function workspace(t) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-agent-bundle-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  return directory;
+}
+test('help and version identify the package without preparing files', () => {
+  const help = run(['--help']).stdout;
+  assert.match(help, /@givolt\/i3-composer-agent/);
+  assert.ok(help.includes(`i3 Composer Agent v${require('../package.json').version}`));
+  assert.ok(help.includes(`Based on agent-skills v${upstream.upstreamVersion}`));
+  assert.equal(run(['--version']).stdout.trim(), require('../package.json').version);
+});
+test('dry run and invalid arguments leave the target untouched', t => {
+  const target = path.join(workspace(t), 'plugin');
+  assert.equal(run(['--codex', '--dir', target, '--dry-run']).status, 0);
+  assert.equal(fs.existsSync(target), false);
+  assert.equal(run(['--codebuddy', '--codex', '--dir', target]).status, 1);
+  assert.equal(run(['--extract', '--dir']).status, 1);
+  assert.equal(fs.existsSync(target), false);
+});
+test('complete bundle preserves reference links and all host assets at a path with spaces', t => {
+  const target = path.join(workspace(t), 'plugin with spaces');
+  const result = run(['--codebuddy', '--dir', target]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.ok(result.stdout.includes(`i3 Composer Agent v${require('../package.json').version}`));
+  assert.ok(result.stdout.includes(`Based on agent-skills v${upstream.upstreamVersion}`));
+  assert.match(result.stdout, /\/plugin install i3-composer-agent@i3-composer-agent/);
+  assert.equal(fs.readdirSync(path.join(target, 'skills')).length, upstream.skills.length);
+  assert.equal(fs.readdirSync(path.join(target, '.claude/commands')).length, upstream.commands.length);
+  assert.equal(fs.readdirSync(path.join(target, 'agents')).filter(name => name.endsWith('.md')).length, upstream.personas.length);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(target, '.codex-plugin/plugin.json'), 'utf8')).name, 'i3-composer-agent');
+  const check = spawnSync(process.execPath, [path.join(target, 'scripts/validate-reference-links.js')], { cwd: target, encoding: 'utf8' });
+  assert.equal(check.status, 0, check.stdout + check.stderr);
+  assert.equal(fs.existsSync(path.join(target, 'AGENTS.md')), false);
+  assert.equal(fs.existsSync(path.join(target, 'CLAUDE.md')), false);
+});
+test('existing unrelated files cannot be replaced even with force', t => {
+  const target = path.join(workspace(t), 'existing');
+  fs.mkdirSync(target);
+  fs.writeFileSync(path.join(target, 'plugin.json'), '{"name":"another-plugin"}\n');
+  fs.writeFileSync(path.join(target, 'keep.txt'), 'business data');
+  assert.equal(run(['--extract', '--dir', target]).status, 1);
+  assert.equal(run(['--extract', '--dir', target, '--force']).status, 1);
+  assert.equal(fs.readFileSync(path.join(target, 'keep.txt'), 'utf8'), 'business data');
+});
+test('installed packages beneath node_modules remain fully extractable', t => {
+  const parent = workspace(t);
+  const installed = path.join(parent, 'node_modules', '@givolt', 'i3-composer-agent');
+  assert.equal(run(['--extract', '--dir', installed]).status, 0);
+  const target = path.join(parent, 'plugin');
+  const result = spawnSync(process.execPath, [path.join(installed, 'bin/i3-composer-agent.cjs'), '--extract', '--dir', target], { encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8')).name, '@givolt/i3-composer-agent');
+  assert.equal(fs.readdirSync(path.join(target, 'skills')).length, upstream.skills.length);
+});
+test('replacement preserves the complete previous bundle in a backup', t => {
+  const parent = workspace(t);
+  const target = path.join(parent, 'plugin');
+  assert.equal(run(['--extract', '--dir', target]).status, 0);
+  fs.writeFileSync(path.join(target, 'custom-note.txt'), 'preserve me');
+  const result = run(['--extract', '--dir', target, '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  const backups = fs.readdirSync(parent).filter(name => name.startsWith('plugin.backup-'));
+  assert.equal(backups.length, 1);
+  assert.equal(fs.readFileSync(path.join(parent, backups[0], 'custom-note.txt'), 'utf8'), 'preserve me');
+  assert.equal(fs.existsSync(path.join(target, 'custom-note.txt')), false);
+});
+test('source directories and aliases cannot be overwritten', t => {
+  assert.equal(run(['--extract', '--dir', root, '--force']).status, 1);
+  const alias = path.join(workspace(t), 'source-alias');
+  fs.symlinkSync(root, alias, 'dir');
+  assert.equal(run(['--extract', '--dir', alias, '--force']).status, 1);
+});

package/rebrand/package.template.json

@@ -0,0 +1,82 @@
+{
+  "name": "@givolt/i3-composer-agent",
+  "description": "i3 Composer Agent: production-grade engineering skills and lifecycle commands for AI coding agents.",
+  "license": "MIT",
+  "author": "Givolt",
+  "contributors": [
+    {
+      "name": "Addy Osmani"
+    }
+  ],
+  "bin": {
+    "i3-composer-agent": "bin/i3-composer-agent.cjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "references/",
+    "agents/",
+    "commands/",
+    ".claude/commands/",
+    ".gemini/commands/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".agents/plugins/",
+    "hooks/",
+    "docs/",
+    "scripts/",
+    "evals/",
+    "rebrand/",
+    "tests/",
+    "plugin.json",
+    "NOTICE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "rebrand": "node rebrand/apply.cjs --apply",
+    "rebrand:check": "node rebrand/apply.cjs --check",
+    "validate": "node scripts/validate-brand.cjs && node scripts/validate-skills.js && node scripts/validate-versions.js && node scripts/validate-commands.js && node scripts/validate-reference-links.js && node scripts/validate-artifact-paths.js",
+    "test": "node --test scripts/*-test.js scripts/lib/*-test.js tests/*.test.cjs rebrand/tests/*.test.cjs",
+    "prepack": "npm run validate"
+  },
+  "keywords": [
+    "i3-composer",
+    "agent-skills",
+    "codebuddy",
+    "codex",
+    "claude-code"
+  ],
+  "i3ComposerAgent": {
+    "pluginFiles": [
+      "bin",
+      "skills",
+      "references",
+      "agents",
+      "commands",
+      ".claude/commands",
+      ".gemini/commands",
+      ".claude-plugin",
+      ".codex-plugin",
+      ".agents/plugins",
+      "hooks",
+      "docs",
+      "scripts",
+      "evals",
+      "rebrand",
+      "tests",
+      "plugin.json",
+      "package.json",
+      "README.md",
+      "LICENSE",
+      "NOTICE.md",
+      "CHANGELOG.md"
+    ]
+  }
+}

package/rebrand/rebrand.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+exec node "$ROOT/rebrand/apply.cjs" "${1:---check}"

package/rebrand/record-upstream.cjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { describe, runtimeRoots, runtimeFiles } = require('./catalog.cjs');
+const root = path.resolve(__dirname, '..');
+const ref = process.argv[2];
+if (!ref || ref.startsWith('-') || process.argv.length !== 3) {
+  console.error('Usage: node rebrand/record-upstream.cjs <reviewed upstream ref>');
+  process.exit(1);
+}
+try {
+  const git = args => execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  const commit = git(['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+  const entries = git(['ls-tree', '-rz', commit, '--', ...runtimeRoots, ...runtimeFiles]).split('\0').filter(Boolean);
+  const blobs = new Map(entries.filter(line => /^100\d+ blob /.test(line)).map(line => {
+    const [metadata, file] = line.split('\t');
+    return [file, metadata.split(' ')[2]];
+  }));
+  const read = file => git(['cat-file', 'blob', blobs.get(file)]);
+  const snapshot = {
+    upstreamCommit: commit,
+    upstreamVersion: JSON.parse(read('plugin.json')).version,
+    ...describe([...blobs.keys()], read),
+  };
+  fs.writeFileSync(path.join(__dirname, 'upstream.json'), JSON.stringify(snapshot, null, 2) + '\n');
+  const brandFile = path.join(__dirname, 'brand.json');
+  const brand = JSON.parse(fs.readFileSync(brandFile, 'utf8'));
+  brand.upstreamCommit = commit;
+  fs.writeFileSync(brandFile, JSON.stringify(brand, null, 2) + '\n');
+  console.log(JSON.stringify({ commit, version: snapshot.upstreamVersion, skills: snapshot.skills.length, commands: snapshot.commands.length }));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}