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

package/docs/developer-onboarding.md

@@ -0,0 +1,116 @@
+# Developer Onboarding
+
+This guide is for people working **on** the i3-composer-agent repository itself: contributing skills, fixing docs, improving the eval harness. If you want to *use* the skills in your own projects, you're looking for [getting-started.md](getting-started.md) instead.
+
+It's a guided tour, not a rulebook. The rules live in [CONTRIBUTING.md](../CONTRIBUTING.md) (contribution workflow), [skill-anatomy.md](skill-anatomy.md) (skill format), and [evals/README.md](../evals/README.md) (eval framework); this document tells you when to read each one and how the pieces fit.
+
+---
+
+## 1. The mental model
+
+The repo has five composable layers. Understanding what each one is *for* prevents the most common contribution mistakes (putting reference material in a skill, building a persona that routes to other personas, duplicating content across skills).
+
+| Layer | Location | Job | In one word |
+|---|---|---|---|
+| **Skills** | `skills/<name>/SKILL.md` | Step-by-step workflows with verification gates | *How* |
+| **Personas** | `agents/<role>.md` | Roles with a perspective and output format | *Who* |
+| **Commands** | `.claude/commands/`, `.gemini/commands/`, `commands/` | User-facing entry points; the orchestration layer | *When* |
+| **References** | `references/*.md` | Checklists skills pull in on demand | *What to check* |
+| **Evals** | `evals/cases/<name>.json` | Proof that skills trigger and behave correctly | *Does it work* |
+
+Two structural rules worth internalizing early:
+
+- **The user (or a slash command) is the orchestrator.** Personas never invoke other personas; the only endorsed multi-persona pattern is parallel fan-out with a merge step (see [references/orchestration-patterns.md](../references/orchestration-patterns.md)).
+- **Don't duplicate, reference.** Skills link to other skills and to `references/` instead of restating content. The same rule applies to docs, including this one.
+
+One scope caveat that trips people up: `AGENTS.md` and `CLAUDE.md` at the repo root configure agents working on *this repo*. They are not reusable assets and setup guides must never tell users to copy them into their own projects; the reusable assets are the skills.
+
+Note that commands exist in three parallel directories (Claude Code, Gemini CLI, Antigravity). Touch one and CI checks parity across all of them, see §3.
+
+## 2. Local setup
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+cd i3-composer-agent
+```
+
+There's no build step and no `package.json`; validators are plain Node scripts. You need:
+
+- **Node 20+** (what CI runs) for the `scripts/` validators
+- **bash** (+ `jq` recommended) for the hook regression test
+- **`gh` CLI** for the duplicate-PR check before proposing a skill
+- **Claude Code** only if you want to run Tier 3 behavioral evals locally
+
+To try the pack live against a local checkout:
+
+```bash
+claude --plugin-dir /path/to/i3-composer-agent
+```
+
+## 3. The verification loop
+
+The repo eats its own cooking: verification is non-negotiable for skills, and it's non-negotiable for contributions to the repo too. Everything CI runs, you can run locally in seconds:
+
+```bash
+# Tier 1, structural: frontmatter, naming, required sections
+node scripts/validate-skills.js
+
+# Command parity and description sync across the three command directories
+node scripts/validate-commands.js
+
+# Tier 2, trigger & routing: positive prompts rank top-k, negatives don't collide
+node scripts/run-evals.js
+
+# Tier 3, behavioral (on demand, spends tokens; --dry-run prints the plan)
+node scripts/run-evals.js --behavioral <skill-name> --dry-run
+
+# Hook regression test, required if you touch hooks/session-start.sh
+# or skills/using-agent-skills/SKILL.md
+bash hooks/session-start-test.sh
+```
+
+The three eval tiers are worth understanding even if you never touch the harness, because a red Tier 2 usually means *fix your skill's description*, not the eval: Tier 2 is a lexical approximation of routing (stemmed TF-IDF over descriptions), and its two target failure modes are a description missing the vocabulary users actually say, and an over-broad description that outranks the right skill. The full design, schema, and trust-level rules are in [evals/README.md](../evals/README.md).
+
+Run the relevant subset before every PR. A PR that arrives green through Tier 1 + Tier 2 + command parity is reviewable; one that doesn't will bounce on mechanics before anyone reads the content.
+
+## 4. Contribution paths
+
+### Path 1: Fixing or improving an existing skill (most common, best first PR)
+
+1. Keep changes focused and minimal; preserve the skill's structure and tone.
+2. If you changed the frontmatter `description`, expect Tier 2 effects; run `node scripts/run-evals.js` and check the skill's trigger prompts still rank.
+3. Run Tier 1 to confirm frontmatter is still valid.
+
+### Path 2: Proposing a new skill (higher bar, do the pre-flight)
+
+The catalog already covers most of the lifecycle, so the burden of proof is on the gap. Before writing anything, run the pre-flight checks in [CONTRIBUTING.md](../CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs (`gh pr list --state open`; near-duplicate clusters already exist), confirm the idea fits [skill-anatomy.md](skill-anatomy.md), and justify the gap explicitly in your PR description. If it overlaps an existing skill, a focused edit to that skill beats a new directory.
+
+A new skill ships as a set, not a single file: the `skills/<kebab-case-name>/SKILL.md`, a matching `evals/cases/<name>.json`, and a `scripts/` directory only when it ships runnable helpers (reference material goes in `references/`, never inside the skill). The exact frontmatter rules, the section anatomy, and the eval-case minimums live in [CONTRIBUTING.md](../CONTRIBUTING.md#structure) and [skill-anatomy.md](skill-anatomy.md); take them from there rather than this tour, so the two can't drift.
+
+One point worth internalizing rather than looking up: when writing trigger prompts, paraphrase how users actually talk; copying the description into the prompts games the eval and tells you nothing.
+
+### Path 3: Docs, references, harness
+
+- Docs and skills are **English only**; translations aren't accepted because they drift ([CONTRIBUTING.md](../CONTRIBUTING.md#translations) has the rationale).
+- Changes to `scripts/run-evals.js` or the eval schema should stay compatible with skill-creator's `evals.json` schema (adopted verbatim for the behavioral tier; that compatibility is a feature, not an accident).
+- Anything touching the session-start hook or the meta-skill it embeds requires the hook regression test (§3).
+
+## 5. Pre-PR checklist
+
+- [ ] Tier 1 green: `node scripts/validate-skills.js`
+- [ ] Tier 2 green: `node scripts/run-evals.js`
+- [ ] Command parity green if you touched any command directory: `node scripts/validate-commands.js`
+- [ ] Hook test green if you touched `hooks/` or `using-agent-skills`
+- [ ] New skill → eval case file present with the minimum trigger/behavioral counts
+- [ ] New skill → gap justified in the PR description; catalog and open PRs checked
+- [ ] No duplicated content; cross-references used instead
+- [ ] Change is small and focused (the repo's own `code-review-and-quality` change-sizing guidance applies to contributions here too)
+
+## 6. Suggested reading order
+
+1. [README.md](../README.md): the catalog and the lifecycle diagram (10 min)
+2. `skills/using-agent-skills/SKILL.md`: how routing works from the agent's side
+3. One well-established skill end to end (e.g. `test-driven-development`): internalize the anatomy by example
+4. [skill-anatomy.md](skill-anatomy.md): the format spec, now with context
+5. [evals/README.md](../evals/README.md): the three tiers and the case format
+6. [CONTRIBUTING.md](../CONTRIBUTING.md) + [AGENTS.md](../AGENTS.md): the rules and the repo-scoped agent config

package/docs/gemini-cli-setup.md

@@ -0,0 +1,133 @@
+# Using i3-composer-agent with Gemini CLI
+
+## Setup
+
+### Option 1: Install as Skills (Recommended)
+
+Gemini CLI has a native skills system that auto-discovers `SKILL.md` files in `.gemini/skills/` or `.agents/skills/` directories. Each skill activates on demand when it matches your task.
+
+**Install from the repo:**
+
+```bash
+gemini skills install /path/to/i3-composer-agent --path skills
+```
+
+**Or install from a local clone:**
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+gemini skills install /path/to/i3-composer-agent/skills/
+```
+
+**Install for a specific workspace only:**
+
+```bash
+gemini skills install /path/to/i3-composer-agent/skills/ --scope workspace
+```
+
+Skills installed at workspace scope go into `.gemini/skills/` (or `.agents/skills/`). User-level skills go into `~/.gemini/skills/`.
+
+Once installed, verify with:
+
+```
+/skills list
+```
+
+Gemini CLI injects skill names and descriptions into the prompt automatically. When it recognizes a matching task, it asks permission to activate the skill before loading its full instructions.
+
+### Option 2: GEMINI.md (Persistent Context)
+
+For skills you want always loaded as persistent project context (rather than on-demand activation), add them to your project's `GEMINI.md`:
+
+```bash
+# Create GEMINI.md with core skills as persistent context
+cat /path/to/i3-composer-agent/skills/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
+```
+
+You can also modularize by importing from separate files:
+
+```markdown
+# Project Instructions
+
+@skills/test-driven-development/SKILL.md
+@skills/incremental-implementation/SKILL.md
+```
+
+Use `/memory show` to verify loaded context, and `/memory reload` to refresh after changes.
+
+> **Skills vs GEMINI.md:** Skills are on-demand expertise that activate only when relevant, keeping your context window clean. GEMINI.md provides persistent context loaded for every prompt. Use skills for phase-specific workflows and GEMINI.md for always-on project conventions.
+
+## Recommended Configuration
+
+### Always-On (GEMINI.md)
+
+Add these as persistent context for every session:
+
+- `incremental-implementation` — Build in small verifiable slices
+- `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
+
+## Advanced Configuration
+
+### MCP Integration
+
+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.
+
+To enable these, ensure you have the relevant MCP extensions installed in your Gemini CLI configuration (`~/.gemini/config.json`).
+
+### Session Hooks
+
+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.
+
+### 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.
+```
+
+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.
+
+| 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 |
+
+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.
+
+## Usage Tips
+
+1. **Prefer skills over GEMINI.md** — Skills activate on demand and keep your context window focused. Only put skills in GEMINI.md if you want them always loaded.
+2. **Skill descriptions matter** — Each SKILL.md has a `description` field in its frontmatter that tells agents when to activate it. The descriptions in this repo are optimized for auto-discovery across all supported tools (Claude Code, Gemini CLI, etc.) by clearly stating both *what* the skill does and *when* it should be triggered.
+3. **Use agents for review** — Copy `agents/code-reviewer.md` content when requesting structured code reviews.
+4. **Combine with references** — Reference checklists from `references/` when working on specific quality areas like testing or performance.

package/docs/getting-started.md

@@ -0,0 +1,208 @@
+# Getting Started with i3-composer-agent
+
+i3-composer-agent works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
+
+Want a worked example before setting up your own project? The
+[interactive tutorials](https://skills.addy.ie/tutorials/) walk through a
+greenfield build, a brownfield feature, and a safe automation loop with
+copyable prompts for Claude Code, Codex, or any other agent.
+
+## How Skills Work
+
+Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria.
+
+**Skills are not reference docs.** They're step-by-step processes the agent follows.
+
+## Quick Start (Any Agent)
+
+### 1. Prepare the plugin bundle
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir ./i3-composer-agent
+```
+
+### 2. Choose a skill
+
+Browse the `skills/` directory. Each subdirectory contains a `SKILL.md` with:
+- **When to use** — triggers that indicate this skill applies
+- **Process** — step-by-step workflow
+- **Verification** — how to confirm the work is done
+- **Common rationalizations** — excuses the agent might use to skip steps
+- **Red flags** — signs the skill is being violated
+
+### 3. Load the skill into your agent
+
+Copy the relevant `SKILL.md` content into your agent's system prompt, rules file, or conversation. The most common approaches:
+
+**System prompt:** Paste the skill content at the start of the session.
+
+**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."
+
+### 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 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.
+
+### Existing projects need no migration
+
+Install the pack from the existing project's root using the normal setup path
+for your agent, then keep working in that project. Skills activate for matching
+tasks; they do not require a new repository layout or a one-time conversion of
+existing code.
+
+Do not copy this repository's root `AGENTS.md` or `CLAUDE.md` into the project.
+Those files configure contributors to i3-composer-agent itself. Add only the skills
+and any project-specific instructions your agent normally reads. For a gradual
+rollout in an established codebase, follow the [Adoption Guide](adoption-guide.md).
+
+## Recommended Setup
+
+Rolling out to a real project? The **[Adoption Guide](adoption-guide.md)** covers two end-to-end paths: the full lifecycle from day one for a greenfield project, and an incremental, verification-first rollout for an established codebase. The setup below is the quick version.
+
+### Minimal (Start here)
+
+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
+
+These three cover the most critical quality gaps in AI-assisted development.
+
+### Full Lifecycle
+
+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
+```
+
+### 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`
+
+## Skill Anatomy
+
+Every skill follows the same structure:
+
+```
+YAML frontmatter (name, description)
+├── Overview — What this skill does
+├── When to Use — Triggers and conditions
+├── Core Process — Step-by-step workflow
+├── Examples — Code samples and patterns
+├── Common Rationalizations — Excuses and rebuttals
+├── Red Flags — Signs the skill is being violated
+└── Verification — Exit criteria checklist
+```
+
+See [skill-anatomy.md](skill-anatomy.md) for the full specification.
+
+## Using Agents
+
+The `agents/` directory contains pre-configured agent personas:
+
+| Agent | Purpose |
+|-------|---------|
+| `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`) |
+
+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.
+
+## Using Commands
+
+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) |
+
+> **Note:** When installed as a Claude Code plugin you may see a warning like
+> _"Default commands/ folder is ignored because the manifest sets 'commands'"_.
+> This is expected. The root `commands/` directory belongs to the Antigravity CLI
+> and is intentionally separate from `.claude/commands/`. All Claude Code slash
+> commands load correctly from `.claude/commands/`; the warning is cosmetic.
+
+## Using References
+
+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 |
+| `definition-of-done.md` | all skills / every change |
+| `observability-checklist.md` | observability-and-instrumentation |
+| `orchestration-patterns.md` | doubt-driven-development |
+
+Load a reference when you need detailed patterns beyond what the skill covers.
+
+If you install one skill with `npx skills add ... --skill <name>`, only the
+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:
+
+- 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.
+- If your repo doesn’t want these files long‑term, delete them before merge or add the folder to `.gitignore` — the workflow doesn’t require them to be permanent.
+
+### Working across sessions
+
+The same artifacts are the handoff between sessions. For a small task, run the whole lifecycle in one session. For anything non-trivial, a fresh session per phase (spec → plan → build → review) keeps context focused — what carries the work forward is the approved files, not the conversation:
+
+- the spec — `SPEC.md`, or wherever your spec actually lives
+- `tasks/plan.md` and `tasks/todo.md` — or the external tracker the plan identifies, if you use one
+
+**Before switching**, make sure those files reflect the decisions that still apply, the scope you approved, the questions still open, the next task, and the current verification state (which tests ran, against what).
+
+**In the new session**, read the actual files and look at `git status` before doing anything. Don't assume approvals you can't see in the artifacts. Treat a recorded "tests pass" as a claim about a specific baseline: re-run the checks it covers if the code has moved since, if it doesn't say what was run against what, or if you're about to touch the area it covered. If the baseline still holds, take it and get on with the next task — the point is a check proportional to what changed, not a full suite at every handoff.
+
+#### 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.
+
+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.
+
+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:
+
+> 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.
+
+> Read SPEC.md, tasks/plan.md and tasks/todo.md, then check where things actually stand — `git status`, plus re-running whatever checks the recorded verification state no longer covers. Tell me the next unchecked task and anything still open, then stop: I'll confirm the scope before you start it. If the plan looks incomplete, say what's missing rather than rewriting it.
+
+## Tips
+
+1. **Start with spec-driven-development** for any non-trivial work
+2. **Always load 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