@givolt/i3-composer-agent 0.6.12 → 1.0.0

package/.agents/plugins/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "0.6.12",
+      "version": "1.0.0",
       "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
       "source": {
         "source": "local",
@@ -16,7 +16,8 @@
         "installation": "AVAILABLE",
         "authentication": "ON_INSTALL"
       },
-      "category": "Productivity"
+      "category": "Productivity",
+      "homepage": "https://github.com/49780522/i3-composer-agent"
     }
   ]
 }

package/.claude-plugin/marketplace.json

@@ -8,9 +8,10 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "0.6.12",
+      "version": "1.0.0",
       "source": "./",
       "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+      "homepage": "https://github.com/49780522/i3-composer-agent",
       "license": "MIT",
       "keywords": [
         "skills",

package/.claude-plugin/plugin.json

@@ -1,10 +1,12 @@
 {
   "name": "i3-composer-agent",
-  "version": "0.6.12",
+  "version": "1.0.0",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "author": {
     "name": "Givolt"
   },
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent",
   "license": "MIT",
   "commands": [
     "./.claude/commands",

package/.codex-plugin/plugin.json

@@ -1,10 +1,12 @@
 {
   "name": "i3-composer-agent",
-  "version": "0.6.12",
+  "version": "1.0.0",
   "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
   "author": {
     "name": "Givolt"
   },
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent",
   "license": "MIT",
   "skills": "./skills/",
   "interface": {

package/CHANGELOG.md

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

package/README.md

@@ -1,178 +1,118 @@
-# i3 Composer Agent
+# i3 Composer Agent v1.0.0
 
-**Intelligence. Integration. Innovation.**
+**Based on agent-skills v0.6.12**
 
-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
+25 skills, 9 commands, 4 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 |
-
-### Plan - Break it down
+| /i3-composer-agent:build | Implement tasks incrementally — build, test, verify, commit. Add "auto" to run the whole plan in one approved pass. |
+| /i3-composer-agent:code-simplify | Simplify code for clarity and maintainability — reduce complexity without changing behavior |
+| /i3-composer-agent:constraints | Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md |
+| /i3-composer-agent:plan | Break work into small verifiable tasks with acceptance criteria and dependency ordering |
+| /i3-composer-agent:review | Conduct a five-axis code review — correctness, readability, architecture, security, performance |
+| /i3-composer-agent:ship | Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision |
+| /i3-composer-agent:spec | Start spec-driven development — write a structured specification before writing code |
+| /i3-composer-agent:test | Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. |
+| /i3-composer-agent:webperf | Run a web performance audit via the web-performance-auditor persona |
 
-| 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 |
+`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
 
-### Build - Write the code
+## Skills
 
-| 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.
-
-## Development and release
+| Skill | Description |
+| --- | --- |
+| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend. |
+| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. |
+| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. |
+| [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch. Use when asked to review a diff or a pull request, even when the diff is pasted inline. |
+| [code-simplification](skills/code-simplification/SKILL.md) | Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. |
+| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when the user wants dimensions they care about — accessibility, web performance, coverage — set up as enforced constraints, when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read. |
+| [context-engineering](skills/context-engineering/SKILL.md) | Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project. |
+| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need to figure out what broke and why — a systematic approach to finding and fixing the root cause rather than guessing. |
+| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. |
+| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. |
+| [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when you want every assumption cross-examined before proceeding, when stress-testing a plan for hidden failure modes, when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production auth, security-sensitive logic, a high-stakes migration, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later. |
+| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Builds production-quality, accessible, responsive user-facing UIs. Use when building or modifying interfaces and pages, creating components, implementing layouts, meeting WCAG accessibility requirements, managing state, or when the output needs to look and feel production-quality rather than AI-generated. |
+| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, splitting uncommitted work in a messy working tree into clean atomic commits, opening or reviewing a pull request (PR), pushing to a remote, or when you need to organize work across multiple parallel streams. Use when cutting a release, choosing a semantic version bump, tagging, or writing a changelog. |
+| [idea-refine](skills/idea-refine/SKILL.md) | Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan". |
+| [incremental-implementation](skills/incremental-implementation/SKILL.md) | Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step. |
+| [interview-me](skills/interview-me/SKILL.md) | Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists. |
+| [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data. |
+| [performance-optimization](skills/performance-optimization/SKILL.md) | Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. |
+| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. |
+| [security-and-hardening](skills/security-and-hardening/SKILL.md) | Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a new package. Use when personal data or privacy compliance (GDPR, CCPA) is involved. |
+| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Prepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. |
+| [source-driven-development](skills/source-driven-development/SKILL.md) | Grounds every implementation decision in official documentation. Use when you want to verify an approach against the official docs before implementing it, or when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters. |
+| [spec-driven-development](skills/spec-driven-development/SKILL.md) | Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. |
+| [test-driven-development](skills/test-driven-development/SKILL.md) | Drives development with tests using the red-green-refactor loop. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. |
+| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked. |
+
+## 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/bin/i3-composer-agent.cjs

@@ -8,7 +8,9 @@ const root = path.resolve(__dirname, '..');
 const pkg = require('../package.json');
 const name = 'i3-composer-agent';
 const args = process.argv.slice(2);
-const help = `${pkg.name} v${pkg.version}
+const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pkg.i3ComposerAgent.upstreamVersion}`;
+const help = `${identity}
+${pkg.name}
 
 Prepare the complete i3 Composer Agent plugin, including shared references.
 
@@ -74,7 +76,7 @@ function main() {
     if (manifest.name !== name) throw new Error('Refusing to replace a directory belonging to another plugin.');
   }
   if (dryRun) {
-    console.log(JSON.stringify({ name, version: pkg.version, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
     return;
   }
   fs.mkdirSync(path.dirname(directory), { recursive: true });
@@ -101,7 +103,8 @@ function main() {
     try { fs.renameSync(staging, directory); }
     catch (error) { if (backup) fs.renameSync(backup, directory); throw error; }
   } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
-  console.log(`Prepared ${name} v${pkg.version} at ${directory}`);
+  console.log(identity);
+  console.log(`Prepared ${name} at ${directory}`);
   if (backup) console.log(`Previous bundle preserved at ${backup}`);
   if (host === 'extract') return;
   console.log('\nRegister and enable the plugin with these native commands:');

package/docs/antigravity-setup.md

@@ -18,7 +18,7 @@ agy plugin install /path/to/i3-composer-agent
 
 1. Prepare the plugin bundle:
    ```bash
-npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+   npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
    ```
 2. Install the plugin using `agy`:
    ```bash

package/docs/comparison.md

@@ -6,7 +6,7 @@
 
 # How agent-skills compares
 
-> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
+> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b8030e023baeebb31781a6653fe8e93026`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
 
 People often ask how **agent-skills** relates to the two other "skills for coding agents" collections they hear about most: **Superpowers** (Jesse Vincent / obra) and **Matt Pocock's skills**. All three are good, share a lot of DNA, and are worth learning from. This page is an honest map of how they are *shaped* differently, so you can pick the one that fits how you work, or borrow across all three.
 

package/package.json

@@ -1,33 +1,91 @@
 {
   "name": "@givolt/i3-composer-agent",
-  "version": "0.6.12",
   "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/" },
+  "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"
+    "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",
+    "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"],
+  "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"
-    ]
-  }
+      "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"
+    ],
+    "upstreamVersion": "0.6.12",
+    "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
+    "upstreamRepository": "https://github.com/addyosmani/agent-skills"
+  },
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/49780522/i3-composer-agent.git"
+  },
+  "homepage": "https://github.com/49780522/i3-composer-agent#readme"
 }

package/plugin.json

@@ -1,5 +1,7 @@
 {
   "name": "i3-composer-agent",
-  "version": "0.6.12",
-  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship."
+  "version": "1.0.0",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent"
 }