qa-workflow-cc 1.0.0

package/skills/qa/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: qa
+description: QA bootstrap — discovers tech stack, generates agents and test resources for any project. Use /qa:full, /qa:init, /qa:continue, /qa:resume, /qa:status for QA operations.
+user-invocable: false
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash, Task, WebSearch, WebFetch"
+model: inherit
+---
+
+# QA Bootstrap Protocol
+
+This skill contains the Phase 0 bootstrap logic for QA. It is invoked by `/qa:init` (bootstrap only) and `/qa:full` (bootstrap + execute).
+
+**This skill is self-bootstrapping.** It works in ANY project directory. On first run it discovers the tech stack, generates all QA infrastructure (agents, skill files, test matrix), and writes `qa-profile.json`.
+
+## Commands (colon sub-commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/qa:full` | Full QA cycle — test, report, fix plan, verify |
+| `/qa:init` | Bootstrap only (this skill) |
+| `/qa:continue` | Execute approved fix plan |
+| `/qa:resume` | Resume from any interrupted state |
+| `/qa:status` | View current QA progress |
+
+## Reference Documents (loaded on-demand by commands)
+
+| File | Content |
+|------|---------|
+| `references/lifecycle.md` | Phase definitions, state machine, edge cases, rules |
+| `references/continuation-format.md` | QA stop-point formatting guide |
+| `references/exit-criteria.md` | Exit criteria + severity definitions |
+| `references/model-profiles.md` | QA agent model allocation table |
+
+---
+
+> Full lifecycle diagram, phase semantics, edge cases, and rules: see `references/lifecycle.md`
+> Exit criteria and severity definitions: see `references/exit-criteria.md`
+> Stop-point formatting templates: see `references/continuation-format.md`
+> Model allocation per agent role: see `references/model-profiles.md`
+
+---
+
+## Phase 0: Bootstrap Protocol
+
+**Triggers when:**
+- `.claude/qa-profile.json` does NOT exist, OR
+- Profile is stale (>30 days old), OR
+- User invoked `/qa init` or `/qa rebootstrap`
+
+**Skip when:**
+- `.claude/qa-profile.json` exists AND is fresh AND user did NOT request init/rebootstrap
+
+If profile exists but is stale (>30 days), prompt the user: "QA profile is N days old. Re-scan? [yes/no]"
+
+### B1: Root Discovery (sequential, main context)
+
+Read these files to establish project basics:
+
+```
+package.json          → name, packageManager, scripts, dependencies, devDependencies
+pnpm-workspace.yaml   → monorepo detection (pnpm)
+turbo.json            → monorepo detection (turborepo)
+lerna.json            → monorepo detection (lerna)
+nx.json               → monorepo detection (nx)
+tsconfig.json         → TypeScript configuration
+CLAUDE.md             → architecture description, agent routing
+README.md             → project description
+```
+
+From `package.json`, apply framework detection heuristics:
+
+```
+IF deps includes "next"                         → framework = "nextjs"
+IF deps includes "expo"                         → framework = "expo"
+IF deps includes "fastify"                      → framework = "fastify"
+IF deps includes "express"                      → framework = "express"
+IF deps includes "remix" or "@remix-run/*"      → framework = "remix"
+IF deps includes "astro"                        → framework = "astro"
+IF deps includes "nuxt"                         → framework = "nuxt"
+IF deps includes "@trpc/server"                 → apiStyle = "trpc"
+IF deps includes "prisma" or "@prisma/client"   → orm = "prisma"
+IF deps includes "drizzle-orm"                  → orm = "drizzle"
+IF deps includes "mongoose"                     → orm = "mongoose"
+IF deps includes "@clerk/nextjs" or "clerk-expo"→ auth = "clerk"
+IF deps includes "next-auth"                    → auth = "next-auth"
+IF deps includes "passport"                     → auth = "passport"
+IF deps includes "@supabase/auth-helpers-*"     → auth = "supabase"
+IF deps includes "vitest"                       → testRunner = "vitest"
+IF deps includes "jest"                         → testRunner = "jest"
+IF deps includes "@playwright/test"             → e2e = "playwright"
+IF deps includes "cypress"                      → e2e = "cypress"
+IF deps includes "@testing-library/react"       → componentLib = "@testing-library/react"
+IF deps includes "@testing-library/react-native"→ componentLib = "@testing-library/react-native"
+```
+
+### B1b: Domain Detection
+
+After root discovery, infer the project's domain from README.md, CLAUDE.md, and any PRD file (`.planning/REQUIREMENTS.md`, `.planning/PRD.md`, or similar):
+
+| Keywords Found | Domain Label |
+|---------------|-------------|
+| "crisis", "safety", "DV", "domestic violence", "addiction", "survivor" | `safety-critical` |
+| "health", "medical", "patient", "HIPAA", "PHI", "clinical" | `healthcare` |
+| "e-commerce", "checkout", "cart", "payment", "PCI", "stripe" | `e-commerce` |
+| "SaaS", "tenant", "organization", "workspace", "multi-tenant" | `multi-tenant-saas` |
+| "education", "student", "course", "LMS", "FERPA" | `education` |
+| "fintech", "banking", "transaction", "KYC", "AML" | `fintech` |
+
+If no keywords match → `domain = "general"`
+
+Also extract from these files:
+- **Target audience description** — who uses this app (e.g., "Women seeking addiction resources")
+- **Domain-specific compliance requirements** — any regulations mentioned (HIPAA, PCI, FERPA, etc.)
+
+Set in profile:
+```
+profile.project.domain         = "safety-critical" (or detected value)
+profile.project.domainKeywords = ["crisis", "addiction"]  (matched keywords)
+profile.project.targetAudience = "Women seeking addiction resources"
+```
+
+### B2: Parallel Research (spawn up to 8 Task agents)
+
+Launch these research agents in parallel:
+
+| Agent | Job | Input | Output |
+|-------|-----|-------|--------|
+| **App Discovery** (1 per app in monorepo, or 1 for single app) | Read app's package.json, detect framework, deps, test config, design system | App path | App entry for profile |
+| **Security Context** | Scan router/route files for auth patterns, tenant isolation, procedure types | Router glob pattern | Security section for profile |
+| **PRD/Feature Analysis** | Read PRD/README, extract feature categories with priorities | PRD path or README | Features section for profile |
+| **Anthropic Docs Research** | Live research of current Anthropic agent/skill/command format docs | WebSearch + context7 + WebFetch | Format rules for generation + verification status |
+| **Stack Testing Research** | WebSearch for testing best practices specific to detected framework + test runner | `profile.apps[].framework`, `profile.testing.testRunner` | Condensed patterns (max 2K tokens) |
+| **Security Research** | WebSearch for security standards specific to detected domain + auth provider | `profile.project.domain`, `profile.security.authMethods` | Domain security profile (max 2K tokens) |
+| **UX/A11Y Research** | WebSearch for accessibility standards specific to detected UI framework + domain | `profile.project.domain`, `profile.apps[].framework` | UX criteria + scoring adjustments (max 2K tokens) |
+
+#### Anthropic Docs Research Agent
+
+This agent performs LIVE research to get the latest Anthropic documentation on agent, skill, and command formats. This replaces the old "Anthropic Format Check" that only read local files.
+
+```
+You are a documentation research agent. Your job is to find the CURRENT Anthropic
+Claude Code documentation on writing custom agents, skills, and commands.
+
+**Step 1: WebSearch queries (run all):**
+- "Anthropic Claude Code custom agents format {current_year}"
+- "Claude Code skills format reference {current_year}"
+- "Claude Code orchestrator pattern multi-agent subagent {current_year}"
+- "Claude Code slash commands custom commands format {current_year}"
+- "site:docs.anthropic.com Claude Code agents skills"
+
+**Step 2: context7 (if available):**
+- Resolve library ID for "claude-code"
+- Query for agent creation docs, skill format docs, command format docs
+
+**Step 3: WebFetch (attempt these paths):**
+- https://docs.anthropic.com/en/docs/claude-code/agents
+- https://docs.anthropic.com/en/docs/claude-code/skills
+- https://docs.anthropic.com/en/docs/claude-code/commands
+
+**Step 4: Reconciliation:**
+- Read local files: ~/.claude/docs/agents-format.md and ~/.claude/docs/skills-format.md
+- Compare live findings against local docs
+- Log any discrepancies (new fields, deprecated fields, changed defaults)
+- USE LIVE FINDINGS for agent generation when they differ from local
+
+**Return a condensed summary (MAX 2000 tokens) organized as:**
+- Agent format: required frontmatter fields, allowed-tools syntax, model values
+- Skill format: required frontmatter fields, user-invocable settings
+- Command format: required frontmatter fields, argument-hint syntax, @file auto-context
+- Discrepancies: {list of differences between live docs and local files}
+- Verification: "verified_current" or "using_local_fallback"
+
+Do NOT return raw URLs. Synthesize into actionable format rules.
+```
+
+**Set in profile after return:**
+```json
+{
+  "research": {
+    "anthropicDocsVerified": true,
+    "anthropicDocsVersion": "{date or version from docs}",
+    "anthropicDocsDiscrepancies": ["list of differences found"]
+  }
+}
+```
+
+#### General Research Agent Prompt Template
+
+```
+You are a research agent. Use WebSearch to find current best practices.
+
+**Queries to run** (from templates/domain-research-queries.md, substituted with detected values):
+{framework-specific queries}
+{domain-specific queries}
+
+For each relevant result, WebFetch the URL for details.
+
+**Return a condensed summary (MAX 2000 tokens) organized as:**
+- Key patterns for {topic}
+- Common pitfalls to test for
+- Framework-specific considerations
+- Checklist items to include in QA
+
+Do NOT return raw URLs or full articles. Synthesize actionable guidance.
+```
+
+**Graceful fallback:** If WebSearch fails or returns nothing useful, proceed without research. Set `profile.research.researchCompleted = false`. Agents generate from templates alone. If Anthropic docs research fails, fall back to local `~/.claude/docs/agents-format.md` and `~/.claude/docs/skills-format.md`. Set `profile.research.anthropicDocsVerified = false`.
+
+If context7 MCP is available, also launch:
+
+| Agent | Job |
+|-------|-----|
+| **Framework Docs** (1 per detected framework) | Fetch current testing patterns via context7 MCP |
+
+**Graceful fallback:** If context7 is unavailable, proceed without latest docs. Note in profile: `"context7Available": false`.
+
+### B3: Determine Monorepo Structure
+
+**If monorepo detected** (pnpm-workspace.yaml, turbo.json, lerna.json, or nx.json):
+- Read workspace config to find app directories
+- For each app directory, read its package.json
+- Create one entry per app in the profile's `apps[]` array
+
+**If single app** (no workspace config):
+- Create one entry with `path: "."` in `apps[]`
+
+### B4: Write Profile
+
+Assemble `.claude/qa-profile.json` from all research results. Schema:
+
+```json
+{
+  "$schema": "qa-profile-v1",
+  "version": 1,
+  "generatedAt": "ISO-8601",
+
+  "project": {
+    "name": "string (from package.json name)",
+    "rootDir": "absolute-path",
+    "monorepo": true,
+    "packageManager": "pnpm|npm|yarn|bun",
+    "language": "typescript|javascript",
+    "domain": "safety-critical|healthcare|e-commerce|multi-tenant-saas|education|fintech|general",
+    "domainKeywords": ["matched", "keywords"],
+    "targetAudience": "description of who uses this app"
+  },
+
+  "apps": [{
+    "name": "string",
+    "path": "relative-path (e.g., apps/web or .)",
+    "framework": "nextjs|expo|fastify|express|remix|astro|nuxt|unknown",
+    "type": "frontend|backend|worker|marketing",
+    "testIdPrefix": "WEB|API|MOB|WK|MKT",
+    "buildCommand": "string",
+    "testCommand": "string",
+    "designSystem": "string|null",
+    "authProvider": "string|null"
+  }],
+
+  "testing": {
+    "testRunner": "vitest|jest",
+    "e2eFramework": "playwright|cypress|none",
+    "componentTestLib": "@testing-library/react|@testing-library/react-native|none",
+    "autoDetected": true,
+    "existingInfrastructure": {
+      "setupFile": "path|null",
+      "helpersFile": "path|null",
+      "configFile": "path|null"
+    },
+    "coverageThresholds": {
+      "statements": 80,
+      "branches": 70,
+      "functions": 80,
+      "lines": 80
+    }
+  },
+
+  "security": {
+    "multiTenancy": true,
+    "tenantIsolationField": "orgId|tenantId|userId|none",
+    "authMethods": ["clerk-jwt", "magic-link", "next-auth", "..."],
+    "procedureTypes": ["protectedProcedure", "publicProcedure", "..."],
+    "routerCount": 0,
+    "routerPath": "glob-pattern"
+  },
+
+  "features": {
+    "prdPath": "path|null",
+    "prdExists": true,
+    "categories": [
+      {
+        "name": "string",
+        "prefix": "string (test ID prefix)",
+        "priority": "P0|P1|P2",
+        "estimatedTests": 0
+      }
+    ],
+    "totalEstimatedTests": 0
+  },
+
+  "agentRouting": {
+    "fixRoutes": [
+      { "pattern": "glob", "agent": "agent-name" }
+    ]
+  },
+
+  "scopes": {
+    "available": ["full", "api", "security", "ux"],
+    "default": "full"
+  },
+
+  "commands": {
+    "typeCheck": "pnpm type-check",
+    "build": "pnpm build",
+    "test": "pnpm test"
+  },
+
+  "config": {
+    "model_profile": "balanced"
+  },
+
+  "research": {
+    "stackTesting": "condensed findings from Stack Testing Research agent",
+    "securityProfile": "condensed findings from Security Research agent",
+    "uxCriteria": "condensed findings from UX/A11Y Research agent",
+    "anthropicDocsVerified": true,
+    "anthropicDocsVersion": "date or version from live docs",
+    "anthropicDocsDiscrepancies": [],
+    "researchedAt": "ISO-8601",
+    "researchCompleted": true
+  },
+
+  "context7Available": true
+}
+```
+
+### B5: Create Directories
+
+```bash
+mkdir -p .claude/agents .claude/skills/testing/resources docs/qa-reports
+```
+
+### B6: Generate Files (parallel Task agents, up to 8)
+
+The template files live at `~/.claude/skills/qa/templates/`. Generate project files by:
+
+1. **Category A — Copy verbatim** (100% generic, no substitution needed):
+   - `templates/nielsen-heuristics.md` → `.claude/skills/testing/resources/nielsen-heuristics.md`
+   - `templates/visual-regression.md` → `.claude/skills/testing/visual-regression.md`
+
+2. **Category B — Copy with variable substitution:**
+   - `templates/unit-test.md` → `.claude/skills/testing/unit-test.md`
+   - `templates/component-test.md` → `.claude/skills/testing/component-test.md`
+   - `templates/e2e-test.md` → `.claude/skills/testing/e2e-test.md`
+   - `templates/qa-report-template.md` → `.claude/skills/testing/resources/qa-report-template.md`
+   - `templates/performance-benchmarks-base.md` → `.claude/skills/testing/resources/performance-benchmarks.md`
+   - `templates/security-checklist-owasp.md` → `.claude/skills/testing/resources/security-checklist.md`
+   - `templates/test-standards.md` → `.claude/skills/testing/test-standards.md`
+
+   For each: Read the template, replace all `{{variable}}` placeholders with values from `qa-profile.json`, write the output.
+
+3. **Category C — Agent generation (domain-aware):**
+   - Read `templates/agent-skeleton.md`
+   - Read `profile.research.*` for domain-specific content from B2 research agents
+   - Read `templates/domain-security-profiles.md` for the matching `profile.project.domain`
+   - For each of the 6 agent sections, substitute profile variables AND domain variables:
+     - `{{DOMAIN_CONTEXT}}` → Combined domain label + target audience + relevant research findings from `profile.research.stackTesting`
+     - `{{SECURITY_PROFILE}}` → Domain security profile from template + research findings from `profile.research.securityProfile`
+     - `{{DOMAIN_UX_CONTEXT}}` → Domain-specific UX scoring adjustments from `profile.research.uxCriteria`
+   - If `profile.research.researchCompleted == false`, use template content only (no research findings to inject)
+   - Write each agent to `.claude/agents/qa-{name}.md`
+
+4. **PRD Test Matrix** (generated, not from template):
+   - If PRD exists: Read the PRD, extract features, generate `.claude/skills/testing/resources/prd-test-matrix.md` with test cases mapped to features
+   - If no PRD: Prompt user: "No PRD found. Would you like to: (a) define key features to test, (b) auto-discover from routes/components, or (c) point to a requirements doc?" If (a), collect feature list interactively. If (b), generate minimal test matrix from route/component discovery. If (c), read the provided path. Mark `prdExists: false` unless user provides a doc.
+
+5. **tRPC Test Skill** (conditional):
+   - If tRPC detected (`security.procedureTypes` is non-empty): Generate `.claude/skills/testing/trpc-test.md` with router test patterns
+   - If no tRPC: Skip
+
+### B7: Handle Existing Files
+
+Before writing each generated file, check if it already exists:
+
+- **File exists AND is newer than profile** → Skip (user customized it). Log: "Skipping {file} — user-modified"
+- **File exists AND is older than profile** → Offer update: "Update {file}? It was last modified {date}."
+- **File does not exist** → Write it
+
+### B8: Validate
+
+After generation, verify:
+1. Glob `.claude/agents/qa-*.md` — expect 6 files (or 5 if no API/security auditor needed)
+2. Glob `.claude/skills/testing/*.md` — expect skill files
+3. Glob `.claude/skills/testing/resources/*.md` — expect resource files
+4. Spot-check: Read first 5 lines of 2 random generated files to verify no leftover `{{variable}}` placeholders
+5. Verify YAML frontmatter is valid in agent files
+6. If `profile.research.anthropicDocsVerified == true`: Cross-check generated agent frontmatter against Anthropic docs findings (required fields, allowed-tools syntax, model values). Log any discrepancies as warnings.
+
+### B9: Report Bootstrap Results
+
+**State checkpoint:** Write initial cycle state before reporting:
+
+```
+Write docs/qa-reports/cycle-state.json: {
+  "cycle": 0,
+  "date": "{YYYY-MM-DD}",
+  "phase": "bootstrap_complete",
+  "scope": "init"
+}
+```
+
+Read and output `~/.claude/skills/qa/templates/stop-points/bootstrap-complete.md`
+Substitute all `{placeholder}` values with profile data from B4.
+
+If `/qa:init` was invoked, STOP HERE. Do not proceed to QA execution.
+
+---
+
+> **Phases 1-9 have been extracted to lean command orchestrators.** See `~/.claude/commands/qa/full.md` for the main QA cycle, `~/.claude/commands/qa/continue.md` for fix execution, and `~/.claude/commands/qa/resume.md` for recovery from any state.

package/skills/qa/references/continuation-format.md

@@ -0,0 +1,58 @@
+# QA Continuation Format
+
+Standard format for QA stop-point output. Follows GSD continuation-format rules adapted for QA lifecycle.
+
+## Format Rules (GSD-Compatible)
+
+1. **Always show WHAT it is** — name + description, never just a command
+2. **Command in inline backticks** — easy to copy-paste
+3. **`/clear` explanation always included** — explains WHY
+4. **"Also available" not "Other options"** — sounds more app-like
+5. **Visual separators** — `---` above and below to make it stand out
+6. **Recovery line always inside separator block** — never floating
+7. **Box-drawing characters:** `━` for top/bottom banners, `─` for separators
+
+## Stop Point Template Files
+
+Templates have been extracted to individual files. Commands read the appropriate template, substitute placeholders, and output directly.
+
+| Stop Point | Template File | Used By |
+|-----------|---------------|---------|
+| Bootstrap Complete | `templates/stop-points/bootstrap-complete.md` | `/qa:init` (terminal), `/qa:full` (informational) |
+| Fix Plan Ready (Phase 6) | `templates/stop-points/fix-ready.md` | `/qa:full` (mandatory user-approval stop) |
+| Certified (Phase 8) | `templates/stop-points/certified.md` | `/qa:full` (terminal — all exit criteria pass) |
+| Escalated (Phase 9) | `templates/stop-points/escalated.md` | `/qa:full` (terminal — stuck defects) |
+| Phase Transition | `templates/stop-points/phase-transition.md` | All commands (inter-phase autonomous continuation) |
+| Status Dashboard | `templates/stop-points/status-dashboard.md` | `/qa:status` (read-only dashboard) |
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+Run /qa:continue
+```
+
+User has no idea what cycle this is or what happens next.
+
+### Don't: Missing /clear explanation
+
+```
+`/qa:full`
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: Recovery line outside separator block
+
+```
+---
+Also available:
+- `/qa:status`
+---
+
+If session interrupted → `/qa:resume`
+```
+
+Recovery line must be INSIDE a `---` block, not floating.

package/skills/qa/references/exit-criteria.md

@@ -0,0 +1,53 @@
+# QA Exit Criteria
+
+Thresholds that must be met for QA certification, plus severity definitions used across all QA agents.
+
+## Exit Criteria
+
+Read from profile and apply defaults:
+
+| Gate | Default Threshold |
+|------|-------------------|
+| P0 features pass | 100% |
+| P1 features pass | 100% (or documented workarounds) |
+| Critical defects open | 0 |
+| Major defects open | 0 |
+| Minor defects open | <10 |
+| UX Score (Nielsen avg) | >= 3.5 / 5.0 |
+| WCAG 2.1 AA critical | 0 violations |
+| Lighthouse Performance | >= 80 (if frontend exists) |
+| Lighthouse Accessibility | >= 85 (if frontend exists) |
+| Tenant isolation verified | All routers (if multi-tenant) |
+| Auth boundary tests | 100% pass (if auth exists) |
+
+## Decision Gate Logic (Phase 5)
+
+```
+IF all exit criteria pass:
+  → decision = "PASS"
+  → Phase 8: Certification
+  → DONE (autonomous — no stop)
+
+ELIF cycle >= 3 AND same defects persist across 2+ cycles:
+  → decision = "ESCALATE"
+  → Phase 9: Escalation
+  → STOP with escalation report
+
+ELIF cycle >= 3 AND blockedDefectIds.length > 0 across 2+ cycles without resolution:
+  → decision = "ESCALATE"
+  → Phase 9: Escalation (include blocked defect history)
+
+ELSE (failures exist):
+  → decision = "FAIL"
+  → Phase 6: Plan Fixes
+  → Continues autonomously into fix planning
+```
+
+## Defect Severity Definitions
+
+| Severity | Definition | Example |
+|----------|-----------|---------|
+| **Critical** | Feature broken, data loss risk, security hole | Cross-tenant data leak, core feature crash |
+| **Major** | Partially broken, no workaround | Form submission fails, auth bypass |
+| **Minor** | Works with issues, workaround exists | Filter doesn't clear on back nav |
+| **Cosmetic** | Visual-only | Icon misalignment, wrong font weight |