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

package/.gemini/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)
+- 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
+
+Act as the web-performance-auditor persona (agents/web-performance-auditor.md) and follow it exactly. Work from:
+
+- 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
+- The mode you expect (Quick or Deep); surface missing inputs if Deep was intended
+
+Return 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.
+"""

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# i3 Composer Agent changes
+
+## 1.0.0 — Unreleased
+
+Upstream baseline: agent-skills 0.6.12 at commit 1401c8b8030e023baeebb31781a6653fe8e93026.
+
+### Changed
+
+- Start independent i3 release numbering. The upstream baseline remains 0.6.12; this replaces the unpublished 0.6.13 candidate.
+- Display the i3 release and upstream baseline together in the README, CLI help, and bundle preparation output. Keep --version machine-readable.
+- Include the upstream version, commit, and repository in package metadata.
+- Maintain source changes on agent/source, generate and validate a branded candidate, then update main in this independent repository.
+
+### Fixed
+
+- Preserve complete reviewed runtime assets when replaying branding, including newly approved upstream skills and commands.
+- Keep replay checks repeatable in npm bundles without repository CI files.
+- Preserve branded ignore rules and exclude Finder metadata from runtime preservation checks.
+
+## 0.6.12
+
+- Publish the first i3 Composer Agent npm distribution based on agent-skills 0.6.12.
+- Retain upstream skill IDs, command workflows, specialist personas, shared references, and MIT attribution.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Addy Osmani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,9 @@
+# Attribution
+
+i3 Composer Agent is a branded distribution of
+[Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani.
+The initial distribution is based on upstream commit `1401c8b` (version 0.6.12).
+
+The original MIT license and copyright notice are preserved in LICENSE.
+Givolt maintains the branding, npm distribution, and bundle preparation CLI.
+The original skill IDs, command workflows, and persona definitions are retained.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# i3 Composer Agent v1.0.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Based on agent-skills v0.6.12**
+
+**Intelligence. Integration. Innovation.**
+
+Engineering skills, lifecycle commands, and specialist personas for AI coding agents.
+Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani
+(MIT). See [NOTICE.md](NOTICE.md) for attribution.
+
+The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
+`i3-composer-agent`. Skill IDs retain their upstream names.
+
+## Prepare the complete plugin
+
+Run in the project where you want to prepare the plugin:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+# Other hosts:
+npx @givolt/i3-composer-agent --codex
+npx @givolt/i3-composer-agent --claude
+```
+
+The command prepares a persistent `./i3-composer-agent/` directory containing
+25 skills, 9 commands, 4 personas,
+and shared references. It prints native registration commands; run those in
+the selected host to enable the plugin. Preparing files does not select a host
+installation scope. See [CodeBuddy setup](docs/codebuddy-setup.md) and
+[Codex setup](docs/codex-setup.md).
+
+CodeBuddy / Claude Code:
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Codex:
+
+```bash
+codex plugin marketplace add ./i3-composer-agent
+codex plugin add i3-composer-agent@i3-composer-agent
+```
+
+Start a new session after enabling the plugin. Codex uses the existing Skill
+names, such as `$spec-driven-development`; lifecycle slash-command adaptation
+is maintained separately.
+
+## Commands
+
+Hosts supporting Claude-compatible plugin commands load these workflows:
+
+| Command | Description |
+| --- | --- |
+| /i3-composer-agent:build | Implement tasks incrementally — build, test, verify, commit. Add "auto" to run the whole plan in one approved pass. |
+| /i3-composer-agent:code-simplify | Simplify code for clarity and maintainability — reduce complexity without changing behavior |
+| /i3-composer-agent:constraints | Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md |
+| /i3-composer-agent:plan | Break work into small verifiable tasks with acceptance criteria and dependency ordering |
+| /i3-composer-agent:review | Conduct a five-axis code review — correctness, readability, architecture, security, performance |
+| /i3-composer-agent:ship | Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision |
+| /i3-composer-agent:spec | Start spec-driven development — write a structured specification before writing code |
+| /i3-composer-agent:test | Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. |
+| /i3-composer-agent:webperf | Run a web performance audit via the web-performance-auditor persona |
+
+`/i3-composer-agent:build auto` runs the existing approved-plan workflow.
+
+## Skills
+
+| Skill | Description |
+| --- | --- |
+| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend. |
+| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. |
+| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. |
+| [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch. Use when asked to review a diff or a pull request, even when the diff is pasted inline. |
+| [code-simplification](skills/code-simplification/SKILL.md) | Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. |
+| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when the user wants dimensions they care about — accessibility, web performance, coverage — set up as enforced constraints, when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read. |
+| [context-engineering](skills/context-engineering/SKILL.md) | Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project. |
+| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need to figure out what broke and why — a systematic approach to finding and fixing the root cause rather than guessing. |
+| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. |
+| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. |
+| [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when you want every assumption cross-examined before proceeding, when stress-testing a plan for hidden failure modes, when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production auth, security-sensitive logic, a high-stakes migration, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later. |
+| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Builds production-quality, accessible, responsive user-facing UIs. Use when building or modifying interfaces and pages, creating components, implementing layouts, meeting WCAG accessibility requirements, managing state, or when the output needs to look and feel production-quality rather than AI-generated. |
+| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, splitting uncommitted work in a messy working tree into clean atomic commits, opening or reviewing a pull request (PR), pushing to a remote, or when you need to organize work across multiple parallel streams. Use when cutting a release, choosing a semantic version bump, tagging, or writing a changelog. |
+| [idea-refine](skills/idea-refine/SKILL.md) | Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan". |
+| [incremental-implementation](skills/incremental-implementation/SKILL.md) | Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step. |
+| [interview-me](skills/interview-me/SKILL.md) | Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists. |
+| [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data. |
+| [performance-optimization](skills/performance-optimization/SKILL.md) | Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. |
+| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. |
+| [security-and-hardening](skills/security-and-hardening/SKILL.md) | Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a new package. Use when personal data or privacy compliance (GDPR, CCPA) is involved. |
+| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Prepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. |
+| [source-driven-development](skills/source-driven-development/SKILL.md) | Grounds every implementation decision in official documentation. Use when you want to verify an approach against the official docs before implementing it, or when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters. |
+| [spec-driven-development](skills/spec-driven-development/SKILL.md) | Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. |
+| [test-driven-development](skills/test-driven-development/SKILL.md) | Drives development with tests using the red-green-refactor loop. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. |
+| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked. |
+
+## Bundle options
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir /path/to/plugin
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
+```
+
+Replacement preserves the previous i3 bundle as a backup. Repository-scoped
+AGENTS.md and CLAUDE.md are not copied into business projects.
+
+## Maintaining this fork
+
+This repository is independent of the GSD-based i3 Composer Work repository.
+`agent/source` retains upstream source and the `rebrand/` rules; `main` contains
+the validated branded distribution. Create release candidates from the source
+branch, replay branding, validate, then update the release branch.
+
+See [maintenance](rebrand/MAINTENANCE.md), [source PR workflow](rebrand/PR-WORKFLOW.md),
+[versioning](rebrand/VERSIONING.md), [changelog](CHANGELOG.md),
+and [validation contract](rebrand/VALIDATION.md).

package/agents/code-reviewer.md

@@ -0,0 +1,102 @@
+---
+name: code-reviewer
+description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
+---
+
+# Senior Code Reviewer
+
+You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.
+
+## Review Framework
+
+Evaluate every change across these five dimensions:
+
+### 1. Correctness
+- Does the code do what the spec/task says it should?
+- Are edge cases handled (null, empty, boundary values, error paths)?
+- Do the tests actually verify the behavior? Are they testing the right things?
+- Are there race conditions, off-by-one errors, or state inconsistencies?
+
+### 2. Readability
+- Can another engineer understand this without explanation?
+- Are names descriptive and consistent with project conventions?
+- Is the control flow straightforward (no deeply nested logic)?
+- Is the code well-organized (related code grouped, clear boundaries)?
+
+### 3. Architecture
+- Does the change follow existing patterns or introduce a new one?
+- If a new pattern, is it justified and documented?
+- Are module boundaries maintained? Any circular dependencies?
+- Is the abstraction level appropriate (not over-engineered, not too coupled)?
+- Are dependencies flowing in the right direction?
+
+### 4. Security
+- Is user input validated and sanitized at system boundaries?
+- Are secrets kept out of code, logs, and version control?
+- Is authentication/authorization checked where needed?
+- Are queries parameterized? Is output encoded?
+- Any new dependencies with known vulnerabilities?
+
+### 5. Performance
+- Any N+1 query patterns?
+- Any unbounded loops or unconstrained data fetching?
+- Any synchronous operations that should be async?
+- Any unnecessary re-renders (in UI components)?
+- Any missing pagination on list endpoints?
+
+## Output Format
+
+Categorize every finding, using the same severity labels as the `code-review-and-quality` skill:
+
+**Critical** — Blocks merge (security vulnerability, data loss risk, broken functionality)
+
+**Required** — Must address before merge (missing test, wrong abstraction, poor error handling)
+
+**Optional** — Worth considering but not required (a simpler design, a useful refactor)
+
+**Nit** — Minor and optional; the author may ignore (formatting, naming, style preferences)
+
+## Review Output Template
+
+```markdown
+## Review Summary
+
+**Verdict:** APPROVE | REQUEST CHANGES
+
+**Overview:** [1-2 sentences summarizing the change and overall assessment]
+
+### Critical Issues
+- [File:line] [Description and recommended fix]
+
+### Required Changes
+- [File:line] [Description and recommended fix]
+
+### Optional
+- [File:line] [Description]
+
+### Nits
+- [File:line] [Description]
+
+### What's Done Well
+- [Positive observation — always include at least one]
+
+### Verification Story
+- Tests reviewed: [yes/no, observations]
+- Build verified: [yes/no]
+- Security checked: [yes/no, observations]
+```
+
+## Rules
+
+1. Review the tests first — they reveal intent and coverage
+2. Read the spec or task description before reviewing code
+3. Every Critical and Required finding should include a specific fix recommendation
+4. Don't approve code with Critical issues
+5. Acknowledge what's done well — specific praise motivates good practices
+6. If you're uncertain about something, say so and suggest investigation rather than guessing
+
+## Composition
+
+- **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
+- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
+- **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [docs/agents.md](../docs/agents.md).

package/agents/security-auditor.md

@@ -0,0 +1,112 @@
+---
+name: security-auditor
+description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+---
+
+# Security Auditor
+
+You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
+
+## Review Scope
+
+### 1. Input Handling
+- Is all user input validated at system boundaries?
+- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
+- Is HTML output encoded to prevent XSS?
+- Are file uploads restricted by type, size, and content?
+- Are URL redirects validated against an allowlist?
+
+### 2. Authentication & Authorization
+- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
+- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
+- Is authorization checked on every protected endpoint?
+- Can users access resources belonging to other users (IDOR)?
+- Are password reset tokens time-limited and single-use?
+- Is rate limiting applied to authentication endpoints?
+
+### 3. Data Protection
+- Are secrets in environment variables (not code)?
+- Are sensitive fields excluded from API responses and logs?
+- Is data encrypted in transit (HTTPS) and at rest (if required)?
+- Is PII handled according to applicable regulations?
+- Are database backups encrypted?
+
+### 4. Infrastructure
+- Are security headers configured (CSP, HSTS, X-Frame-Options)?
+- Is CORS restricted to specific origins?
+- Are dependencies audited for known vulnerabilities?
+- Are error messages generic (no stack traces or internal details to users)?
+- Is the principle of least privilege applied to service accounts?
+
+### 5. Third-Party Integrations
+- Are API keys and tokens stored securely?
+- Are webhook payloads verified (signature validation)?
+- Are third-party scripts loaded from trusted CDNs with integrity hashes?
+- Are OAuth flows using PKCE and state parameters?
+- Are server-side fetches of user-supplied URLs allowlisted (SSRF)?
+
+### 6. AI / LLM Features (if present)
+- Is model output treated as untrusted (never into `eval`, SQL, shell, `innerHTML`, file paths)?
+- Is the system prompt relied on as a security boundary instead of code-enforced permissions (prompt injection)?
+- Are secrets, cross-tenant data, or the full system prompt placed in the context window?
+- Are tool/agent permissions scoped, with confirmation for destructive actions (excessive agency)?
+- Are token, rate, and recursion limits set (unbounded consumption)?
+
+Map findings to the OWASP Top 10 for LLM Applications where relevant.
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
+| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
+| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
+| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
+| **Info** | Best practice recommendation, no current risk | Consider adopting |
+
+## Output Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Location:** [file:line]
+- **Description:** [What the vulnerability is]
+- **Impact:** [What an attacker could do]
+- **Proof of concept:** [How to exploit it]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Security practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Focus on exploitable vulnerabilities, not theoretical risks
+2. Every finding must include a specific, actionable recommendation
+3. Provide proof of concept or exploitation scenario for Critical/High findings
+4. Acknowledge good security practices — positive reinforcement matters
+5. Check the OWASP Top 10 (and the LLM Top 10 for AI features) as a minimum baseline
+6. Review dependencies for known CVEs and supply-chain risk (typosquats, postinstall scripts)
+7. Never suggest disabling security controls as a "fix"
+8. Start from trust boundaries — where untrusted data enters — and reason about each with STRIDE before enumerating findings
+
+## Composition
+
+- **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component.
+- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
+- **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [docs/agents.md](../docs/agents.md).

package/agents/test-engineer.md

@@ -0,0 +1,95 @@
+---
+name: test-engineer
+description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
+---
+
+# Test Engineer
+
+You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.
+
+## Approach
+
+### 1. Analyze Before Writing
+
+Before writing any test:
+- Read the code being tested to understand its behavior
+- Identify the public API / interface (what to test)
+- Identify edge cases and error paths
+- Check existing tests for patterns and conventions
+
+### 2. Test at the Right Level
+
+```
+Pure logic, no I/O          → Unit test
+Crosses a boundary          → Integration test
+Critical user flow          → E2E test
+```
+
+Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
+
+### 3. Follow the Prove-It Pattern for Bugs
+
+When asked to write a test for a bug:
+1. Write a test that demonstrates the bug (must FAIL with current code)
+2. Confirm the test fails
+3. Report the test is ready for the fix implementation
+
+### 4. Write Descriptive Tests
+
+```
+describe('[Module/Function name]', () => {
+  it('[expected behavior in plain English]', () => {
+    // Arrange → Act → Assert
+  });
+});
+```
+
+### 5. Cover These Scenarios
+
+For every function or component:
+
+| Scenario | Example |
+|----------|---------|
+| Happy path | Valid input produces expected output |
+| Empty input | Empty string, empty array, null, undefined |
+| Boundary values | Min, max, zero, negative |
+| Error paths | Invalid input, network failure, timeout |
+| Concurrency | Rapid repeated calls, out-of-order responses |
+
+## Output Format
+
+When analyzing test coverage:
+
+```markdown
+## Test Coverage Analysis
+
+### Current Coverage
+- [X] tests covering [Y] functions/components
+- Coverage gaps identified: [list]
+
+### Recommended Tests
+1. **[Test name]** — [What it verifies, why it matters]
+2. **[Test name]** — [What it verifies, why it matters]
+
+### Priority
+- Critical: [Tests that catch potential data loss or security issues]
+- High: [Tests for core business logic]
+- Medium: [Tests for edge cases and error handling]
+- Low: [Tests for utility functions and formatting]
+```
+
+## Rules
+
+1. Test behavior, not implementation details
+2. Each test should verify one concept
+3. Tests should be independent — no shared mutable state between tests
+4. Avoid snapshot tests unless reviewing every change to the snapshot
+5. Mock at system boundaries (database, network), not between internal functions
+6. Every test name should read like a specification
+7. A test that never fails is as useless as a test that always fails
+
+## Composition
+
+- **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug.
+- **Invoke via:** `/test` (TDD workflow) or `/ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
+- **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [docs/agents.md](../docs/agents.md).