@givolt/i3-composer-agent 0.6.12 → 1.0.0

package/rebrand/templates/README.md

@@ -1,178 +1,86 @@
-# i3 Composer Agent
+# i3 Composer Agent v{{RELEASE_VERSION}}
 
-**Intelligence. Integration. Innovation.**
+**Based on agent-skills v{{UPSTREAM_VERSION}}**
 
-Production-grade engineering skills, lifecycle commands, and specialist personas
-for AI coding agents. This is the engineering-skill product in the i3 Composer
-family; the GSD-derived workflow product is maintained separately.
+**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 and the upstream baseline.
+(MIT). See [NOTICE.md](NOTICE.md) for attribution.
 
-## Prepare the complete plugin with npx
+The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
+`i3-composer-agent`. Skill IDs retain their upstream names.
 
-The npm package is `@givolt/i3-composer-agent`. The plugin and marketplace ID is
-`i3-composer-agent`. Skill IDs and workflow behavior retain their upstream names.
+## Prepare the complete plugin
 
-Once the package is published, run this in the project where you want to use it:
+Run in the project where you want to prepare the plugin:
 
 ```bash
 npx @givolt/i3-composer-agent --codebuddy
-# Or prepare a bundle for another host:
+# Other hosts:
 npx @givolt/i3-composer-agent --codex
 npx @givolt/i3-composer-agent --claude
 ```
 
-The CLI prepares a persistent `./i3-composer-agent/` directory with all 25 skills,
-9 commands, 4 personas, and shared references. It prints the native registration
-commands; run those in the selected host to enable the plugin.
+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
+CodeBuddy / Claude Code:
 
 ```text
 /plugin marketplace add ./i3-composer-agent
 /plugin install i3-composer-agent@i3-composer-agent
 ```
 
-Use the absolute directory printed by the CLI if the host has a different
-working directory. See [CodeBuddy setup](docs/codebuddy-setup.md).
-
-### Codex
+Codex:
 
 ```bash
 codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new Codex session. Invoke the existing skills by name, using `/skills`
-or `$spec-driven-development` in CLI/IDE. This conversion preserves Codex's
-skill adapter; lifecycle slash-command adaptation is a separate task.
-See [Codex setup](docs/codex-setup.md).
-
-### Bundle options
-
-```bash
-npx @givolt/i3-composer-agent --extract --dir /path/to/i3-composer-agent
-npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
-npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
-```
-
-An existing directory is refused unless `--force` targets an i3 Composer Agent
-bundle. Replacement keeps the previous directory as a backup. No repository
-AGENTS.md or CLAUDE.md is copied into the target project.
+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.
-Use the namespaced form, for example `/i3-composer-agent:spec`.
+Hosts supporting Claude-compatible plugin commands load these workflows:
 
-| Command | Workflow |
+| Command | Description |
 | --- | --- |
-| `/i3-composer-agent:spec` | Define objectives, constraints, and acceptance criteria |
-| `/i3-composer-agent:plan` | Write ordered, verifiable tasks |
-| `/i3-composer-agent:build` | Implement the next task with verification |
-| `/i3-composer-agent:build auto` | Execute the approved plan with per-task verification |
-| `/i3-composer-agent:test` | Test-first development and regression checks |
-| `/i3-composer-agent:constraints` | Establish a written quality bar |
-| `/i3-composer-agent:review` | Review code quality and correctness |
-| `/i3-composer-agent:webperf` | Audit web performance |
-| `/i3-composer-agent:code-simplify` | Simplify code without changing behavior |
-| `/i3-composer-agent:ship` | Review launch readiness and rollback |
-
-## All 25 Skills
-
-The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
-
-### Meta - Discover which skill applies
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
-
-### Define - Clarify what to build
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
-| [idea-refine](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
-| [spec-driven-development](skills/spec-driven-development/SKILL.md) | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |
-| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Interviews you for a quality bar with sane default thresholds, writes CONSTRAINTS.md, places each check by cost, and catches agents silencing checks or skipping tests to get green | No standards are written down, or an agent is producing more than anyone reads |
+{{COMMAND_TABLE}}
 
-### Plan - Break it down
+`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
 
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |
+## Skills
 
-### Build - Write the code
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [incremental-implementation](skills/incremental-implementation/SKILL.md) | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
-| [test-driven-development](skills/test-driven-development/SKILL.md) | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
-| [context-engineering](skills/context-engineering/SKILL.md) | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |
-| [source-driven-development](skills/source-driven-development/SKILL.md) | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
-| [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
-| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
-| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
-
-### Verify - Prove it works
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |
-| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
-
-### Review - Quality gates before merge
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
-| [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
-| [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
-| [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
-
-### Ship - Deploy with confidence
-
-| Skill | What It Does | Use When |
-|-------|-------------|----------|
-| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
-| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
-| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
-| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features |
-| [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
-| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
-
----
-
-## Personas and shared references
-
-The four original personas remain in [agents/](agents/): code reviewer, security
-auditor, test engineer, and web performance auditor. Shared checklists remain in [references/](references/).
-Their relative layout is preserved across npm packaging and bundle extraction.
-
-## Other hosts
-
-The existing [host guides](docs/other-hosts.md) describe additional integrations.
-Prepare the complete local bundle first and use its path in host-specific setup.
-Per-skill installation is separate and may omit the shared references, command
-wrappers, and personas.
+| Skill | Description |
+| --- | --- |
+{{SKILL_TABLE}}
 
-## Development and release
+## Bundle options
 
 ```bash
-npm run rebrand:check
-npm run validate
-npm test
-node scripts/run-evals.js --min-rank1 95
-npm pack --pack-destination /path/to/release-directory
+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
 ```
 
-[npx](https://docs.npmjs.com/cli/npm-exec/) runs the package executable;
-`npm pack` builds a tarball and `npm publish` publishes it.
-Local preparation does not establish registry publication or model behavior.
-See [brand maintenance](rebrand/MAINTENANCE.md) for source/release separation.
+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
 
-## License
+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.
 
-MIT. Original copyright and license are retained in [LICENSE](LICENSE).
+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/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);
+});

package/rebrand/upstream.json

@@ -0,0 +1,171 @@
+{
+  "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
+  "upstreamVersion": "0.6.12",
+  "skills": [
+    "api-and-interface-design",
+    "browser-testing-with-devtools",
+    "ci-cd-and-automation",
+    "code-review-and-quality",
+    "code-simplification",
+    "constraint-driven-development",
+    "context-engineering",
+    "debugging-and-error-recovery",
+    "deprecation-and-migration",
+    "documentation-and-adrs",
+    "doubt-driven-development",
+    "frontend-ui-engineering",
+    "git-workflow-and-versioning",
+    "idea-refine",
+    "incremental-implementation",
+    "interview-me",
+    "observability-and-instrumentation",
+    "performance-optimization",
+    "planning-and-task-breakdown",
+    "security-and-hardening",
+    "shipping-and-launch",
+    "source-driven-development",
+    "spec-driven-development",
+    "test-driven-development",
+    "using-agent-skills"
+  ],
+  "commands": [
+    "build",
+    "code-simplify",
+    "constraints",
+    "plan",
+    "review",
+    "ship",
+    "spec",
+    "test",
+    "webperf"
+  ],
+  "personas": [
+    "code-reviewer",
+    "security-auditor",
+    "test-engineer",
+    "web-performance-auditor"
+  ],
+  "references": [
+    "references/accessibility-checklist.md",
+    "references/definition-of-done.md",
+    "references/observability-checklist.md",
+    "references/orchestration-patterns.md",
+    "references/performance-checklist.md",
+    "references/security-checklist.md",
+    "references/testing-patterns.md"
+  ],
+  "runtimeFiles": [
+    ".agents/plugins/marketplace.json",
+    ".claude-plugin/marketplace.json",
+    ".claude-plugin/plugin.json",
+    ".claude/commands/build.md",
+    ".claude/commands/code-simplify.md",
+    ".claude/commands/constraints.md",
+    ".claude/commands/plan.md",
+    ".claude/commands/review.md",
+    ".claude/commands/ship.md",
+    ".claude/commands/spec.md",
+    ".claude/commands/test.md",
+    ".claude/commands/webperf.md",
+    ".codex-plugin/plugin.json",
+    ".gemini/commands/build.toml",
+    ".gemini/commands/code-simplify.toml",
+    ".gemini/commands/constraints.toml",
+    ".gemini/commands/planning.toml",
+    ".gemini/commands/review.toml",
+    ".gemini/commands/ship.toml",
+    ".gemini/commands/spec.toml",
+    ".gemini/commands/test.toml",
+    ".gemini/commands/webperf.toml",
+    "LICENSE",
+    "agents/code-reviewer.md",
+    "agents/security-auditor.md",
+    "agents/test-engineer.md",
+    "agents/web-performance-auditor.md",
+    "commands/build.toml",
+    "commands/code-simplify.toml",
+    "commands/constraints.toml",
+    "commands/planning.toml",
+    "commands/review.toml",
+    "commands/ship.toml",
+    "commands/spec.toml",
+    "commands/test.toml",
+    "commands/webperf.toml",
+    "hooks/SDD-CACHE.md",
+    "hooks/SIMPLIFY-IGNORE.md",
+    "hooks/sdd-cache-post.sh",
+    "hooks/sdd-cache-pre.sh",
+    "hooks/sdd-cache-test.sh",
+    "hooks/session-start-test.sh",
+    "hooks/session-start.sh",
+    "hooks/simplify-ignore-test.sh",
+    "hooks/simplify-ignore.sh",
+    "plugin.json",
+    "references/accessibility-checklist.md",
+    "references/definition-of-done.md",
+    "references/observability-checklist.md",
+    "references/orchestration-patterns.md",
+    "references/performance-checklist.md",
+    "references/security-checklist.md",
+    "references/testing-patterns.md",
+    "skills/api-and-interface-design/SKILL.md",
+    "skills/browser-testing-with-devtools/SKILL.md",
+    "skills/ci-cd-and-automation/SKILL.md",
+    "skills/code-review-and-quality/SKILL.md",
+    "skills/code-simplification/SKILL.md",
+    "skills/constraint-driven-development/SKILL.md",
+    "skills/constraint-driven-development/references/floor-guard.md",
+    "skills/context-engineering/SKILL.md",
+    "skills/debugging-and-error-recovery/SKILL.md",
+    "skills/deprecation-and-migration/SKILL.md",
+    "skills/documentation-and-adrs/SKILL.md",
+    "skills/doubt-driven-development/SKILL.md",
+    "skills/frontend-ui-engineering/SKILL.md",
+    "skills/git-workflow-and-versioning/SKILL.md",
+    "skills/idea-refine/SKILL.md",
+    "skills/idea-refine/examples.md",
+    "skills/idea-refine/frameworks.md",
+    "skills/idea-refine/refinement-criteria.md",
+    "skills/idea-refine/scripts/idea-refine.sh",
+    "skills/incremental-implementation/SKILL.md",
+    "skills/interview-me/SKILL.md",
+    "skills/observability-and-instrumentation/SKILL.md",
+    "skills/performance-optimization/SKILL.md",
+    "skills/performance-optimization/references/optimization-patterns.md",
+    "skills/planning-and-task-breakdown/SKILL.md",
+    "skills/security-and-hardening/SKILL.md",
+    "skills/security-and-hardening/references/hardening-patterns.md",
+    "skills/shipping-and-launch/SKILL.md",
+    "skills/source-driven-development/SKILL.md",
+    "skills/spec-driven-development/SKILL.md",
+    "skills/test-driven-development/SKILL.md",
+    "skills/using-agent-skills/SKILL.md"
+  ],
+  "skillFrontmatter": {
+    "api-and-interface-design": "44f904d462977e9514f439ac7c057b8691613ba8160360ad9d28b830d3a24001",
+    "browser-testing-with-devtools": "e235631718d18a0527d00eb718ecece2218bbf205d742632f8197b30c052e96b",
+    "ci-cd-and-automation": "dd73253ec445a9af27ebeab74404ee7a770919e40ec9db0b34af4fa9ec36bf7c",
+    "code-review-and-quality": "bf3dda5e08190fcf00175a5053f53550bca91ca32b0a06e4b97cd33e046e8eb7",
+    "code-simplification": "cee4dc87b4bc95d77fe646d4ab9e66c9a422dd081a833d657d618aaf2967b5a2",
+    "constraint-driven-development": "0da347bd34b155ab79cad1e0ee80238f3b4b91b1a17ca0fc2f68460c02224194",
+    "context-engineering": "f4f18514e5eeb162ef9f925dea85af2c72ba79f9b157783a06c39c0bde102d3f",
+    "debugging-and-error-recovery": "658d96f63d56946214a7ec87be0347c78d6024a18f6481dc9f7310638f403629",
+    "deprecation-and-migration": "388d5e7e549f1b728213f0f50d91e9ca96210e0cb23fd9fccd30755268dd01f9",
+    "documentation-and-adrs": "6b2a9d19ebbb81570022a89f09b4810eeb0643a48c698989ee27a224f90bc026",
+    "doubt-driven-development": "df8954091f08c14b0e91bf3bf330f43d5a8408c1efe697591b7b0e8448251c71",
+    "frontend-ui-engineering": "323624fe7ec44bdb4fad3c9488e55993119912625fffa20ee5787389da2b600d",
+    "git-workflow-and-versioning": "dd28469b0f294865dbd20d622a9fee5f05ef87ab1599e973fec6d15a16f76e15",
+    "idea-refine": "07eedcfcba98c6c8f6985917830c4b3d93d4e17af05a9b2ca1b8cb54226bc1b9",
+    "incremental-implementation": "d31e04a0d7b07fc7d01e0176aafbba5607f1cfe7a29a634498305d95c2b3bd3b",
+    "interview-me": "62700902b592a4fa28f6f71f2581d4e1dee412ff288eb156ed97fac3db8b4295",
+    "observability-and-instrumentation": "652b9724e431bd7cfd4481bbab31bb079eeab2b5f70ebc04cf66743e37028721",
+    "performance-optimization": "76befb0806caad12322de8fe372d2e984f6e07c393fd8d3658537c92c7e285cf",
+    "planning-and-task-breakdown": "c3bc139dfa7af82e2d11c7cf461bbf923add7d6494d669da98925f77a7671641",
+    "security-and-hardening": "981142e38769394e6e7760250f2dd599dff21a370040f3f141c42507f04ea540",
+    "shipping-and-launch": "02cc76557e581957cb4987a53e03a8d1aa04c72dc735390d52ae4eed3ddeddf9",
+    "source-driven-development": "233bf9f16f5fe0960c988a5feb2efc475b9b24f9e145d960f8c63e44f4f34fde",
+    "spec-driven-development": "e21f25e534ffa3e2de9ac08c40f8d1d90cef17ad55702f83301cbc2a297c2dcb",
+    "test-driven-development": "38f1489687eaa60761522a8e3efaa926b52786b0e1b3c57947a6050c0da340de",
+    "using-agent-skills": "df5d4f61855ac46da3371bad8c05edb8bc9375ba191acc82b0cca257cfec946c"
+  }
+}

package/scripts/validate-brand.cjs

@@ -7,8 +7,16 @@ 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']) {
@@ -22,10 +30,10 @@ for (const relative of ['.claude-plugin/marketplace.json', '.agents/plugins/mark
 }
 assert.ok(json('.codex-plugin/plugin.json').interface.shortDescription.length <= 30);
 const skills = fs.readdirSync(path.join(root, 'skills')).filter(name => fs.existsSync(path.join(root, 'skills', name, 'SKILL.md')));
-assert.equal(skills.length, 25, 'brand conversion must preserve the 25-skill collection');
+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, 9, 'brand conversion must preserve the nine commands');
+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`);
@@ -33,4 +41,4 @@ for (const command of commands) {
 }
 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, 25 skills, nine commands, and upstream attribution are consistent.');
+console.log('Brand identity, package entrypoint, reviewed upstream catalog, and attribution are consistent.');