@givolt/i3-composer-agent 1.0.1 → 2.1.0

package/README.md

@@ -1,15 +1,9 @@
-# i3 Composer Agent v1.0.1
-
-**Based on agent-skills v0.6.12**
+# i3 Composer Agent v2.1.0
 
 **Intelligence. Integration. Innovation.**
 
-Engineering skills, lifecycle commands, and specialist personas for AI coding agents.
-Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani
-(MIT). See [NOTICE.md](NOTICE.md) for attribution.
-
 The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
-`i3-composer-agent`. Skill IDs retain their upstream names.
+`i3-composer-agent`. Commands and Skill IDs use the `i3-` prefix.
 
 ## Install with the wizard
 
@@ -19,36 +13,55 @@ Run in the project where you want to use the skills:
 npx @givolt/i3-composer-agent
 # Preselect a tool; the wizard still allows multiple selections:
 npx @givolt/i3-composer-agent --codebuddy
+npx @givolt/i3-composer-agent --workbuddy
 ```
 
 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).
+an installation summary, and confirmation. It offers 80 directory
+presets: the pinned [Vercel Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
+plus a native WorkBuddy preset.
 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.
 
 Every selected tool receives all 25 skills and shared references.
-CodeBuddy and Claude Code also receive 9 short command workflows
+CodeBuddy, WorkBuddy and Claude Code also receive 9 short command workflows
 and 4 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.
+once. A standard MIT license accompanies the shared references.
 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).
+[CodeBuddy setup](docs/codebuddy-setup.md), [WorkBuddy setup](docs/workbuddy-setup.md)
+and [Codex setup](docs/codex-setup.md).
 
 For an explicit installation without prompts:
 
 ```bash
 npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope project --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes
 npx @givolt/i3-composer-agent --claude --scope global --yes
 npx @givolt/i3-composer-agent --codebuddy --scope project --dry-run
 ```
 
-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.
+CodeBuddy and WorkBuddy share one project installation under `.codebuddy/`.
+Existing `.workbuddy/` project settings are preserved. Global installations use
+separate `~/.codebuddy/` and `~/.workbuddy/` directories.
+
+Unchanged manifest-owned assets from the same version and scope are reused;
+adding a client merges its ID into the shared installation manifest. Modified
+files, unowned collisions and version upgrades require confirmation; use
+`--force` with noninteractive installs after reviewing the dry run.
+After successful installation, replaced files and installer-owned historical
+backups are removed. A failed installation restores the previous files.
 `npx -y` accepts npm's package download prompt; the package's own `--yes` flag
 accepts the explicit installation plan.
 
+Earlier native installations migrate their unprefixed Skill and command paths
+when those paths belong to this package's previous installation manifest.
+The migration removes owned legacy paths after successful installation. Use
+`/i3-spec` in CodeBuddy or WorkBuddy, or `$i3-spec-driven-development`
+in Codex after upgrading.
+
 ## Prepare the complete plugin
 
 For native plugin registration, including plugin hooks, explicitly prepare a
@@ -78,59 +91,60 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new session after enabling the plugin. Codex uses the existing Skill
-names, such as `$spec-driven-development`; lifecycle slash-command adaptation
+Start a new session after enabling the plugin. Codex uses the branded Skill
+names, such as `$i3-spec-driven-development`; lifecycle slash-command adaptation
 is maintained separately.
 
 ## Commands
 
-Native CodeBuddy and Claude Code installations use short filenames such as
-`/spec`, `/plan`, `/build` and `/ship`. Hosts supporting Claude-compatible plugin
+Native CodeBuddy, WorkBuddy and Claude Code installations use short filenames such as
+`/i3-spec`, `/i3-plan`, `/i3-build` and `/i3-ship`. Hosts supporting Claude-compatible plugin
 commands load the same workflows under the plugin namespace:
 
 | Command | Description |
 | --- | --- |
-| /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 |
-
-`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
+| /i3-composer-agent:i3-build | Implement tasks incrementally — build, test, verify, commit. Add "auto" to run the whole plan in one approved pass. |
+| /i3-composer-agent:i3-code-simplify | Simplify code for clarity and maintainability — reduce complexity without changing behavior |
+| /i3-composer-agent:i3-constraints | Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md |
+| /i3-composer-agent:i3-plan | Break work into small verifiable tasks with acceptance criteria and dependency ordering |
+| /i3-composer-agent:i3-review | Conduct a five-axis code review — correctness, readability, architecture, security, performance |
+| /i3-composer-agent:i3-ship | Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision |
+| /i3-composer-agent:i3-spec | Start spec-driven development — write a structured specification before writing code |
+| /i3-composer-agent:i3-test | Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. |
+| /i3-composer-agent:i3-webperf | Run a web performance audit via the web-performance-auditor persona |
+
+`/i3-build auto` runs the existing approved-plan workflow in native installations;
+plugin installations use `/i3-composer-agent:i3-build auto`.
 
 ## Skills
 
 | 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. |
+| [i3-api-and-interface-design](skills/i3-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. |
+| [i3-browser-testing-with-devtools](skills/i3-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. |
+| [i3-ci-cd-and-automation](skills/i3-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. |
+| [i3-code-review-and-quality](skills/i3-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. |
+| [i3-code-simplification](skills/i3-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. |
+| [i3-constraint-driven-development](skills/i3-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. |
+| [i3-context-engineering](skills/i3-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. |
+| [i3-debugging-and-error-recovery](skills/i3-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. |
+| [i3-deprecation-and-migration](skills/i3-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. |
+| [i3-documentation-and-adrs](skills/i3-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. |
+| [i3-doubt-driven-development](skills/i3-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. |
+| [i3-frontend-ui-engineering](skills/i3-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. |
+| [i3-git-workflow-and-versioning](skills/i3-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. |
+| [i3-idea-refine](skills/i3-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". |
+| [i3-incremental-implementation](skills/i3-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. |
+| [i3-interview-me](skills/i3-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. |
+| [i3-observability-and-instrumentation](skills/i3-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. |
+| [i3-performance-optimization](skills/i3-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. |
+| [i3-planning-and-task-breakdown](skills/i3-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. |
+| [i3-security-and-hardening](skills/i3-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. |
+| [i3-shipping-and-launch](skills/i3-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. |
+| [i3-source-driven-development](skills/i3-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. |
+| [i3-spec-driven-development](skills/i3-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. |
+| [i3-test-driven-development](skills/i3-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. |
+| [i3-using-agent-skills](skills/i3-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
 
@@ -140,17 +154,6 @@ npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
 npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
 ```
 
-Explicit `--dir` retains the original plugin preparation behavior. Replacement
-preserves the previous i3 bundle as a backup. Repository-scoped
+Explicit `--dir` retains the plugin preparation behavior. Successful replacement
+removes the previous bundle and this plugin's historical backups. Repository-scoped
 AGENTS.md and CLAUDE.md are not copied into business projects.
-
-## Maintaining this fork
-
-This repository is independent of the GSD-based i3 Composer Work repository.
-`agent/source` retains upstream source and the `rebrand/` rules; `main` contains
-the validated branded distribution. Create release candidates from the source
-branch, replay branding, validate, then update the release branch.
-
-See [maintenance](rebrand/MAINTENANCE.md), [source PR workflow](rebrand/PR-WORKFLOW.md),
-[versioning](rebrand/VERSIONING.md), [changelog](CHANGELOG.md),
-and [validation contract](rebrand/VALIDATION.md).

package/agents/code-reviewer.md

@@ -46,7 +46,7 @@ Evaluate every change across these five dimensions:
 
 ## Output Format
 
-Categorize every finding, using the same severity labels as the `code-review-and-quality` skill:
+Categorize every finding, using the same severity labels as the `i3-code-review-and-quality` skill:
 
 **Critical** — Blocks merge (security vulnerability, data loss risk, broken functionality)
 
@@ -98,5 +98,5 @@ Categorize every finding, using the same severity labels as the `code-review-and
 ## Composition
 
 - **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
-- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
+- **Invoke via:** `/i3-review` (single-perspective review) or `/i3-ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
 - **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [docs/agents.md](../docs/agents.md).

package/agents/security-auditor.md

@@ -108,5 +108,5 @@ Map findings to the OWASP Top 10 for LLM Applications where relevant.
 ## Composition
 
 - **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component.
-- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
+- **Invoke via:** `/i3-ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
 - **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [docs/agents.md](../docs/agents.md).

package/agents/test-engineer.md

@@ -91,5 +91,5 @@ When analyzing test coverage:
 ## Composition
 
 - **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug.
-- **Invoke via:** `/test` (TDD workflow) or `/ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
+- **Invoke via:** `/i3-test` (TDD workflow) or `/i3-ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
 - **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [docs/agents.md](../docs/agents.md).

package/agents/web-performance-auditor.md

@@ -33,7 +33,7 @@ Populate the scorecard only with values backed by these sources. Mark unmeasured
 | Lab metrics, opportunities, diagnostics | Lighthouse JSON | None (parse a provided file) |
 | Field metrics (real users, p75) | CrUX API | `CRUX_API_KEY` or `GOOGLE_API_KEY` env var |
 | Combined lab + field | PageSpeed Insights JSON | None for parsing; the user provides the JSON |
-| Live trace, LCP attribution, INP attribution, layout shift attribution | Chrome DevTools MCP server (`performance_*`, `lighthouse_audit`) | `chrome-devtools` MCP server configured in the harness (see `skills/browser-testing-with-devtools`) |
+| Live trace, LCP attribution, INP attribution, layout shift attribution | Chrome DevTools MCP server (`performance_*`, `lighthouse_audit`) | `chrome-devtools` MCP server configured in the harness (see `skills/i3-browser-testing-with-devtools`) |
 | Manual terminal capture (Lighthouse, trace, screenshot) | Chrome DevTools MCP CLI (e.g. `chrome-devtools lighthouse_audit --output-format=json`) | `npx -p chrome-devtools-mcp chrome-devtools <tool>` or `npm i -g chrome-devtools-mcp` (CLI is independent of the harness) |
 
 If a source is unavailable, do not fabricate. Skip the related section of the scorecard and continue with what you have.
@@ -173,12 +173,12 @@ Identify the framework and rendering model (React, Vue, Svelte, Angular, Next.js
 6. Do not recommend micro-optimizations without evidence they affect a Core Web Vital or another measurable metric.
 7. Acknowledge good performance practices — positive reinforcement matters.
 8. Use `references/performance-checklist.md` as the minimum baseline for each area.
-9. Delegate granular optimization guidance and remediation steps to `skills/performance-optimization/SKILL.md` — keep this report at the audit level.
+9. Delegate granular optimization guidance and remediation steps to `skills/i3-performance-optimization/SKILL.md` — keep this report at the audit level.
 10. Fold AI-generated anti-patterns into their relevant area (Network or Rendering/JS); do not create a separate "AI" category.
 11. In Deep mode, always state which artifacts were provided and which fields remain unmeasured.
 
 ## Composition
 
 - **Invoke directly when:** the user wants a performance-focused pass on a web application, a specific component, a route, or a live URL.
-- **Invoke via:** `/webperf` (dedicated performance audit command). Not included in `/ship` fan-out — performance audits apply to web applications only, not to utility libraries or CLI tools, so adding it to a global pre-launch fan-out would create noise in non-web projects.
+- **Invoke via:** `/i3-webperf` (dedicated performance audit command). Not included in `/i3-ship` fan-out — performance audits apply to web applications only, not to utility libraries or CLI tools, so adding it to a global pre-launch fan-out would create noise in non-web projects.
 - **Do not invoke from another persona.** If `code-reviewer` flags a performance concern that warrants a deeper pass, surface that recommendation in the report; the user or a slash command initiates the deeper pass. See [docs/agents.md](../docs/agents.md).

package/bin/agent-targets.json

@@ -721,6 +721,17 @@
         "base": "home",
         "path": ".zencoder/skills"
       }
+    },
+    {
+      "id": "workbuddy",
+      "label": "WorkBuddy",
+      "projectSkillsDir": ".codebuddy/skills",
+      "globalSkillsDir": {
+        "base": "env",
+        "env": "WORKBUDDY_CONFIG_DIR",
+        "fallback": ".workbuddy",
+        "path": "skills"
+      }
     }
   ]
 }

package/bin/asset-fingerprint.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { nativeContent } = require('./native-content.cjs');
+
+// Compare the complete tree without following links. When asset is provided,
+// hash the source as it will be rendered by the native installer.
+function fingerprint(file, asset) {
+  const hash = crypto.createHash('sha256');
+  function visit(current, relative) {
+    let stat;
+    try { stat = fs.lstatSync(current); }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+      if (asset) throw new Error(`Package contains an unsupported file: ${current}`);
+      return false;
+    }
+    hash.update(JSON.stringify([relative, stat.isDirectory() ? 'directory' : 'file', stat.mode & 0o111]) + '\n');
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(current).sort()) {
+        if (asset && entry === '.DS_Store') continue;
+        if (!visit(path.join(current, entry), path.join(relative, entry))) return false;
+      }
+    } else {
+      const content = asset && current.endsWith('.md')
+        ? Buffer.from(nativeContent(fs.readFileSync(current, 'utf8'), asset))
+        : fs.readFileSync(current);
+      hash.update(String(content.length) + '\n');
+      hash.update(content);
+    }
+    return true;
+  }
+  return visit(file, '') ? hash.digest('hex') : undefined;
+}
+
+module.exports = { fingerprint };

package/bin/cleanup-backups.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function cleanupBackups(directory, prefix, belongs = () => true) {
+  // Installer backups have a v4 UUID suffix. Ignore lookalikes and symlinks.
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith(prefix) || !uuid.test(entry.name.slice(prefix.length))) continue;
+    const backup = path.join(directory, entry.name);
+    if (belongs(backup)) fs.rmSync(backup, { recursive: true });
+  }
+}
+
+module.exports = { cleanupBackups };

package/bin/i3-composer-agent.cjs

@@ -4,11 +4,12 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { cleanupBackups } = require('./cleanup-backups.cjs');
 const root = path.resolve(__dirname, '..');
 const pkg = require('../package.json');
 const name = 'i3-composer-agent';
 const args = process.argv.slice(2);
-const identity = `i3 Composer Agent v${pkg.version}\nBased on agent-skills v${pkg.i3ComposerAgent.upstreamVersion}`;
+const identity = `i3 Composer Agent v${pkg.version}`;
 const help = `${identity}
 ${pkg.name}
 
@@ -17,6 +18,8 @@ Install engineering skills with a multi-tool installation wizard.
 Usage:
   npx ${pkg.name}
   npx ${pkg.name} --codebuddy
+  npx ${pkg.name} --workbuddy
+  npx ${pkg.name} --agents codebuddy,workbuddy --scope project --yes
   npx ${pkg.name} --agents codebuddy,codex --scope project --yes
   npx ${pkg.name} --prepare --claude --dir <directory>
   npx ${pkg.name} --extract --dir <directory>
@@ -24,6 +27,7 @@ Usage:
 Options:
   --agents <ids>      Comma-separated tool IDs; multiple tools are supported
   --codebuddy        Preselect CodeBuddy desktop IDE / CodeBuddy Code
+  --workbuddy        Preselect WorkBuddy (shared project / independent global)
   --codex            Preselect Codex
   --claude           Preselect Claude Code
   --scope <scope>    project or global (or use --global / --local)
@@ -33,12 +37,12 @@ Options:
   --prepare          Prepare a complete plugin for native plugin registration
   --dir <directory>  Plugin output directory; implies --prepare
   --dry-run          Show the installation or bundle plan without writing files
-  --force            Replace existing assets, preserving backups
+  --force            Replace existing assets; remove old files after success
   --version          Print the package version
   --help             Show this help
 
 The terminal wizard selects tools and scope, then installs native skill files.
-CodeBuddy and Claude Code also receive short lifecycle commands and personas.
+CodeBuddy, WorkBuddy and Claude Code also receive short commands and personas.
 Other tools receive skills and references; command availability is host-specific.
 Use --prepare for complete plugins, including hooks and host registration.
 `;
@@ -63,6 +67,7 @@ function prepare() {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--prepare') continue;
+    if (arg === '--workbuddy') throw new Error('For native WorkBuddy installation, use --workbuddy --scope project|global --yes without --prepare or --dir.');
     if (['--codebuddy', '--codex', '--claude', '--extract'].includes(arg)) {
       if (host) throw new Error('Choose exactly one host flag or --extract.');
       host = arg.slice(2);
@@ -87,12 +92,13 @@ function prepare() {
     if (manifest.name !== name) throw new Error('Refusing to replace a directory belonging to another plugin.');
   }
   if (dryRun) {
-    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    console.log(JSON.stringify({ name, version: pkg.version, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
     return;
   }
   fs.mkdirSync(path.dirname(directory), { recursive: true });
   const staging = fs.mkdtempSync(path.join(path.dirname(directory), `.${name}-`));
   let backup;
+  let completed = false;
   try {
     for (const relative of pkg.i3ComposerAgent.pluginFiles) {
       const source = path.join(root, relative);
@@ -113,10 +119,18 @@ function prepare() {
     }
     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 }); }
+    completed = true;
+  } finally {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+    if (completed) cleanupBackups(path.dirname(directory), `${path.basename(directory)}.backup-`, previous => {
+      const manifest = path.join(previous, 'plugin.json');
+      try {
+        return !fs.lstatSync(manifest).isSymbolicLink() && JSON.parse(fs.readFileSync(manifest, 'utf8')).name === name;
+      } catch { return false; }
+    });
+  }
   console.log(identity);
   console.log(`Prepared ${name} at ${directory}`);
-  if (backup) console.log(`Previous bundle preserved at ${backup}`);
   if (host === 'extract') return;
   console.log('\nRegister and enable the plugin with these native commands:');
   const selector = `${name}@${name}`;
@@ -127,7 +141,7 @@ function prepare() {
   } else {
     console.log(`/plugin marketplace add ${quote(directory)}`);
     console.log(`/plugin install ${selector}`);
-    console.log(`Use /${name}:spec, /${name}:plan, /${name}:build, and /${name}:ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
+    console.log(`Use /${name}:i3-spec, /${name}:i3-plan, /${name}:i3-build, and /${name}:i3-ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
   }
 }
 async function main() {
@@ -142,7 +156,7 @@ async function main() {
   const options = { agents: [], projectDir: process.cwd() };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (['--codebuddy', '--codex', '--claude'].includes(arg)) options.agents.push(arg.slice(2));
+    if (['--codebuddy', '--workbuddy', '--codex', '--claude'].includes(arg)) options.agents.push(arg.slice(2));
     else if (['--agents', '--scope', '--project-dir'].includes(arg)) {
       if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} requires a value.`);
       const value = args[++i];
@@ -168,7 +182,7 @@ async function main() {
   }
   const plan = installer.planInstallation(options);
   if (options.dryRun) {
-    console.log(JSON.stringify({ name, version: pkg.version, upstreamVersion: pkg.i3ComposerAgent.upstreamVersion, upstreamCommit: pkg.i3ComposerAgent.upstreamCommit, mode: plan.mode, scope: plan.scope, agents: plan.agents, targets: plan.targets, conflicts: plan.conflicts }, null, 2));
+    console.log(JSON.stringify({ name, version: pkg.version, mode: plan.mode, scope: plan.scope, agents: plan.agents, targets: plan.targets, conflicts: plan.conflicts, reused: plan.reused }, null, 2));
     return;
   }
   if (!options.yes) {
@@ -176,15 +190,16 @@ async function main() {
     if (!confirmed) { console.log('Installation cancelled. No files changed.'); return; }
     options.force = plan.conflicts.length > 0;
   }
-  const backups = installer.executeInstallation(plan, { force: options.force });
+  installer.executeInstallation(plan, { force: options.force });
   console.log(identity);
+  if (plan.reused.length) console.log(`Reused ${plan.reused.length} unchanged assets from the same package version.`);
   for (const target of plan.targets) {
     console.log(`Installed ${target.agents.join(', ')} skills at ${target.skillsDirectory}`);
-    if (target.commandsDirectory) console.log(`Commands: /spec, /plan, /build, /ship (all ${fs.readdirSync(target.commandsDirectory).filter(file => file.endsWith('.md')).length} workflows) at ${target.commandsDirectory}`);
+    if (target.commandsDirectory) console.log(`Commands: /i3-spec, /i3-plan, /i3-build, /i3-ship (all ${fs.readdirSync(target.commandsDirectory).filter(file => file.endsWith('.md')).length} workflows) at ${target.commandsDirectory}`);
   }
-  for (const backup of backups) console.log(`Previous assets preserved at ${backup}`);
   console.log('Reload the IDE window or start a new host session to discover installed files.');
-  if (plan.agents.some(id => !['codebuddy', 'claude-code'].includes(id))) console.log('These tools use the existing skill IDs; lifecycle slash-command support depends on the host.');
-  console.log('Native skill installation does not enable plugin hooks. Use --prepare for complete plugin registration.');
+  if (plan.agents.some(id => !['codebuddy', 'workbuddy', 'claude-code'].includes(id))) console.log('These tools use the existing skill IDs; lifecycle slash-command support depends on the host.');
+  console.log('Native skill installation does not enable plugin hooks.');
+  if (plan.agents.some(id => ['codebuddy', 'codex', 'claude-code'].includes(id))) console.log('For CodeBuddy, Codex or Claude Code plugin registration, use --prepare with the matching host flag.');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });