qa-ai-repo 0.1.0 → 0.2.0

package/README.md

@@ -65,5 +65,20 @@ npm link                            # then `qa-ai list` works anywhere
 
 ## Publishing
 
-Bump `version` in `package.json`, then `npm publish`. Objective folders ship
-automatically (see `.npmignore`); no need to enumerate them.
+Objective folders ship automatically (see `.npmignore`); no need to enumerate
+them.
+
+**Automated (recommended).** A GitHub Actions workflow
+(`.github/workflows/release.yml`) publishes to npm whenever you cut a Release:
+
+1. Add a repo secret `NPM_TOKEN` (an npm *Automation* access token):
+   Settings → Secrets and variables → Actions → New repository secret.
+2. Bump `version` in `package.json` and commit.
+3. Create a GitHub Release (tag e.g. `v0.1.0`). The workflow smoke-tests the
+   CLI and publishes; it skips automatically if that version is already on npm.
+
+The workflow publishes with npm **provenance** (verified build attestation),
+enabled by `--provenance` + the `id-token: write` permission. This requires a
+public repo.
+
+**Manual.** `npm login` then `npm publish` from the repo root.

package/api-contract-testing/agents/api-contract-author.md

@@ -0,0 +1,38 @@
+---
+name: api-contract-author
+description: Use to add or extend API contract tests for a service. It detects the stack and interface (OpenAPI/GraphQL/Pact), recommends consumer-driven vs spec-first, scaffolds the tests, and wires can-i-deploy / breaking-change gates into CI.
+tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+You are a senior API quality engineer specializing in contract testing.
+
+## Process
+
+1. **Discover the interface.** Look for an OpenAPI/AsyncAPI spec, GraphQL schema,
+   route definitions, existing HTTP clients, and any current Pact/contract
+   setup. Identify providers and their consumers.
+2. **Recommend an approach** (state your reasoning briefly):
+   - Internal, you own the consumers → **consumer-driven (Pact)**.
+   - Public/many consumers with a spec → **spec-first (OpenAPI + Schemathesis +
+     oasdiff)**.
+   - Both → do both.
+3. **Scaffold the tests** in the project's language/framework:
+   - Consumer tests generating pacts with type/shape matchers (not exact values).
+   - Provider verification with provider states for setup.
+   - Or spec conformance (Schemathesis/Dredd) + a spec lint (Spectral).
+4. **Add the gates.** Wire `can-i-deploy` (Pact) or a breaking-change diff
+   (`oasdiff` / GraphQL Inspector) into CI so incompatible changes block deploy —
+   not just report.
+5. **Run what you can** locally and iterate until green; note anything that needs
+   a broker/credentials the environment lacks.
+
+## Principles
+
+- Contract ≠ end-to-end: verify interface shape and semantics, keep it small.
+- Match on types/shape; version anything backward-incompatible.
+- Every contract is tied to a service version + git sha.
+
+## Report
+
+The files added/changed, approach chosen and why, the CI gates wired in, and any
+follow-ups requiring a Pact Broker / PactFlow or spec that doesn't exist yet.

package/api-contract-testing/objective.json

@@ -0,0 +1,4 @@
+{
+  "title": "API Contract Testing",
+  "description": "Catch breaking API changes before they ship — consumer-driven contracts (Pact) and spec-first validation (OpenAPI/Schemathesis/Dredd), with provider verification and can-i-deploy gates wired into CI."
+}

package/api-contract-testing/skills/api-contract-testing/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: api-contract-testing
+description: Design and implement API contract tests so a provider can't break its consumers. Use when adding contract tests, choosing between consumer-driven (Pact) and spec-first (OpenAPI) approaches, verifying providers, or gating deploys on compatibility. Covers REST, GraphQL, and event/message contracts.
+---
+
+# API Contract Testing
+
+Contract testing verifies that two services **agree on the interface** without
+standing up both in a slow, flaky end-to-end environment. It catches breaking
+changes at the boundary — the highest-value, lowest-cost API tests.
+
+## Pick the approach (see `tooling.md` for tool choices)
+
+- **Consumer-driven contracts (Pact)** — when *you own the consumers* and want
+  each consumer to declare exactly what it needs. Consumers generate a contract;
+  the provider verifies against all of them. Best for internal microservices.
+- **Spec-first / provider contracts (OpenAPI, JSON Schema, AsyncAPI)** — when a
+  spec is the source of truth (public API, many/unknown consumers). Validate
+  that real traffic conforms to the spec in both directions.
+- Use **both** when you publish a spec *and* have known internal consumers.
+
+## Consumer-driven (Pact) workflow
+
+1. **Consumer test**: write an interaction (request → expected response) against
+   a Pact mock; run the consumer's real client code against it. This generates a
+   pact file — assert on *shape/types*, not exact values (use matchers).
+2. **Publish** the pact (with consumer version + git sha + branch/tag) to a
+   Pact Broker / PactFlow.
+3. **Provider verification**: the provider replays every consumer interaction
+   against its real implementation, using provider states to set up data.
+4. **`can-i-deploy`**: before releasing either side, query the broker to confirm
+   the version is compatible with everything it will meet in the target env.
+   Block the deploy if not.
+
+## Spec-first workflow
+
+1. Treat the **OpenAPI/AsyncAPI** spec as the contract; lint it (Spectral) in CI.
+2. **Provider side**: assert responses conform to the spec — property-based
+   fuzzing (Schemathesis) or replaying the spec's examples (Dredd).
+3. **Consumer side**: run against a spec-driven **mock** (Prism) so consumers
+   develop against the contract, not a live service.
+4. **Detect breaking changes**: diff the spec against the last released version
+   (e.g. `oasdiff`) and fail CI on backward-incompatible changes.
+
+## Principles
+
+- **Contract ≠ end-to-end.** Verify the interface shape and semantics, not full
+  business flows. Keep each interaction small and deterministic.
+- **Match on type/shape, not brittle exact values** (except enums/status codes
+  that are genuinely part of the contract).
+- **Version everything** — pacts and specs are tied to a service version + sha
+  so `can-i-deploy` can reason about environments.
+- **Backward compatibility is the rule**: additive changes are safe; removing a
+  field, tightening a type, or changing status codes is breaking — version it.
+- **Provider states** replace shared fixtures — each interaction declares the
+  state it needs; keep them cheap and isolated.
+- **Gate deploys**, don't just report. A contract test that doesn't block a bad
+  release is documentation, not a test.
+
+## CI wiring
+
+- Consumer PR → run consumer tests → publish pact (tagged with branch).
+- Provider PR → verify against `main`-tagged pacts → publish results.
+- Pre-deploy → `can-i-deploy --to <env>` (or spec breaking-change diff) as a gate.
+- Nightly → verify all consumers against provider `main` to catch drift early.
+
+See `tooling.md` for language-specific tools and when to use each.

package/api-contract-testing/skills/api-contract-testing/tooling.md

@@ -0,0 +1,37 @@
+# API Contract Testing — Tooling Guide
+
+Choose by *who owns the consumers* and *what the source of truth is*.
+
+## Consumer-driven contracts
+- **Pact** — the standard for consumer-driven contracts. SDKs for JS/TS, Java,
+  .NET, Go, Python, Ruby, PHP, Rust. Use with a **Pact Broker** or **PactFlow**
+  for storing contracts, `can-i-deploy`, and webhooks.
+- Use when: internal microservices, you control the consumers, HTTP or messages.
+
+## Spec-first (OpenAPI / REST)
+- **Spectral** — lint the OpenAPI spec (style + governance) in CI.
+- **Schemathesis** — property-based fuzzing that checks responses conform to the
+  OpenAPI schema; great at finding edge-case violations.
+- **Dredd** — validate an API against its OpenAPI/API Blueprint examples.
+- **Prism** — spin up a mock server from the spec so consumers develop against
+  the contract; also does request/response validation as a proxy.
+- **oasdiff** — diff two OpenAPI specs and fail CI on breaking changes.
+
+## GraphQL
+- **GraphQL Inspector** / **graphql-schema-linter** — schema diffing and
+  breaking-change detection against the previous schema.
+- Apollo **Rover** + schema checks if using a registry/federation.
+
+## Async / event-driven
+- **AsyncAPI** as the contract for Kafka/AMQP/WebSocket messages.
+- **Pact** message pacts for consumer-driven event contracts.
+
+## General HTTP assertions (lighter weight)
+- **Postman/Newman**, **Karate**, **REST Assured** (Java), **Tavern** (Python)
+  for schema assertions when full contract tooling is overkill.
+
+## Rule of thumb
+- Internal services, you own both sides → **Pact + Broker**.
+- Public/partner API with a published spec → **OpenAPI + Spectral + Schemathesis
+  + oasdiff**.
+- Both → publish the spec *and* run Pact for known internal consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qa-ai-repo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install reusable QA skills, agents, and MCP servers into Claude Code, Cursor, Windsurf, and other AI coding tools with one command.",
   "type": "module",
   "bin": {

package/qa-strategy/agents/qa-strategist.md

@@ -0,0 +1,34 @@
+---
+name: qa-strategist
+description: Use to create a tailored QA strategy for a team or project. It runs a structured intake (tech stack, team size, release cadence, current maturity, risk/compliance), then produces a risk-based strategy with an automation plan, quality gates, tooling, and a phased roadmap.
+tools: Read, Grep, Glob, Write
+---
+
+You are a pragmatic QA strategy consultant. Your job is to produce a QA strategy
+that fits the team's reality — right-sized to their risk, stack, and capacity.
+
+## Process
+
+1. **Inspect first.** If pointed at a codebase, detect languages, frameworks,
+   test directories, CI config, and coverage. Use findings to pre-fill the
+   intake and confirm rather than ask.
+2. **Run the intake interview.** Work through the six sections (Product, Tech
+   stack, Team & process, Current state, Non-functional & risk, Goals &
+   constraints). Ask one section at a time, in plain questions. Never dump all
+   questions at once. If the user answers tersely, proceed — don't interrogate.
+3. **Don't invent facts.** Mark unknowns as `TBD` and state the assumption you'll
+   proceed with so the user can correct it.
+4. **Write the strategy** to `QA-STRATEGY.md` using the standard section
+   structure. Every recommendation must trace to an input.
+5. **Be decisive and specific.** Recommend concrete tools, gates, and first
+   steps — not "consider adding tests." Prioritize by risk (likelihood ×
+   impact). Favor a healthy test pyramid and fast CI feedback.
+
+## Output
+
+A `QA-STRATEGY.md` covering: context snapshot, goals & metrics, risk-based
+prioritization, test levels & types, automation strategy, CI/CD quality gates,
+roles & ownership, tooling, and a phased Now/Next/Later roadmap with owners and
+success metrics. End with open questions and assumptions to validate.
+
+Keep it concise enough that the team will actually read and act on it.

package/qa-strategy/objective.json

@@ -0,0 +1,4 @@
+{
+  "title": "QA Strategy",
+  "description": "Interview a team about its product, tech stack, size, and release cadence, then generate a tailored, risk-based QA strategy with an automation plan, quality gates, tooling, and a phased rollout."
+}

package/qa-strategy/skills/qa-strategy/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: qa-strategy
+description: Produce a tailored, risk-based QA strategy for a team or project. Use when asked to "create a QA strategy", "assess our testing approach", "build a test plan/roadmap", or decide what and how much to automate. First gathers a defined set of inputs (tech stack, team size, release cadence, current maturity, risk/compliance), then writes the strategy.
+---
+
+# QA Strategy
+
+Generate a QA strategy that fits *this* team — not a generic checklist. The
+strategy is only as good as its inputs, so **always gather the intake first**,
+then produce the strategy against a consistent template.
+
+## How to run
+
+1. **Collect the intake.** Ask the questions in `intake.md`. Ask them in
+   batches (grouped by section), not all at once. If the user has already
+   supplied some answers (in the prompt, a repo, a doc), pre-fill those and only
+   ask what's missing or ambiguous. Do not invent answers — if something is
+   unknown, mark it `TBD` and note the assumption you'll proceed with.
+2. **Infer what you can from the codebase** when available: languages,
+   frameworks, existing test dirs, CI config, coverage — confirm rather than ask.
+3. **Write the strategy** using `strategy-template.md`. Every recommendation
+   must trace back to an input (e.g. "daily deploys → block merges on a fast
+   smoke suite"). Tailor depth to team size and maturity.
+4. **Prioritize by risk.** Rank areas by likelihood × impact; put automation
+   and coverage where failures hurt most, not uniformly.
+5. **Make it actionable.** End with a phased roadmap (Now / Next / Later) with
+   concrete first steps, owners, and success metrics — not aspirations.
+
+## Principles
+
+- **Right-size it.** A 3-person startup shipping daily and a 50-person org with
+  compliance needs get very different strategies. Match rigor to risk and team
+  capacity.
+- **Test pyramid, not ice-cream cone.** Favor many fast unit/integration tests,
+  fewer E2E; call out where the current shape is inverted.
+- **Automate the repetitive and high-risk; keep humans for exploratory.**
+- **Quality gates over quality theater.** Tie recommendations to CI gates and
+  measurable signals (escape rate, flake rate, lead time), not vanity coverage %.
+- **Start where they are.** Recommend the next 2–3 improvements, not a rewrite.
+
+## Inputs and outputs
+
+- `intake.md` — the question set to collect before writing anything.
+- `strategy-template.md` — the structure of the delivered strategy document.

package/qa-strategy/skills/qa-strategy/intake.md

@@ -0,0 +1,43 @@
+# QA Strategy — Intake Questionnaire
+
+Collect these before writing the strategy. Ask by section, pre-fill anything
+already known, and mark unknowns `TBD` with a stated assumption. Bold items are
+the minimum needed to produce a useful first draft.
+
+## 1. Product & scope
+- **What is the product?** (web app, mobile app, API/backend service, desktop, CLI, embedded, data/ML pipeline)
+- **What platforms must you support?** (browsers, iOS/Android versions, OS)
+- Who are the users and what's the scale? (internal tool vs. public; approx. traffic/DAU)
+- What are the most critical user journeys / revenue-bearing flows?
+
+## 2. Tech stack
+- **Languages & frameworks** (frontend, backend, mobile)
+- Data stores, queues, and major third-party integrations
+- **Existing test frameworks/tools** (e.g. Jest, Pytest, Playwright, Cypress, Selenium, JUnit, k6)
+- Repo layout: monorepo vs. polyrepo; number of services
+
+## 3. Team & process
+- **Team size and roles** (# engineers, # dedicated QA/SDET, PM, designers)
+- Who owns quality today? (devs test their own work? separate QA? none?)
+- **Release cadence & deployment** (per-commit / daily / weekly / monthly; CI/CD maturity)
+- Branching & review model (trunk-based, PR reviews, feature branches)
+- Ways of working (Scrum/Kanban, sprint length)
+
+## 4. Current quality state
+- **What testing exists today?** (unit / integration / E2E / manual / none) and rough coverage
+- How is testing run — locally, in CI, both? Which CI system?
+- Known pain points (flaky tests, slow suites, prod escapes, long release cycles)
+- Bug/defect tracking tool and current escape/severity trends if known
+
+## 5. Non-functional & risk requirements
+- **Compliance/regulatory needs** (HIPAA, PCI-DSS, SOC 2, GDPR, accessibility/WCAG, none)
+- Performance/load expectations and SLAs/SLOs
+- Security testing needs (SAST/DAST, pentest cadence)
+- Accessibility, i18n/l10n, offline, or device-specific requirements
+- Areas where a failure would be most damaging (safety, money, data loss, reputation)
+
+## 6. Goals & constraints
+- **Primary goal for the next quarter** (ship faster, reduce escapes, cut flake, hit coverage/compliance)
+- Success metrics you care about (escape rate, MTTR, lead time, coverage, flake rate)
+- Constraints: budget for tooling/headcount, timeline, hard deadlines
+- Appetite for change (incremental improvements vs. willing to invest in a bigger shift)

package/qa-strategy/skills/qa-strategy/strategy-template.md

@@ -0,0 +1,66 @@
+# QA Strategy — <Product / Team Name>
+
+> Generated <date> · Owner: <name> · Status: Draft
+
+## 0. Context snapshot
+One paragraph summarizing the intake: product, stack, team size, cadence, and
+current quality state. List key assumptions and any `TBD` inputs.
+
+## 1. Quality goals & metrics
+- Primary goal(s) this quarter (tie to the team's stated goal).
+- Target metrics with current → target, e.g.:
+  | Metric | Now | Target |
+  |--------|-----|--------|
+  | Prod escape rate | ? | ↓ |
+  | E2E flake rate | ? | < 1% |
+  | CI feedback time | ? | < 10 min |
+  | Critical-path coverage | ? | 100% |
+
+## 2. Risk-based test prioritization
+Rank features/flows by **likelihood × impact**. Concentrate effort on the top
+tier. A short table: area → risk → what coverage it warrants.
+
+## 3. Test scope & levels
+Recommended mix across the pyramid, justified by stack and team size:
+- **Unit** — where, framework, target.
+- **Integration / contract** — service boundaries, APIs, DB.
+- **End-to-end** — only critical journeys; keep the count small.
+- **Manual / exploratory** — what stays human (usability, edge exploration).
+Call out if the current shape is inverted and how to rebalance.
+
+## 4. Test types beyond functional
+Only those the intake justifies:
+- Performance/load · Security (SAST/DAST/pentest) · Accessibility (WCAG)
+- Compatibility (browsers/devices) · i18n/l10n · Resilience/chaos
+- Compliance-driven testing (HIPAA/PCI/SOC 2) with required evidence.
+
+## 5. Automation strategy
+- What to automate first (high-risk + high-repetition) and what not to.
+- Recommended frameworks/tools (respect existing stack; justify changes).
+- Test data & environment management approach.
+- Standards: naming, structure, stable locators, no fixed sleeps, isolation.
+
+## 6. CI/CD integration & quality gates
+- Which suites run at which stage (pre-commit / PR / merge / nightly / release).
+- **Merge gates**: what must pass to merge (fast smoke + unit/integration).
+- Handling flake (quarantine, retry policy) and keeping the suite fast.
+- Release checklist and rollback signals.
+
+## 7. Roles & ownership
+- Who writes, reviews, and maintains tests (dev-owned vs. QA/SDET).
+- Bug triage flow, severity definitions, and SLAs.
+- Definition of Done for a story to include quality criteria.
+
+## 8. Tooling recommendations
+Concrete tools for: test frameworks, CI, reporting/dashboards, coverage,
+performance, security, accessibility, bug tracking. Note cost/effort and
+whether each is adopt-now or later.
+
+## 9. Rollout roadmap
+Phased, with owners and success criteria — not a wish list.
+- **Now (0–4 weeks):** 2–3 concrete first steps.
+- **Next (1–2 months):** build-out.
+- **Later (quarter+):** maturity, harder NFRs, scale.
+
+## 10. Risks & open questions
+Assumptions to validate, `TBD` inputs to resolve, and dependencies/blockers.