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

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

package/rebrand/templates/README.md

@@ -0,0 +1,86 @@
+# i3 Composer Agent v{{RELEASE_VERSION}}
+
+**Based on agent-skills v{{UPSTREAM_VERSION}}**
+
+**Intelligence. Integration. Innovation.**
+
+Engineering skills, lifecycle commands, and specialist personas for AI coding agents.
+Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani
+(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.
+
+## Prepare the complete plugin
+
+Run in the project where you want to prepare the plugin:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+# Other hosts:
+npx @givolt/i3-composer-agent --codex
+npx @givolt/i3-composer-agent --claude
+```
+
+The command prepares a persistent `./i3-composer-agent/` directory containing
+{{SKILL_COUNT}} skills, {{COMMAND_COUNT}} commands, {{PERSONA_COUNT}} personas,
+and shared references. It prints native registration commands; run those in
+the selected host to enable the plugin. Preparing files does not select a host
+installation scope. See [CodeBuddy setup](docs/codebuddy-setup.md) and
+[Codex setup](docs/codex-setup.md).
+
+CodeBuddy / Claude Code:
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Codex:
+
+```bash
+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
+is maintained separately.
+
+## Commands
+
+Hosts supporting Claude-compatible plugin commands load these workflows:
+
+| Command | Description |
+| --- | --- |
+{{COMMAND_TABLE}}
+
+`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
+
+## Skills
+
+| Skill | Description |
+| --- | --- |
+{{SKILL_TABLE}}
+
+## Bundle options
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir /path/to/plugin
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
+```
+
+Replacement preserves the previous i3 bundle as a backup. Repository-scoped
+AGENTS.md and CLAUDE.md are not copied into business projects.
+
+## Maintaining this fork
+
+This repository is independent of the GSD-based i3 Composer Work repository.
+`agent/source` retains upstream source and the `rebrand/` rules; `main` contains
+the validated branded distribution. Create release candidates from the source
+branch, replay branding, validate, then update the release branch.
+
+See [maintenance](rebrand/MAINTENANCE.md), [source PR workflow](rebrand/PR-WORKFLOW.md),
+[versioning](rebrand/VERSIONING.md), [changelog](CHANGELOG.md),
+and [validation contract](rebrand/VALIDATION.md).

package/rebrand/templates/codebuddy-setup.md

@@ -0,0 +1,41 @@
+# Using i3 Composer Agent with CodeBuddy
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+```
+
+In the CodeBuddy chat, register the prepared directory and install the plugin:
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Use the absolute directory printed by the CLI if CodeBuddy has a different
+working directory. Choose the intended installation scope in CodeBuddy's native
+plugin manager. Reload plugins or start a new session after installation.
+
+CodeBuddy supports the existing `.claude-plugin/plugin.json` compatibility
+manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
+original lifecycle commands and their workflow content.
+
+```text
+/i3-composer-agent:spec
+/i3-composer-agent:plan
+/i3-composer-agent:build
+/i3-composer-agent:build auto
+/i3-composer-agent:review
+/i3-composer-agent:ship
+```
+
+Skill IDs, persona names, artifact paths, and workflow gates retain their
+upstream behavior. The plugin namespace changes to `i3-composer-agent`.
+
+The bundle includes all skills and shared `references/`. Installing individual
+skills is a different distribution method and does not install the command
+wrappers or persona definitions.
+
+The CLI prepares files and prints registration commands. Actual host discovery
+and model execution should be verified after registering the plugin.

package/rebrand/templates/codex-setup.md

@@ -0,0 +1,34 @@
+# Using i3 Composer Agent with Codex
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codex
+```
+
+The CLI copies a persistent `./i3-composer-agent/` bundle and prints these
+native registration commands. Run them to enable the plugin:
+
+```bash
+codex plugin marketplace add ./i3-composer-agent
+codex plugin add i3-composer-agent@i3-composer-agent
+```
+
+Start a new Codex session after registration. All 25 existing skills keep their
+original IDs. In CLI/IDE, use `/skills` or `$spec-driven-development`; in chat,
+explicitly request the relevant skill from i3 Composer Agent.
+
+The adapter in `.codex-plugin/plugin.json` points at the unchanged `skills/`
+layout. Shared checklists remain under `references/`, so skill-relative links
+resolve inside the complete plugin bundle.
+
+The short lifecycle commands (`/spec`, `/plan`, `/build`, `/ship`) remain
+available in hosts that load the Claude-compatible command manifest. Codex
+lifecycle-command adaptation is separate from this brand conversion. Native
+Codex `/plan` switches planning mode; it is not the plugin's planning wrapper.
+
+Do not preload `using-agent-skills/SKILL.md` into always-on context: Codex routes
+skills natively. The meta-skill can remain installed and explicitly invoked.
+
+For local source testing, replace `./i3-composer-agent` above with the absolute
+path to the branded checkout. The CLI does not modify existing plugin settings.

package/rebrand/tests/pipeline.test.cjs

@@ -0,0 +1,185 @@
+'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 baselineVersion = require('../upstream.json').upstreamVersion;
+
+function run(directory, executable, args) {
+  return spawnSync(executable, args, { cwd: directory, encoding: 'utf8' });
+}
+function git(directory, args) {
+  const result = run(directory, 'git', args);
+  assert.equal(result.status, 0, result.stderr);
+  return result.stdout.trim();
+}
+function node(directory, file, args = []) { return run(directory, process.execPath, [file, ...args]); }
+function fixture(t, branch = 'release/test-candidate') {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-agent-replay-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  for (const name of ['skills', 'references', 'agents', 'commands', '.claude', '.gemini', '.claude-plugin', '.codex-plugin', '.agents', 'hooks', 'docs', 'scripts', 'evals', 'rebrand', 'LICENSE', 'plugin.json', 'README.md']) {
+    fs.cpSync(path.join(root, name), path.join(directory, name), { recursive: true, filter: file => !file.includes(`${path.sep}results${path.sep}`) });
+  }
+  // Model an upstream source checkout, including when this suite runs in a packed branded bundle.
+  for (const name of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']) {
+    const file = path.join(directory, name);
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    data.name = 'agent-skills';
+    data.version = baselineVersion;
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+  }
+  git(directory, ['init', '--initial-branch', branch]);
+  git(directory, ['config', 'user.name', 'Pipeline Test']);
+  git(directory, ['config', 'user.email', 'pipeline@example.test']);
+  git(directory, ['add', '.']);
+  git(directory, ['commit', '-m', 'upstream fixture']);
+  return directory;
+}
+function record(directory) {
+  const result = node(directory, 'rebrand/record-upstream.cjs', ['HEAD']);
+  assert.equal(result.status, 0, result.stderr);
+}
+function apply(directory) {
+  const result = node(directory, 'rebrand/apply.cjs', ['--apply']);
+  assert.equal(result.status, 0, result.stderr);
+}
+
+test('a source checkout generates a complete, repeatable branded distribution', t => {
+  const directory = fixture(t);
+  record(directory);
+  apply(directory);
+  const pkg = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8'));
+  assert.equal(pkg.name, '@givolt/i3-composer-agent');
+  const brand = JSON.parse(fs.readFileSync(path.join(directory, 'rebrand/brand.json'), 'utf8'));
+  assert.equal(pkg.version, brand.releaseVersion);
+  assert.equal(fs.existsSync(path.join(directory, 'bin/i3-composer-agent.cjs')), true);
+  assert.equal(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  const check = node(directory, 'rebrand/apply.cjs', ['--check']);
+  assert.equal(check.status, 0, check.stdout + check.stderr);
+});
+
+test('brand fixes advance independently while preserving upstream provenance', t => {
+  const directory = fixture(t);
+  record(directory);
+  const upstreamFile = path.join(directory, 'rebrand/upstream.json');
+  const originalUpstream = fs.readFileSync(upstreamFile, 'utf8');
+  const upstream = JSON.parse(originalUpstream);
+  const brandFile = path.join(directory, 'rebrand/brand.json');
+  const brand = JSON.parse(fs.readFileSync(brandFile, 'utf8'));
+  const releaseVersion = `${Number(upstream.upstreamVersion.split('.')[0]) + 1}.0.1`;
+  brand.releaseVersion = releaseVersion;
+  fs.writeFileSync(brandFile, JSON.stringify(brand, null, 2) + '\n');
+  apply(directory);
+  const packageFile = path.join(directory, 'package.json');
+  const originalPackage = fs.readFileSync(packageFile, 'utf8');
+  const pkg = JSON.parse(originalPackage);
+  assert.equal(pkg.version, releaseVersion);
+  assert.equal(pkg.i3ComposerAgent.upstreamVersion, upstream.upstreamVersion);
+  assert.equal(pkg.i3ComposerAgent.upstreamCommit, upstream.upstreamCommit);
+  assert.equal(fs.readFileSync(upstreamFile, 'utf8'), originalUpstream);
+  const releaseLabel = `i3 Composer Agent v${releaseVersion}`;
+  const upstreamLabel = `Based on agent-skills v${upstream.upstreamVersion}`;
+  for (const output of [fs.readFileSync(path.join(directory, 'README.md'), 'utf8'), node(directory, 'bin/i3-composer-agent.cjs', ['--help']).stdout]) {
+    assert.ok(output.includes(releaseLabel), output);
+    assert.ok(output.includes(upstreamLabel), output);
+  }
+  assert.equal(node(directory, 'bin/i3-composer-agent.cjs', ['--version']).stdout.trim(), releaseVersion);
+  const dryRun = node(directory, 'bin/i3-composer-agent.cjs', ['--extract', '--dry-run', '--dir', directory + '-prepared']);
+  assert.equal(dryRun.status, 0, dryRun.stderr);
+  assert.equal(JSON.parse(dryRun.stdout).upstreamVersion, upstream.upstreamVersion);
+  assert.equal(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  pkg.i3ComposerAgent.upstreamVersion = releaseVersion;
+  fs.writeFileSync(packageFile, JSON.stringify(pkg));
+  assert.notEqual(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  fs.writeFileSync(packageFile, originalPackage);
+  assert.equal(node(directory, 'rebrand/apply.cjs', ['--check']).status, 0);
+});
+
+test('writing a brand transform on the protected source branch changes nothing', t => {
+  const directory = fixture(t, 'agent/source');
+  const before = fs.readFileSync(path.join(directory, 'plugin.json'));
+  const result = node(directory, 'rebrand/apply.cjs', ['--apply']);
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /source branch/i);
+  assert.deepEqual(fs.readFileSync(path.join(directory, 'plugin.json')), before);
+  assert.equal(fs.existsSync(path.join(directory, 'package.json')), false);
+});
+
+test('a reviewed upstream catalog can grow without losing its new skill or command', t => {
+  const directory = fixture(t);
+  const skill = path.join(directory, 'skills/upstream-new-skill');
+  fs.mkdirSync(skill);
+  fs.writeFileSync(path.join(skill, 'SKILL.md'), '---\nname: upstream-new-skill\ndescription: New upstream capability.\n---\n# Upstream capability\n');
+  fs.writeFileSync(path.join(directory, '.claude/commands/upstream-new-command.md'), '---\ndescription: Invoke the new upstream capability.\n---\nUse agent-skills:upstream-new-skill.\n');
+  git(directory, ['add', 'skills', '.claude/commands']);
+  git(directory, ['commit', '-m', 'new upstream capability']);
+  record(directory);
+  apply(directory);
+  const result = node(directory, 'scripts/validate-brand.cjs');
+  assert.equal(result.status, 0, result.stderr);
+  const description = JSON.parse(fs.readFileSync(path.join(directory, '.codex-plugin/plugin.json'), 'utf8')).interface.longDescription;
+  assert.match(description, /26 engineering skills/);
+  const readme = fs.readFileSync(path.join(directory, 'README.md'), 'utf8');
+  assert.match(readme, /upstream-new-skill/);
+  assert.match(readme, /upstream-new-command/);
+});
+
+test('missing files and altered skill identifiers fail preservation validation', t => {
+  const directory = fixture(t);
+  record(directory);
+  apply(directory);
+  const file = path.join(directory, 'skills/using-agent-skills/SKILL.md');
+  const original = fs.readFileSync(file, 'utf8');
+  fs.writeFileSync(file, original.replace('name: using-agent-skills', 'name: renamed-meta-skill'));
+  assert.notEqual(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  fs.writeFileSync(file, original);
+  fs.rmSync(file);
+  assert.notEqual(node(directory, 'scripts/validate-brand.cjs').status, 0);
+});
+
+test('checkout line endings do not masquerade as an upstream skill change', t => {
+  const directory = fixture(t);
+  record(directory);
+  const file = path.join(directory, 'skills/using-agent-skills/SKILL.md');
+  fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace(/\r?\n/g, '\r\n'));
+  const script = path.join(directory, 'scripts/validate-versions.js');
+  fs.writeFileSync(script, fs.readFileSync(script, 'utf8').replace(/\r?\n/g, '\r\n'));
+  apply(directory);
+  assert.equal(node(directory, 'scripts/validate-brand.cjs').status, 0);
+});
+
+test('a new upstream package manifest requires an explicit distribution adaptation', t => {
+  const directory = fixture(t);
+  record(directory);
+  fs.writeFileSync(path.join(directory, 'package.json'), '{"name":"agent-skills","dependencies":{"upstream-runtime":"1.0.0"}}\n');
+  const before = fs.readFileSync(path.join(directory, 'plugin.json'));
+  const result = node(directory, 'rebrand/apply.cjs', ['--apply']);
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /package\.json/);
+  assert.deepEqual(fs.readFileSync(path.join(directory, 'plugin.json')), before);
+});
+
+test('a distribution without repository CI files remains unchanged by a replay check', t => {
+  const directory = fixture(t);
+  record(directory);
+  apply(directory);
+  fs.rmSync(path.join(directory, '.github'), { recursive: true, force: true });
+  const result = node(directory, 'rebrand/apply.cjs', ['--check']);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.equal(fs.existsSync(path.join(directory, '.github')), false);
+});
+
+test('Finder metadata does not masquerade as an upstream runtime file', t => {
+  const directory = fixture(t);
+  record(directory);
+  fs.writeFileSync(path.join(directory, 'skills/.DS_Store'), 'Finder metadata');
+  fs.writeFileSync(path.join(directory, 'skills/spec-driven-development/.DS_Store'), 'Finder metadata');
+  apply(directory);
+  assert.equal(node(directory, 'scripts/validate-brand.cjs').status, 0);
+  const result = node(directory, 'rebrand/apply.cjs', ['--check']);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});