qa-workflow-cc 1.0.0

package/skills/qa/references/lifecycle.md

@@ -0,0 +1,181 @@
+# QA Lifecycle Reference
+
+Phase definitions, state machine, edge cases, and operational rules for the QA orchestrator.
+
+## Lifecycle Overview
+
+```
+/qa:full
+  │
+  ├─ Phase 0: Bootstrap (if needed)
+  │    └─ Writes cycle-state: phase="bootstrap_complete"
+  ├─ Phase 1: Load Resources
+  ├─ Phase 2: Parse Scope
+  │    └─ /qa:resume reads cycle-state → routes to correct phase
+  │
+  ╔═══════════════════════════════════════╗
+  ║  CYCLE LOOP (max 3 iterations)       ║
+  ║                                       ║
+  ║  Phase 3: Execute Tests               ║
+  ║    └─ Saves raw results to disk       ║
+  ║  Phase 4: Consolidate Report          ║
+  ║    └─ Reads from saved raw results    ║
+  ║  Phase 5: Decision Gate               ║
+  ║    ├─ PASS → Phase 8 (certify)        ║
+  ║    ├─ FAIL → Phase 6 (plan fixes)     ║
+  ║    └─ STUCK → Phase 9 (escalate)      ║
+  ║                                       ║
+  ║  Phase 6: Plan Fixes                  ║
+  ║    └─ ■ STOP — present plan           ║
+  ║        user runs: /qa:continue        ║
+  ║                                       ║
+  ║  Phase 7: Execute Fixes               ║  ← /qa:continue enters here
+  ║    └─ Batch checkpoints per priority  ║
+  ║  Phase 7b: Verify (type-check +       ║
+  ║            build + re-test failed)    ║
+  ║    └─ GOTO Phase 3 (next cycle)       ║
+  ║                                       ║
+  ╚═══════════════════════════════════════╝
+  │
+  Phase 8: Certification (all pass)
+  Phase 9: Escalation (stuck after 3 cycles)
+```
+
+**Key principle:** After the user approves fixes (`/qa:continue`), Phases 7→7b→3→4→5 run autonomously. If the next cycle still has failures, Phases 6→STOP happens again. The user only ever sees stop points, never intermediate states.
+
+**State management:** Every phase writes to `cycle-state.json` BEFORE executing, following the GSD "write state before execute" pattern. If context resets at any point, `/qa:resume` reads the state file and re-enters at the correct phase.
+
+## Phase Value Semantics
+
+| Phase | Meaning |
+|-------|---------|
+| `bootstrap_complete` | Profile and agents generated, ready for first QA cycle |
+| `testing` | Test agents spawned, may still be running |
+| `testing_complete` | All agents returned, raw results saved to disk |
+| `reporting_complete` | Consolidated report written, ready for decision gate |
+| `awaiting_fix_approval` | Fix plan written, waiting for user to run `/qa:continue` |
+| `fixing` | Fix execution in progress (check `batchProgress` for details) |
+| `verifying` | Post-fix verification running |
+| `certified` | All exit criteria passed — terminal state |
+| `escalated` | Stuck defects — manual intervention needed — terminal state |
+
+## cycle-state.json Schema
+
+```json
+{
+  "cycle": 1,
+  "date": "YYYY-MM-DD",
+  "scope": "full",
+  "phase": "bootstrap_complete|testing|testing_complete|reporting_complete|awaiting_fix_approval|fixing|verifying|certified|escalated",
+  "verdict": "PASS|FAIL",
+  "decision": "PASS|FAIL|ESCALATE",
+  "summary": {
+    "totalTests": 0,
+    "passing": 0,
+    "failing": 0,
+    "skipped": 0,
+    "passRate": 0.0
+  },
+  "defects": {
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "cosmetic": 0,
+    "total": 0
+  },
+  "failedTestIds": [],
+  "openDefectIds": [],
+  "blockedDefectIds": [],
+  "fixPlanPath": "docs/qa-reports/fix-plan-cycle-{N}.md",
+  "rawResultsDir": "docs/qa-reports/cycle-{N}-raw/",
+  "agentTasks": [],
+  "batchProgress": {
+    "completedBatches": [],
+    "currentBatch": null,
+    "batchResults": {}
+  },
+  "previousCycles": [],
+  "exitCriteria": {}
+}
+```
+
+## Resume Logic (`/qa:resume`)
+
+1. Read `docs/qa-reports/cycle-state.json`
+2. If file missing → error: "No QA state found. Run `/qa:full` to start."
+3. If file is corrupt or unreadable → error: "State file corrupt. Options: `/qa:full` (fresh start) or `/qa:cycle-{N}` (re-test)"
+4. Route based on `state.phase`:
+
+| state.phase | Resume Action |
+|-------------|---------------|
+| `bootstrap_complete` | → Phase 1 (load resources, then Phase 3) |
+| `testing` | → Phase 3 (check for raw results in `docs/qa-reports/cycle-{N}-raw/`; re-spawn missing agents) |
+| `testing_complete` | → Phase 4 (consolidate from saved raw results) |
+| `reporting_complete` | → Phase 5 (re-evaluate decision gate) |
+| `awaiting_fix_approval` | → Output fix plan summary + stop (same as Phase 6 stop) |
+| `fixing` | → Phase 7 (skip completed batches per `state.batchProgress`) |
+| `verifying` | → Phase 7b (re-run verification) |
+| `certified` | → Output: "Already certified. Run `/qa:full cycle-{N+1}` for new cycle." |
+| `escalated` | → Output: "Escalated. Review `docs/qa-reports/escalation-*.md`" |
+
+**Resume error messages:**
+
+```
+If state.phase == "testing" AND state.agentTasks exist:
+  → "Previous test agents may still be running. Re-spawning test phase."
+
+If state.phase == "fixing" AND state.batchProgress.currentBatch exists:
+  → "Resuming fix execution from batch {currentBatch}. Skipping completed: {completedBatches}"
+```
+
+## Continue Logic (`/qa:continue`)
+
+1. Read `docs/qa-reports/cycle-state.json`
+2. Verify `state.phase` is `"awaiting_fix_approval"` — if not, error: "No pending fix plan. Run `/qa:full` instead."
+3. Read the fix plan from `state.fixPlanPath`
+4. Jump directly to Phase 7: Execute Fixes
+
+## Cycle-N Logic (`/qa:full cycle-N`)
+
+1. Set cycle number to N
+2. Read previous cycle report if exists (for regression comparison)
+3. Jump to Phase 3: Execute Tests — runs ALL tests, not just previously failed ones
+4. Report compares results against previous cycle to show improvement
+
+## Edge Cases
+
+| Scenario | Handling |
+|----------|---------|
+| **No PRD found** | Infer features from route files + components; mark `prdExists: false`; all tests P1; optionally offer requirements discovery (Phase 0.5) |
+| **No API/backend** | Skip security auditor; security focuses on client-side |
+| **Single app (not monorepo)** | Single entry in `apps[]` with `path: "."` |
+| **Existing `.claude/agents/qa-*.md`** | Check mtime vs profile; skip if newer (user customized) |
+| **No test runner detected** | Default to vitest; note `"testing.autoDetected": false` |
+| **context7 unavailable** | Graceful fallback; generate without latest docs |
+| **Profile stale (>30 days)** | Prompt user: "QA profile is N days old. Re-scan?" |
+| **No tenant isolation detected** | Skip tenant isolation audit; focus on auth and OWASP |
+| **`/qa:continue` with no pending plan** | Error: "No pending fix plan. Run `/qa:full` to start a new cycle." |
+| **`/qa:continue` after manual fixes** | Works — Phase 7 reads fix plan but skips fixes already applied, then Phase 7b verifies |
+| **`/qa:resume` with no state file** | Error: "No QA state found. Run `/qa:full` to start." |
+| **`/qa:resume` with corrupt state** | Error: "State file corrupt. Options: `/qa:full` (fresh start) or `/qa:full cycle-{N}` (re-test)" |
+| **Context reset during Phase 3** | `/qa:resume` → re-enters Phase 3, checks for saved raw results in `cycle-{N}-raw/`, re-spawns missing agents |
+| **Context reset during Phase 7 batch** | `/qa:resume` → reads `batchProgress`, skips completed batches, resumes current batch |
+| **Context reset after Phase 6 stop** | `/qa:continue` works as normal (state + fix plan both persisted to disk) |
+| **Cycle 1 has 0 failures** | Skip Phases 6-7, go straight to Phase 8 certification |
+| **All fixes blocked in Phase 7** | Still proceeds to Phase 7b verification, then next cycle catches remaining issues |
+
+## Important Rules
+
+- NEVER skip the security audit if multi-tenancy is detected
+- Always verify type-check and build pass after fixes
+- Each cycle should improve the pass rate — if not, investigate why
+- The test matrix is the source of truth — don't invent tests not in the matrix
+- Keep reports concise but include evidence for every failure
+- All profile-driven: read paths, commands, and scopes from qa-profile.json
+- The ONLY user-facing stop point is fix plan approval (Phase 6 → `/qa:continue`)
+- Phase 8 (certification) and Phase 9 (escalation) are terminal — they output and stop
+- Between cycles, do NOT stop — Phase 7b flows into Phase 3 automatically
+- Every phase MUST write to `cycle-state.json` BEFORE executing (GSD "write state before execute" pattern)
+- Raw test results MUST be saved to `docs/qa-reports/cycle-{N}-raw/` — never rely on agent memory across phases
+- `/qa:resume` reads `cycle-state.json` and routes to the correct phase — all phases must be resumable
+- `blockedDefectIds` persists across cycles — excluded from fix plans, included in escalation reports

package/skills/qa/references/model-profiles.md

@@ -0,0 +1,77 @@
+# QA Model Profiles
+
+Model profiles control which Claude model each QA agent uses. Mirrors GSD's model profile system.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| qa-test-executor | opus | sonnet | sonnet |
+| qa-security-auditor | opus | sonnet | sonnet |
+| qa-ux-optimizer | opus | sonnet | haiku |
+| qa-report-writer | sonnet | sonnet | haiku |
+| qa-fix-planner | opus | opus | sonnet |
+| qa-verifier | opus | sonnet | sonnet |
+| fix-implementer | sonnet | sonnet | sonnet |
+| anthropic-docs-researcher | sonnet | haiku | haiku |
+| stack-research | sonnet | haiku | haiku |
+| security-research | sonnet | haiku | haiku |
+| ux-research | sonnet | haiku | haiku |
+
+## Profile Philosophy
+
+**quality** — Maximum reasoning power
+- Opus for all test execution and security (where detection matters)
+- Opus for fix planning (architecture decisions)
+- Sonnet for report writing and fix implementation (follows instructions)
+- Use when: quota available, security-critical projects, safety-critical domains
+
+**balanced** (default) — Smart allocation
+- Opus only for fix planning (where architecture decisions happen)
+- Sonnet for test execution, security, verification (needs reasoning)
+- Sonnet for report writing (needs synthesis)
+- Haiku for research agents (web search + summarize)
+- Use when: normal development, good balance of quality and cost
+
+**budget** — Minimal Opus usage
+- Sonnet for anything that writes code or runs tests
+- Haiku for research and reports
+- Use when: conserving quota, high-volume work, less critical phases
+
+## Resolution Logic
+
+Orchestrator commands (`/qa:full`, `/qa:continue`, `/qa:resume`) resolve model before spawning:
+
+```
+1. Read .claude/qa-profile.json
+2. Get config.model_profile (default: "balanced")
+3. Look up agent in table above
+4. Pass model parameter to Task call
+```
+
+## Configuration
+
+Set in `.claude/qa-profile.json`:
+```json
+{
+  "config": {
+    "model_profile": "balanced"
+  }
+}
+```
+
+Override per-invocation is not supported — change the profile config to switch.
+
+## Design Rationale
+
+**Why Opus for qa-fix-planner?**
+Fix planning involves root cause analysis, blast radius assessment, and architecture-aware fix routing. Model quality has the highest impact here.
+
+**Why Sonnet for qa-test-executor in balanced?**
+Test execution follows structured test matrices and runs automated tests. The matrix provides the reasoning; execution is verification.
+
+**Why Opus for qa-security-auditor in quality?**
+Security auditing requires nuanced reasoning about data flow, tenant isolation, and edge cases. Missing a vulnerability is high-cost.
+
+**Why Haiku for research agents in balanced?**
+Research agents run WebSearch queries and summarize results. This is information retrieval, not reasoning.