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

package/docs/comparison.md

@@ -0,0 +1,131 @@
+<!--
+  This document is for developers evaluating the project. It is NOT a skill and
+  is not meant to be loaded into an agent's context. It lives in docs/ so it
+  stays out of the agent's working set.
+-->
+
+# How agent-skills compares
+
+> **Upstream research:** This comparison is retained from Addy Osmani's `agent-skills` at commit `1401c8b8030e023baeebb31781a6653fe8e93026`. Its experiments describe the upstream project; they are not independent evaluations of i3 Composer Agent.
+
+People often ask how **agent-skills** relates to the two other "skills for coding agents" collections they hear about most: **Superpowers** (Jesse Vincent / obra) and **Matt Pocock's skills**. All three are good, share a lot of DNA, and are worth learning from. This page is an honest map of how they are *shaped* differently, so you can pick the one that fits how you work, or borrow across all three.
+
+> **TL;DR** — They optimize for different moments. **agent-skills** organizes the *whole product lifecycle* (Define, Plan, Build, Verify, Review, Ship) with review personas, anti-rationalization guards, and an in-repo eval framework that checks the skills actually route and behave. **Superpowers** leans into *autonomous, reasoning-heavy* runs with subagents, a strict pipeline, and worktree isolation. **Matt Pocock's skills** are a *sharp, opinionated Claude Code toolkit* distilled from one expert's daily workflow, with a signature "grill me" interrogation loop. None is "best" in the abstract; it depends on the work in front of you.
+
+---
+
+## At a glance
+
+| | **agent-skills** | **Superpowers** | **Matt Pocock's skills** |
+|---|---|---|---|
+| **Core idea** | Encode the full senior-engineering lifecycle as skills | A complete development *methodology* built on composable skills | One expert's Claude Code workflow, open-sourced and evolving |
+| **Organizing principle** | SDLC **phases** (Define to Ship) behind a meta-skill router | A single disciplined loop: brainstorm, plan, execute, review | A curated toolbox of focused, composable commands |
+| **Catalog size** | 25 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated |
+| **Lifecycle coverage** | Broad: idea refinement, API and UI design, security, performance, CI/CD, observability, deprecation, ADRs, launch | Deep but narrow: TDD, debugging, planning, review, skill authoring | Define and Build heavy: grilling, PRDs, issues, TDD, architecture, bug triage, knowledge management |
+| **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus `/webperf`), with a `/build auto` full-plan mode | Skill-chained pipeline (`brainstorming`, `writing-plans`, `subagent-driven-development`) | Slash commands (`/grill-me`, `/tdd`, `/to-prd`, `/diagnosing-bugs`, `/grill-with-docs`) |
+| **Distinctive mechanisms** | Anti-rationalization tables and Red Flags in every skill; parallel review **personas** in `/ship`; reference checklists; a **three-tier eval framework** in CI | Subagent-driven development with a task reviewer (spec + quality) and a fix loop; git-worktree isolation; skills-that-write-skills, pressure-tested | The **grilling** primitive (one question at a time, design-tree walking); seam-based TDD; explicit user-invoked vs model-invoked split; issue-tracker integration |
+| **Quality measurement** | Trigger, routing, and behavioral evals run against the catalog (in-repo, some in CI) | Pressure-testing methodology is core to its philosophy; the eval suite itself now lives in a separate repo | None shipped in-repo |
+| **Tooling reach** | Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Windsurf, Copilot, Kiro, Codex, Command Code, plus the `npx skills` CLI | One of the widest and most actively churned surfaces: Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Kimi, Factory Droid, Antigravity, Pi | Claude Code first, distributed via `npx skills add`; other agents work with varying fidelity |
+| **Governance** | Actively reviews and merges community contributions; every skill ships an eval | Largely solo-authored; a substantial backlog of unmerged community PRs | Solo-authored, self-merged, developed openly in public |
+| **Best for** | Driving a feature through every phase with a human checkpoint at each | Long, autonomous, reasoning-heavy or exploratory work | A pragmatic, battle-tested daily loop, strongest at requirements and TDD |
+
+*(We deliberately leave out star counts and adoption figures: they are cited wildly differently across blogs and change weekly. All three are actively used and maintained.)*
+
+---
+
+## The three projects, in their own terms
+
+### Superpowers (obra)
+
+A full software-development *methodology* built on composable skills. It bets on **autonomy and upfront reasoning**. A session runs a deliberately linear pipeline: Socratic brainstorming that writes a dated spec and permits exactly one handoff, detailed plans written to be executable by "an enthusiastic junior engineer with poor taste and no context," then subagent-driven execution where a fresh subagent implements each task and a task reviewer signs off on both spec compliance and code quality before it closes, with a fix loop for anything it flags and a whole-branch review on the most capable model at the end. Git worktrees keep parallel work isolated, and its `writing-skills` skill applies TDD to documentation itself: no skill ships without a failing test first.
+
+Its strengths are real: hand off a sizable chunk and come back to a reviewed result, with strong guardrails against an agent rationalizing its way past the process. The trade-offs are the flip side of that discipline. Coverage is narrow (it is an inner-loop build methodology, not a security-to-launch lifecycle), the single pipeline can feel heavy on small changes, and the recent direction has been about paying down that cost, for example consolidating to a single task reviewer for roughly twice the speed and half the tokens. The loudest thing its community keeps asking for, multi-agent team execution, is not yet in the box.
+
+**Repo:** <https://github.com/obra/superpowers>
+
+### Matt Pocock's skills
+
+Matt open-sourced the Claude Code skills he actually uses, and the collection has grown into a broad, opinionated toolbox organized in public, complete with visible `in-progress/` and `deprecated/` directories that model the discipline the skills preach. The center of gravity is not TDD, it is **grilling**: a reusable interrogation loop that asks one question at a time, walks each branch of the design tree resolving dependencies in order, offers a recommended answer per question, prefers reading the codebase over asking, and refuses to proceed until you confirm a shared understanding. `grill-me` and `grill-with-docs` are thin wrappers over it. The TDD skill is distinctive too and cheerfully heterodox ("refactoring is not part of the loop," it belongs to code review), and there is a deliberate split between user-invoked and model-invoked skills to treat agent context as a scarce budget.
+
+Its strengths are authenticity and sharpness: this is how one very good engineer ships, not a committee's idea of a framework, and the requirements-grilling loop is genuinely excellent. The trade-offs: it is Claude Code first in practice (other agents surface reliability rough edges), there are no in-repo evals to catch regressions, lifecycle coverage past Build is thin, and some skills couple to a personal setup wizard and tracker conventions. Recent work is pushing from single-session skills toward multi-session orchestration through issue trackers (the in-progress `wayfinder`).
+
+**Repo:** <https://github.com/mattpocock/skills> · related: <https://github.com/mattpocock/agent-rules-books>
+
+### agent-skills (this project)
+
+agent-skills organizes the **entire product lifecycle** as skills, with a meta-skill (`using-agent-skills`) that routes a task to the right one. Every skill carries a **Common Rationalizations** table (the excuses an agent makes to skip a step, each rebutted) and **Red Flags**. Slash commands map one-to-one to lifecycle phases; `/build auto` runs a whole approved plan in one pass; and `/ship` fans out review **personas** (`code-reviewer`, `security-auditor`, `test-engineer`, `web-performance-auditor`) in parallel, then merges them into a go/no-go. It keeps a human checkpoint at each phase, ships seven reference checklists including a Definition of Done, and runs across most major agent tools with a single-command install on several of them.
+
+What is newer, and the current point of difference: a **three-tier eval framework** lives in the repo. Tier 1 checks structure, Tier 2 checks that each skill's description carries the vocabulary users actually say and that no two skills collide on routing (deterministic, runs in CI), and Tier 3 grades an agent's real execution trace against per-skill expectations. Neither of the other two ships that kind of in-repo, catalog-wide measurement today. The honest trade-off in the other direction: agent-skills has less of a single opinionated "run" than Superpowers, and none of the three has yet solved durable cross-session memory well.
+
+---
+
+## A real head-to-head: Superpowers vs. agent-skills
+
+Om Mishra ran a controlled experiment, same model, same repo, same prompt in Claude Code, changing only the skill framework, and wrote it up:
+
+**["Superpowers vs Agent-Skills: Faster Shipping, Safer Reasoning"](https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/)** by Om Mishra
+
+Summarized fairly:
+
+- **agent-skills** moved to code faster (~8 min vs ~12) and ran **more validation passes** (7 vs 5, including the full test suite). That broader validation caught a compatibility issue *outside* the immediate feature that the feature-specific tests missed. He gave it the edge on **validation depth** for that task.
+- **Superpowers** invested more **upfront architectural reasoning**, which he still prefers as his daily driver for evolving production systems and exploratory work with no established pattern to follow.
+- Token efficiency was effectively identical; both replanned once.
+
+It is one developer's single-task experiment, not a benchmark, but it is a concrete illustration of the core trade-off: **broad disciplined validation versus heavy upfront reasoning**. His own conclusion is the honest one: pick the tool to the task.
+
+---
+
+## How to decide what to use
+
+The at-a-glance table tells you how they are shaped. This is how to choose in practice.
+
+### Start with the shape of your work
+
+- **A whole feature, front to back?** agent-skills. It is the only one of the three that carries you from spec through security, performance, and launch with a checkpoint at each phase, so nothing quietly skips the review or the pre-flight.
+- **A big, ambiguous chunk you want to hand off and walk away from?** Superpowers. Its pipeline and subagent review are built to run for a long time and hand back a result that has already been reviewed against the spec.
+- **A fast, focused daily loop, especially getting requirements right before code?** Matt Pocock's skills. The grilling loop is the sharpest requirements tool of the three, and the toolkit stays out of your way.
+
+### Then weight what you actually care about
+
+- **Breadth of coverage** (security, performance, CI/CD, observability, launch): agent-skills is the clear pick; the others are inner-loop focused.
+- **Autonomy over a long run**: Superpowers, by design.
+- **Low ceremony on small changes**: Pocock's toolkit is lightest; agent-skills offers a middle gear (a small change can skip straight to `/test` and `/review`); Superpowers is the most process-heavy.
+- **Confidence that the skills themselves work**: agent-skills is the only one with catalog-wide evals in the repo, so a description or routing regression fails CI rather than surfacing as a mysterious "why didn't the skill fire" later.
+- **Requirements interrogation**: Pocock's grilling is the reference implementation; agent-skills' `interview-me` is close in spirit and gaining an opt-in collaborative mode.
+- **Platform spread**: agent-skills and Superpowers both run almost everywhere; Pocock is happiest on Claude Code.
+- **A human gate at each step vs. a hands-off run**: agent-skills checkpoints by default; Superpowers minimizes mid-run check-ins on purpose.
+
+### Concrete scenarios
+
+- *"Ship a new endpoint with auth, tests, and a security pass before merge."* agent-skills: `/spec` to `/ship`, with the security-auditor and test-engineer personas fanning out at the end.
+- *"Refactor a gnarly subsystem overnight and review it in the morning."* Superpowers: hand it the plan, let subagent-driven development and the task reviewer run.
+- *"I have a vague idea and keep letting the agent guess the requirements."* Pocock's `grill-me` (or agent-skills' `interview-me`) to pin down intent before any code.
+- *"Fix one clear bug, test-first."* Any of them; reach for the lightest one you already have installed.
+- *"Standardize how a team of engineers uses agents across a repo."* agent-skills: the phase commands, personas, and shared checklists give a team a common vocabulary, and the evals keep custom skills honest.
+- *"Roll my own skills and know they trigger correctly."* agent-skills, and borrow Superpowers' pressure-testing discipline for the ones that must not be rationalized away.
+
+### Solo vs. team
+
+For a solo developer, taste and momentum win: pick the one whose defaults match how you already work, and the lowest-ceremony option is often the most-used one. For a team, the calculus shifts toward shared structure and guardrails you can enforce: named phases, review personas, checklists, and evals that fail CI are what keep five people (and their agents) converging on the same standard rather than five private workflows. That is the situation agent-skills is built for, though a team can absolutely adopt Superpowers' review discipline or Pocock's grilling loop within it.
+
+### The shared frontier (true of all three)
+
+None of these has solved **durable cross-session memory** well yet: what an agent learned in one session rarely carries cleanly into the next. All three are circling it (learnings files, handoff artifacts, tracker-backed planning maps). If that is your bottleneck, know that you are at the edge of what any of them ships today, and expect to stitch some of it yourself for now.
+
+---
+
+## Combining them
+
+You do not have to choose exclusively, but combine with care. These are Markdown skills, not runtimes, so cherry-picking *individual* skills works well: pull in Pocock's `grill-me`, a Superpowers isolation pattern, or a specific checklist alongside your main setup.
+
+What does not work is running two of them as your **active router at the same time**. Stacked meta-skills fight over command names (`/tdd` defined in two places), compete on routing logic, and pull in different TDD philosophies, so you get unpredictable behavior rather than the best of both. Pick one framework as your primary router, and borrow from the others a la carte.
+
+---
+
+## Sources
+
+- Superpowers: <https://github.com/obra/superpowers>
+- Matt Pocock's skills: <https://github.com/mattpocock/skills>
+- Om Mishra, *Superpowers vs Agent-Skills*: <https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/>
+
+*Spotted something inaccurate about another project here? Open an issue or PR. We would rather be fair than flattering.*

package/docs/copilot-cli-setup.md

@@ -0,0 +1,64 @@
+# Using i3-composer-agent with GitHub Copilot CLI
+
+The standalone `copilot` command-line tool installs this repository as a plugin and discovers every skill in `skills/`. For Copilot inside VS Code, see [copilot-setup.md](copilot-setup.md) instead — the setup and the invocation model are different.
+
+## Install
+
+**From this repository's marketplace** — register it, then install from it. `i3-composer-agent` is the marketplace name this repository declares, not a GitHub-wide registry, and the name only resolves after the `marketplace add`:
+
+```bash
+copilot plugin marketplace add /path/to/i3-composer-agent
+copilot plugin install i3-composer-agent@i3-composer-agent
+```
+
+**Directly from the repository**, without registering a marketplace:
+
+```bash
+copilot plugin install /path/to/i3-composer-agent
+```
+
+**From a local clone**, for a session-scoped development install:
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+copilot --plugin-dir /path/to/i3-composer-agent
+```
+
+`--plugin-dir` loads the plugin for that session only and installs nothing persistently — use it while editing skills.
+
+## Verify
+
+```bash
+copilot plugin list   # i3-composer-agent@i3-composer-agent
+copilot skill list    # the plugin's skills, alongside the built-in ones
+```
+
+In an interactive session, `/skills list` shows the same catalog.
+
+## What you get, and what you don't
+
+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.
+
+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).
+
+## Usage
+
+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 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.
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---------|---------------|
+| `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. |
+| 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

@@ -0,0 +1,162 @@
+# Using i3-composer-agent with GitHub Copilot
+
+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).
+
+## Setup
+
+### Copilot Instructions
+
+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
+
+# 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
+```
+
+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.
+
+For more details, refer [Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills) and the VS Code guide to [agent skills](https://code.visualstudio.com/docs/agent-customization/agent-skills).
+
+### Agent Personas (*.agent.md)
+
+Copilot supports specialized agent personas. Use the i3-composer-agent agents:
+
+> **Important:** GitHub Copilot requires custom agent files to be named `*.agent.md`.
+> Files named `*.md` are silently ignored by Copilot.
+> See [VS Code custom agents docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents#_custom-agent-file-structure) for details.
+
+```bash
+# Create the agents directory and copy agent definitions
+mkdir -p .github/agents
+cp /path/to/i3-composer-agent/agents/code-reviewer.md .github/agents/code-reviewer.agent.md
+cp /path/to/i3-composer-agent/agents/test-engineer.md .github/agents/test-engineer.agent.md
+cp /path/to/i3-composer-agent/agents/security-auditor.md .github/agents/security-auditor.agent.md
+```
+
+Invoke agents in Copilot Chat:
+- `@code-reviewer Review this PR`
+- `@test-engineer Analyze test coverage for this module`
+- `@security-auditor Check this endpoint for vulnerabilities`
+
+### Custom Instructions (User Level)
+
+For skills you want across all repositories:
+
+1. Open VS Code → Settings → GitHub Copilot → Custom Instructions
+2. Add your most-used skill summaries
+
+## Recommended Configuration
+
+### .github/copilot-instructions.md
+
+GitHub Copilot supports project-level instructions via `.github/copilot-instructions.md`.
+
+```markdown
+# Project Coding Standards
+
+## Testing
+- Write tests before code (TDD)
+- For bugs: write a failing test first, then fix (Prove-It pattern)
+- Test hierarchy: unit > integration > e2e (use the lowest level that captures the behavior)
+- Run `npm test` after every change
+
+## Code Quality
+- Review across five axes: correctness, readability, architecture, security, performance
+- Every PR must pass: lint, type check, tests, build
+- No secrets in code or version control
+
+## Implementation
+- Build in small, verifiable increments
+- Each increment: implement → test → verify → commit
+- Never mix formatting changes with behavior changes
+
+## Boundaries
+- Always: Run tests before commits, validate user input
+- Ask first: Database schema changes, new dependencies
+- Never: Commit secrets, remove failing tests, skip verification
+```
+
+### Specialized Agents
+
+Use the agents for targeted review workflows in Copilot Chat.
+
+## Lifecycle Workflows
+
+Skills are user-invocable by default, so once they're discovered the whole lifecycle is available under the skills' own names — no extra configuration:
+
+| 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 |
+
+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 code-review-and-quality skill to review my staged changes.
+
+### Optional: short `/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.
+
+Create one, without clobbering an existing file:
+
+```bash
+mkdir -p .github/prompts
+[ -e .github/prompts/spec.prompt.md ] || cat > .github/prompts/spec.prompt.md <<'EOF'
+---
+description: Write a structured spec before writing code
+---
+
+Use the 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.
+Then write a spec covering objective, commands, project structure, code style,
+testing strategy, and boundaries. Save it as SPEC.md in the project root and
+confirm with me before any code is written.
+EOF
+```
+
+Reload the window, then type `/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.
+
+| 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. |
+
+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:
+
+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.
+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
+
+1. **Keep instructions concise** — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files.
+2. **Use agents for review** — The code-reviewer, test-engineer, and security-auditor agents are designed for Copilot's agent model.
+3. **Reference in chat** — When working on a specific phase, paste the relevant skill content into Copilot Chat for context.
+4. **Combine with PR reviews** — Set up Copilot to review PRs using the code-reviewer agent persona.

package/docs/cursor-setup.md

@@ -0,0 +1,225 @@
+# Using i3-composer-agent with Cursor
+
+How to wire [i3-composer-agent](../README.md) into **Cursor** using current, supported project context — not legacy monolith files or Kaizen-specific layouts.
+
+---
+
+## What Cursor supports today
+
+Cursor combines **rules** (short policies) and **skills** (full workflows):
+
+| Layer | Path | Role |
+|-------|------|------|
+| **Project rules** | `.cursor/rules/*.mdc` | Always-on or file-scoped instructions (`alwaysApply`, `globs`) |
+| **Project skills** | `.cursor/skills/<skill-name>/SKILL.md` | Agent-discovered workflows; read when the task matches the skill `description` |
+| **User rules** | Cursor Settings → Rules | Account-wide policies |
+| **User skills** (optional) | `~/.cursor/skills/` | Global skills available in every workspace |
+
+Docs: [Rules](https://docs.cursor.com/context/rules) · [Skills](https://docs.cursor.com/context/skills) (URLs may redirect as Cursor updates docs).
+
+### Rules vs skills
+
+- **Rules** — concise, stable (“use conventional commits”, “type-annotate public Python APIs”). Prefer one concern per file; avoid large pasted guides.
+- **Skills** — step-by-step processes from this repo (`test-driven-development`, `code-review-and-quality`, etc.). **Do not** copy entire `SKILL.md` bodies into rules; that duplicates `.cursor/skills/` and wastes context.
+
+### Legacy (avoid for new setups)
+
+| Legacy | Prefer |
+|--------|--------|
+| Root `.cursorrules` | `.cursor/rules/*.mdc` |
+| Copying `SKILL.md` → `.cursor/rules/` | `.cursor/skills/<name>/SKILL.md` |
+| “Load 10 skills as always-on rules” | 1–2 thin `alwaysApply` rules + skills on demand |
+
+---
+
+## Recommended project layout
+
+```text
+your-project/
+├── .cursor/
+│   ├── rules/                    # Short .mdc policies (yours)
+│   │   └── i3-composer-agent.mdc      # Optional: “use project skills” pointer
+│   └── skills/                   # What Cursor Agent loads
+│       ├── using-agent-skills/
+│       ├── test-driven-development/
+│       ├── code-review-and-quality/
+│       └── …                     # Synced from i3-composer-agent + your own skills
+└── i3-composer-agent/                 # Optional: git submodule or vendor clone
+    └── skills/                   # Upstream source only
+```
+
+**Source of truth for the agent:** `.cursor/skills/`.  
+Treat `i3-composer-agent/skills/` (or a cloned [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)) as **upstream** — sync into `.cursor/skills/`, do not edit only upstream and expect Cursor to see it.
+
+---
+
+## Setup (any repository)
+
+### 1. Install skills into `.cursor/skills/`
+
+**From a local clone of i3-composer-agent** (at project root or elsewhere):
+
+```bash
+mkdir -p .cursor/skills
+rsync -a /path/to/i3-composer-agent/skills/ .cursor/skills/
+```
+
+**First-time copy without overwriting your custom skills:**
+
+```bash
+rsync -a --ignore-existing /path/to/i3-composer-agent/skills/ .cursor/skills/
+```
+
+**After upstream updates:**
+
+```bash
+rsync -a /path/to/i3-composer-agent/skills/ .cursor/skills/
+```
+
+Each skill folder must contain `SKILL.md` with YAML frontmatter, at minimum:
+
+```yaml
+---
+name: test-driven-development
+description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior.
+---
+```
+
+Cursor uses `description` (and related metadata) to decide when to apply a skill.
+
+### 2. Add minimal project rules (optional but useful)
+
+Create `.cursor/rules/i3-composer-agent.mdc`:
+
+```markdown
+---
+description: Use i3-composer-agent workflows from .cursor/skills
+alwaysApply: true
+---
+
+Before non-trivial technical work:
+
+1. Route via `.cursor/skills/using-agent-skills/SKILL.md`.
+2. Read and follow the matching skill under `.cursor/skills/<name>/SKILL.md`.
+3. Open `reference.md` in that folder when the skill links to it.
+4. Prefer project skills over guessing; user does not need to say "read skill" each time.
+```
+
+Add **separate** `.mdc` files for repo-specific standards (style, language, stack), keeping each file focused.
+
+**Rule file format:**
+
+```markdown
+---
+description: Shown in Cursor rule UI
+alwaysApply: false
+globs: "**/*.{ts,tsx}"
+---
+
+# Your rule content
+```
+
+| Field | Use |
+|-------|-----|
+| `alwaysApply: true` | Every chat in this project |
+| `globs` | When matching files are in context |
+| `alwaysApply: false` + no globs | Agent-request / manual rule (Cursor UI) |
+
+### 3. User-level skills (optional)
+
+Copy or install skills you want everywhere under `~/.cursor/skills/`. Use for stack-wide guides (e.g. language patterns) that are not part of i3-composer-agent.
+
+Project skills in `.cursor/skills/` take precedence for **this** repo’s workflows.
+
+### 4. Verify
+
+1. **Settings → Rules** — project `.mdc` files listed.
+2. **Agent chat** — skills from `.cursor/skills/` appear in the skill list (if your Cursor build exposes it).
+3. Run a task that maps to a skill (e.g. “add a feature with tests first”) without naming the file — agent should open `test-driven-development` when routing works.
+
+---
+
+## How agents should use skills
+
+1. **Discover** — `using-agent-skills` maps task phase → skill name.
+2. **Read** — full process in `.cursor/skills/<name>/SKILL.md`.
+3. **Deep dive** — `reference.md`, `references/*.md`, or linked checklists when the skill says so.
+4. **Combine** — e.g. `incremental-implementation` + `api-and-interface-design` for an API slice.
+
+Explicit user phrases (“follow TDD”, “use code-review-and-quality”) still help if the agent drifts.
+
+### Phase → skill (quick map)
+
+| You are… | Skill |
+|----------|--------|
+| Clarifying requirements | `interview-me`, `idea-refine`, `spec-driven-development` |
+| Planning tasks | `planning-and-task-breakdown` |
+| Implementing | `incremental-implementation`, `frontend-ui-engineering`, `api-and-interface-design` |
+| Testing | `test-driven-development`, `browser-testing-with-devtools` |
+| Debugging | `debugging-and-error-recovery` |
+| Reviewing | `code-review-and-quality`, `code-simplification` |
+| Security / performance | `security-and-hardening`, `performance-optimization` |
+| Git / CI / ship | `git-workflow-and-versioning`, `ci-cd-and-automation`, `shipping-and-launch` |
+
+Full tree: `skills/using-agent-skills/SKILL.md` in the repo.
+
+---
+
+## What not to do
+
+| Avoid | Do instead |
+|-------|------------|
+| Paste all skills into one rule | Sync to `.cursor/skills/` |
+| Maintain two diverging copies | `rsync` from upstream; commit `.cursor/skills/` |
+| Many `alwaysApply: true` rules | One routing rule + focused globs rules |
+| Rely on `.cursorrules` only | Migrate to `.mdc` + skills |
+| Expect `i3-composer-agent/agents/*.md` to auto-load | Paste in chat, or distill a short rule |
+
+---
+
+## Context tips
+
+- Keep **always-on** rules small (routing + 1–2 non-negotiables).
+- Let **skills** carry long checklists and rationalization tables.
+- Add phase-specific **globs** rules only when needed (e.g. `**/*.py`, `**/components/**`).
+- Nudge by skill name if verification steps are skipped.
+
+---
+
+## `agents/` directory
+
+Files under `i3-composer-agent/agents/` (e.g. code reviewer persona) are **not** loaded automatically by Cursor. Options:
+
+- Reference the skill equivalent (`code-review-and-quality`).
+- Paste agent markdown into the chat for one review.
+- Extract a **short** checklist into a `.mdc` rule.
+
+---
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|--------|
+| Skill never used | `SKILL.md` under `.cursor/skills/<name>/`? Valid frontmatter `description`? |
+| Rules ignored | Extension `.mdc`? Correct `alwaysApply` / `globs`? |
+| Stale workflow | Re-`rsync` from `i3-composer-agent/skills/` |
+| Duplicate instructions | Remove skill content from rules; keep one source |
+| Wrong skill picked | Narrow `description` in custom skills; nudge in chat |
+
+---
+
+## Checklist (new project)
+
+- [ ] `mkdir -p .cursor/skills` and sync from `i3-composer-agent/skills/`
+- [ ] Optional: `.cursor/rules/i3-composer-agent.mdc` with routing hint
+- [ ] Add repo-specific rules as separate small `.mdc` files
+- [ ] Commit `.cursor/skills/` and `.cursor/rules/` (team shares behavior)
+- [ ] Skip giant `.cursorrules` unless required by legacy tooling
+
+---
+
+## See also
+
+- [getting-started.md](getting-started.md)
+- [../README.md](../README.md) — Cursor quick blurb
+- Upstream: [github.com/addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)