@givolt/i3-composer-agent 1.0.1 → 2.1.0

package/docs/gemini-cli-setup.md

@@ -41,9 +41,9 @@ For skills you want always loaded as persistent project context (rather than on-
 
 ```bash
 # Create GEMINI.md with core skills as persistent context
-cat /path/to/i3-composer-agent/skills/incremental-implementation/SKILL.md > GEMINI.md
+cat /path/to/i3-composer-agent/skills/i3-incremental-implementation/SKILL.md > GEMINI.md
 echo -e "\n---\n" >> GEMINI.md
-cat /path/to/i3-composer-agent/skills/code-review-and-quality/SKILL.md >> GEMINI.md
+cat /path/to/i3-composer-agent/skills/i3-code-review-and-quality/SKILL.md >> GEMINI.md
 ```
 
 You can also modularize by importing from separate files:
@@ -51,8 +51,8 @@ You can also modularize by importing from separate files:
 ```markdown
 # Project Instructions
 
-@skills/test-driven-development/SKILL.md
-@skills/incremental-implementation/SKILL.md
+@skills/i3-test-driven-development/SKILL.md
+@skills/i3-incremental-implementation/SKILL.md
 ```
 
 Use `/memory show` to verify loaded context, and `/memory reload` to refresh after changes.
@@ -65,18 +65,18 @@ Use `/memory show` to verify loaded context, and `/memory reload` to refresh aft
 
 Add these as persistent context for every session:
 
-- `incremental-implementation` — Build in small verifiable slices
-- `code-review-and-quality` — Five-axis review
+- `i3-incremental-implementation` — Build in small verifiable slices
+- `i3-code-review-and-quality` — Five-axis review
 
 ### On-Demand (Skills)
 
 Install these as skills so they activate only when relevant:
 
-- `test-driven-development` — Activates when implementing logic or fixing bugs
-- `spec-driven-development` — Activates when starting a new project or feature
-- `frontend-ui-engineering` — Activates when building UI
-- `security-and-hardening` — Activates during security reviews
-- `performance-optimization` — Activates during performance work
+- `i3-test-driven-development` — Activates when implementing logic or fixing bugs
+- `i3-spec-driven-development` — Activates when starting a new project or feature
+- `i3-frontend-ui-engineering` — Activates when building UI
+- `i3-security-and-hardening` — Activates during security reviews
+- `i3-performance-optimization` — Activates during performance work
 
 ## Advanced Configuration
 
@@ -84,8 +84,8 @@ Install these as skills so they activate only when relevant:
 
 Many skills in this pack leverage [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools to interact with the environment. For example:
 
-- `browser-testing-with-devtools` uses the `chrome-devtools` MCP extension.
-- `performance-optimization` can benefit from performance-related MCP tools.
+- `i3-browser-testing-with-devtools` uses the `chrome-devtools` MCP extension.
+- `i3-performance-optimization` can benefit from performance-related MCP tools.
 
 To enable these, ensure you have the relevant MCP extensions installed in your Gemini CLI configuration (`~/.gemini/config.json`).
 
@@ -93,37 +93,37 @@ To enable these, ensure you have the relevant MCP extensions installed in your G
 
 Gemini CLI supports session lifecycle hooks. You can use these to automatically inject context or run validation scripts at the start of a session.
 
-To replicate the `i3-composer-agent` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill. `hooks/session-start.sh` in this repo is a ready-made script for that: it prints the `using-agent-skills` meta-skill as a standard `SessionStart` JSON envelope on stdout.
+To replicate the `i3-composer-agent` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill. `hooks/session-start.sh` in this repo is a ready-made script for that: it prints the `i3-using-agent-skills` meta-skill as a standard `SessionStart` JSON envelope on stdout.
 
 ### Explicit Context Loading
 
 You can explicitly load any skill into your current session by referencing it with the `@` symbol in your prompt:
 
 ```markdown
-Use the @skills/test-driven-development/SKILL.md skill to implement this fix.
+Use the @skills/i3-test-driven-development/SKILL.md skill to implement this fix.
 ```
 
 This is useful when you want to ensure a specific workflow is followed without waiting for auto-discovery.
 
 ## Slash Commands
 
-The repo ships 9 slash commands under `.gemini/commands/`: 8 lifecycle commands plus the `/webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root.
+The repo ships 9 slash commands under `.gemini/commands/`: 8 lifecycle commands plus the `/i3-webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root.
 
 | Command | What it does |
 |---------|--------------|
-| `/spec` | Write a structured spec before writing code |
-| `/constraints` | Define and enforce the project's quality bar |
-| `/planning` | Break work into small, verifiable tasks |
-| `/build` | Implement the next task incrementally |
-| `/test` | Run TDD workflow — red, green, refactor |
-| `/review` | Five-axis code review |
-| `/code-simplify` | Reduce complexity without changing behavior |
-| `/ship` | Pre-launch checklist via parallel persona fan-out |
-| `/webperf` | Audit browser-facing apps for Core Web Vitals and performance issues |
+| `/i3-spec` | Write a structured spec before writing code |
+| `/i3-constraints` | Define and enforce the project's quality bar |
+| `/i3-planning` | Break work into small, verifiable tasks |
+| `/i3-build` | Implement the next task incrementally |
+| `/i3-test` | Run TDD workflow — red, green, refactor |
+| `/i3-review` | Five-axis code review |
+| `/i3-code-simplify` | Reduce complexity without changing behavior |
+| `/i3-ship` | Pre-launch checklist via parallel persona fan-out |
+| `/i3-webperf` | Audit browser-facing apps for Core Web Vitals and performance issues |
 
 Each command invokes the corresponding skill automatically — no manual skill loading required.
 
-> **Note:** Use `/planning` instead of `/plan` — `/plan` conflicts with a Gemini CLI internal command name.
+> **Note:** Use `/i3-planning` instead of `/i3-plan` — `/i3-plan` conflicts with a Gemini CLI internal command name.
 
 ## Usage Tips
 

package/docs/getting-started.md

@@ -38,13 +38,13 @@ Copy the relevant `SKILL.md` content into your agent's system prompt, rules file
 
 **Rules file:** Add skill content to your project's rules file (CLAUDE.md, .cursorrules, etc.).
 
-**Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change."
+**Conversation:** Reference the skill when giving instructions: "Follow the i3-test-driven-development process for this change."
 
 ### 4. Use the meta-skill for discovery when needed
 
-If your agent does not route skills natively, start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill.
+If your agent does not route skills natively, start with the `i3-using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill.
 
-If your host already discovers and activates skills from their descriptions, do not also paste `using-agent-skills` into an always-on system prompt or rules file. That creates two routers for the same task. Install the individual skills and let the host activate them on demand instead.
+If your host already discovers and activates skills from their descriptions, do not also paste `i3-using-agent-skills` into an always-on system prompt or rules file. That creates two routers for the same task. Install the individual skills and let the host activate them on demand instead.
 
 ### Existing projects need no migration
 
@@ -66,9 +66,9 @@ Rolling out to a real project? The **[Adoption Guide](adoption-guide.md)** cover
 
 Load three essential skills into your rules file:
 
-1. **spec-driven-development** — For defining what to build
-2. **test-driven-development** — For proving it works
-3. **code-review-and-quality** — For verifying quality before merge
+1. **i3-spec-driven-development** — For defining what to build
+2. **i3-test-driven-development** — For proving it works
+3. **i3-code-review-and-quality** — For verifying quality before merge
 
 These three cover the most critical quality gaps in AI-assisted development.
 
@@ -77,19 +77,19 @@ These three cover the most critical quality gaps in AI-assisted development.
 For comprehensive coverage, load skills by phase:
 
 ```
-Starting a project:  spec-driven-development → planning-and-task-breakdown
-During development:  incremental-implementation + test-driven-development
-Before merge:        code-review-and-quality + security-and-hardening
-Before deploy:       shipping-and-launch
+Starting a project:  i3-spec-driven-development → i3-planning-and-task-breakdown
+During development:  i3-incremental-implementation + i3-test-driven-development
+Before merge:        i3-code-review-and-quality + i3-security-and-hardening
+Before deploy:       i3-shipping-and-launch
 ```
 
 ### Context-Aware Loading
 
 Don't load all skills at once — it wastes context. Load skills relevant to the current task:
 
-- Working on UI? Load `frontend-ui-engineering`
-- Debugging? Load `debugging-and-error-recovery`
-- Setting up CI? Load `ci-cd-and-automation`
+- Working on UI? Load `i3-frontend-ui-engineering`
+- Debugging? Load `i3-debugging-and-error-recovery`
+- Setting up CI? Load `i3-ci-cd-and-automation`
 
 ## Skill Anatomy
 
@@ -117,7 +117,7 @@ The `agents/` directory contains pre-configured agent personas:
 | `code-reviewer.md` | Five-axis code review |
 | `test-engineer.md` | Test strategy and writing |
 | `security-auditor.md` | Vulnerability detection |
-| `web-performance-auditor.md` | Core Web Vitals & performance audit (via `/webperf`) |
+| `web-performance-auditor.md` | Core Web Vitals & performance audit (via `/i3-webperf`) |
 
 Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
 
@@ -127,16 +127,16 @@ The `.claude/commands/` directory contains slash commands for Claude Code:
 
 | Command | Skill Invoked |
 |---------|---------------|
-| `/spec` | spec-driven-development |
-| `/constraints` | constraint-driven-development |
-| `/plan` | planning-and-task-breakdown |
-| `/build` | incremental-implementation + test-driven-development |
-| `/build auto` | planning-and-task-breakdown → incremental-implementation + test-driven-development (whole plan, one approval) |
-| `/test` | test-driven-development |
-| `/review` | code-review-and-quality |
-| `/code-simplify` | code-simplification |
-| `/ship` | shipping-and-launch |
-| `/webperf` | web-performance-auditor (specialist agent, web apps only) |
+| `/i3-spec` | i3-spec-driven-development |
+| `/i3-constraints` | i3-constraint-driven-development |
+| `/i3-plan` | i3-planning-and-task-breakdown |
+| `/i3-build` | i3-incremental-implementation + i3-test-driven-development |
+| `/i3-build auto` | i3-planning-and-task-breakdown → i3-incremental-implementation + i3-test-driven-development (whole plan, one approval) |
+| `/i3-test` | i3-test-driven-development |
+| `/i3-review` | i3-code-review-and-quality |
+| `/i3-code-simplify` | i3-code-simplification |
+| `/i3-ship` | i3-shipping-and-launch |
+| `/i3-webperf` | web-performance-auditor (specialist agent, web apps only) |
 
 > **Note:** When installed as a Claude Code plugin you may see a warning like
 > _"Default commands/ folder is ignored because the manifest sets 'commands'"_.
@@ -150,13 +150,13 @@ The `references/` directory contains supplementary checklists:
 
 | Reference | Use With |
 |-----------|----------|
-| `testing-patterns.md` | test-driven-development |
-| `performance-checklist.md` | performance-optimization |
-| `security-checklist.md` | security-and-hardening |
-| `accessibility-checklist.md` | frontend-ui-engineering |
+| `testing-patterns.md` | i3-test-driven-development |
+| `performance-checklist.md` | i3-performance-optimization |
+| `security-checklist.md` | i3-security-and-hardening |
+| `accessibility-checklist.md` | i3-frontend-ui-engineering |
 | `definition-of-done.md` | all skills / every change |
-| `observability-checklist.md` | observability-and-instrumentation |
-| `orchestration-patterns.md` | doubt-driven-development |
+| `observability-checklist.md` | i3-observability-and-instrumentation |
+| `orchestration-patterns.md` | i3-doubt-driven-development |
 
 Load a reference when you need detailed patterns beyond what the skill covers.
 
@@ -165,12 +165,10 @@ selected `skills/<name>/` directory is copied. The skill still works, but paths
 to supplementary checklists in the repo-level `references/` directory are
 unavailable. Use a whole-repo integration, clone the repository, or copy the
 needed checklist into a `references/` directory inside the installed skill.
-This portability gap is tracked in
-[upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361).
 
 ## Spec and task artifacts
 
-The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress:
+The `/i3-spec` and `/i3-plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress:
 
 - Keep them in version control during development so the human and the agent have a shared source of truth.
 - Update them when scope or decisions change.
@@ -189,11 +187,11 @@ The same artifacts are the handoff between sessions. For a small task, run the w
 
 #### Task-boundary restarts and Ralph loops
 
-`/build auto` can run the whole approved plan in one session. It does not require or perform a fresh process per task. Its per-task status updates, verification results, and commits make each completed task a restartable boundary, so a capable external harness may exit and resume there without depending on chat history.
+`/i3-build auto` can run the whole approved plan in one session. It does not require or perform a fresh process per task. Its per-task status updates, verification results, and commits make each completed task a restartable boundary, so a capable external harness may exit and resume there without depending on chat history.
 
-A shell-level "Ralph loop" is harness behavior, not a separate skill workflow. If you use one, restart only after the current task has reached a recorded boundary; on re-entry, read the durable artifacts and repository state before selecting the next pending task. A process exit is not evidence that a task passed, and a restart must not bypass an approval gate. See the `context-engineering` skill's **Restartable Session Boundaries** section for the handoff checklist.
+A shell-level "Ralph loop" is harness behavior, not a separate skill workflow. If you use one, restart only after the current task has reached a recorded boundary; on re-entry, read the durable artifacts and repository state before selecting the next pending task. A process exit is not evidence that a task passed, and a restart must not bypass an approval gate. See the `i3-context-engineering` skill's **Restartable Session Boundaries** section for the handoff checklist.
 
-This doesn't need the `/spec` and `/plan` wrappers — plain requests work in any agent, including a `npx skills add` install that only has the skills:
+This doesn't need the `/i3-spec` and `/i3-plan` wrappers — plain requests work in any agent, including a `npx skills add` install that only has the skills:
 
 > Read SPEC.md, then break it into small verifiable tasks with acceptance criteria and dependency order. Save them to tasks/plan.md and tasks/todo.md. No product code yet — show me the plan first.
 
@@ -201,8 +199,8 @@ This doesn't need the `/spec` and `/plan` wrappers — plain requests work in an
 
 ## Tips
 
-1. **Start with spec-driven-development** for any non-trivial work
-2. **Always load test-driven-development** when writing code
+1. **Start with i3-spec-driven-development** for any non-trivial work
+2. **Always load i3-test-driven-development** when writing code
 3. **Don't skip verification steps** — they're the whole point
 4. **Load skills selectively** — more context isn't always better
 5. **Use the agents for review** — different perspectives catch different issues

package/docs/opencode-setup.md

@@ -30,7 +30,7 @@ npx skills add /path/to/i3-composer-agent --list     # browse before installing
 Install a single skill:
 
 ```bash
-npx skills add /path/to/i3-composer-agent --skill spec-driven-development
+npx skills add /path/to/i3-composer-agent --skill i3-spec-driven-development
 ```
 
 By default `npx skills` installs into a tool-specific directory (often `.claude/skills/` or a shared location). OpenCode will discover skills placed there because it reads `.claude/skills/<name>/SKILL.md` and the generic `.agents/skills/<name>/SKILL.md` paths.
@@ -42,7 +42,7 @@ mkdir -p .opencode/skills
 cp -r .claude/skills/<skill-name> .opencode/skills/
 ```
 
-> **Note:** Per-skill installs copy only the skill directory itself. If a skill references shared files under `references/`, copy those into the installed skill directory or install the whole pack. See [upstream agent-skills #361](https://github.com/addyosmani/agent-skills/issues/361) for background.
+> **Note:** Per-skill installs copy only the skill directory itself. If a skill references shared files under `references/`, copy those into the installed skill directory or install the whole pack.
 
 ### Option 2: Prepare the plugin bundle
 
@@ -61,12 +61,12 @@ mkdir -p .opencode/skills
 cp -r /path/to/i3-composer-agent/skills/<skill-name> .opencode/skills/
 ```
 
-For example, to install `spec-driven-development` and `incremental-implementation`:
+For example, to install `i3-spec-driven-development` and `i3-incremental-implementation`:
 
 ```bash
 mkdir -p .opencode/skills
-cp -r /path/to/i3-composer-agent/skills/spec-driven-development .opencode/skills/
-cp -r /path/to/i3-composer-agent/skills/incremental-implementation .opencode/skills/
+cp -r /path/to/i3-composer-agent/skills/i3-spec-driven-development .opencode/skills/
+cp -r /path/to/i3-composer-agent/skills/i3-incremental-implementation .opencode/skills/
 ```
 
 #### Global installation
@@ -89,11 +89,11 @@ If you already share skills across Claude Code and OpenCode, any of these locati
 
 ### What to copy
 
-Copy the directories under `skills/` (for example `skills/spec-driven-development/`). Each directory must contain a `SKILL.md` file. Do not copy the repository's root `AGENTS.md` or `CLAUDE.md`; those files configure development of this repository itself.
+Copy the directories under `skills/` (for example `skills/i3-spec-driven-development/`). Each directory must contain a `SKILL.md` file. Do not copy the repository's root `AGENTS.md` or `CLAUDE.md`; those files configure development of this repository itself.
 
 ## Project `AGENTS.md`
 
-Create an `AGENTS.md` in **your own project** root. This is the system prompt that tells OpenCode when and how to invoke the installed skills. Unlike the repo-scoped `AGENTS.md` in `addyosmani/agent-skills`, this file belongs to your project and should be adapted to your stack.
+Create an `AGENTS.md` in **your own project** root. This is the system prompt that tells OpenCode when and how to invoke the installed skills. Unlike the repo-scoped `AGENTS.md` in `i3-composer-agent`, this file belongs to your project and should be adapted to your stack.
 
 Below is a template you can paste into your project's `AGENTS.md`:
 
@@ -113,13 +113,13 @@ This project uses skills installed under `.opencode/skills/` (or a compatible pa
 
 Map the user's intent to the matching skill automatically:
 
-- Feature / new functionality → `spec-driven-development`, then `incremental-implementation` and `test-driven-development`
-- Planning / breakdown → `planning-and-task-breakdown`
-- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
-- Code review → `code-review-and-quality`
-- Refactoring / simplification → `code-simplification`
-- API or interface design → `api-and-interface-design`
-- UI work → `frontend-ui-engineering`
+- Feature / new functionality → `i3-spec-driven-development`, then `i3-incremental-implementation` and `i3-test-driven-development`
+- Planning / breakdown → `i3-planning-and-task-breakdown`
+- Bug / failure / unexpected behavior → `i3-debugging-and-error-recovery`
+- Code review → `i3-code-review-and-quality`
+- Refactoring / simplification → `i3-code-simplification`
+- API or interface design → `i3-api-and-interface-design`
+- UI work → `i3-frontend-ui-engineering`
 
 ## Execution Model
 
@@ -133,7 +133,7 @@ For every request:
 
 Save this as `AGENTS.md` in your project root. OpenCode will load it automatically.
 
-> **Note:** The root `AGENTS.md` inside the `addyosmani/agent-skills` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files).
+> **Note:** The root `AGENTS.md` inside the `i3-composer-agent` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files).
 
 ## How It Works
 
@@ -156,21 +156,21 @@ When your project's `AGENTS.md` instructs the agent to use skills, the agent eva
 
 Examples:
 
-- "build a feature" → `incremental-implementation` + `test-driven-development`
-- "design a system" → `spec-driven-development`
-- "fix a bug" → `debugging-and-error-recovery`
-- "review this code" → `code-review-and-quality`
+- "build a feature" → `i3-incremental-implementation` + `i3-test-driven-development`
+- "design a system" → `i3-spec-driven-development`
+- "fix a bug" → `i3-debugging-and-error-recovery`
+- "review this code" → `i3-code-review-and-quality`
 
 ### 3. Lifecycle Mapping (Implicit Commands)
 
 OpenCode does not require slash commands, but if you prefer them see the next section. In agent-driven mode the lifecycle is mapped implicitly:
 
-- DEFINE → `spec-driven-development`
-- PLAN → `planning-and-task-breakdown`
-- BUILD → `incremental-implementation` + `test-driven-development`
-- VERIFY → `debugging-and-error-recovery`
-- REVIEW → `code-review-and-quality`
-- SHIP → `shipping-and-launch`
+- DEFINE → `i3-spec-driven-development`
+- PLAN → `i3-planning-and-task-breakdown`
+- BUILD → `i3-incremental-implementation` + `i3-test-driven-development`
+- VERIFY → `i3-debugging-and-error-recovery`
+- REVIEW → `i3-code-review-and-quality`
+- SHIP → `i3-shipping-and-launch`
 
 ### Copy the optional slash commands
 
@@ -190,10 +190,10 @@ A typical command file looks like:
 description: Break work into small verifiable tasks
 ---
 
-Invoke the planning-and-task-breakdown skill. Read the spec and create tasks with acceptance criteria.
+Invoke the i3-planning-and-task-breakdown skill. Read the spec and create tasks with acceptance criteria.
 ```
 
-Save it as `.opencode/commands/plan.md` to enable `/plan` in OpenCode.
+Save it as `.opencode/commands/i3-plan.md` to enable `/i3-plan` in OpenCode.
 
 ## Usage Examples
 
@@ -206,7 +206,7 @@ Add authentication to this app
 
 Agent behavior:
 - Detects feature work
-- Invokes `spec-driven-development`
+- Invokes `i3-spec-driven-development`
 - Produces a spec before writing code
 - Moves to planning and implementation skills
 
@@ -218,7 +218,7 @@ This endpoint is returning 500 errors
 ```
 
 Agent behavior:
-- Invokes `debugging-and-error-recovery`
+- Invokes `i3-debugging-and-error-recovery`
 - Reproduces → localizes → fixes → adds guards
 
 ### Example 3: Code Review
@@ -229,7 +229,7 @@ Review this PR
 ```
 
 Agent behavior:
-- Invokes `code-review-and-quality`
+- Invokes `i3-code-review-and-quality`
 - Applies structured review (correctness, design, readability, etc.)
 
 ## Agent Expectations
@@ -256,4 +256,4 @@ These rules are enforced by your project's `AGENTS.md`, not by the copy of the s
 3. OpenCode discovers the skills and your `AGENTS.md` guides the agent to invoke them.
 4. Optionally add `.opencode/commands/*.md` for explicit slash commands.
 
-This keeps the reusable assets (skills) separate from the repository-specific configuration (the `addyosmani/agent-skills` root `AGENTS.md`).
+This keeps the reusable assets (skills) separate from the repository-specific configuration (the `i3-composer-agent` root `AGENTS.md`).

package/docs/windsurf-setup.md

@@ -8,11 +8,11 @@ Windsurf uses `.windsurfrules` for project-specific agent instructions:
 
 ```bash
 # Create a combined rules file from your most important skills
-cat /path/to/i3-composer-agent/skills/test-driven-development/SKILL.md > .windsurfrules
+cat /path/to/i3-composer-agent/skills/i3-test-driven-development/SKILL.md > .windsurfrules
 echo "\n---\n" >> .windsurfrules
-cat /path/to/i3-composer-agent/skills/incremental-implementation/SKILL.md >> .windsurfrules
+cat /path/to/i3-composer-agent/skills/i3-incremental-implementation/SKILL.md >> .windsurfrules
 echo "\n---\n" >> .windsurfrules
-cat /path/to/i3-composer-agent/skills/code-review-and-quality/SKILL.md >> .windsurfrules
+cat /path/to/i3-composer-agent/skills/i3-code-review-and-quality/SKILL.md >> .windsurfrules
 ```
 
 ### Global Rules
@@ -30,19 +30,19 @@ Keep `.windsurfrules` focused on 2-3 essential skills to stay within context lim
 # .windsurfrules
 # Essential i3-composer-agent for this project
 
-[Paste test-driven-development SKILL.md]
+[Paste i3-test-driven-development SKILL.md]
 
 ---
 
-[Paste incremental-implementation SKILL.md]
+[Paste i3-incremental-implementation SKILL.md]
 
 ---
 
-[Paste code-review-and-quality SKILL.md]
+[Paste i3-code-review-and-quality SKILL.md]
 ```
 
 ## Usage Tips
 
 1. **Be selective** — Windsurf's context is limited. Choose skills that address your biggest quality gaps.
-2. **Reference in conversation** — Paste additional skill content into the chat when working on specific phases (e.g., paste `security-and-hardening` when building auth).
+2. **Reference in conversation** — Paste additional skill content into the chat when working on specific phases (e.g., paste `i3-security-and-hardening` when building auth).
 3. **Use references as checklists** — Paste `references/security-checklist.md` and ask Windsurf to verify each item.

package/docs/workbuddy-setup.md

@@ -0,0 +1,92 @@
+# Using i3 Composer Agent with WorkBuddy
+
+## Native installation
+
+Run inside your project:
+
+```bash
+npx @givolt/i3-composer-agent --workbuddy
+```
+
+The terminal wizard preselects WorkBuddy and lets you add other clients before
+choosing project or global scope. For explicit installation:
+
+```bash
+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
+```
+
+| Selected clients | Project files | Global files |
+| --- | --- | --- |
+| CodeBuddy | `.codebuddy/` | `~/.codebuddy/` |
+| WorkBuddy | `.codebuddy/` | `~/.workbuddy/` |
+| CodeBuddy and WorkBuddy | One shared `.codebuddy/` installation | One installation in each client's directory |
+
+WorkBuddy natively discovers project Commands, Skills and personas in
+`.codebuddy/`. If your project already has `.workbuddy/`, i3 preserves its
+contents and adds `.codebuddy/` for the shared native files. Both directories may
+therefore exist in the same workspace.
+
+Project installation includes:
+
+- `.codebuddy/skills/`: all 25 Skills with their existing `i3-` IDs.
+- `.codebuddy/commands/`: all 9 short `/i3-*` workflows.
+- `.codebuddy/agents/`: all 4 persona prompts.
+- `.codebuddy/references/`: shared references and the standard MIT license.
+- `.codebuddy/docs/agents.md`: persona documentation.
+- `.codebuddy/.i3-composer-agent.json`: managed asset and client records.
+
+Global WorkBuddy installation uses the same layout under `~/.workbuddy/`.
+If you use a separate WorkBuddy profile, set `WORKBUDDY_CONFIG_DIR` to its
+configuration directory when installing. The installer does not borrow
+`CODEBUDDY_CONFIG_DIR` for WorkBuddy. Open the corresponding profile in the host.
+
+## Discovery and invocation
+
+Open the project in WorkBuddy and start a new chat after installation. Type `/`
+to inspect the project Commands, and inspect the Skills list. Examples:
+
+```text
+/i3-spec
+/i3-plan
+/i3-build
+/i3-build auto
+/i3-review
+/i3-ship
+```
+
+Commands invoke the installed Skill IDs without a plugin namespace. Native
+Buddy commands refer to `CODEBUDDY.md` and the installed persona directories.
+Shared project commands refer to the current host's user-level persona directory
+so they work for either client. `/i3-ship` uses native subagents when available
+and reads the installed persona prompts sequentially otherwise. Skill content,
+`$ARGUMENTS`, workflow approval gates, and relative reference links are retained.
+
+The [WorkBuddy project documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)
+describes these native project directories. The [task-bar command documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Task-Bar)
+describes command discovery, and the [CLI command documentation](https://www.codebuddy.cn/docs/cli/slash-commands)
+describes Markdown commands and `$ARGUMENTS`.
+
+## Adding a second client or upgrading
+
+Either client can be installed first. Installing the other at the same package
+version and scope reuses unmodified manifest-owned files and merges the client
+IDs. It does not create a second project copy. Missing files are restored;
+unrelated settings and custom command filenames are preserved.
+
+Review an upgrade or conflict before replacing files:
+
+```bash
+npx @givolt/i3-composer-agent --workbuddy --scope project --dry-run
+npx @givolt/i3-composer-agent --workbuddy --scope project --yes --force
+```
+
+Modified assets, unowned filename collisions and different versions require
+confirmation or `--force`. Successful replacements remove old files and managed
+historical backups. If installation fails, the previous files are restored.
+
+Native installation provides Commands, Skills and personas. It does not register
+a WorkBuddy plugin or enable plugin hooks; `--prepare --workbuddy` is unsupported.
+File installation and command discovery are separate from model execution and
+workflow acceptance in the host.

package/hooks/SDD-CACHE.md

@@ -1,10 +1,10 @@
 # sdd-cache hook
 
-Cross-session citation cache for [`source-driven-development`](../skills/source-driven-development/SKILL.md). Skips redundant `WebFetch` calls without weakening the skill's "verify against current docs" guarantee.
+Cross-session citation cache for [`i3-source-driven-development`](../skills/i3-source-driven-development/SKILL.md). Skips redundant `WebFetch` calls without weakening the skill's "verify against current docs" guarantee.
 
 ## Why
 
-`source-driven-development` fetches official docs for every framework-specific decision. Working on the same project across sessions means fetching the same pages over and over. Caching the content as local memory would contradict the skill — docs change, and a stale cache hides that.
+`i3-source-driven-development` fetches official docs for every framework-specific decision. Working on the same project across sessions means fetching the same pages over and over. Caching the content as local memory would contradict the skill — docs change, and a stale cache hides that.
 
 This hook caches fetched content on disk, but **revalidates with the origin server on every reuse** via HTTP `If-None-Match` / `If-Modified-Since`. Content is only served from cache when the server responds `304 Not Modified`, which is a fresh verification — not a memory read.
 
@@ -48,7 +48,7 @@ This hook caches fetched content on disk, but **revalidates with the origin serv
 
 2. Make sure `.claude/sdd-cache/` is in your `.gitignore` (already included in this repo).
 
-3. Use `/source-driven-development` (or the skill) as usual. No changes to the skill or the agent's workflow — the cache is transparent.
+3. Use `/i3-source-driven-development` (or the skill) as usual. No changes to the skill or the agent's workflow — the cache is transparent.
 
 ## Mental model
 

package/hooks/SIMPLIFY-IGNORE.md

@@ -1,6 +1,6 @@
 # simplify-ignore hook
 
-Block-level protection for `/code-simplify`. Mark code that should never be simplified — the model won't see it.
+Block-level protection for `/i3-code-simplify`. Mark code that should never be simplified — the model won't see it.
 
 ## Setup
 
@@ -42,7 +42,7 @@ result[3] = buf[3] ^ key[3];
 }
 ```
 
-3. Run `/code-simplify` — protected blocks become `/* BLOCK_de115a1d: perf-critical */` placeholders. The model reasons about surrounding code without seeing the protected implementation.
+3. Run `/i3-code-simplify` — protected blocks become `/* BLOCK_de115a1d: perf-critical */` placeholders. The model reasons about surrounding code without seeing the protected implementation.
 
 > **Note:** The hook stores temporary backups in `.claude/.simplify-ignore-cache/`. Make sure this path is in your `.gitignore`.
 

package/hooks/session-start-test.sh

@@ -37,7 +37,7 @@ if (hasJq) {
     throw new Error('additionalContext is missing startup preface');
   }
   if (!ctx.includes('# Using i3 Composer Agent')) {
-    throw new Error('additionalContext is missing using-agent-skills content');
+    throw new Error('additionalContext is missing i3-using-agent-skills content');
   }
 } else if (!ctx.includes('jq is required')) {
   throw new Error('additionalContext is missing jq fallback guidance');

package/hooks/session-start.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # i3-composer-agent session start hook
-# Injects the using-agent-skills meta-skill into a new session.
+# Injects the i3-using-agent-skills meta-skill into a new session.
 #
 # Not wired by the plugin: hosts that already route skills from their
 # descriptions (Claude Code, Codex CLI) would run a second router on top of
@@ -13,7 +13,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILLS_DIR="$(dirname "$SCRIPT_DIR")/skills"
-META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"
+META_SKILL="$SKILLS_DIR/i3-using-agent-skills/SKILL.md"
 
 if ! command -v jq >/dev/null 2>&1; then
   echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: jq is required for the session-start hook but was not found on PATH. Install jq (e.g. `brew install jq` or `apt-get install jq`) to enable meta-skill injection. Skills remain available individually."}}'
@@ -29,5 +29,5 @@ if [ -f "$META_SKILL" ]; then
 $CONTENT" \
     '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $context}}'
 else
-  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: using-agent-skills meta-skill not found. Skills may still be available individually."}}'
+  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: i3-using-agent-skills meta-skill not found. Skills may still be available individually."}}'
 fi