@givolt/i3-composer-agent 1.0.0 → 2.0.0

package/docs/adoption-guide.md

@@ -28,44 +28,44 @@ A new project is the best-case scenario: there's no legacy behavior to preserve,
 ### Day 0 | Install and wire up
 
 1. Install the pack (`npx skills add /path/to/i3-composer-agent`, or the native integration for your tool, see [getting-started.md](getting-started.md)).
-2. If the host has no native skill router, load `using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. On hosts with native routing, install the individual skills and do not preload the meta-skill as always-on context.
-3. Add a short project rules file (`CLAUDE.md`, `.cursorrules`, etc.) with your stack, commands, and boundaries, `context-engineering` describes what belongs there.
+2. If the host has no native skill router, load `i3-using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. On hosts with native routing, install the individual skills and do not preload the meta-skill as always-on context.
+3. Add a short project rules file (`CLAUDE.md`, `.cursorrules`, etc.) with your stack, commands, and boundaries, `i3-context-engineering` describes what belongs there.
 
 ### Day 0 | Define before you build
 
 Run the lifecycle in order for the project's first real feature:
 
 ```
-/spec   →  SPEC.md            (spec-driven-development)
-/plan   →  tasks/plan.md      (planning-and-task-breakdown)
-/build  →  one slice at a time (incremental-implementation + test-driven-development)
-/review →  before every merge  (code-review-and-quality)
-/ship   →  when going live     (shipping-and-launch)
+/i3-spec   →  SPEC.md            (i3-spec-driven-development)
+/i3-plan   →  tasks/plan.md      (i3-planning-and-task-breakdown)
+/i3-build  →  one slice at a time (i3-incremental-implementation + i3-test-driven-development)
+/i3-review →  before every merge  (i3-code-review-and-quality)
+/i3-ship   →  when going live     (i3-shipping-and-launch)
 ```
 
-`/build auto` is a good fit for greenfield: you approve the plan once and every task still runs test-driven and commits individually. The spec and plan artifacts (`SPEC.md`, `tasks/`) are living documents, keep them in version control while the work is in flight. If the feature spans more than one session, those files are also the handoff, see [working across sessions](getting-started.md#working-across-sessions).
+`/i3-build auto` is a good fit for greenfield: you approve the plan once and every task still runs test-driven and commits individually. The spec and plan artifacts (`SPEC.md`, `tasks/`) are living documents, keep them in version control while the work is in flight. If the feature spans more than one session, those files are also the handoff, see [working across sessions](getting-started.md#working-across-sessions).
 
 ### From the start, treat these as always-on
 
-- **test-driven-development**, coverage debt is cheapest to avoid at zero.
-- **git-workflow-and-versioning**, atomic commits and ~100-line changes are habits, not retrofits.
-- **security-and-hardening**, auth, input validation, and secrets handling are structural; bolting them on later is a migration project.
-- **documentation-and-adrs**, the first architectural decisions are exactly the ones nobody will remember the _why_ of in two years. An ADR now prevents the brownfield archaeology described in Path B.
+- **i3-test-driven-development**, coverage debt is cheapest to avoid at zero.
+- **i3-git-workflow-and-versioning**, atomic commits and ~100-line changes are habits, not retrofits.
+- **i3-security-and-hardening**, auth, input validation, and secrets handling are structural; bolting them on later is a migration project.
+- **i3-documentation-and-adrs**, the first architectural decisions are exactly the ones nobody will remember the _why_ of in two years. An ADR now prevents the brownfield archaeology described in Path B.
 
 ### Add as the project grows
 
 | When                                | Load                                                          |
 | ----------------------------------- | ------------------------------------------------------------- |
-| First public API or module boundary | `api-and-interface-design`                                    |
-| First UI work                       | `frontend-ui-engineering` (+ `browser-testing-with-devtools`) |
-| First CI pipeline                   | `ci-cd-and-automation`                                        |
-| First production deploy             | `observability-and-instrumentation`, `shipping-and-launch`    |
-| Performance requirements appear     | `performance-optimization`                                    |
+| First public API or module boundary | `i3-api-and-interface-design`                                    |
+| First UI work                       | `i3-frontend-ui-engineering` (+ `i3-browser-testing-with-devtools`) |
+| First CI pipeline                   | `i3-ci-cd-and-automation`                                        |
+| First production deploy             | `i3-observability-and-instrumentation`, `i3-shipping-and-launch`    |
+| Performance requirements appear     | `i3-performance-optimization`                                    |
 
 ### Greenfield anti-patterns
 
-- **Skipping `/spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase.
-- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `using-agent-skills` route, but not both.
+- **Skipping `/i3-spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase.
+- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `i3-using-agent-skills` route, but not both.
 - **Deferring observability until "there's something to observe."** Instrument as you build, retrofitting structured logging is a Path B problem you're choosing to create.
 
 ---
@@ -78,38 +78,38 @@ In an established codebase, the risk profile inverts: the danger isn't building
 
 Goal: the agent understands the codebase before it modifies anything.
 
-1. **`context-engineering` first.** Write the project rules file describing the real conventions, the ones in the code, not the ones in the wiki. Include build/test commands, directory meaning, known landmines ("don't touch `legacy/billing`, it has no tests and three known workarounds").
-2. **`code-review-and-quality` on incoming changes.** Reviewing is zero-risk and immediately valuable: the five-axis review and its severity labels (which separate what blocks a merge, Critical and Required, from what doesn't) work on any PR regardless of the codebase's state.
-3. **`debugging-and-error-recovery` for the bugs you were fixing anyway.** The five-step triage (reproduce → localize → reduce → fix → guard) shines in unfamiliar code, and the "guard" step starts building the regression suite you don't have.
-4. **`doubt-driven-development` as a safety net.** Legacy code is exactly the "unfamiliar code, high cost of being wrong" scenario this skill targets. Adversarial fresh-context review of the agent's claims about how the legacy system works catches confident hallucinations before they become commits.
+1. **`i3-context-engineering` first.** Write the project rules file describing the real conventions, the ones in the code, not the ones in the wiki. Include build/test commands, directory meaning, known landmines ("don't touch `legacy/billing`, it has no tests and three known workarounds").
+2. **`i3-code-review-and-quality` on incoming changes.** Reviewing is zero-risk and immediately valuable: the five-axis review and its severity labels (which separate what blocks a merge, Critical and Required, from what doesn't) work on any PR regardless of the codebase's state.
+3. **`i3-debugging-and-error-recovery` for the bugs you were fixing anyway.** The five-step triage (reproduce → localize → reduce → fix → guard) shines in unfamiliar code, and the "guard" step starts building the regression suite you don't have.
+4. **`i3-doubt-driven-development` as a safety net.** Legacy code is exactly the "unfamiliar code, high cost of being wrong" scenario this skill targets. Adversarial fresh-context review of the agent's claims about how the legacy system works catches confident hallucinations before they become commits.
 
 ### Phase 2 | Tests before change
 
 Goal: every area the agent will touch gets a safety net first.
 
-- **`test-driven-development`, applied selectively.** Don't aim for global coverage; aim for coverage _where change is planned_. For untested legacy behavior, write characterization tests, tests that pin down what the code currently does, right or wrong, before any modification. The Beyonce Rule applies: if the agent liked a behavior enough to depend on it, it should have put a test on it.
-- **`code-simplification` on the worst hotspots.** Chesterton's Fence is the operative principle: the skill forces the agent to understand _why_ code exists before removing it. Behavior-preserving simplification plus characterization tests is the lowest-risk way to make legacy code changeable.
-- **`git-workflow-and-versioning` everywhere.** Small atomic commits matter _more_ in brownfield: when a change to old code breaks something subtle, a ~100-line commit is bisectable; a 2,000-line "modernization" commit is not.
+- **`i3-test-driven-development`, applied selectively.** Don't aim for global coverage; aim for coverage _where change is planned_. For untested legacy behavior, write characterization tests, tests that pin down what the code currently does, right or wrong, before any modification. The Beyonce Rule applies: if the agent liked a behavior enough to depend on it, it should have put a test on it.
+- **`i3-code-simplification` on the worst hotspots.** Chesterton's Fence is the operative principle: the skill forces the agent to understand _why_ code exists before removing it. Behavior-preserving simplification plus characterization tests is the lowest-risk way to make legacy code changeable.
+- **`i3-git-workflow-and-versioning` everywhere.** Small atomic commits matter _more_ in brownfield: when a change to old code breaks something subtle, a ~100-line commit is bisectable; a 2,000-line "modernization" commit is not.
 
 ### Phase 3 | New work runs the full lifecycle
 
 Goal: two-speed adoption, legacy code stays under the Phase 1–2 regime; **new features get the greenfield treatment**.
 
-- New feature in the old codebase? `/spec → /plan → /build → /review`. The spec's boundaries section is where you declare what legacy surface the feature may and may not touch.
-- **`api-and-interface-design` at the seams.** When new code must talk to old code, design the boundary contract-first. Hyrum's Law is not theoretical in a years-old codebase, someone depends on every observable behavior, including the bugs.
-- **`security-and-hardening` as an audit, then a gate.** Run it once across the existing attack surface (auth, input handling, dependencies, the dependency audit alone usually pays for the exercise), file what you find, then enforce it on new changes.
+- New feature in the old codebase? `/i3-spec → /i3-plan → /i3-build → /i3-review`. The spec's boundaries section is where you declare what legacy surface the feature may and may not touch.
+- **`i3-api-and-interface-design` at the seams.** When new code must talk to old code, design the boundary contract-first. Hyrum's Law is not theoretical in a years-old codebase, someone depends on every observable behavior, including the bugs.
+- **`i3-security-and-hardening` as an audit, then a gate.** Run it once across the existing attack surface (auth, input handling, dependencies, the dependency audit alone usually pays for the exercise), file what you find, then enforce it on new changes.
 
 ### Phase 4 | Pay down, deprecate, observe
 
-- **`deprecation-and-migration`** is the brownfield skill par excellence: code-as-liability, compulsory vs. advisory deprecation, and zombie-code removal give you a disciplined way to shrink the legacy surface instead of just wrapping it.
-- **`observability-and-instrumentation`** retrofitted along the paths you actually debug: structured logging and RED metrics on the top incident sources first.
-- **`performance-optimization`** when regressions matter, its measure-first rule prevents the classic legacy trap of optimizing code that was never the bottleneck.
+- **`i3-deprecation-and-migration`** is the brownfield skill par excellence: code-as-liability, compulsory vs. advisory deprecation, and zombie-code removal give you a disciplined way to shrink the legacy surface instead of just wrapping it.
+- **`i3-observability-and-instrumentation`** retrofitted along the paths you actually debug: structured logging and RED metrics on the top incident sources first.
+- **`i3-performance-optimization`** when regressions matter, its measure-first rule prevents the classic legacy trap of optimizing code that was never the bottleneck.
 
 ### Brownfield anti-patterns
 
 - **"Big bang" adoption.** Loading the full lifecycle onto a legacy codebase on day one produces specs for code that already exists and refactors without safety nets. Sequence it.
 - **Letting the agent refactor untested code.** No characterization tests, no refactor. This is the single most expensive shortcut in brownfield adoption.
-- **Skipping `context-engineering` because "the code is the documentation."** The agent will infer conventions from the worst file it happens to read. Tell it the real ones.
+- **Skipping `i3-context-engineering` because "the code is the documentation."** The agent will infer conventions from the worst file it happens to read. Tell it the real ones.
 - **Treating the legacy system's behavior as wrong by default.** Chesterton's Fence: the weird retry loop may be load-bearing. Understand, then change.
 - **Ratcheting nothing.** Adoption should make quality monotonically better: each phase adds a gate that doesn't come back off. If a month in you can't name what's now enforced that wasn't before, the rollout has stalled.
 
@@ -117,11 +117,11 @@ Goal: two-speed adoption, legacy code stays under the Phase 1–2 regime; **new
 
 ## The two paths converge
 
-Both end in the same steady state: `/spec → /plan → /build → /review → /ship` for new work, always-on TDD and git discipline, review gates before merge, and skills loaded by phase rather than in bulk. Greenfield gets there in days; brownfield gets there in a quarter, and the difference is exactly the safety nets (context, characterization tests, boundaries) that the old codebase never had.
+Both end in the same steady state: `/i3-spec → /i3-plan → /i3-build → /i3-review → /i3-ship` for new work, always-on TDD and git discipline, review gates before merge, and skills loaded by phase rather than in bulk. Greenfield gets there in days; brownfield gets there in a quarter, and the difference is exactly the safety nets (context, characterization tests, boundaries) that the old codebase never had.
 
 |                        | Greenfield                     | Brownfield                               |
 | ---------------------- | ------------------------------ | ---------------------------------------- |
-| First skill loaded     | Native router, or `using-agent-skills` + `/spec` | `context-engineering`                    |
+| First skill loaded     | Native router, or `i3-using-agent-skills` + `/i3-spec` | `i3-context-engineering`                    |
 | First value delivered  | Spec'd, tested first feature   | Zero-risk reviews and safer bug fixes    |
 | TDD posture            | Universal from commit one      | Selective: tests where change is planned |
 | Refactoring rule       | Rare (little to refactor)      | Characterization tests first, always     |

package/docs/agents.md

@@ -15,9 +15,9 @@ Three layers, each with a distinct job:
 
 | Layer | What it is | Example | Composition role |
 |-------|-----------|---------|------------------|
-| **Skill** | A workflow with steps and exit criteria | `code-review-and-quality` | The *how* — invoked from inside a persona or command |
+| **Skill** | A workflow with steps and exit criteria | `i3-code-review-and-quality` | The *how* — invoked from inside a persona or command |
 | **Persona** | A role with a perspective and an output format | `code-reviewer` | The *who* — adopts a viewpoint, produces a report |
-| **Command** | A user-facing entry point | `/review`, `/ship` | The *when* — composes personas and skills |
+| **Command** | A user-facing entry point | `/i3-review`, `/i3-ship` | The *when* — composes personas and skills |
 
 The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow.
 
@@ -34,14 +34,14 @@ Pick this when you want one perspective on the current change and the user is in
 ### Slash command (single persona behind it)
 Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
 
-- `/review` → wraps `code-reviewer` with the project's review skill
-- `/test` → wraps `test-engineer` with TDD skill
-- `/webperf` → wraps `web-performance-auditor` for performance-focused audits on web apps
+- `/i3-review` → wraps `code-reviewer` with the project's review skill
+- `/i3-test` → wraps `test-engineer` with TDD skill
+- `/i3-webperf` → wraps `web-performance-auditor` for performance-focused audits on web apps
 
 ### Slash command (orchestrator — fan-out)
 Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges.
 
-- `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
+- `/i3-ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
 
 This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns.
 
@@ -51,16 +51,16 @@ This is the only orchestration pattern this repo endorses. See [references/orche
 Is the work a single perspective on a single artifact?
 ├── Yes → Direct persona invocation
 └── No  → Are the sub-tasks independent (no shared mutable state, no ordering)?
-         ├── Yes → Slash command with parallel fan-out (e.g. /ship)
-         └── No  → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)
+         ├── Yes → Slash command with parallel fan-out (e.g. /i3-ship)
+         └── No  → Sequential slash commands run by the user (/i3-spec → /i3-plan → /i3-build → /i3-test → /i3-review)
 ```
 
 ## Worked example: valid orchestration
 
-`/ship` is the canonical fan-out orchestrator in this repo:
+`/i3-ship` is the canonical fan-out orchestrator in this repo:
 
 ```
-/ship
+/i3-ship
   ├── (parallel) code-reviewer    → review report
   ├── (parallel) security-auditor → audit report
   └── (parallel) test-engineer    → coverage report
@@ -93,7 +93,7 @@ A `meta-orchestrator` persona whose job is "decide which other persona to call":
 Why this fails:
 - Pure routing layer with no domain value
 - Adds two paraphrasing hops → information loss + 2× token cost
-- The user already knows they want a review; let them call `/review` directly
+- The user already knows they want a review; let them call `/i3-review` directly
 - Replicates work that slash commands and `AGENTS.md` intent-mapping already do
 
 ## Rules for personas
@@ -107,7 +107,7 @@ Why this fails:
 
 The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification:
 
-- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example.
+- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/i3-ship` is the canonical example.
 - **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
 
 Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping.

package/docs/antigravity-setup.md

@@ -45,21 +45,21 @@ agy plugin list
 
 ## Lifecycle Workflows and Command Compatibility
 
-Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [upstream agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
+Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/i3-build` and the other short wrappers are available. This is tracked in [upstream agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
 
 Use the native plugin skills directly while that importer limitation applies:
 
 | Intended wrapper | Direct Antigravity invocation | Notes |
 |------------------|-------------------------------|-------|
-| `/spec` | `/i3-composer-agent:spec-driven-development` | Writes a structured spec before code |
-| `/constraints` | `/i3-composer-agent:constraint-driven-development` | Defines and enforces the project's quality bar |
-| `/planning` | `/i3-composer-agent:planning-and-task-breakdown` | Antigravity's built-in `/planning` command is a separate plan-mode control |
-| `/build` | `/i3-composer-agent:incremental-implementation` | Also invoke `/i3-composer-agent:test-driven-development`; wrapper-only `/build auto` orchestration is unavailable |
-| `/test` | `/i3-composer-agent:test-driven-development` | Runs the red-green-refactor workflow |
-| `/review` | `/i3-composer-agent:code-review-and-quality` | Runs the five-axis review workflow |
-| `/code-simplify` | `/i3-composer-agent:code-simplification` | Simplifies without changing behavior |
-| `/ship` | `/i3-composer-agent:shipping-and-launch` | The wrapper's automatic persona fan-out is unavailable; invoke specialist agents separately |
-| `/webperf` | Select `web-performance-auditor` from `/agents` | This workflow is a persona, not a skill |
+| `/i3-spec` | `/i3-composer-agent:i3-spec-driven-development` | Writes a structured spec before code |
+| `/i3-constraints` | `/i3-composer-agent:i3-constraint-driven-development` | Defines and enforces the project's quality bar |
+| `/i3-planning` | `/i3-composer-agent:i3-planning-and-task-breakdown` | Antigravity's built-in `/i3-planning` command is a separate plan-mode control |
+| `/i3-build` | `/i3-composer-agent:i3-incremental-implementation` | Also invoke `/i3-composer-agent:i3-test-driven-development`; wrapper-only `/i3-build auto` orchestration is unavailable |
+| `/i3-test` | `/i3-composer-agent:i3-test-driven-development` | Runs the red-green-refactor workflow |
+| `/i3-review` | `/i3-composer-agent:i3-code-review-and-quality` | Runs the five-axis review workflow |
+| `/i3-code-simplify` | `/i3-composer-agent:i3-code-simplification` | Simplifies without changing behavior |
+| `/i3-ship` | `/i3-composer-agent:i3-shipping-and-launch` | The wrapper's automatic persona fan-out is unavailable; invoke specialist agents separately |
+| `/i3-webperf` | Select `web-performance-auditor` from `/agents` | This workflow is a persona, not a skill |
 
 Do not add YAML frontmatter to the TOML files as a workaround. Gemini CLI reads the parallel TOML command format with a strict parser, and `---` frontmatter makes those files invalid TOML without changing Antigravity's conversion behavior.
 
@@ -80,7 +80,7 @@ To validate that your local plugin is correctly structured and contains all skil
 agy plugin validate /path/to/i3-composer-agent
 ```
 
-Then start a fresh session and type `/i3-composer-agent:` to inspect the namespaced skill catalog. If the validator reports that commands were converted but `/build` returns `No matches`, use the direct invocations above; reinstalling or adding a TOML `name` field does not resolve the known importer limitation.
+Then start a fresh session and type `/i3-composer-agent:` to inspect the namespaced skill catalog. If the validator reports that commands were converted but `/i3-build` returns `No matches`, use the direct invocations above; reinstalling or adding a TOML `name` field does not resolve the known importer limitation.
 
 ---
 
@@ -90,9 +90,9 @@ Then start a fresh session and type `/i3-composer-agent:` to inspect the namespa
 Antigravity CLI automatically discovers the `SKILL.md` files located in the `skills/` directory of the installed plugin. Using the trigger descriptions in each skill's frontmatter, the agent will dynamically activate the appropriate workflow when it detects matching developer intent.
 
 For example, when you ask the agent to:
-- **Design a new system** → It will suggest/activate `spec-driven-development`.
-- **Implement a feature** → It will activate `incremental-implementation` and `test-driven-development`.
-- **Fix a bug** → It will activate `debugging-and-error-recovery`.
+- **Design a new system** → It will suggest/activate `i3-spec-driven-development`.
+- **Implement a feature** → It will activate `i3-incremental-implementation` and `i3-test-driven-development`.
+- **Fix a bug** → It will activate `i3-debugging-and-error-recovery`.
 
 ### 2. Specialized Agent Personas
 The plugin registers reusable subagent definitions from the `agents/` directory:

package/docs/codebuddy-setup.md

@@ -1,12 +1,60 @@
 # Using i3 Composer Agent with CodeBuddy
 
-Prepare the complete plugin inside the project where you want to use it:
+## Desktop IDE installation
+
+Run inside your business project:
 
 ```bash
 npx @givolt/i3-composer-agent --codebuddy
 ```
 
-In the CodeBuddy chat, register the prepared directory and install the plugin:
+The terminal wizard preselects CodeBuddy, still allows multiple tools, and asks
+for project or global scope before installing. Project scope writes these paths:
+
+- `.codebuddy/skills/` — all 25 skills with `i3-` IDs.
+- `.codebuddy/references/` — shared checklists used by skill-relative links.
+- `.codebuddy/commands/` — all 9 existing lifecycle workflows.
+- `.codebuddy/agents/` — all 4 persona definitions.
+
+Global scope uses the same layout under `~/.codebuddy/`. Existing assets require
+confirmed replacement and are preserved in backup directories. Settings are
+not replaced. Reload the CodeBuddy window or start a new chat, then inspect
+the Skills list and type `/` to inspect the command menu.
+
+```text
+/i3-spec
+/i3-plan
+/i3-build
+/i3-build auto
+/i3-review
+/i3-ship
+```
+
+The command wrappers reference installed skill IDs without the plugin namespace.
+Their workflow content and approval gates are retained. File installation does
+not itself prove that the IDE has discovered or executed every workflow.
+
+For multiple tools or a noninteractive installation:
+
+```bash
+npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
+npx @givolt/i3-composer-agent --codebuddy --scope global --yes
+```
+
+CodeBuddy documents [IDE skills](https://www.codebuddy.cn/docs/ide/Features/Skills)
+and [IDE custom commands](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands).
+The directory layout follows its [configuration directory reference](https://www.codebuddy.cn/docs/cli/codebuddy-dir).
+
+## CodeBuddy Code native plugin registration
+
+For the terminal CodeBuddy Code plugin manager, explicitly prepare the full
+plugin instead of native skill installation:
+
+```bash
+npx @givolt/i3-composer-agent --prepare --codebuddy
+```
+
+In CodeBuddy Code, register the prepared directory and install the plugin:
 
 ```text
 /plugin marketplace add ./i3-composer-agent
@@ -14,28 +62,28 @@ In the CodeBuddy chat, register the prepared directory and install the plugin:
 ```
 
 Use the absolute directory printed by the CLI if CodeBuddy has a different
-working directory. Choose the intended installation scope in CodeBuddy's native
+working directory. Choose the intended installation scope in CodeBuddy Code's native
 plugin manager. Reload plugins or start a new session after installation.
 
-CodeBuddy supports the existing `.claude-plugin/plugin.json` compatibility
+CodeBuddy Code supports the existing `.claude-plugin/plugin.json` compatibility
 manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
 original lifecycle commands and their workflow content.
 
 ```text
-/i3-composer-agent:spec
-/i3-composer-agent:plan
-/i3-composer-agent:build
-/i3-composer-agent:build auto
-/i3-composer-agent:review
-/i3-composer-agent:ship
+/i3-composer-agent:i3-spec
+/i3-composer-agent:i3-plan
+/i3-composer-agent:i3-build
+/i3-composer-agent:i3-build auto
+/i3-composer-agent:i3-review
+/i3-composer-agent:i3-ship
 ```
 
-Skill IDs, persona names, artifact paths, and workflow gates retain their
-upstream behavior. The plugin namespace changes to `i3-composer-agent`.
+Skill IDs and command filenames use `i3-`. Persona names, artifact paths,
+and workflow gates retain their upstream behavior. The plugin namespace is
+`i3-composer-agent`.
 
-The bundle includes all skills and shared `references/`. Installing individual
-skills is a different distribution method and does not install the command
-wrappers or persona definitions.
+The prepared plugin includes all skills, personas, commands, hooks and shared
+`references/`. Native skill installation above does not enable plugin hooks.
 
-The CLI prepares files and prints registration commands. Actual host discovery
+In this explicit mode the CLI prepares files and prints registration commands. Actual host discovery
 and model execution should be verified after registering the plugin.

package/docs/codex-setup.md

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

package/docs/commandcode-setup.md

@@ -17,7 +17,7 @@ In an interactive terminal this shows a multi-select so you can choose which of
 **Install a specific skill:**
 
 ```bash
-cmd skills add /path/to/i3-composer-agent -s spec-driven-development
+cmd skills add /path/to/i3-composer-agent -s i3-spec-driven-development
 ```
 
 **User scope** (installs into `~/.commandcode/skills/`, available in every project):
@@ -30,7 +30,7 @@ cmd skills add /path/to/i3-composer-agent --global
 
 ```bash
 # Branch selectors apply to Git sources; prepared npm bundles have no Git history.
-cmd skills add /path/to/i3-composer-agent/skills/interview-me   # a specific path in the repo
+cmd skills add /path/to/i3-composer-agent/skills/i3-interview-me   # a specific path in the repo
 cmd skills add /path/to/i3-composer-agent --force         # overwrite / update if already installed
 ```
 
@@ -38,8 +38,8 @@ cmd skills add /path/to/i3-composer-agent --force         # overwrite / update i
 
 ```bash
 cmd skills list                       # list installed skills (project + user + bundled)
-cmd skills remove spec-driven-development           # remove a project-scoped skill
-cmd skills remove spec-driven-development --global  # remove a user-scoped skill
+cmd skills remove i3-spec-driven-development           # remove a project-scoped skill
+cmd skills remove i3-spec-driven-development --global  # remove a user-scoped skill
 ```
 
 `--force` on `add` re-fetches and overwrites an existing skill, which is how you update to the latest version.
@@ -49,7 +49,7 @@ cmd skills remove spec-driven-development --global  # remove a user-scoped skill
 Installed skills are discovered automatically and appear in the TUI slash menu, tagged `[skill]`:
 
 ```
-/spec-driven-development   [skill] Write a spec before writing code…
+/i3-spec-driven-development   [skill] Write a spec before writing code…
 ```
 
 Type `/` to browse, or start typing a skill name to filter. Use `/skills` to enable/disable skills.

package/docs/copilot-cli-setup.md

@@ -40,7 +40,7 @@ In an interactive session, `/skills list` shows the same catalog.
 The root `plugin.json` is the manifest Copilot CLI reads — it takes precedence over `.claude-plugin/plugin.json`, which belongs to Claude Code. That root manifest declares only a name, version and description, so component paths fall back to their defaults:
 
 - **Skills — available.** With no explicit path, the CLI uses the conventional `skills/` directory, and the skills are discovered there.
-- **Lifecycle commands — not available.** The root manifest has no `commands` field, so nothing registers `/spec`, `/plan`, `/build`, `/test`, `/review` or `/ship`. Those files live in `.claude/commands/` and are Claude Code commands.
+- **Lifecycle commands — not available.** The root manifest has no `commands` field, so nothing registers `/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review` or `/i3-ship`. Those files live in `.claude/commands/` and are Claude Code commands.
 
 For manifest precedence and the per-component path defaults, see the [CLI plugin reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) and [Creating plugins](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating).
 
@@ -48,11 +48,11 @@ For manifest precedence and the per-component path defaults, see the [CLI plugin
 
 Name the skill you want, or describe the task and let the agent route to it:
 
-> Use the spec-driven-development skill to write a spec for [the feature].
+> Use the i3-spec-driven-development skill to write a spec for [the feature].
 
-> Use the test-driven-development skill: write a failing test for this bug first, then fix it.
+> Use the i3-test-driven-development skill: write a failing test for this bug first, then fix it.
 
-> Use the code-review-and-quality skill to review my staged changes.
+> Use the i3-code-review-and-quality skill to review my staged changes.
 
 ## Troubleshooting
 
@@ -60,5 +60,5 @@ Name the skill you want, or describe the task and let the agent route to it:
 |---------|---------------|
 | `plugin install` can't resolve `i3-composer-agent@i3-composer-agent` | Run `copilot plugin marketplace add /path/to/i3-composer-agent` first — that name only resolves once the marketplace is registered. Or install the repository directly. |
 | Plugin installed but no skills | `copilot plugin list` to confirm the plugin, then `copilot skill list` (or `/skills list` in session) to see what was discovered. |
-| `/spec`, `/build` and friends are not found | Expected, not a broken install: the root manifest registers no commands. Ask for the skill by name instead. |
+| `/i3-spec`, `/i3-build` and friends are not found | Expected, not a broken install: the root manifest registers no commands. Ask for the skill by name instead. |
 | Skills changed locally but the CLI shows the old copy | Start a fresh session, or run with `--plugin-dir` pointing at your clone. |

package/docs/copilot-setup.md

@@ -2,7 +2,7 @@
 
 This guide covers Copilot in VS Code. For the standalone `copilot` command-line tool, see [copilot-cli-setup.md](copilot-cli-setup.md).
 
-**What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/spec-driven-development`, `/test-driven-development`, and so on. `npx skills add /path/to/i3-composer-agent` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/spec`, `/plan`, `/build`, `/test`, `/review`, `/ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows).
+**What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/i3-spec-driven-development`, `/i3-test-driven-development`, and so on. `npx skills add /path/to/i3-composer-agent` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows).
 
 ## Setup
 
@@ -11,11 +11,11 @@ This guide covers Copilot in VS Code. For the standalone `copilot` command-line
 Copilot supports creating agent skills using a `.github/skills`, `.claude/skills`, or `.agents/skills` directory in your repository.
 
 ```bash
-mkdir -p .github/skills/test-driven-development .github/skills/code-review-and-quality
+mkdir -p .github/skills/i3-test-driven-development .github/skills/i3-code-review-and-quality
 
 # Create files for essential skills
-cat /path/to/i3-composer-agent/skills/test-driven-development/SKILL.md > .github/skills/test-driven-development/SKILL.md
-cat /path/to/i3-composer-agent/skills/code-review-and-quality/SKILL.md > .github/skills/code-review-and-quality/SKILL.md
+cat /path/to/i3-composer-agent/skills/i3-test-driven-development/SKILL.md > .github/skills/i3-test-driven-development/SKILL.md
+cat /path/to/i3-composer-agent/skills/i3-code-review-and-quality/SKILL.md > .github/skills/i3-code-review-and-quality/SKILL.md
 ```
 
 Whichever of these two routes you use, the result is one `SKILL.md` per skill directory under one of those three project paths. An installer run with a global/user flag writes somewhere else instead — check its output for the path it used. Run `/skills` in Copilot Chat to open the **Configure Skills** menu and confirm what got discovered.
@@ -91,26 +91,26 @@ Skills are user-invocable by default, so once they're discovered the whole lifec
 
 | Workflow | Copilot invocation | Notes |
 |----------|--------------------|-------|
-| Define | `/spec-driven-development` | Writes a structured spec before code |
-| Plan | `/planning-and-task-breakdown` | Produces `tasks/plan.md` and `tasks/todo.md` |
-| Build | `/incremental-implementation` | Pair with `/test-driven-development`; one slice at a time |
-| Verify | `/test-driven-development` | Red-green-refactor, Prove-It for bugs |
-| Review | `/code-review-and-quality` | Five-axis review |
-| Ship | `/shipping-and-launch` | Launch readiness |
+| Define | `/i3-spec-driven-development` | Writes a structured spec before code |
+| Plan | `/i3-planning-and-task-breakdown` | Produces `tasks/plan.md` and `tasks/todo.md` |
+| Build | `/i3-incremental-implementation` | Pair with `/i3-test-driven-development`; one slice at a time |
+| Verify | `/i3-test-driven-development` | Red-green-refactor, Prove-It for bugs |
+| Review | `/i3-code-review-and-quality` | Five-axis review |
+| Ship | `/i3-shipping-and-launch` | Launch readiness |
 
 Type `/` to browse what's actually loaded in this workspace.
 
 Natural language is the fallback, and works in any Copilot surface whether or not the slash commands show up:
 
-> Use the spec-driven-development skill to write a spec for [the feature].
+> Use the i3-spec-driven-development skill to write a spec for [the feature].
 
-> Use the code-review-and-quality skill to review my staged changes.
+> Use the i3-code-review-and-quality skill to review my staged changes.
 
-### Optional: short `/spec`-style aliases
+### Optional: short `/i3-spec`-style aliases
 
 VS Code's extension-host local agents support [prompt files](https://code.visualstudio.com/docs/agent-customization/prompt-files) at `.github/prompts/<name>.prompt.md`, and each becomes a `/<name>` slash command. The Agent Host does **not** use prompt files — there, use the skill names above.
 
-An alias is a thin shortcut to one skill, nothing more. These aliases do not implement the orchestration in this repo's Claude Code commands — `/build auto`'s single-approval plan-and-implement pass and `/ship`'s parallel persona fan-out. Reproducing that on Copilot is its own piece of work, not something a one-file alias covers. Prefer the skill names as your default; reach for aliases only if the short form is worth the extra file.
+An alias is a thin shortcut to one skill, nothing more. These aliases do not implement the orchestration in this repo's Claude Code commands — `/i3-build auto`'s single-approval plan-and-implement pass and `/i3-ship`'s parallel persona fan-out. Reproducing that on Copilot is its own piece of work, not something a one-file alias covers. Prefer the skill names as your default; reach for aliases only if the short form is worth the extra file.
 
 Create one, without clobbering an existing file:
 
@@ -121,7 +121,7 @@ mkdir -p .github/prompts
 description: Write a structured spec before writing code
 ---
 
-Use the spec-driven-development skill.
+Use the i3-spec-driven-development skill.
 
 Ask clarifying questions about the objective and target users, core features and
 acceptance criteria, stack preferences and constraints, and known boundaries.
@@ -131,27 +131,27 @@ confirm with me before any code is written.
 EOF
 ```
 
-Reload the window, then type `/spec`.
+Reload the window, then type `/i3-spec`.
 
-For the rest, run the same `mkdir`/`cat` block with the filename swapped (the filename *is* the command name), and take the `description` and body from this table. **Replace the entire body below the `---` frontmatter**, not just the skill name — the spec body's SPEC.md and clarifying-question instructions belong to Define only, and leaving them in would make `/plan` or `/test` write a spec.
+For the rest, run the same `mkdir`/`cat` block with the filename swapped (the filename *is* the command name), and take the `description` and body from this table. **Replace the entire body below the `---` frontmatter**, not just the skill name — the spec body's SPEC.md and clarifying-question instructions belong to Define only, and leaving them in would make `/i3-plan` or `/i3-test` write a spec.
 
 | Alias file | `description` | Complete body — everything below the frontmatter |
 |------------|---------------|--------------------------------------------------|
-| `.github/prompts/plan.prompt.md` | Break an approved spec into ordered, verifiable tasks | Use the planning-and-task-breakdown skill. Read the spec, then break the work into small, independently verifiable tasks, each with acceptance criteria and explicit dependency order. Save the result to `tasks/plan.md` and `tasks/todo.md`. Write no product code — show me the plan and wait for my approval. |
-| `.github/prompts/build.prompt.md` | Implement the next planned task, test-first | Use the incremental-implementation and test-driven-development skills. Read `tasks/plan.md` and `tasks/todo.md`, then take the next unchecked task and only that one. Write a failing test first, make it pass, refactor, run the suite, and tick the task off. Stop there and report what changed. |
-| `.github/prompts/test.prompt.md` | Write tests before the code that satisfies them | Use the test-driven-development skill. For new behavior, write a failing test that captures it before any implementation. For a bug, reproduce it with a failing test first, then fix it. Run the suite after each step and show me the red and the green output. |
+| `.github/prompts/plan.prompt.md` | Break an approved spec into ordered, verifiable tasks | Use the i3-planning-and-task-breakdown skill. Read the spec, then break the work into small, independently verifiable tasks, each with acceptance criteria and explicit dependency order. Save the result to `tasks/plan.md` and `tasks/todo.md`. Write no product code — show me the plan and wait for my approval. |
+| `.github/prompts/build.prompt.md` | Implement the next planned task, test-first | Use the i3-incremental-implementation and i3-test-driven-development skills. Read `tasks/plan.md` and `tasks/todo.md`, then take the next unchecked task and only that one. Write a failing test first, make it pass, refactor, run the suite, and tick the task off. Stop there and report what changed. |
+| `.github/prompts/test.prompt.md` | Write tests before the code that satisfies them | Use the i3-test-driven-development skill. For new behavior, write a failing test that captures it before any implementation. For a bug, reproduce it with a failing test first, then fix it. Run the suite after each step and show me the red and the green output. |
 
 Write the body yourself, or take it from this table, rather than copying `.claude/commands/*.md` verbatim: those files reference skills as `i3-composer-agent:<name>`, a Claude Code plugin namespace that means nothing to Copilot.
 
 ### If the skill slash commands don't appear
 
-Work through these in order — `/spec-driven-development` missing and `/spec` missing have different causes:
+Work through these in order — `/i3-spec-driven-development` missing and `/i3-spec` missing have different causes:
 
 1. **Check where the skills landed.** Each one needs its own directory containing a `SKILL.md`. The project-level paths this guide uses are `.github/skills/`, `.claude/skills/` and `.agents/skills/` — but an installer run with a global/user flag writes outside the workspace instead (`~/.agents/skills/` and equivalents), so a skill that isn't in any of the three may simply be installed personally. Confirm the actual path against the [VS Code agent skills docs](https://code.visualstudio.com/docs/agent-customization/agent-skills), then re-install into the project if you wanted it project-scoped.
 2. **Check the frontmatter.** `name` must be present and valid — it *is* the slash command. A skill whose frontmatter opts out of user invocation won't appear.
 3. **Check the Configure Skills menu.** Run `/skills` and confirm the skill is enabled here.
 4. **Start a fresh session.** Newly added skills aren't always picked up mid-conversation.
-5. **Check the host.** If `/spec-driven-development` works but your `/spec` alias doesn't, you're likely on the Agent Host, which doesn't read prompt files.
+5. **Check the host.** If `/i3-spec-driven-development` works but your `/i3-spec` alias doesn't, you're likely on the Agent Host, which doesn't read prompt files.
 6. **Check versions.** VS Code (**Help → About**) and the Copilot Chat extension; skills-as-slash-commands is recent, so update if either is behind.
 
 ## Usage Tips