@givolt/i3-composer-agent 0.6.12 → 1.0.1

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

@@ -0,0 +1,193 @@
+'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 cli = path.join(root, 'bin/i3-composer-agent.cjs');
+const upstream = require('../rebrand/upstream.json');
+function workspace(t) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-agent-install-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  return fs.realpathSync(directory);
+}
+function run(directory, args) {
+  return spawnSync(process.execPath, [cli, ...args], { cwd: directory, encoding: 'utf8' });
+}
+test('native CodeBuddy installation includes short commands, personas and usable references', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--codebuddy', '--scope', 'project', '--yes']);
+  assert.equal(result.status, 0, result.stderr);
+  const base = path.join(directory, '.codebuddy');
+  assert.equal(fs.readdirSync(path.join(base, 'skills')).length, upstream.skills.length);
+  assert.equal(fs.readdirSync(path.join(base, 'commands')).length, upstream.commands.length);
+  assert.equal(fs.readdirSync(path.join(base, 'agents')).length, upstream.personas.length);
+  const command = fs.readFileSync(path.join(base, 'commands/spec.md'), 'utf8');
+  assert.match(command, /Invoke the spec-driven-development skill/);
+  assert.doesNotMatch(command, /i3-composer-agent:/);
+  const ship = fs.readFileSync(path.join(base, 'commands/ship.md'), 'utf8');
+  assert.match(ship, /\.codebuddy\/agents\//);
+  assert.doesNotMatch(ship, /\.claude\/agents\//);
+  assert.ok(fs.existsSync(path.join(base, 'references/definition-of-done.md')));
+  assert.equal(fs.readFileSync(path.join(base, 'i3-composer-agent-LICENSE'), 'utf8'), fs.readFileSync(path.join(root, 'LICENSE'), 'utf8'));
+  assert.match(fs.readFileSync(path.join(base, 'i3-composer-agent-NOTICE.md'), 'utf8'), /Addy Osmani/);
+  assert.equal(fs.existsSync(path.join(directory, 'AGENTS.md')), false);
+  assert.equal(fs.existsSync(path.join(directory, 'i3-composer-agent')), false);
+  assert.match(result.stdout, /\/spec/);
+});
+test('multiple tools retain their own destinations and share universal skills without duplicate work', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--agents', 'codebuddy,codex,cursor,claude-code', '--scope', 'project', '--yes']);
+  assert.equal(result.status, 0, result.stderr);
+  for (const base of ['.codebuddy', '.agents', '.claude']) {
+    assert.equal(fs.readdirSync(path.join(directory, base, 'skills')).length, upstream.skills.length);
+    assert.ok(fs.existsSync(path.join(directory, base, 'references/testing-patterns.md')));
+  }
+  const manifest = JSON.parse(fs.readFileSync(path.join(directory, '.agents/.i3-composer-agent.json')));
+  assert.deepEqual(manifest.agents.sort(), ['codex', 'cursor']);
+  assert.equal(fs.existsSync(path.join(directory, '.agents/commands')), false);
+});
+test('installation dry run describes scope and destinations without changing project files', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--agents', 'codebuddy,codex', '--scope', 'project', '--dry-run']);
+  assert.equal(result.status, 0, result.stderr);
+  const plan = JSON.parse(result.stdout);
+  assert.equal(plan.mode, 'install');
+  assert.equal(plan.scope, 'project');
+  assert.equal(plan.targets.length, 2);
+  assert.deepEqual(fs.readdirSync(directory), []);
+});
+test('all copied Markdown reference links and stable skill frontmatter remain valid', t => {
+  const directory = workspace(t);
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes']).status, 0);
+  const base = path.join(directory, '.codebuddy');
+  function visit(folder) {
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+      const file = path.join(folder, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name.endsWith('.md')) {
+        const content = fs.readFileSync(file, 'utf8');
+        for (const match of content.matchAll(/\]\(([^)]+)\)/g)) {
+          const relative = match[1].split('#')[0];
+          if (relative.includes('references/') && !/^[a-z]+:/i.test(relative)) {
+            assert.ok(fs.existsSync(path.resolve(path.dirname(file), relative)), `${file}: ${relative}`);
+          }
+        }
+      }
+    }
+  }
+  visit(path.join(base, 'skills'));
+  for (const id of upstream.skills) {
+    const head = content => content.match(/^---\r?\n[\s\S]*?\r?\n---/)[0];
+    assert.equal(head(fs.readFileSync(path.join(base, 'skills', id, 'SKILL.md'), 'utf8')), head(fs.readFileSync(path.join(root, 'skills', id, 'SKILL.md'), 'utf8')));
+  }
+});
+test('existing assets are protected; confirmed replacement backs them up and preserves unrelated settings', t => {
+  const directory = workspace(t);
+  const base = path.join(directory, '.codebuddy');
+  fs.mkdirSync(path.join(base, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(base, 'commands/spec.md'), 'my custom command');
+  fs.writeFileSync(path.join(base, 'settings.json'), '{"keep":"my settings"}\n');
+  const args = ['--codebuddy', '--scope', 'project', '--yes'];
+  assert.equal(run(directory, args).status, 1);
+  assert.equal(fs.existsSync(path.join(base, 'skills')), false);
+  const result = run(directory, [...args, '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  const backups = fs.readdirSync(base).filter(file => file.startsWith('.i3-composer-agent-backup-'));
+  assert.equal(backups.length, 1);
+  assert.equal(fs.readFileSync(path.join(base, backups[0], 'commands/spec.md'), 'utf8'), 'my custom command');
+  assert.equal(fs.readFileSync(path.join(base, 'settings.json'), 'utf8'), '{"keep":"my settings"}\n');
+  assert.equal(fs.existsSync(path.join(base, backups[0], 'settings.json')), false);
+});
+test('global installation uses injected home and config roots without touching the real user configuration', t => {
+  const directory = workspace(t);
+  const { planInstallation, executeInstallation } = require('../bin/install.cjs');
+  const plan = planInstallation({ agents: ['codebuddy', 'codex', 'claude-code', 'opencode'], scope: 'global', home: directory, env: { XDG_CONFIG_HOME: path.join(directory, 'config'), CLAUDE_CONFIG_DIR: path.join(directory, 'custom-claude') } });
+  assert.ok(plan.targets.every(target => target.skillsDirectory.startsWith(directory + path.sep)));
+  assert.ok(plan.targets.some(target => target.skillsDirectory === path.join(directory, 'custom-claude/skills')));
+  assert.ok(plan.targets.some(target => target.skillsDirectory === path.join(directory, 'config/opencode/skills')));
+  executeInstallation(plan);
+  for (const target of plan.targets) {
+    assert.equal(fs.readdirSync(target.skillsDirectory).length, upstream.skills.length);
+    assert.ok(fs.existsSync(path.join(target.referencesDirectory, 'definition-of-done.md')));
+  }
+});
+test('the pinned tool catalog plans all project choices and rejects unsupported global choices before writing', t => {
+  const directory = workspace(t);
+  const { registry, planInstallation } = require('../bin/install.cjs');
+  assert.equal(registry.agents.length, 79);
+  assert.equal(registry.commit, '48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e');
+  const plan = planInstallation({ agents: registry.agents.map(agent => agent.id), scope: 'project', projectDir: directory });
+  assert.equal(plan.agents.length, registry.agents.length);
+  assert.ok(plan.targets.length < plan.agents.length);
+  assert.equal(new Set(plan.assets.map(asset => asset.destination)).size, plan.assets.length);
+  for (const agent of registry.agents) {
+    if (agent.globalSkillsDir) assert.ok(planInstallation({ agents: [agent.id], scope: 'global', home: directory, env: {} }).targets[0].skillsDirectory.startsWith(directory + path.sep));
+    else assert.throws(() => planInstallation({ agents: [agent.id], scope: 'global', home: directory, env: {} }), /project installation only/);
+  }
+  assert.deepEqual(fs.readdirSync(directory), []);
+});
+test('failed installation restores prior assets and removes all newly written files', t => {
+  const directory = workspace(t);
+  const { planInstallation, executeInstallation } = require('../bin/install.cjs');
+  const prior = path.join(directory, '.codebuddy/skills/api-and-interface-design');
+  fs.mkdirSync(prior, { recursive: true });
+  fs.writeFileSync(path.join(prior, 'custom.md'), 'prior skill content');
+  const plan = planInstallation({ agents: ['codebuddy', 'codex'], scope: 'project', projectDir: directory });
+  const realRename = fs.renameSync;
+  let failed = false;
+  fs.renameSync = (source, destination) => {
+    if (!failed && destination === plan.assets[1].destination) { failed = true; throw new Error('simulated disk failure'); }
+    return realRename(source, destination);
+  };
+  try { assert.throws(() => executeInstallation(plan, { force: true }), /simulated disk failure/); }
+  finally { fs.renameSync = realRename; }
+  assert.equal(fs.readFileSync(path.join(prior, 'custom.md'), 'utf8'), 'prior skill content');
+  assert.deepEqual(fs.readdirSync(path.dirname(prior)), ['api-and-interface-design']);
+  assert.deepEqual(fs.readdirSync(path.join(directory, '.codebuddy')), ['skills']);
+  assert.equal(fs.existsSync(path.join(directory, '.agents')), false);
+});
+test('replacing a skill symlink backs up the link and leaves its external source untouched', t => {
+  const directory = workspace(t);
+  const external = path.join(directory, 'external-skill');
+  const skills = path.join(directory, '.codebuddy/skills');
+  fs.mkdirSync(external);
+  fs.writeFileSync(path.join(external, 'custom.md'), 'external source');
+  fs.mkdirSync(skills, { recursive: true });
+  fs.symlinkSync(external, path.join(skills, 'spec-driven-development'), 'dir');
+  const result = run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--force']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(fs.readdirSync(external), ['custom.md']);
+  assert.equal(fs.lstatSync(path.join(skills, 'spec-driven-development')).isSymbolicLink(), false);
+  const base = path.dirname(skills);
+  const backup = fs.readdirSync(base).find(file => file.startsWith('.i3-composer-agent-backup-'));
+  assert.equal(fs.lstatSync(path.join(base, backup, 'skills/spec-driven-development')).isSymbolicLink(), true);
+});
+test('package destinations, shared directory symlinks and ambiguous noninteractive flags fail without writes', t => {
+  const directory = workspace(t);
+  for (const args of [ ['--codebuddy'], ['--codebuddy', '--yes'], ['--agents', 'unknown', '--scope', 'project', '--yes'], ['--codebuddy', '--scope', 'invalid', '--yes'], ['--codebuddy', '--scope', 'project', '--global', '--yes'] ]) {
+    assert.equal(run(directory, args).status, 1);
+    assert.deepEqual(fs.readdirSync(directory), []);
+  }
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--project-dir', root]).status, 1);
+  fs.mkdirSync(path.join(directory, '.codebuddy'));
+  fs.symlinkSync(path.join(root, 'skills'), path.join(directory, '.codebuddy/skills'), 'dir');
+  assert.equal(run(directory, ['--codebuddy', '--scope', 'project', '--yes', '--force']).status, 1);
+  assert.deepEqual(fs.readdirSync(path.join(directory, '.codebuddy')), ['skills']);
+});
+test('explicit plugin preparation remains available and does not install native host files', t => {
+  const directory = workspace(t);
+  const result = run(directory, ['--prepare', '--codebuddy']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /\/plugin install/);
+  assert.equal(fs.existsSync(path.join(directory, 'i3-composer-agent/plugin.json')), true);
+  assert.equal(fs.existsSync(path.join(directory, '.codebuddy')), false);
+  const listing = run(directory, ['--list-agents']);
+  assert.equal(listing.status, 0, listing.stderr);
+  assert.equal(listing.stdout.trim().split('\n').length, 79);
+  assert.match(listing.stdout, /codebuddy/);
+  assert.match(listing.stdout, /windsurf/);
+});

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

@@ -1,178 +1,124 @@
-# 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.
+## Install with the wizard
 
-Once the package is published, run this in the project where you want to use it:
+Run in the project where you want to use the skills:
 
 ```bash
+npx @givolt/i3-composer-agent
+# Preselect a tool; the wizard still allows multiple selections:
 npx @givolt/i3-composer-agent --codebuddy
-# Or prepare a bundle for another host:
-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 interactive terminal wizard offers multiple tools, project or global scope,
+an installation summary, and confirmation. Its 79 tool directory presets come
+from the pinned [Vercel Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts).
+Choose by tool ID or comma-separated menu numbers. Use `--list-agents` to list
+the choices. Directory presets are not an execution test of every host.
 
-### CodeBuddy / Claude Code
+Every selected tool receives all {{SKILL_COUNT}} skills and shared references.
+CodeBuddy and Claude Code also receive {{COMMAND_COUNT}} short command workflows
+and {{PERSONA_COUNT}} persona files. Other tools use their native skill support;
+short lifecycle commands depend on the host. Shared destinations are installed
+once. License and attribution files accompany each native installation.
+Reload the IDE window or start a new session after installation. See
+[CodeBuddy setup](docs/codebuddy-setup.md) and [Codex setup](docs/codex-setup.md).
 
-```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
+For an explicit installation without prompts:
 
 ```bash
-codex plugin marketplace add ./i3-composer-agent
-codex plugin add i3-composer-agent@i3-composer-agent
+npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --claude --scope global --yes
+npx @givolt/i3-composer-agent --codebuddy --scope project --dry-run
 ```
 
-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).
+Existing assets require confirmation; use `--force` with noninteractive installs.
+Replacement preserves previous files in a `.i3-composer-agent-backup-*` directory
+under each tool configuration root. Unrelated settings are left in place.
+`npx -y` accepts npm's package download prompt; the package's own `--yes` flag
+accepts the explicit installation plan.
+
+## Prepare the complete plugin
 
-### Bundle options
+For native plugin registration, including plugin hooks, explicitly prepare a
+persistent `./i3-composer-agent/` bundle:
 
 ```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
+npx @givolt/i3-composer-agent --prepare --codebuddy
+npx @givolt/i3-composer-agent --prepare --codex
+npx @givolt/i3-composer-agent --prepare --claude
 ```
 
-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.
-
-## Commands
-
-Hosts supporting Claude-compatible plugin commands load these workflows.
-Use the namespaced form, for example `/i3-composer-agent:spec`.
-
-| Command | Workflow |
-| --- | --- |
-| `/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
+The bundle includes skills, commands, personas, hooks and references. Run the
+registration commands printed by the CLI in the intended host. This preparation
+mode does not install native skills or choose the host plugin manager's scope.
 
-| 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 |
+CodeBuddy Code (terminal) / Claude Code:
 
-### 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 |
-
-### Plan - Break it down
-
-| 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 |
-
-### 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 |
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
 
-### Review - Quality gates before merge
+Codex:
 
-| 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 |
+```bash
+codex plugin marketplace add ./i3-composer-agent
+codex plugin add i3-composer-agent@i3-composer-agent
+```
 
-### Ship - Deploy with confidence
+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.
 
-| 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 |
+## Commands
 
----
+Native CodeBuddy and Claude Code installations use short filenames such as
+`/spec`, `/plan`, `/build` and `/ship`. Hosts supporting Claude-compatible plugin
+commands load the same workflows under the plugin namespace:
 
-## Personas and shared references
+| Command | Description |
+| --- | --- |
+{{COMMAND_TABLE}}
 
-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.
+`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
 
-## Other hosts
+## Skills
 
-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.
+Explicit `--dir` retains the original plugin preparation behavior. 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).