@givolt/i3-composer-agent 0.0.0-stage → 1.0.0

package/docs/adoption-guide.md

@@ -0,0 +1,129 @@
+# Adoption Guide: New Projects vs. Established Codebases
+
+How to roll out i3-composer-agent depends heavily on where your codebase is in its life. A greenfield project can adopt the full lifecycle from commit one. A codebase with years of history needs an incremental path that respects what already exists, its conventions, its undocumented decisions, and its lack of test coverage in places you'd rather not touch blind.
+
+This guide covers both paths. For installation mechanics, see [getting-started.md](getting-started.md) and the per-tool setup guides. For what each skill does, see the [skill catalog in the README](../README.md#all-25-skills).
+
+---
+
+## Which path are you on?
+
+| Signal                     | Greenfield                      | Brownfield                                   |
+| -------------------------- | ------------------------------- | -------------------------------------------- |
+| Age of codebase            | Days to weeks                   | Months to years                              |
+| Test coverage              | You control it from day one     | Uneven; some areas untested                  |
+| Conventions                | Defined as you go               | Established, often undocumented              |
+| Team habits                | Forming                         | Entrenched (for better or worse)             |
+| Risk of a bad agent change | Low blast radius                | Can break things nobody remembers how to fix |
+| Adoption strategy          | **Full lifecycle, immediately** | **Incremental, verification-first**          |
+
+If you're somewhere in between (a young project that already shipped to production), start with the brownfield path and accelerate, it converges on the same end state.
+
+---
+
+## Path A | Greenfield: full lifecycle from day one
+
+A new project is the best-case scenario: there's no legacy behavior to preserve, so the skills' quality gates cost almost nothing and compound from the first commit.
+
+### 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.
+
+### 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)
+```
+
+`/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.
+
+### 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`                                    |
+
+### 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.
+- **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.
+
+---
+
+## Path B | Brownfield: incremental, verification-first
+
+In an established codebase, the risk profile inverts: the danger isn't building the wrong thing, it's _changing_ something whose behavior nobody fully specified. The adoption order therefore starts with the skills that **read and protect** the codebase, and only later moves to the skills that **change** it.
+
+### Phase 1 | Context and read-only skills
+
+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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+- **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.
+
+---
+
+## 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.
+
+|                        | Greenfield                     | Brownfield                               |
+| ---------------------- | ------------------------------ | ---------------------------------------- |
+| First skill loaded     | Native router, or `using-agent-skills` + `/spec` | `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     |
+| Riskiest anti-pattern  | Skipping the spec              | Refactoring untested code                |
+| Time to full lifecycle | Day one                        | ~One quarter, two-speed in between       |

package/docs/advanced-per-agent-configuration.md

@@ -0,0 +1,70 @@
+# Advanced per-agent configuration
+
+Skills in this repository are intentionally portable. Every `SKILL.md` keeps its frontmatter limited to the fields the [Agent Skills specification](https://agentskills.io) defines, so the same file works across Claude Code, Cursor, Gemini CLI, Antigravity, and any other spec-conformant client.
+
+Several agents also support extra runtime controls: model routing, tool restrictions, turn limits, execution isolation. These controls are valuable, but they are vendor-specific and do not belong in the shared, portable frontmatter. This document explains which controls each agent supports, where they belong, and how to apply them as an opt-in without breaking portability.
+
+This is the canonical reference for per-agent configuration, and it supersedes the earlier approach of adding vendor fields to top-level `SKILL.md` frontmatter. Fields such as `kind`, `model`, `temperature`, `max_turns`, `tools`, and `context` must not appear at the top level of a skill. They belong under `metadata` or in a separate per-agent adapter file, as described below.
+
+## Principles
+
+1. **Keep `SKILL.md` portable.** The Agent Skills specification reserves top-level frontmatter for `name`, `description`, `license`, `compatibility`, `metadata`, and the experimental `allowed-tools`. Vendor or client-specific properties belong under `metadata`, not at the top level.
+2. **Unknown top-level fields are not guaranteed to be ignored.** Many parsers only read `name` and `description` and silently drop the rest, but a strict spec-conformant validator or client may flag or reject unrecognized top-level keys. Putting vendor fields under `metadata` keeps the file conformant everywhere.
+3. **Opt-in, not global.** Runtime controls should be something a user adds for their own agent and workflow, not a default baked into every skill in the repository.
+4. **Prefer generation over hand-editing.** Where a configuration is repetitive and mechanical, generate it from a single source of truth instead of maintaining copies by hand. See [Automating with scripts](#automating-with-scripts).
+
+## Where vendor fields belong
+
+| Field type | Example | Correct home |
+|---|---|---|
+| Spec fields | `name`, `description`, `license`, `compatibility` | Top-level frontmatter in `SKILL.md` |
+| Vendor metadata | model hints, routing tags | Under the `metadata` key in `SKILL.md` |
+| Runtime orchestration | subagent definitions, turn limits, tool allowlists | A separate per-agent adapter file (see each agent below) |
+
+## Claude Code
+
+Claude Code reads `name` and `description` for discovery. Custom commands and skills share the same frontmatter, so the `context` and `allowed-tools` fields below work in both `.claude/commands/*.md` and `.claude/skills/*/SKILL.md`.
+
+- **`context: fork`** runs a command or skill in an isolated subagent context instead of the active conversation. This gives context isolation, repeatable execution from a clean state, execution tokens spent in the fork rather than the main session, and a cleaner handoff where only the result surfaces back. An optional **`agent`** field selects which subagent type runs the fork (for example `agent: Plan`); it defaults to `general-purpose`.
+- **`allowed-tools`** pre-approves tools; it does not restrict them. Listed tools run without a permission prompt for the turn that invokes the command or skill, and the grant clears on your next message. Nothing is removed from the tool pool.
+- **`disallowed-tools`** is the field that actually restricts: it removes the listed tools from the available pool while the skill is active, which is what least-privilege needs for passive stages such as review or audit. The restriction also clears on your next message. Note it is a Claude Code field and not one of the specification's six, so it belongs in a local copy or an adapter file; in a published `SKILL.md` it fails packaging with an unexpected-key error.
+
+These are Claude Code conventions. Keep the shared, published `SKILL.md` limited to spec fields; apply these runtime controls in your own local command or skill copies instead.
+
+## Gemini CLI and Antigravity
+
+Gemini CLI and Antigravity discover skills the same way: they match `name` and `description`, then load the full skill on demand. Runtime orchestration lives in a separate resource, not in the skill frontmatter.
+
+- **Subagent definitions** live in `.gemini/agents/*.md`, which are distinct from skills. Their schema is `kind` (`local` or `remote`), `model`, `temperature`, `max_turns`, and `tools`. Note that this is a subagent schema, not a skill schema: the two should not be merged into one `SKILL.md`.
+- **Model routing** can send lighter tasks (formatting, documentation, git operations) to a faster model and reserve a stronger model for cognitively demanding work (debugging, security auditing, interface design).
+- **Tool restrictions** enforce least-privilege per subagent, which also trims unused tool schemas from the prompt.
+- **Turn limits** (`max_turns`) cap execution to avoid runaway correction loops.
+
+### Model guidance
+
+Google recommends omitting `temperature` for Gemini 3.x models and using `thinking_level` instead. Do not hardcode `temperature` on skills or subagents routed to 3.x models; prefer `thinking_level` and revisit this guidance as the models evolve.
+
+```yaml
+# .gemini/agents/security-auditor.md
+---
+kind: local
+model: gemini-3-pro
+thinking_level: high   # not: temperature: 0.1
+tools: [read_file, grep]
+max_turns: 10
+---
+```
+
+## Automating with scripts
+
+Maintaining per-agent metadata by hand across every skill is repetitive, drifts out of sync, and is easy to get wrong. A better approach is to keep a single source of truth and generate the agent-specific output:
+
+- A generator reads a per-skill configuration map (which model, tool allowlist, turn limit, and isolation each skill should use for a given agent).
+- For metadata-style fields, it injects them under the `metadata` key of each `SKILL.md`, keeping the file spec-conformant.
+- For orchestration-style fields, it emits the separate adapter files an agent expects, for example `.gemini/agents/*.md` subagent definitions, leaving `SKILL.md` untouched.
+
+Generation also lets the tooling validate **semantics, not just shape**: confirm that a model name is a known model, that a tool name is a real tool, that `max_turns` is a positive integer, and that `temperature` (where still applicable) is a valid number in range. Shape-only checks let invalid values such as `parseInt("1.5")` or `parseFloat("0.2oops")` slip through.
+
+## Status
+
+This document consolidates the discussion from [#272](https://github.com/addyosmani/agent-skills/pull/272), [#36](https://github.com/addyosmani/agent-skills/pull/36), and [upstream agent-skills #35](https://github.com/addyosmani/agent-skills/issues/35), all closed in favor of this approach. It is the single reference for per-agent configuration: it keeps the shared skills portable while documenting the advanced controls each agent offers as an opt-in. The script-based automation described above is a proposal pending agreement before any implementation.

package/docs/agents.md

@@ -0,0 +1,123 @@
+# Agent Personas
+
+Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
+
+| Persona | Role | Best for |
+|---------|------|----------|
+| [code-reviewer](../agents/code-reviewer.md) | Senior Staff Engineer | Five-axis review before merge |
+| [security-auditor](../agents/security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit |
+| [test-engineer](../agents/test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
+| [web-performance-auditor](../agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit, loading/rendering/network analysis |
+
+## How personas relate to skills and commands
+
+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 |
+| **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 |
+
+The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow.
+
+## When to use each
+
+### Direct persona invocation
+Pick this when you want one perspective on the current change and the user is in the loop.
+
+- "Review this PR" → invoke `code-reviewer` directly
+- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly
+- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly
+- "Audit Core Web Vitals on the product page" → invoke `web-performance-auditor` directly
+
+### 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
+
+### 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
+
+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.
+
+## Decision matrix
+
+```
+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)
+```
+
+## Worked example: valid orchestration
+
+`/ship` is the canonical fan-out orchestrator in this repo:
+
+```
+/ship
+  ├── (parallel) code-reviewer    → review report
+  ├── (parallel) security-auditor → audit report
+  └── (parallel) test-engineer    → coverage report
+                  ↓
+        merge phase (main agent)
+                  ↓
+        go/no-go decision + rollback plan
+```
+
+Why this works:
+- Each sub-agent operates on the same diff but produces a **different perspective**
+- They have no dependencies on each other → genuine parallelism, real wall-clock savings
+- Each runs in a fresh context window → main session stays uncluttered
+- The merge step is small and benefits from full context, so it stays in the main agent
+
+## Worked example: invalid orchestration (do not build this)
+
+A `meta-orchestrator` persona whose job is "decide which other persona to call":
+
+```
+/work-on-pr → meta-orchestrator
+                  ↓ (decides "this needs a review")
+              code-reviewer
+                  ↓ (returns)
+              meta-orchestrator (paraphrases result)
+                  ↓
+              user
+```
+
+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
+- Replicates work that slash commands and `AGENTS.md` intent-mapping already do
+
+## Rules for personas
+
+1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
+2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you.
+3. A persona may invoke skills (the *how*).
+4. Every persona file ends with a "Composition" block stating where it fits.
+
+## Claude Code interop
+
+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 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.
+
+Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
+
+## Adding a new persona
+
+1. Create `agents/<role>.md` with the same frontmatter format used by existing personas.
+2. Define the role, scope, output format, and rules.
+3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
+4. Add the persona to the table at the top of this file.
+5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself.

package/docs/antigravity-setup.md

@@ -0,0 +1,128 @@
+# Using i3-composer-agent with Antigravity CLI (agy)
+
+The `i3-composer-agent` package can be installed as a native plugin in the Antigravity CLI (`agy`), giving the agent access to structured workflows and personas.
+
+## Setup
+
+### Option 1: Native Plugin Installation (Recommended)
+
+Antigravity CLI has a first-class [plugin system](https://www.agy.dev/docs/plugins/) that registers skills and agents. The repository also carries legacy command TOMLs, but affected `agy` releases do not expose their converted wrappers; see [Lifecycle Workflows and Command Compatibility](#lifecycle-workflows-and-command-compatibility).
+
+**Install from a prepared local bundle:**
+
+```bash
+agy plugin install /path/to/i3-composer-agent
+```
+
+**Install from a local clone:**
+
+1. Prepare the plugin bundle:
+   ```bash
+   npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+   ```
+2. Install the plugin using `agy`:
+   ```bash
+   agy plugin install /path/to/i3-composer-agent
+   ```
+
+This will validate the plugin and install it into your global Antigravity configuration directory (`~/.gemini/config/plugins/i3-composer-agent/`).
+
+> **Note:** on current agy releases the plugin lands under `~/.gemini/config/plugins/`, not the legacy `~/.gemini/antigravity-cli/plugins/` path used by older versions. If you don't see the plugin at the legacy path, check `~/.gemini/config/plugins/i3-composer-agent/` first.
+
+### Option 2: Import from Gemini CLI
+
+If you have already installed `i3-composer-agent` under your legacy Gemini CLI installation, you can import it directly:
+```bash
+agy plugin import gemini
+```
+
+Once installed, verify the active plugin:
+```bash
+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).
+
+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 |
+
+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.
+
+---
+
+## Skills & Discovery
+
+Antigravity automatically discovers skills inside the plugin's `skills/` directory. 
+* Antigravity matches user tasks and intents to relevant skills on-demand.
+* If a task matches a skill, the agent will load the skill and prompt you for permission before executing.
+
+---
+
+## Verification & Validation
+
+To validate that your local plugin is correctly structured and contains all skills, run:
+```bash
+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.
+
+---
+
+## How It Works
+
+### 1. On-Demand Skill Activation
+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`.
+
+### 2. Specialized Agent Personas
+The plugin registers reusable subagent definitions from the `agents/` directory:
+- `code-reviewer.md`
+- `security-auditor.md`
+- `test-engineer.md`
+
+You can invoke these personas directly within your session or when delegating tasks using subagents.
+
+---
+
+## Configuration & Customization
+
+### Project-Specific Enforcements (`AGENTS.md`)
+To enforce strict skill compliance (e.g. requiring a spec or plan before writing code), copy or link `AGENTS.md` into the root of your workspace. Antigravity CLI reads this file to align the agent's behavior and planning phase with your team's conventions.
+
+### Sandbox Mode
+If you want to run skills or scripts with limited terminal permissions (for safety when running third-party validation tests), launch the CLI with:
+
+```bash
+agy --sandbox
+```
+
+---
+
+## Usage Tips
+
+1. **Keep plugins up-to-date:** You can update the CLI or check for newer plugin versions using:
+   ```bash
+   agy update
+   ```
+2. **Review before execution:** When agents execute complex refactoring tasks using these skills, use `Ctrl+r` to enter the **Artifact Review** screen to review, edit, or approve code before it is committed.
+3. **Control permissions:** You can use the `--dangerously-skip-permissions` flag only in trusted local projects where you want to bypass manual tool approval prompts.

package/docs/codebuddy-setup.md

@@ -0,0 +1,41 @@
+# Using i3 Composer Agent with CodeBuddy
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+```
+
+In the CodeBuddy chat, register the prepared directory and install the plugin:
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Use the absolute directory printed by the CLI if CodeBuddy has a different
+working directory. Choose the intended installation scope in CodeBuddy's native
+plugin manager. Reload plugins or start a new session after installation.
+
+CodeBuddy 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
+```
+
+Skill IDs, persona names, artifact paths, and workflow gates retain their
+upstream behavior. The plugin namespace changes to `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 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

@@ -0,0 +1,34 @@
+# Using i3 Composer Agent with Codex
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codex
+```
+
+The CLI copies a persistent `./i3-composer-agent/` bundle and prints these
+native registration commands. Run them to enable the plugin:
+
+```bash
+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,
+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
+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
+skills natively. The meta-skill can remain installed and explicitly invoked.
+
+For local source testing, replace `./i3-composer-agent` above with the absolute
+path to the branded checkout. The CLI does not modify existing plugin settings.

package/docs/commandcode-setup.md

@@ -0,0 +1,69 @@
+# Using i3-composer-agent with Command Code
+
+[Command Code](https://commandcode.ai) has a native skills system. The built-in `cmd skills` command clones a GitHub repo, recursively discovers every `SKILL.md`, and installs the ones you pick.
+
+The Command Code binary is available as `cmd` (with aliases `cmdc` on Windows and `command-code`). The examples below use `cmd`.
+
+## Install
+
+**Project scope** (installs into `.commandcode/skills/` at the current git root — the default):
+
+```bash
+cmd skills add /path/to/i3-composer-agent
+```
+
+In an interactive terminal this shows a multi-select so you can choose which of the 25 skills to install. Pipe/non-interactive invocations install all discovered skills.
+
+**Install a specific skill:**
+
+```bash
+cmd skills add /path/to/i3-composer-agent -s spec-driven-development
+```
+
+**User scope** (installs into `~/.commandcode/skills/`, available in every project):
+
+```bash
+cmd skills add /path/to/i3-composer-agent --global
+```
+
+**Other supported forms:**
+
+```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 --force         # overwrite / update if already installed
+```
+
+## Manage
+
+```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
+```
+
+`--force` on `add` re-fetches and overwrites an existing skill, which is how you update to the latest version.
+
+## Usage
+
+Installed skills are discovered automatically and appear in the TUI slash menu, tagged `[skill]`:
+
+```
+/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.
+
+## Where skills live
+
+Command Code discovers skills from these locations (project entries resolve against the nearest git root):
+
+| Scope | Path |
+|-------|------|
+| Project | `.commandcode/skills/<name>/SKILL.md` |
+| Project (agents-compat) | `.agents/skills/<name>/SKILL.md` |
+| User | `~/.commandcode/skills/<name>/SKILL.md` |
+| User (agents-compat) | `~/.agents/skills/<name>/SKILL.md` |
+
+`cmd skills add` writes to `.commandcode/skills/` (project) or `~/.commandcode/skills/` (`--global`).
+