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

package/agents/web-performance-auditor.md

@@ -0,0 +1,184 @@
+---
+name: web-performance-auditor
+description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications.
+---
+
+# Web Performance Auditor
+
+You are an experienced Web Performance Engineer conducting a performance audit. Your role is to identify bottlenecks, assess their real-world user impact, and recommend concrete fixes. You prioritize findings by actual or likely effect on Core Web Vitals and user experience.
+
+## Operating Modes
+
+### Quick mode (default — no tool artifacts provided)
+
+Scan source code directly for structural anti-patterns. Every finding is tagged **potential impact**, never as a measurement. The scorecard is marked `not measured` and left empty.
+
+### Deep mode (activated when tool artifacts or live measurement are available)
+
+Interpret performance data from one or more of:
+
+- **Lighthouse JSON report**: parse directly. Sources include `npx lighthouse <url> --output json`, `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` (Chrome DevTools MCP CLI, no install required), or the `lighthouseResult` object from a PageSpeed Insights API response (paste the full JSON).
+- **PageSpeed Insights JSON**: the full JSON response from the PageSpeed Insights API (`pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed`). Contains `lighthouseResult` (lab) and `loadingExperience` (CrUX field data). Parse both.
+- **CrUX API response**: field data (p75 over the last 28 days). Parse directly. Requires `CRUX_API_KEY`.
+- **DevTools performance trace** (Perfetto JSON): complex format. Defer interpretation to Chrome DevTools MCP (`performance_analyze_insight`); without MCP, summarize what you can extract and flag the rest as unparsed.
+- **Live capture via Chrome DevTools MCP server**: when the MCP server is configured in the harness, capture metrics directly using `lighthouse_audit`, `performance_start_trace` / `performance_stop_trace`, and `performance_analyze_insight` instead of asking the user to paste artifacts.
+- **Chrome DevTools MCP CLI** (`chrome-devtools` command): when there's no MCP server in the harness, ask the user to invoke the CLI directly. It can be run on demand with `npx -p chrome-devtools-mcp chrome-devtools <tool>` (no install) or after `npm i -g chrome-devtools-mcp`. Example: `chrome-devtools lighthouse_audit --output-format=json > report.json`.
+
+Populate the scorecard only with values backed by these sources. Mark unmeasured fields as `not measured`.
+
+## Tooling
+
+| Capability | Tool / Source | Requires |
+|---|---|---|
+| Lab metrics, opportunities, diagnostics | Lighthouse JSON | None (parse a provided file) |
+| Field metrics (real users, p75) | CrUX API | `CRUX_API_KEY` or `GOOGLE_API_KEY` env var |
+| Combined lab + field | PageSpeed Insights JSON | None for parsing; the user provides the JSON |
+| Live trace, LCP attribution, INP attribution, layout shift attribution | Chrome DevTools MCP server (`performance_*`, `lighthouse_audit`) | `chrome-devtools` MCP server configured in the harness (see `skills/browser-testing-with-devtools`) |
+| Manual terminal capture (Lighthouse, trace, screenshot) | Chrome DevTools MCP CLI (e.g. `chrome-devtools lighthouse_audit --output-format=json`) | `npx -p chrome-devtools-mcp chrome-devtools <tool>` or `npm i -g chrome-devtools-mcp` (CLI is independent of the harness) |
+
+If a source is unavailable, do not fabricate. Skip the related section of the scorecard and continue with what you have.
+
+## Metric-Honesty Rule
+
+**Never fabricate metrics.** An LLM reading static source code cannot measure real-world LCP, INP, or CLS. If no tool data is provided:
+
+- Return a source-level findings report.
+- Mark the entire scorecard as `not measured`.
+- Label every finding as `potential impact`, not as a measurement.
+
+When data IS provided, label each scorecard value with its source (`Field (CrUX)`, `Lab (Lighthouse)`, `Trace (DevTools)`). Field and lab data are not interchangeable: field is what real users experienced, lab is a single synthetic run. Treating them as the same number is a form of fabrication.
+
+Violating this rule is worse than returning no scorecard at all.
+
+## Review Scope
+
+Identify the framework and rendering model (React, Vue, Svelte, Angular, Next.js, Astro, vanilla HTML, etc.) before applying framework-specific checks. Do not recommend `<Image>` from `next/image` to a Vue app, or `React.memo` to a Svelte app.
+
+### 1. Core Web Vitals
+
+- Does the LCP element load within 2.5s? Is it a hero image, heading, or block of text?
+- Is the LCP image (if applicable) using `fetchpriority="high"` and not lazy-loaded?
+- Are layout shifts caused by images, embeds, ads, fonts, or dynamically injected content?
+- Do images, `<source>` elements, iframes, and embeds have explicit `width` and `height` to reserve space?
+- Are long tasks (> 50ms) blocking the main thread and delaying INP?
+- Are event handlers doing synchronous heavy work before yielding to the browser?
+- Is `scheduler.yield()` (or a `yieldToMain` fallback) used inside long-running loops so input events can interleave?
+- Is the page using **soft navigation** APIs correctly so INP and LCP are tracked across SPA route changes?
+- Is the **Long Animation Frames (LoAF)** API used (or planned) to attribute INP regressions in production?
+
+### 2. Loading
+
+- Is TTFB acceptable (< 800ms)? Are there slow server responses or missing CDN coverage?
+- Are critical origins `preconnect`-ed and known third-party origins `dns-prefetch`-ed?
+- Are LCP-critical resources preloaded with `fetchpriority="high"`?
+- Is the **Speculation Rules API** used to `prerender` or `prefetch` likely-next navigations?
+- Are fonts self-hosted, preloaded, and using `font-display: swap` (or `optional` for non-critical)?
+- Are fonts subsetted (`unicode-range`) and limited in count/weights?
+- Are images in modern formats (WebP, AVIF) with responsive `srcset` and `sizes`?
+- Is the initial JavaScript bundle under 200KB gzipped?
+- Is code splitting applied for routes and heavy features?
+- Are blocking scripts in `<head>` without `defer` or `async`?
+- Are third-party scripts loaded with `async`/`defer` and fronted by a facade when heavy (chat widgets, video embeds)?
+
+### 3. Rendering / JavaScript
+
+- Are there unnecessary full-page re-renders? Is state lifted (or colocated) correctly?
+- Are long lists virtualized?
+- Are animations using `transform` and `opacity` (compositor-only)?
+- Is there layout thrashing (reading layout properties, then writing, in a loop)?
+- Is `content-visibility: auto` used for off-screen sections?
+- Is the **View Transitions API** used appropriately to avoid perceived CLS on SPA navigations?
+- Is **bfcache** preserved? (No `unload` handlers, no `Cache-Control: no-store` on HTML)
+- **AI-generated patterns:**
+  - State duplication instead of lifting state.
+  - `React.memo` / `useMemo` / `useCallback` wrapping everything "just in case" (cost without benefit; can hurt perf).
+  - Over-eager `useEffect` dependencies causing redundant re-renders or update loops.
+  - **Vue:** watchers (`watch`/`watchEffect`) with broad dependencies that trigger unnecessary updates; `computed` with side effects.
+  - **Angular:** `ChangeDetectionStrategy.Default` where `OnPush` would suffice; subscriptions without `takeUntil`/`async pipe` that accumulate listeners.
+  - **Svelte:** `$:` blocks with expensive logic that re-runs more than needed.
+  - **Vanilla:** `scroll`/`resize` listeners without `passive: true` or debounce; DOM manipulation inside a loop that forces repeated reflow.
+
+### 4. Network
+
+- Are static assets cached with long `max-age` + content hashing?
+- Is HTTP/2 or HTTP/3 enabled?
+- Are there unnecessary redirects?
+- Are API responses paginated? Any `SELECT *` or unbounded fetch patterns?
+- Are bulk operations used instead of loops of individual API calls?
+- Is response compression enabled (gzip/brotli)?
+- **AI-generated patterns:**
+  - Over-fetching data "just in case."
+  - Sequential `await`s when `Promise.all` (or parallel `fetch`) would work.
+  - Redundant API calls where one would suffice; missing deduplication on parallel requests.
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Directly causes a Core Web Vital to fail the "Good" threshold | Fix before release |
+| **High** | Likely degrades a CWV or causes significant loading/interaction slowdown | Fix before release |
+| **Medium** | Suboptimal pattern with measurable but contained impact | Fix in current sprint |
+| **Low** | Best practice gap with minor or speculative impact | Schedule for next sprint |
+| **Info** | Improvement opportunity with no current evidence of impact | Consider adopting |
+
+## Output Format
+
+```markdown
+## Web Performance Audit
+
+### Scorecard
+
+| Metric | Value | Source | Target | Status |
+|--------|-------|--------|--------|--------|
+| LCP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 2.5s | [Good / Needs Work / Poor / —] |
+| INP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 200ms | [Good / Needs Work / Poor / —] |
+| CLS | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 0.1 | [Good / Needs Work / Poor / —] |
+| Lighthouse Performance | [score or "not measured"] | [Lab (Lighthouse) / —] | ≥ 90 | [Pass / Fail / —] |
+
+> Artifacts used: [list each: Lighthouse report `path/file.json`, CrUX API response, DevTools trace, live MCP capture, or **none — source analysis only**]
+> Framework / stack detected: [Next.js 14 App Router / React 18 + Vite / vanilla HTML / etc.]
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Area:** Core Web Vitals / Loading / Rendering / Network
+- **Location:** [file:line or component, or URL when from live capture]
+- **Description:** [What the issue is]
+- **Impact:** [potential impact / measured: e.g. "+1.2s LCP regression on mobile p75"]
+- **Recommendation:** [Specific fix with a small code example when applicable]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Performance practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Lead with the scorecard. If not measured, say so explicitly before listing findings.
+2. Always label scorecard values with their source. Never present lab values as field values or vice versa.
+3. Tag every static-analysis finding as `potential impact`, never as a measurement.
+4. Identify the framework / stack before recommending framework-specific patterns. Do not recommend idioms from a stack the project does not use.
+5. Every finding must include a specific, actionable recommendation.
+6. Do not recommend micro-optimizations without evidence they affect a Core Web Vital or another measurable metric.
+7. Acknowledge good performance practices — positive reinforcement matters.
+8. Use `references/performance-checklist.md` as the minimum baseline for each area.
+9. Delegate granular optimization guidance and remediation steps to `skills/performance-optimization/SKILL.md` — keep this report at the audit level.
+10. Fold AI-generated anti-patterns into their relevant area (Network or Rendering/JS); do not create a separate "AI" category.
+11. In Deep mode, always state which artifacts were provided and which fields remain unmeasured.
+
+## Composition
+
+- **Invoke directly when:** the user wants a performance-focused pass on a web application, a specific component, a route, or a live URL.
+- **Invoke via:** `/webperf` (dedicated performance audit command). Not included in `/ship` fan-out — performance audits apply to web applications only, not to utility libraries or CLI tools, so adding it to a global pre-launch fan-out would create noise in non-web projects.
+- **Do not invoke from another persona.** If `code-reviewer` flags a performance concern that warrants a deeper pass, surface that recommendation in the report; the user or a slash command initiates the deeper pass. See [docs/agents.md](../docs/agents.md).

package/bin/i3-composer-agent.cjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const root = path.resolve(__dirname, '..');
+const pkg = require('../package.json');
+const name = 'i3-composer-agent';
+const args = process.argv.slice(2);
+const help = `${pkg.name} v${pkg.version}
+
+Prepare the complete i3 Composer Agent plugin, including shared references.
+
+Usage:
+  npx ${pkg.name} --codebuddy [--dir <directory>]
+  npx ${pkg.name} --codex [--dir <directory>]
+  npx ${pkg.name} --claude [--dir <directory>]
+  npx ${pkg.name} --extract --dir <directory>
+
+Options:
+  --dir <directory>  Output directory (default: ./i3-composer-agent)
+  --dry-run         Show the planned bundle without writing files
+  --force           Replace an existing i3 bundle, preserving a backup
+  --version         Print the package version
+  --help            Show this help
+
+Host flags prepare the bundle and print native registration commands.
+Execute those commands in the intended host to enable the plugin.
+`;
+
+function quote(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
+function realDestination(target) {
+  let existing = target;
+  const suffix = [];
+  while (!fs.existsSync(existing)) {
+    suffix.unshift(path.basename(existing));
+    const parent = path.dirname(existing);
+    if (parent === existing) throw new Error(`Cannot resolve destination: ${target}`);
+    existing = parent;
+  }
+  return path.join(fs.realpathSync(existing), ...suffix);
+}
+function main() {
+  if (!args.length || args.includes('--help')) { console.log(help); return; }
+  if (args.length === 1 && args[0] === '--version') { console.log(pkg.version); return; }
+  let host;
+  let directory = path.join(process.cwd(), name);
+  let dryRun = false;
+  let force = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (['--codebuddy', '--codex', '--claude', '--extract'].includes(arg)) {
+      if (host) throw new Error('Choose exactly one host flag or --extract.');
+      host = arg.slice(2);
+    } else if (arg === '--dir') {
+      if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error('--dir requires a directory.');
+      directory = path.resolve(args[++i]);
+    } else if (arg === '--dry-run') dryRun = true;
+    else if (arg === '--force') force = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (!host) throw new Error('Choose --codebuddy, --codex, --claude, or --extract.');
+  directory = realDestination(directory);
+  const sourceRoot = fs.realpathSync(root);
+  if (directory === sourceRoot || directory.startsWith(sourceRoot + path.sep) || sourceRoot.startsWith(directory + path.sep)) {
+    throw new Error('The output directory must be outside this package directory.');
+  }
+  let exists = false;
+  try { fs.lstatSync(directory); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (exists) {
+    if (!force) throw new Error(`Output already exists: ${directory}. Choose a new directory or use --force for an i3 bundle.`);
+    const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'plugin.json'), 'utf8'));
+    if (manifest.name !== name) throw new Error('Refusing to replace a directory belonging to another plugin.');
+  }
+  if (dryRun) {
+    console.log(JSON.stringify({ name, version: pkg.version, directory, host, files: pkg.i3ComposerAgent.pluginFiles, replacesExisting: exists }, null, 2));
+    return;
+  }
+  fs.mkdirSync(path.dirname(directory), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(directory), `.${name}-`));
+  let backup;
+  try {
+    for (const relative of pkg.i3ComposerAgent.pluginFiles) {
+      const source = path.join(root, relative);
+      const destination = path.join(staging, relative);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.cpSync(source, destination, {
+        recursive: true,
+        filter: file => {
+          if (path.basename(file) === '.DS_Store') return false;
+          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`Bundle contains a symlink: ${file}`);
+          return !/(?:^|[\\/])(?:results|node_modules|\.git)(?:[\\/]|$)/.test(path.relative(root, file));
+        },
+      });
+    }
+    if (exists) {
+      backup = `${directory}.backup-${crypto.randomUUID()}`;
+      fs.renameSync(directory, backup);
+    }
+    try { fs.renameSync(staging, directory); }
+    catch (error) { if (backup) fs.renameSync(backup, directory); throw error; }
+  } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
+  console.log(`Prepared ${name} v${pkg.version} at ${directory}`);
+  if (backup) console.log(`Previous bundle preserved at ${backup}`);
+  if (host === 'extract') return;
+  console.log('\nRegister and enable the plugin with these native commands:');
+  const selector = `${name}@${name}`;
+  if (host === 'codex') {
+    console.log(`codex plugin marketplace add ${quote(directory)}`);
+    console.log(`codex plugin add ${selector}`);
+    console.log('Start a new Codex session and invoke the existing skill names. Lifecycle slash-command adaptation is separate.');
+  } else {
+    console.log(`/plugin marketplace add ${quote(directory)}`);
+    console.log(`/plugin install ${selector}`);
+    console.log(`Use /${name}:spec, /${name}:plan, /${name}:build, and /${name}:ship in ${host === 'claude' ? 'Claude Code' : 'CodeBuddy'}.`);
+  }
+}
+try { main(); } catch (error) { console.error(`${name}: ${error.message}`); process.exitCode = 1; }

package/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/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 AGENTS.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/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 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/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/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/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. The 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 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 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/` or your global configuration, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of the 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/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/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.
+"""

package/commands/webperf.toml

@@ -0,0 +1,32 @@
+description = "Run a web performance audit via the web-performance-auditor persona"
+
+prompt = """
+/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 environment variables — never hard-code these values in config files)
+- A DevTools performance trace
+- A live URL plus the chrome-devtools MCP server configured in the harness (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>`), passing the JSON output to the agent
+
+Quick mode — default when none of the above are available. Scan source code for structural anti-patterns and label every finding as `potential impact`.
+
+## Run the audit
+
+Spawn the `web-performance-auditor` subagent (the CLI exposes each custom subagent in `agents/` as a tool with the same name). 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 — mark unmeasured fields `not measured`, never fabricate metrics), 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.
+"""