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

package/.agents/plugins/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "i3-composer-agent",
+  "interface": {
+    "displayName": "i3 Composer Agent"
+  },
+  "plugins": [
+    {
+      "name": "i3-composer-agent",
+      "version": "1.0.0",
+      "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity",
+      "homepage": "https://github.com/49780522/i3-composer-agent"
+    }
+  ]
+}

package/.claude/commands/build.md

@@ -0,0 +1,44 @@
+---
+description: Implement tasks incrementally — build, test, verify, commit. Add "auto" to run the whole plan in one approved pass.
+---
+
+Invoke the i3-composer-agent:incremental-implementation skill alongside i3-composer-agent:test-driven-development.
+
+## Modes
+
+- **`/build`** — implement the *next* pending task, then stop (careful, one slice at a time).
+- **`/build auto`** — generate the plan if needed, get a single approval, then implement *every* task without stopping between them.
+
+`$ARGUMENTS` selects the mode. Treat `auto` (canonical) or `all` as autonomous mode; anything else (or empty) is the default single-task mode. Note: autonomous mode is not faster *per task* — it runs the same test-driven loop — it only removes the human stepping *between* tasks.
+
+## Default: one task
+
+Pick the next pending task from the plan. Then:
+
+1. Read the task's acceptance criteria
+2. Load relevant context (existing code, patterns, types)
+3. Write a failing test for the expected behavior (RED)
+4. Implement the minimum code to pass the test (GREEN)
+5. Run the full test suite to check for regressions
+6. Run the build to verify compilation
+7. Commit with a descriptive message
+8. Mark the task complete and stop
+
+## Autonomous: the whole plan (`/build auto`)
+
+Use this once a spec exists and you want to collapse plan + build into one run. It removes the manual stepping between tasks — **not** the verification. Every task still earns a passing test and its own commit.
+
+1. **Require a spec.** Look only for a spec at a known path: `SPEC.md` at the repo root, `docs/SPEC.md`, or a file under `spec/`. A README or arbitrary doc does **not** count. If none exists, stop and tell the user to run `/spec` first — do not invent requirements.
+2. **Establish a clean baseline.** Run `git status --porcelain`. If there are uncommitted changes outside the expected planning artifacts (`SPEC.md`, `docs/SPEC.md`, `spec/*`, `tasks/plan.md`, `tasks/todo.md`), stop and ask the user to commit, stash, or confirm how to handle them. Autonomous per-task commits must not absorb unrelated local work, or the clean-rollback guarantee breaks.
+3. **Plan if needed.** If there is no `tasks/plan.md`, invoke i3-composer-agent:planning-and-task-breakdown to generate one.
+4. **Single checkpoint.** Present the full plan and wait for an unambiguous affirmative (e.g. "approve", "go", "yes"). Treat hedged responses ("looks reasonable", "I guess") as **not** approved. This is the only human gate — after approval, run autonomously. If you generated `tasks/plan.md`, commit it as a single preparatory commit now so it doesn't bleed into the first task's commit.
+5. **Execute every task in dependency order.** Use each task's declared dependencies; if they aren't explicit, execute in the order the plan lists them. For each task, run the full default loop above (RED → GREEN → regression → build → commit → mark complete). Stage only the files that task touched plus its task-status update — never `git add -A` blindly — and make one commit per task so any point is a clean rollback.
+6. **Stop and ask the user** (do not push through) when:
+   - a test can't be made to pass or the build breaks without an obvious fix → follow i3-composer-agent:debugging-and-error-recovery
+   - the spec is ambiguous, or a task needs a decision the spec doesn't cover
+   - a task is high-risk or irreversible — auth/permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets, **or anything you can't undo with `git revert`** → follow i3-composer-agent:doubt-driven-development and get explicit sign-off before continuing
+
+   After the user resolves a blocker, they re-invoke `/build auto` — it resumes from the next pending task.
+7. **Summarize at the end:** tasks completed, tests added, commits made, and anything skipped, flagged, or left for the user.
+
+If any step fails, follow the i3-composer-agent:debugging-and-error-recovery skill.

package/.claude/commands/code-simplify.md

@@ -0,0 +1,22 @@
+---
+description: Simplify code for clarity and maintainability — reduce complexity without changing behavior
+---
+
+Invoke the i3-composer-agent:code-simplification skill.
+
+Simplify recently changed code (or the specified scope) while preserving exact behavior:
+
+1. Read CLAUDE.md and study project conventions
+2. Identify the target code — recent changes unless a broader scope is specified
+3. Understand the code's purpose, callers, edge cases, and test coverage before touching it
+4. Scan for simplification opportunities:
+   - Deep nesting → guard clauses or extracted helpers
+   - Long functions → split by responsibility
+   - Nested ternaries → if/else or switch
+   - Generic names → descriptive names
+   - Duplicated logic → shared functions
+   - Dead code → remove after confirming
+5. Apply each simplification incrementally — run tests after each change
+6. Verify all tests pass, the build succeeds, and the diff is clean
+
+If tests fail after a simplification, revert that change and reconsider. Use `code-review-and-quality` to review the result.

package/.claude/commands/constraints.md

@@ -0,0 +1,32 @@
+---
+description: Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md
+---
+
+Invoke the i3-composer-agent:constraint-driven-development skill.
+
+$ARGUMENTS
+
+Default behaviour with no arguments: set up constraints for this repository.
+
+1. **Detect first.** Read package.json / pyproject.toml / go.mod, the test runner, existing lint configs, current coverage output, CI workflows, and the agent harness in use. Report what you found in two lines. Never ask for anything you can read.
+
+2. **Interview, at most four questions.** One at a time, each with your best guess and a usable default so "I don't know" still produces a working config:
+   - Which dimensions beyond the floor (coverage, security, performance, accessibility, architecture)
+   - Block or warn when a check fails mid-task
+   - Target numbers, or measure today's values and hold them
+   - Slowest check tolerated before handing work back
+
+3. **Write CONSTRAINTS.md** at the repo root with a Floor section, enforced numbers, measured-only metrics with today's values, and an exceptions table with owners and expiry dates. Every number needs a stated reason.
+
+4. **Install what each picked dimension needs.** A dimension with a number and no tool behind it is an aspiration. Use the de facto tool so existing config keeps working: Semgrep for code scanning, gitleaks (always `--redact`) for secrets, osv-scanner for dependencies, axe-core for accessibility, Lighthouse for web vitals, size-limit for bundles, dependency-cruiser for boundaries, Stryker for assertion quality. Record the exact command next to each rule in CONSTRAINTS.md. Accessibility and performance need a running URL; if the project has none, say so and drop the dimension rather than inventing a check. Add the commands to package.json as check:fast / check:task / check:full.
+
+5. **Place each check by cost.** Types, lint and secrets in the edit loop (seconds). Related tests and changed-line coverage at task end (under 90s). Everything else at review or in CI. Scope checks to the diff, not the whole repo.
+
+6. **Point the agent at it.** Add a line to CLAUDE.md telling agents to read CONSTRAINTS.md and never weaken it to make a change pass.
+
+7. **Verify.** Run the constraints against the current branch. If anything fails that the user disagrees with, fix the constraint now rather than leaving a gate people will learn to ignore.
+
+Sub-commands:
+- `/constraints check` — run the current constraints against this branch and report
+- `/constraints guard` — inspect the diff for a weakened bar: lowered thresholds, skipped or deleted tests, new suppression comments, unfinished stubs, new exceptions
+- `/constraints ratchet` — record today's measured values as the floor that must not fall

package/.claude/commands/plan.md

@@ -0,0 +1,18 @@
+---
+description: Break work into small verifiable tasks with acceptance criteria and dependency ordering
+---
+
+Invoke the i3-composer-agent:planning-and-task-breakdown skill.
+
+Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then:
+
+1. Enter plan mode — read only, no code changes
+2. Identify the dependency graph between components
+3. Slice work vertically (one complete path per task, not horizontal layers)
+4. Write tasks with acceptance criteria and verification steps
+5. Add checkpoints between phases
+6. Present the plan for human review
+
+Save the plan to tasks/plan.md and task list to tasks/todo.md.
+
+If tasks/plan.md or tasks/todo.md already exists with unchecked tasks for different work, stop and ask before writing — never silently overwrite an incomplete plan.

package/.claude/commands/review.md

@@ -0,0 +1,16 @@
+---
+description: Conduct a five-axis code review — correctness, readability, architecture, security, performance
+---
+
+Invoke the i3-composer-agent:code-review-and-quality skill.
+
+Review the current changes (staged or recent commits) across all five axes:
+
+1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
+2. **Readability** — Clear names? Straightforward logic? Well-organized?
+3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level?
+4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
+5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
+
+Categorize findings as Critical, Important, or Suggestion.
+Output a structured review with specific file:line references and fix recommendations.

package/.claude/commands/ship.md

@@ -0,0 +1,72 @@
+---
+description: Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision
+---
+
+Invoke the i3-composer-agent:shipping-and-launch skill.
+
+`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here.
+
+## Phase A — Parallel fan-out
+
+Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command.
+
+In Claude Code, each call passes `subagent_type` matching the persona's `name` field:
+
+1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template.
+2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report.
+3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis.
+
+In other harnesses without an Agent tool, invoke each persona's system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works.
+
+Constraints (from Claude Code's subagent model):
+- Subagents cannot spawn other subagents — do not let one persona delegate to another.
+- Each subagent gets its own context window and returns only its report to this main session.
+- If you need teammates that talk to each other instead of just reporting back, use Claude Code Agent Teams and reference these personas as teammate types (see `references/orchestration-patterns.md`).
+
+**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `.claude/agents/` or `~/.claude/agents/`, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Claude Code's scope priority table, so user-level definitions win by design.
+
+## Phase B — Merge in main context
+
+Once all three reports are back, the main agent (not a sub-persona) synthesizes them:
+
+1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
+2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis.
+3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable.
+4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist).
+5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly.
+6. **Documentation** — README, ADRs, changelog. Verify directly.
+
+## Phase C — Decision and rollback
+
+Produce a single output:
+
+```markdown
+## Ship Decision: GO | NO-GO
+
+### Blockers (must fix before ship)
+- [Source persona: Critical finding + file:line]
+
+### Recommended fixes (should fix before ship)
+- [Source persona: Important finding + file:line]
+
+### Acknowledged risks (shipping anyway)
+- [Risk + mitigation]
+
+### Rollback plan
+- Trigger conditions: [what signals would prompt rollback]
+- Rollback procedure: [exact steps]
+- Recovery time objective: [target]
+
+### Specialist reports (full)
+- [code-reviewer report]
+- [security-auditor report]
+- [test-engineer report]
+```
+
+## Rules
+
+1. The three Phase A personas run in parallel — never sequentially.
+2. Personas do not call each other. The main agent merges in Phase B.
+3. The rollback plan is mandatory before any GO decision.
+4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk.
+5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small.

package/.claude/commands/spec.md

@@ -0,0 +1,17 @@
+---
+description: Start spec-driven development — write a structured specification before writing code
+---
+
+Invoke the i3-composer-agent:spec-driven-development skill.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+1. The objective and target users
+2. Core features and acceptance criteria
+3. Tech stack preferences and constraints
+4. Known boundaries (what to always do, ask first about, and never do)
+
+Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries.
+
+If the request bundles several independently testable capabilities, first propose a capability map (module ids, dependency direction, build order) per the skill's Phase 0 and get it approved, then spec each module in dependency order.
+
+Save the spec as SPEC.md in the project root and confirm with the user before proceeding.

package/.claude/commands/test.md

@@ -0,0 +1,19 @@
+---
+description: Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern.
+---
+
+Invoke the i3-composer-agent:test-driven-development skill.
+
+For new features:
+1. Write tests that describe the expected behavior (they should FAIL)
+2. Implement the code to make them pass
+3. Refactor while keeping tests green
+
+For bug fixes (Prove-It pattern):
+1. Write a test that reproduces the bug (must FAIL)
+2. Confirm the test fails
+3. Implement the fix
+4. Confirm the test passes
+5. Run the full test suite for regressions
+
+For browser-related issues, also invoke i3-composer-agent:browser-testing-with-devtools to verify with Chrome DevTools MCP.

package/.claude/commands/webperf.md

@@ -0,0 +1,32 @@
+---
+description: Run a web performance audit via the web-performance-auditor persona
+---
+
+`/webperf` targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output.
+
+## Determine the mode
+
+**Deep mode** — activate when any of these is available:
+- A Lighthouse JSON report file (e.g. `npx lighthouse <url> --output json --output-path ./report.json`, or `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` from the Chrome DevTools MCP CLI)
+- A PageSpeed Insights JSON response (includes Lighthouse + CrUX)
+- A CrUX API response (requires `CRUX_API_KEY` or `GOOGLE_API_KEY`)
+- A DevTools performance trace
+- A live URL plus the `chrome-devtools` MCP server configured in the harness (the agent can capture metrics directly via `lighthouse_audit` and `performance_*` tools)
+- The Chrome DevTools MCP CLI invoked locally (via `npx -p chrome-devtools-mcp chrome-devtools <tool>` or after `npm i -g chrome-devtools-mcp`) — the user runs commands like `chrome-devtools lighthouse_audit --output-format=json` and passes the JSON output to the agent
+
+**Quick mode** — default when none of the above are available. The agent scans source code for structural anti-patterns and labels every finding as `potential impact`.
+
+## Run the audit
+
+Spawn the `web-performance-auditor` subagent. Pass it explicitly:
+
+- The files, components, or diff under review
+- Any artifact paths (Lighthouse JSON, PSI JSON, CrUX response, trace) or pasted JSON content
+- The target URL or page name when known
+- A note on which mode you expect (Quick or Deep), so the agent surfaces missing inputs if Deep was intended
+
+The subagent returns a scorecard (only populated with sourced values), a ranked list of findings, positive observations, and proactive recommendations.
+
+## Output
+
+Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "i3-composer-agent",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "owner": {
+    "name": "Givolt"
+  },
+  "plugins": [
+    {
+      "name": "i3-composer-agent",
+      "version": "1.0.0",
+      "source": "./",
+      "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+      "homepage": "https://github.com/49780522/i3-composer-agent",
+      "license": "MIT",
+      "keywords": [
+        "skills",
+        "agents",
+        "engineering",
+        "spec",
+        "tdd",
+        "review",
+        "ship"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "i3-composer-agent",
+  "version": "1.0.0",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "author": {
+    "name": "Givolt"
+  },
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent",
+  "license": "MIT",
+  "commands": [
+    "./.claude/commands",
+    "./commands"
+  ],
+  "skills": "./skills",
+  "experimental": {
+    "evals": "evals/plugin"
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "i3-composer-agent",
+  "version": "1.0.0",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "author": {
+    "name": "Givolt"
+  },
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent",
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "i3 Composer Agent",
+    "shortDescription": "Engineering workflow skills",
+    "longDescription": "i3 Composer Agent packages 25 engineering skills from Addy Osmani's Agent Skills, covering requirements, planning, implementation, testing, review, and shipping.",
+    "developerName": "Givolt",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Help me choose the right engineering workflow for this task",
+      "Plan and implement this change using the relevant i3 Composer Agent"
+    ]
+  }
+}

package/.gemini/commands/build.toml

@@ -0,0 +1,43 @@
+description = "Implement tasks incrementally — build, test, verify, commit. Add \"auto\" to run the whole plan in one approved pass."
+
+prompt = """
+Invoke the incremental-implementation skill alongside test-driven-development.
+
+## Modes
+
+- `/build` — implement the next pending task, then stop (careful, one slice at a time).
+- `/build auto` — generate the plan if needed, get a single approval, then implement every task without stopping between them.
+
+The arguments select the mode. Treat `auto` (canonical) or `all` as autonomous mode; anything else (or empty) is the default single-task mode. Note: autonomous mode is not faster per task — it runs the same test-driven loop — it only removes the human stepping between tasks.
+
+## Default: one task
+
+Pick the next pending task from the plan. Then:
+
+1. Read the task's acceptance criteria
+2. Load relevant context (existing code, patterns, types)
+3. Write a failing test for the expected behavior (RED)
+4. Implement the minimum code to pass the test (GREEN)
+5. Run the full test suite to check for regressions
+6. Run the build to verify compilation
+7. Commit with a descriptive message
+8. Mark the task complete and stop
+
+## Autonomous: the whole plan (`/build auto`)
+
+Use this once a spec exists and you want to collapse plan + build into one run. It removes the manual stepping between tasks — not the verification. Every task still earns a passing test and its own commit.
+
+1. Require a spec. Look only for a spec at a known path: SPEC.md at the repo root, docs/SPEC.md, or a file under spec/. A README or arbitrary doc does NOT count. If none exists, stop and tell the user to run /spec first — do not invent requirements.
+2. Establish a clean baseline. Run `git status --porcelain`. If there are uncommitted changes outside the expected planning artifacts (SPEC.md, docs/SPEC.md, spec/*, tasks/plan.md, tasks/todo.md), stop and ask the user to commit, stash, or confirm how to handle them. Autonomous per-task commits must not absorb unrelated local work, or the clean-rollback guarantee breaks.
+3. Plan if needed. If there is no tasks/plan.md, invoke the planning-and-task-breakdown skill to generate one.
+4. Single checkpoint. Present the full plan and wait for an unambiguous affirmative (e.g. "approve", "go", "yes"). Treat hedged responses ("looks reasonable", "I guess") as NOT approved. This is the only human gate — after approval, run autonomously. If you generated tasks/plan.md, commit it as a single preparatory commit now so it doesn't bleed into the first task's commit.
+5. Execute every task in dependency order. Use each task's declared dependencies; if they aren't explicit, execute in the order the plan lists them. For each task, run the full default loop above (RED → GREEN → regression → build → commit → mark complete). Stage only the files that task touched plus its task-status update — never `git add -A` blindly — and make one commit per task so any point is a clean rollback.
+6. Stop and ask the user (do not push through) when:
+   - a test can't be made to pass or the build breaks without an obvious fix → follow the debugging-and-error-recovery skill
+   - the spec is ambiguous, or a task needs a decision the spec doesn't cover
+   - a task is high-risk or irreversible — auth/permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets, or anything you can't undo with `git revert` → follow the doubt-driven-development skill and get explicit sign-off before continuing
+   After the user resolves a blocker, they re-invoke /build auto — it resumes from the next pending task.
+7. Summarize at the end: tasks completed, tests added, commits made, and anything skipped, flagged, or left for the user.
+
+If any step fails, follow the debugging-and-error-recovery skill.
+"""

package/.gemini/commands/code-simplify.toml

@@ -0,0 +1,22 @@
+description = "Simplify code for clarity and maintainability — reduce complexity without changing behavior"
+
+prompt = """
+Invoke the code-simplification skill.
+
+Simplify recently changed code (or the specified scope) while preserving exact behavior:
+
+1. Read GEMINI.md and study project conventions
+2. Identify the target code — recent changes unless a broader scope is specified
+3. Understand the code's purpose, callers, edge cases, and test coverage before touching it
+4. Scan for simplification opportunities:
+   - Deep nesting → guard clauses or extracted helpers
+   - Long functions → split by responsibility
+   - Nested ternaries → if/else or switch
+   - Generic names → descriptive names
+   - Duplicated logic → shared functions
+   - Dead code → remove after confirming
+5. Apply each simplification incrementally — run tests after each change
+6. Verify all tests pass, the build succeeds, and the diff is clean
+
+If tests fail after a simplification, revert that change and reconsider. Use `code-review-and-quality` to review the result.
+"""

package/.gemini/commands/constraints.toml

@@ -0,0 +1,32 @@
+description = "Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md"
+
+prompt = """
+Invoke the constraint-driven-development skill.
+
+$ARGUMENTS
+
+Default behaviour with no arguments: set up constraints for this repository.
+
+1. **Detect first.** Read package.json / pyproject.toml / go.mod, the test runner, existing lint configs, current coverage output, CI workflows, and the agent harness in use. Report what you found in two lines. Never ask for anything you can read.
+
+2. **Interview, at most four questions.** One at a time, each with your best guess and a usable default so "I don't know" still produces a working config:
+   - Which dimensions beyond the floor (coverage, security, performance, accessibility, architecture)
+   - Block or warn when a check fails mid-task
+   - Target numbers, or measure today's values and hold them
+   - Slowest check tolerated before handing work back
+
+3. **Write CONSTRAINTS.md** at the repo root with a Floor section, enforced numbers, measured-only metrics with today's values, and an exceptions table with owners and expiry dates. Every number needs a stated reason.
+
+4. **Install what each picked dimension needs.** A dimension with a number and no tool behind it is an aspiration. Use the de facto tool so existing config keeps working: Semgrep for code scanning, gitleaks (always `--redact`) for secrets, osv-scanner for dependencies, axe-core for accessibility, Lighthouse for web vitals, size-limit for bundles, dependency-cruiser for boundaries, Stryker for assertion quality. Record the exact command next to each rule in CONSTRAINTS.md. Accessibility and performance need a running URL; if the project has none, say so and drop the dimension rather than inventing a check. Add the commands to package.json as check:fast / check:task / check:full.
+
+5. **Place each check by cost.** Types, lint and secrets in the edit loop (seconds). Related tests and changed-line coverage at task end (under 90s). Everything else at review or in CI. Scope checks to the diff, not the whole repo.
+
+6. **Point the agent at it.** Add a line to AGENTS.md and GEMINI.md telling agents to read CONSTRAINTS.md and never weaken it to make a change pass.
+
+7. **Verify.** Run the constraints against the current branch. If anything fails that the user disagrees with, fix the constraint now rather than leaving a gate people will learn to ignore.
+
+Sub-commands:
+- `/constraints check` — run the current constraints against this branch and report
+- `/constraints guard` — inspect the diff for a weakened bar: lowered thresholds, skipped or deleted tests, new suppression comments, unfinished stubs, new exceptions
+- `/constraints ratchet` — record today's measured values as the floor that must not fall
+"""

package/.gemini/commands/planning.toml

@@ -0,0 +1,18 @@
+description = "Break work into small verifiable tasks with acceptance criteria and dependency ordering"
+
+prompt = """
+Invoke the planning-and-task-breakdown skill.
+
+Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then:
+
+1. Enter plan mode — read only, no code changes
+2. Identify the dependency graph between components
+3. Slice work vertically (one complete path per task, not horizontal layers)
+4. Write tasks with acceptance criteria and verification steps
+5. Add checkpoints between phases
+6. Present the plan for human review
+
+Save the plan to tasks/plan.md and task list to tasks/todo.md.
+
+If tasks/plan.md or tasks/todo.md already exists with unchecked tasks for different work, stop and ask before writing — never silently overwrite an incomplete plan.
+"""

package/.gemini/commands/review.toml

@@ -0,0 +1,16 @@
+description = "Conduct a five-axis code review — correctness, readability, architecture, security, performance"
+
+prompt = """
+Invoke the code-review-and-quality skill.
+
+Review the current changes (staged or recent commits) across all five axes:
+
+1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
+2. **Readability** — Clear names? Straightforward logic? Well-organized?
+3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level?
+4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
+5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
+
+Categorize findings as Critical, Important, or Suggestion.
+Output a structured review with specific file:line references and fix recommendations.
+"""

package/.gemini/commands/ship.toml

@@ -0,0 +1,72 @@
+description = "Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision"
+
+prompt = """
+Invoke the shipping-and-launch skill.
+
+`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here.
+
+## Phase A — Parallel fan-out
+
+Spawn three subagents concurrently. Gemini CLI exposes each custom subagent in `agents/` as a tool with the same name — so `code-reviewer.md` becomes a `code-reviewer` tool the main agent can call, and `@code-reviewer` works as an explicit invocation in the prompt. **Issue all three subagent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command.
+
+Dispatch each persona by tool name:
+
+1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template.
+2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report.
+3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis.
+
+If subagents are unavailable in the current Gemini CLI version, invoke each persona's system prompt sequentially in the main context and treat their outputs as if returned in parallel — the merge phase still works.
+
+Constraints (from Gemini CLI's subagent model):
+- Subagents run in isolated context loops and return only their report to this main session.
+- Do not let one persona delegate to another — keep the fan-out flat.
+- For richer multi-agent collaboration where teammates talk to each other instead of just reporting back, see `references/orchestration-patterns.md`.
+
+**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `agents/` (this plugin's agents, at the repo root) or `~/.gemini/agents/` (user-level), those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Gemini CLI's scope priority table, so user-level definitions win by design.
+
+## Phase B — Merge in main context
+
+Once all three reports are back, the main agent (not a sub-persona) synthesizes them:
+
+1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
+2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis.
+3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable.
+4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist).
+5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly.
+6. **Documentation** — README, ADRs, changelog. Verify directly.
+
+## Phase C — Decision and rollback
+
+Produce a single output:
+
+```markdown
+## Ship Decision: GO | NO-GO
+
+### Blockers (must fix before ship)
+- [Source persona: Critical finding + file:line]
+
+### Recommended fixes (should fix before ship)
+- [Source persona: Important finding + file:line]
+
+### Acknowledged risks (shipping anyway)
+- [Risk + mitigation]
+
+### Rollback plan
+- Trigger conditions: [what signals would prompt rollback]
+- Rollback procedure: [exact steps]
+- Recovery time objective: [target]
+
+### Specialist reports (full)
+- [code-reviewer report]
+- [security-auditor report]
+- [test-engineer report]
+```
+
+## Rules
+
+1. The three Phase A personas run in parallel — never sequentially.
+2. Personas do not call each other. The main agent merges in Phase B.
+3. The rollback plan is mandatory before any GO decision.
+4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk.
+5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small.
+"""

package/.gemini/commands/spec.toml

@@ -0,0 +1,17 @@
+description = "Start spec-driven development — write a structured specification before writing code"
+
+prompt = """
+Invoke the spec-driven-development skill.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+1. The objective and target users
+2. Core features and acceptance criteria
+3. Tech stack preferences and constraints
+4. Known boundaries (what to always do, ask first about, and never do)
+
+Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries.
+
+If the request bundles several independently testable capabilities, first propose a capability map (module ids, dependency direction, build order) per the skill's Phase 0 and get it approved, then spec each module in dependency order.
+
+Save the spec as SPEC.md in the project root and confirm with the user before proceeding.
+"""

package/.gemini/commands/test.toml

@@ -0,0 +1,19 @@
+description = "Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern."
+
+prompt = """
+Invoke the test-driven-development skill.
+
+For new features:
+1. Write tests that describe the expected behavior (they should FAIL)
+2. Implement the code to make them pass
+3. Refactor while keeping tests green
+
+For bug fixes (Prove-It pattern):
+1. Write a test that reproduces the bug (must FAIL)
+2. Confirm the test fails
+3. Implement the fix
+4. Confirm the test passes
+5. Run the full test suite for regressions
+
+For browser-related issues, also invoke browser-testing-with-devtools to verify with Chrome DevTools MCP.
+"""