qa-workflow-cc 1.0.0

package/commands/qa/full.md

@@ -0,0 +1,149 @@
+---
+name: qa:full
+description: Run complete QA cycle with autonomous test-fix-verify loop
+argument-hint: "[api|security|ux|{app-name}|cycle-N|--report-only|--fix|--verify]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+<execution_context>
+@.claude/qa-profile.json
+@docs/qa-reports/cycle-state.json
+</execution_context>
+
+<objective>
+Run a complete QA cycle: Bootstrap (if needed) → Test → Report → Decision → Fix Plan → STOP.
+After user approves fixes via `/qa:continue`, executes fixes → verify → re-test autonomously.
+
+**Orchestrator role:** Parse arguments, resolve model profiles, route to correct phase, spawn specialized agents, manage state transitions. NEVER write code directly — always delegate to agents.
+
+**IMPORTANT:** Read reference docs on-demand, not all at once. Only load what the current phase needs.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Supported arguments:**
+- (empty) or `full` → Full QA cycle starting at Phase 1 (or bootstrap if needed)
+- `api` → API/backend tests only
+- `security` → Security audit only
+- `ux` → UX evaluation only
+- `{app-name}` → Tests for specific app (by name from profile)
+- `cycle-N` → Start fresh cycle N (re-test everything)
+- `--report-only` → Test + report, skip fix planning
+- `--fix` → Same as `/qa:continue` (enter fix phase)
+- `--verify` → Re-verify without re-testing
+</context>
+
+<process>
+
+## 1. Resolve Model Profile
+
+Read `config.model_profile` from the auto-loaded qa-profile.json (default: "balanced").
+Read and resolve per-agent models from `~/.claude/skills/qa/references/model-profiles.md`.
+
+## Context Inlining (GSD Pattern)
+
+Before any Task() spawn, the orchestrator MUST:
+1. Read .claude/qa-profile.json → PROFILE (already auto-loaded)
+2. Read docs/qa-reports/cycle-state.json → STATE (already auto-loaded)
+3. Read ~/.claude/skills/qa/references/model-profiles.md → resolve per-agent model
+4. Inline relevant PROFILE and STATE sections into each Task() prompt
+5. Do NOT rely on @ references crossing Task() boundaries
+
+## 2. Check Bootstrap Status
+
+If qa-profile.json was NOT loaded (auto-context returned empty/missing):
+- Run bootstrap: Follow `~/.claude/skills/qa/workflows/bootstrap.md`
+- After bootstrap completes, re-read the profile
+- If `$ARGUMENTS` is `init` → STOP after bootstrap (this is handled by `/qa:init`)
+
+If profile exists but is stale (>30 days from `generatedAt`):
+- Prompt user: "QA profile is N days old. Re-scan? [yes/no]"
+- If yes → re-bootstrap
+- If no → proceed with existing profile
+
+## 3. Parse Scope
+
+Determine test scope from `$ARGUMENTS`:
+
+| Argument | Scope Filter |
+|----------|-------------|
+| `api` | Backend apps only, security auditor |
+| `security` | Security auditor only |
+| `ux` | UX optimizer only |
+| `{app-name}` | Match against `profile.apps[].name` |
+| `cycle-N` | Full scope, set cycle=N |
+| (default) | Full scope |
+
+Validate scope against `profile.scopes.available`. Error if invalid.
+
+## 4. Determine Cycle Number
+
+- If `cycle-N` argument: Use N
+- If cycle-state.json exists and has previous cycles: Use last cycle + 1
+- Otherwise: Cycle 1
+
+## 5. Phase 3: Execute Tests
+
+Follow `~/.claude/skills/qa/workflows/test-phase.md`
+
+## 6. Phase 4: Consolidate Report
+
+Follow `~/.claude/skills/qa/workflows/report-phase.md`
+
+## 7. Phase 5: Decision Gate
+
+Follow `~/.claude/skills/qa/workflows/decision-gate.md`
+
+Route based on decision:
+- **PASS** → Phase 8 (certification)
+- **FAIL** → Phase 6 (plan fixes)
+- **ESCALATE** → Phase 9 (escalation)
+
+## 8. Phase 6: Plan Fixes (if FAIL)
+
+Follow `~/.claude/skills/qa/workflows/fix-plan.md`
+
+**STOP — Present fix plan:**
+
+Read and output `~/.claude/skills/qa/templates/stop-points/fix-ready.md`
+Substitute all `{placeholder}` values with data from the fix plan and report.
+
+## 9. Phase 8: Certification (if PASS)
+
+Write certification report to `docs/qa-reports/final-certification-{date}.md`.
+Update state: `{ "phase": "certified", "verdict": "PASS" }`
+
+Read and output `~/.claude/skills/qa/templates/stop-points/certified.md`
+Substitute all `{placeholder}` values with certification data.
+
+## 10. Phase 9: Escalation (if ESCALATE)
+
+Write escalation analysis to `docs/qa-reports/escalation-cycle-{N}.md`.
+Update state: `{ "phase": "escalated" }`
+
+Read and output `~/.claude/skills/qa/templates/stop-points/escalated.md`
+Substitute all `{placeholder}` values with escalation data.
+
+</process>
+
+<success_criteria>
+- [ ] Model profile resolved from qa-profile.json config
+- [ ] Bootstrap triggered if profile missing
+- [ ] Scope parsed and validated
+- [ ] Test agents spawned with correct model and skill file instructions
+- [ ] Raw results saved to disk before consolidation
+- [ ] State checkpoints written BEFORE each phase execution
+- [ ] Decision gate evaluated against exit criteria
+- [ ] Stop point output matches template from templates/stop-points/
+- [ ] Recovery lines included at all transition points
+</success_criteria>

package/commands/qa/init.md

@@ -0,0 +1,105 @@
+---
+name: qa:init
+description: Bootstrap QA infrastructure — discover tech stack, generate agents and skill files
+argument-hint: "[--rebootstrap]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+<objective>
+Run QA bootstrap only (Phase 0). Discovers tech stack, researches Anthropic docs, generates agents and skill files, writes qa-profile.json, then STOPS.
+
+Does NOT execute any QA tests. Use `/qa:full` after bootstrap to start testing.
+
+**If `--rebootstrap` flag:** Force re-discovery even if qa-profile.json already exists.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Flags:**
+- `--rebootstrap` — Force fresh discovery even if profile exists
+</context>
+
+<process>
+
+## 1. Check Existing Profile
+
+```bash
+ls .claude/qa-profile.json 2>/dev/null
+```
+
+**If profile exists AND `--rebootstrap` NOT set:**
+- Read profile, check `generatedAt` timestamp
+- If fresh (<30 days): "QA profile already exists (generated {date}). Use `--rebootstrap` to force re-discovery, or `/qa:full` to start testing."
+- If stale (>30 days): Prompt user: "QA profile is {N} days old. Re-scan? [yes/no]"
+  - If no: STOP with message above
+  - If yes: Continue to bootstrap
+
+**If profile missing OR `--rebootstrap` set:** Continue to bootstrap.
+
+## 2. Invoke Bootstrap
+
+Invoke the `/qa` skill which contains the full Phase 0 Bootstrap Protocol (B1-B9).
+
+The skill file at `~/.claude/skills/qa/SKILL.md` contains:
+- B1: Root Discovery (package.json, framework detection, domain detection)
+- B2: Parallel Research (app discovery, security context, PRD analysis, Anthropic docs research, stack/security/UX research)
+- B3: Monorepo structure detection
+- B4: Profile assembly (qa-profile.json)
+- B5: Directory creation + project-level CLAUDE.md registration
+- B6: File generation (skill files, agent files, test matrix)
+- B7: Existing file handling (skip user-modified files)
+- B8: Validation (check generated files)
+- B9: State checkpoint + output
+
+Pass the `--rebootstrap` context so bootstrap knows to overwrite existing files.
+
+## 3. Project-Level Registration (GAP 6)
+
+After bootstrap completes, check project CLAUDE.md:
+
+```bash
+ls CLAUDE.md 2>/dev/null
+```
+
+**If CLAUDE.md exists:** Check if QA section already present. If not, append:
+
+```markdown
+
+## QA Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/qa:full` | Full QA cycle — test, report, fix plan, verify |
+| `/qa:full api` | API/backend tests only |
+| `/qa:full security` | Security audit only |
+| `/qa:full ux` | UX heuristic evaluation only |
+| `/qa:init` | Bootstrap QA infrastructure (first-time setup) |
+| `/qa:continue` | Execute approved fix plan |
+| `/qa:resume` | Resume from any interrupted state |
+| `/qa:status` | View current QA progress |
+
+QA reports: `docs/qa-reports/`
+QA profile: `.claude/qa-profile.json`
+```
+
+**If no CLAUDE.md:** Skip registration (not all projects have one).
+
+## 4. Output Bootstrap Complete
+
+The `/qa` skill handles the B9 output. After it returns, read and output:
+`~/.claude/skills/qa/templates/stop-points/bootstrap-complete.md`
+Substitute all `{placeholder}` values with profile data from B4.
+
+**STOP HERE.** Do not proceed to QA execution.
+
+</process>

package/commands/qa/resume.md

@@ -0,0 +1,91 @@
+---
+name: qa:resume
+description: Resume QA from any interrupted state by reading cycle-state.json
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<execution_context>
+@.claude/qa-profile.json
+@docs/qa-reports/cycle-state.json
+</execution_context>
+
+<objective>
+Resume QA execution from wherever it was interrupted. Reads cycle-state.json and routes to the correct phase.
+
+This is the universal recovery command — works from any state.
+</objective>
+
+<process>
+
+## 1. Validate State File
+
+Read cycle-state.json from auto-context.
+
+**If missing or empty:**
+- Error: "No QA state found. Run `/qa:full` to start."
+- STOP
+
+**If corrupt or unreadable:**
+- Error: "State file corrupt. Options: `/qa:full` (fresh start) or `/qa:full cycle-{N}` (re-test)"
+- STOP
+
+## 2. Resolve Model Profile
+
+Read `config.model_profile` from qa-profile.json (default: "balanced").
+Resolve per-agent models from `~/.claude/skills/qa/references/model-profiles.md`.
+
+## 3. Route Based on State
+
+| state.phase | Action |
+|-------------|--------|
+| `bootstrap_complete` | Load resources → Phase 3 (start testing). Route to `/qa:full` logic. |
+| `testing` | Check for raw results in `docs/qa-reports/cycle-{N}-raw/`. Re-spawn missing agents. Display: "Previous test agents may still be running. Re-spawning test phase." |
+| `testing_complete` | Phase 4: Consolidate from saved raw results. Read from `state.rawResultsDir`. |
+| `reporting_complete` | Phase 5: Re-evaluate decision gate. Read report, apply exit criteria. |
+| `awaiting_fix_approval` | Re-display fix plan summary. Output Phase 6 stop point template. |
+| `fixing` | Phase 7: Read `state.batchProgress`. Skip `completedBatches`. Resume from `currentBatch`. Display: "Resuming fix execution from batch {currentBatch}. Skipping completed: {completedBatches}" |
+| `verifying` | Phase 7b: Re-run verification. |
+| `certified` | "Already certified. Run `/qa:full cycle-{N+1}` for a new cycle." STOP |
+| `escalated` | "Escalated. Review `docs/qa-reports/escalation-cycle-{N}.md`. After resolving: `/qa:full cycle-{N+1}`" STOP |
+
+## 4. Execute Resumed Phase
+
+Route to the appropriate workflow file based on phase:
+
+| Resumed Phase | Workflow |
+|---------------|----------|
+| testing | Follow `~/.claude/skills/qa/workflows/test-phase.md` (re-spawn missing agents only) |
+| testing_complete | Follow `~/.claude/skills/qa/workflows/report-phase.md` |
+| reporting_complete | Follow `~/.claude/skills/qa/workflows/decision-gate.md` |
+| fixing | Follow `~/.claude/skills/qa/workflows/fix-execute.md` (skip completed batches) |
+| verifying | Follow `~/.claude/skills/qa/workflows/verify-phase.md` |
+
+**For testing phase resume:**
+- Check which agents already have saved results in `cycle-{N}-raw/`
+- Only re-spawn agents that DON'T have saved results
+- After all results collected → continue to Phase 4
+
+**For fixing phase resume:**
+- Read `batchProgress.completedBatches` — these are done
+- Read `batchProgress.currentBatch` — start here
+- Read `batchProgress.batchResults` — for context
+- Continue fix execution from current batch
+
+## 5. Continue Autonomously
+
+After resuming at the correct phase, continue the normal autonomous flow:
+- Phase 3 → 4 → 5 → (6 → STOP | 8 → STOP | 9 → STOP)
+- Phase 7 → 7b → 3 (next cycle)
+
+All transition points output the phase-transition template:
+Read and output `~/.claude/skills/qa/templates/stop-points/phase-transition.md`
+
+</process>

package/commands/qa/status.md

@@ -0,0 +1,66 @@
+---
+name: qa:status
+description: View current QA progress — cycle history, current phase, next action
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+<execution_context>
+@.claude/qa-profile.json
+@docs/qa-reports/cycle-state.json
+</execution_context>
+
+<objective>
+Display a progress dashboard showing current QA state, cycle history, and recommended next action. Read-only — does not modify any files.
+</objective>
+
+<process>
+
+## 1. Check State
+
+Read cycle-state.json from auto-context.
+
+**If missing:**
+- "No QA state found. Run `/qa:init` to bootstrap, then `/qa:full` to start testing."
+- STOP
+
+## 2. Read Profile
+
+Read qa-profile.json from auto-context for project name and scope info.
+
+**If missing:**
+- "No QA profile found. Run `/qa:init` to bootstrap."
+- STOP
+
+## 3. Gather Cycle History
+
+Read `state.previousCycles` for cycle history data.
+
+Also check for existing reports:
+```bash
+ls docs/qa-reports/cycle-*-*.md 2>/dev/null
+```
+
+## 4. Display Dashboard
+
+Read and output `~/.claude/skills/qa/templates/stop-points/status-dashboard.md`
+Substitute all `{placeholder}` values with data from state and profile.
+
+## 5. Phase Descriptions (for display)
+
+| Phase Value | Human-Readable Label |
+|-------------|---------------------|
+| `bootstrap_complete` | Bootstrap complete, ready for first cycle |
+| `testing` | Test agents running |
+| `testing_complete` | Tests complete, awaiting consolidation |
+| `reporting_complete` | Report written, awaiting decision |
+| `awaiting_fix_approval` | Fix plan ready for review |
+| `fixing` | Fix execution in progress |
+| `verifying` | Post-fix verification running |
+| `certified` | QA certified — all gates passed |
+| `escalated` | Blocked — manual intervention needed |
+
+</process>

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "qa-workflow-cc",
+  "version": "1.0.0",
+  "description": "Autonomous QA orchestrator for Claude Code — test-fix-verify cycles that run themselves.",
+  "bin": {
+    "qa-workflow-cc": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "skills/",
+    "VERSION"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "qa",
+    "testing",
+    "autonomous",
+    "orchestrator"
+  ],
+  "author": "desland01",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/desland01/qa-workflow.git"
+  }
+}