qaa-agent 1.6.2 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/.claude/commands/create-test.md +164 -164
  2. package/.claude/commands/qa-audit.md +37 -37
  3. package/.claude/commands/qa-blueprint.md +54 -54
  4. package/.claude/commands/qa-fix.md +36 -36
  5. package/.claude/commands/qa-from-ticket.md +24 -24
  6. package/.claude/commands/qa-gap.md +20 -20
  7. package/.claude/commands/qa-map.md +47 -47
  8. package/.claude/commands/qa-pom.md +36 -36
  9. package/.claude/commands/qa-pr.md +23 -23
  10. package/.claude/commands/qa-pyramid.md +37 -37
  11. package/.claude/commands/qa-report.md +38 -38
  12. package/.claude/commands/qa-research.md +33 -33
  13. package/.claude/commands/qa-start.md +22 -22
  14. package/.claude/commands/qa-testid.md +19 -19
  15. package/.claude/commands/qa-validate.md +42 -42
  16. package/.claude/commands/update-test.md +58 -58
  17. package/.claude/settings.json +20 -20
  18. package/.claude/skills/qa-bug-detective/SKILL.md +122 -122
  19. package/.claude/skills/qa-learner/SKILL.md +150 -150
  20. package/.claude/skills/qa-repo-analyzer/SKILL.md +88 -88
  21. package/.claude/skills/qa-self-validator/SKILL.md +109 -109
  22. package/.claude/skills/qa-template-engine/SKILL.md +113 -113
  23. package/.claude/skills/qa-testid-injector/SKILL.md +93 -93
  24. package/.claude/skills/qa-workflow-documenter/SKILL.md +87 -87
  25. package/.mcp.json +8 -8
  26. package/CHANGELOG.md +71 -71
  27. package/CLAUDE.md +553 -553
  28. package/agents/qa-pipeline-orchestrator.md +1378 -1378
  29. package/agents/qaa-analyzer.md +524 -524
  30. package/agents/qaa-bug-detective.md +446 -446
  31. package/agents/qaa-codebase-mapper.md +935 -935
  32. package/agents/qaa-e2e-runner.md +415 -415
  33. package/agents/qaa-executor.md +651 -651
  34. package/agents/qaa-planner.md +390 -390
  35. package/agents/qaa-project-researcher.md +319 -319
  36. package/agents/qaa-scanner.md +424 -424
  37. package/agents/qaa-testid-injector.md +585 -585
  38. package/agents/qaa-validator.md +452 -452
  39. package/bin/install.cjs +198 -198
  40. package/bin/lib/commands.cjs +709 -709
  41. package/bin/lib/config.cjs +307 -307
  42. package/bin/lib/core.cjs +497 -497
  43. package/bin/lib/frontmatter.cjs +299 -299
  44. package/bin/lib/init.cjs +989 -989
  45. package/bin/lib/milestone.cjs +241 -241
  46. package/bin/lib/model-profiles.cjs +60 -60
  47. package/bin/lib/phase.cjs +911 -911
  48. package/bin/lib/roadmap.cjs +306 -306
  49. package/bin/lib/state.cjs +748 -748
  50. package/bin/lib/template.cjs +222 -222
  51. package/bin/lib/verify.cjs +842 -842
  52. package/bin/qaa-tools.cjs +607 -607
  53. package/docs/COMMANDS.md +341 -341
  54. package/docs/DEMO.md +182 -182
  55. package/docs/TESTING.md +156 -156
  56. package/package.json +41 -41
  57. package/templates/failure-classification.md +391 -391
  58. package/templates/gap-analysis.md +409 -409
  59. package/templates/pr-template.md +48 -48
  60. package/templates/qa-analysis.md +381 -381
  61. package/templates/qa-audit-report.md +465 -465
  62. package/templates/qa-repo-blueprint.md +636 -636
  63. package/templates/scan-manifest.md +312 -312
  64. package/templates/test-inventory.md +582 -582
  65. package/templates/testid-audit-report.md +354 -354
  66. package/templates/validation-report.md +243 -243
  67. package/workflows/qa-analyze.md +296 -296
  68. package/workflows/qa-from-ticket.md +536 -536
  69. package/workflows/qa-gap.md +303 -303
  70. package/workflows/qa-pr.md +389 -389
  71. package/workflows/qa-start.md +1168 -1168
  72. package/workflows/qa-testid.md +356 -356
  73. package/workflows/qa-validate.md +295 -295
package/docs/COMMANDS.md CHANGED
@@ -1,341 +1,341 @@
1
- # QAA Commands Reference
2
-
3
- ## When to Use What
4
-
5
- ```
6
- "I have a project with no tests" → /qa-start
7
- "I want to understand the codebase first" → /qa-map
8
- "I need tests for a specific feature" → /create-test
9
- "I have a Jira/Linear ticket to cover" → /qa-from-ticket
10
- "I want to check if my tests are good" → /qa-validate
11
- "My tests are failing after a deploy" → /qa-fix
12
- "I want to ship my tests as a PR" → /qa-pr
13
- "I want a full report for my manager" → /qa-report
14
- "I need to know what's missing in our test suite" → /qa-gap
15
- "I want to add data-testid to components" → /qa-testid
16
- "I need Page Object Models" → /qa-pom
17
- "I want to audit test quality" → /qa-audit
18
- "I need a QA repo structure from scratch" → /qa-blueprint
19
- "I want to see our testing pyramid balance" → /qa-pyramid
20
- "I want to analyze without generating anything" → /qa-analyze
21
- "I want to research best testing practices" → /qa-research
22
- "I want to improve existing tests" → /update-test
23
- ```
24
-
25
- ---
26
-
27
- ## Full Pipeline
28
-
29
- ### /qa-start
30
-
31
- **What it does:** Runs the entire QA automation pipeline end-to-end. Scans the repo, maps the codebase, analyzes architecture, plans test cases, generates test files, validates them, runs E2E tests against the live app, and delivers everything as a draft PR.
32
-
33
- **When to use:** Starting QA from scratch on a project, or doing a full gap-fill on an existing QA repo.
34
-
35
- ```
36
- /qa-start --dev-repo /path/to/project
37
- /qa-start --dev-repo /path/to/project --qa-repo /path/to/tests
38
- /qa-start --dev-repo /path/to/project --auto
39
- ```
40
-
41
- **Pipeline:**
42
- ```
43
- scan → map → analyze → [testid-inject] → plan → generate → validate → [e2e-run] → [bug-detective] → deliver
44
- ```
45
-
46
- **Produces:** SCAN_MANIFEST.md, 8 codebase map documents, QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md, test files, POMs, fixtures, VALIDATION_REPORT.md, E2E_RUN_REPORT.md, draft PR.
47
-
48
- ---
49
-
50
- ## Discovery & Analysis
51
-
52
- ### /qa-map
53
-
54
- **What it does:** Deep-scans the codebase with 4 parallel agents (testability, risk, patterns, existing tests) and produces 8 documents that become the shared context for all other commands. This is the "brain" of the system.
55
-
56
- **When to use:** Before using `/create-test` on a mature project. Run it once, and every subsequent command benefits from the codebase knowledge.
57
-
58
- ```
59
- /qa-map
60
- /qa-map --focus testability
61
- /qa-map --focus risk
62
- ```
63
-
64
- **Produces:** TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md — all in `.qa-output/codebase/`.
65
-
66
- ---
67
-
68
- ### /qa-analyze
69
-
70
- **What it does:** Scans and analyzes a repository without generating any tests. Produces assessment documents only — architecture overview, risk areas, test inventory with every test case specified, and a testing pyramid recommendation.
71
-
72
- **When to use:** You want to understand what needs testing before committing to generation. Good for presenting a plan to the team before executing.
73
-
74
- ```
75
- /qa-analyze
76
- /qa-analyze --dev-repo /path/to/project
77
- /qa-analyze --dev-repo /path/to/project --qa-repo /path/to/tests
78
- ```
79
-
80
- **Produces:** SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, and either QA_REPO_BLUEPRINT.md (no QA repo) or GAP_ANALYSIS.md (QA repo provided).
81
-
82
- ---
83
-
84
- ### /qa-research
85
-
86
- **What it does:** Researches the best testing stack, frameworks, and patterns for a specific project. Checks official docs, community best practices, and produces opinionated recommendations with confidence levels.
87
-
88
- **When to use:** You're setting up testing for the first time and want to know which framework to use, or you're evaluating whether to switch from Jest to Vitest.
89
-
90
- ```
91
- /qa-research
92
- /qa-research --focus api-testing
93
- /qa-research --focus e2e-strategy
94
- ```
95
-
96
- **Produces:** TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md (depending on mode).
97
-
98
- ---
99
-
100
- ### /qa-gap
101
-
102
- **What it does:** Compares a dev repo against its QA repo to find coverage gaps. Shows what's tested, what's missing, what's broken, and what's low quality.
103
-
104
- **When to use:** You already have tests but suspect there are holes. Want a concrete list of what to add next.
105
-
106
- ```
107
- /qa-gap --dev-repo /path/to/project --qa-repo /path/to/tests
108
- ```
109
-
110
- **Produces:** GAP_ANALYSIS.md with coverage map, missing tests, broken tests, and prioritized recommendations.
111
-
112
- ---
113
-
114
- ### /qa-pyramid
115
-
116
- **What it does:** Analyzes the distribution of your test suite against the ideal testing pyramid (60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E). Shows where you're heavy and where you're light.
117
-
118
- **When to use:** You want to know if your test suite is balanced or if you're over-invested in E2E and under-invested in unit tests.
119
-
120
- ```
121
- /qa-pyramid ./tests
122
- /qa-pyramid ./tests --dev-repo /path/to/project
123
- ```
124
-
125
- **Produces:** PYRAMID_ANALYSIS.md with current vs target distribution and an action plan.
126
-
127
- ---
128
-
129
- ## Test Creation
130
-
131
- ### /create-test
132
-
133
- **What it does:** Generates tests for a specific feature or module. Reads the codebase map (if available) to understand the project's code patterns, API contracts, and existing conventions. If E2E tests are generated and an app is running, opens a real browser, captures actual locators from the page, fixes any mismatches, and loops until tests pass.
134
-
135
- **When to use:** Daily work. A new feature shipped and you need tests for it.
136
-
137
- ```
138
- /create-test login
139
- /create-test "checkout flow"
140
- /create-test "user API" --dev-repo /path/to/project
141
- /create-test login --app-url http://localhost:3000
142
- /create-test login --skip-run
143
- ```
144
-
145
- **Produces:** Test spec files, POMs, fixtures. E2E_RUN_REPORT.md if tests were run against the app.
146
-
147
- ---
148
-
149
- ### /qa-from-ticket
150
-
151
- **What it does:** Fetches a ticket from Jira, Linear, GitHub Issues, or a file. Extracts acceptance criteria and edge cases. Maps each criterion to test cases with a traceability matrix. Generates test files and validates them.
152
-
153
- **When to use:** You work from tickets and want every acceptance criterion to have a corresponding test before the feature ships.
154
-
155
- ```
156
- /qa-from-ticket https://company.atlassian.net/browse/PROJ-123
157
- /qa-from-ticket #456
158
- /qa-from-ticket ./tickets/feature-spec.md
159
- /qa-from-ticket "As a user I want to reset my password via email"
160
- ```
161
-
162
- **Produces:** TEST_CASES_FROM_TICKET.md (traceability matrix), GENERATION_PLAN_TICKET.md, test files, VALIDATION_REPORT.md.
163
-
164
- ---
165
-
166
- ### /qa-pom
167
-
168
- **What it does:** Generates Page Object Model files for given pages. Follows CLAUDE.md POM rules: one class per page, no assertions, locators as properties, extends shared base.
169
-
170
- **When to use:** You have pages that need POMs but don't want to generate full test suites yet.
171
-
172
- ```
173
- /qa-pom ./src/pages
174
- /qa-pom ./src/pages --framework playwright
175
- ```
176
-
177
- **Produces:** POM files in `pages/` directory with BasePage and feature pages.
178
-
179
- ---
180
-
181
- ### /qa-testid
182
-
183
- **What it does:** Scans frontend source code, audits interactive elements for missing `data-testid` attributes, and injects them following the naming convention (`{context}-{description}-{element-type}` in kebab-case). Creates a separate branch for the changes.
184
-
185
- **When to use:** Before writing E2E tests. You want every button, input, and link to have a stable test ID.
186
-
187
- ```
188
- /qa-testid ./src/components
189
- /qa-testid ./src
190
- ```
191
-
192
- **Produces:** TESTID_AUDIT_REPORT.md (coverage score, proposed values) and modified source files with `data-testid` attributes.
193
-
194
- ---
195
-
196
- ## Validation & Fixing
197
-
198
- ### /qa-validate
199
-
200
- **What it does:** Validates test files against CLAUDE.md standards. Runs 4 static layers (syntax, structure, dependencies, logic) with auto-fix up to 3 loops. Optionally runs E2E tests against a live app to verify locators and assertions with real page data.
201
-
202
- **When to use:** After writing or generating tests, before shipping. Or as a quality check on an existing test suite.
203
-
204
- ```
205
- /qa-validate ./tests
206
- /qa-validate ./tests --classify
207
- /qa-validate ./tests --run --app-url http://localhost:3000
208
- ```
209
-
210
- **Produces:** VALIDATION_REPORT.md. FAILURE_CLASSIFICATION_REPORT.md if `--classify` used. E2E_RUN_REPORT.md if `--run` used.
211
-
212
- ---
213
-
214
- ### /qa-fix
215
-
216
- **What it does:** Diagnoses and fixes broken test files. Reads failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes test code errors.
217
-
218
- **When to use:** Tests that were passing started failing after a deploy or code change.
219
-
220
- ```
221
- /qa-fix ./tests/e2e/checkout*
222
- /qa-fix ./tests --error "timeout waiting for selector"
223
- ```
224
-
225
- **Produces:** Fixed test files. FAILURE_CLASSIFICATION_REPORT.md with evidence for each failure.
226
-
227
- ---
228
-
229
- ### /update-test
230
-
231
- **What it does:** Improves existing tests without rewriting them. Upgrades locator tiers, makes assertions more specific, fixes naming conventions, adds missing test IDs.
232
-
233
- **When to use:** Your tests work but don't follow current standards. You want incremental improvement, not a rewrite.
234
-
235
- ```
236
- /update-test ./tests
237
- /update-test ./tests --scope locators
238
- /update-test ./tests --scope assertions
239
- ```
240
-
241
- **Produces:** Updated test files with improvements applied.
242
-
243
- ---
244
-
245
- ## Reporting & Auditing
246
-
247
- ### /qa-audit
248
-
249
- **What it does:** Full 6-dimension quality audit of a test suite. Scores: Locator Quality (20%), Assertion Specificity (20%), POM Compliance (15%), Test Coverage (20%), Naming Convention (15%), Test Data Management (10%). Gives a weighted overall score.
250
-
251
- **When to use:** You want a quality score for your test suite with concrete recommendations for improvement.
252
-
253
- ```
254
- /qa-audit ./tests
255
- /qa-audit ./tests --dev-repo /path/to/project
256
- ```
257
-
258
- **Produces:** QA_AUDIT_REPORT.md with scores, critical issues, and effort-estimated recommendations (S/M/L).
259
-
260
- ---
261
-
262
- ### /qa-report
263
-
264
- **What it does:** Generates a QA status report adapted to the audience. Team level gets file-level details. Management gets high-level metrics. Client gets a coverage summary.
265
-
266
- **When to use:** Standups, sprint reviews, client updates.
267
-
268
- ```
269
- /qa-report ./tests
270
- /qa-report ./tests --audience management
271
- /qa-report ./tests --audience client
272
- ```
273
-
274
- **Produces:** QA_STATUS_REPORT.md with metrics, pyramid distribution, risk areas, recommendations.
275
-
276
- ---
277
-
278
- ### /qa-blueprint
279
-
280
- **What it does:** Generates a complete QA repository structure blueprint — recommended stack, folder layout, config files, CI/CD pipeline, npm scripts, and definition of done.
281
-
282
- **When to use:** You're starting a QA repo from scratch and want a solid structure before writing the first test.
283
-
284
- ```
285
- /qa-blueprint
286
- /qa-blueprint --dev-repo /path/to/project
287
- ```
288
-
289
- **Produces:** SCAN_MANIFEST.md, QA_REPO_BLUEPRINT.md.
290
-
291
- ---
292
-
293
- ## Delivery
294
-
295
- ### /qa-pr
296
-
297
- **What it does:** Creates a draft PR from QA artifacts already on disk. Auto-detects git platform (GitHub, Azure DevOps, GitLab). Applies your team's branch naming convention (asks once, remembers forever). Shows what will be committed and waits for your confirmation before pushing.
298
-
299
- **When to use:** After generating or fixing tests, you want to package them as a PR.
300
-
301
- ```
302
- /qa-pr --ticket PROJ-123 --title "login tests"
303
- /qa-pr --scope e2e
304
- /qa-pr --ticket PROJ-456 --title "checkout" --base develop
305
- ```
306
-
307
- **Produces:** Git branch (following your convention), commits, draft PR with summary. Returns the PR URL.
308
-
309
- ---
310
-
311
- ## Common Flows
312
-
313
- ### New project, no tests
314
- ```
315
- /qa-start --dev-repo ./myproject --auto
316
- ```
317
-
318
- ### Mature project, new feature
319
- ```
320
- /qa-map # once
321
- /create-test "password reset" # generates + runs
322
- /qa-pr --ticket PROJ-123 "reset tests" # ships as PR
323
- ```
324
-
325
- ### From a Jira ticket
326
- ```
327
- /qa-from-ticket https://jira.company.com/browse/PROJ-456
328
- /qa-pr --ticket PROJ-456 "login flow"
329
- ```
330
-
331
- ### Fix broken tests after deploy
332
- ```
333
- /qa-fix ./tests/e2e/checkout*
334
- /qa-pr --ticket PROJ-789 "fix checkout tests"
335
- ```
336
-
337
- ### Quality check before release
338
- ```
339
- /qa-audit ./tests --dev-repo ./myproject
340
- /qa-report ./tests --audience management
341
- ```
1
+ # QAA Commands Reference
2
+
3
+ ## When to Use What
4
+
5
+ ```
6
+ "I have a project with no tests" → /qa-start
7
+ "I want to understand the codebase first" → /qa-map
8
+ "I need tests for a specific feature" → /create-test
9
+ "I have a Jira/Linear ticket to cover" → /qa-from-ticket
10
+ "I want to check if my tests are good" → /qa-validate
11
+ "My tests are failing after a deploy" → /qa-fix
12
+ "I want to ship my tests as a PR" → /qa-pr
13
+ "I want a full report for my manager" → /qa-report
14
+ "I need to know what's missing in our test suite" → /qa-gap
15
+ "I want to add data-testid to components" → /qa-testid
16
+ "I need Page Object Models" → /qa-pom
17
+ "I want to audit test quality" → /qa-audit
18
+ "I need a QA repo structure from scratch" → /qa-blueprint
19
+ "I want to see our testing pyramid balance" → /qa-pyramid
20
+ "I want to analyze without generating anything" → /qa-analyze
21
+ "I want to research best testing practices" → /qa-research
22
+ "I want to improve existing tests" → /update-test
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Full Pipeline
28
+
29
+ ### /qa-start
30
+
31
+ **What it does:** Runs the entire QA automation pipeline end-to-end. Scans the repo, maps the codebase, analyzes architecture, plans test cases, generates test files, validates them, runs E2E tests against the live app, and delivers everything as a draft PR.
32
+
33
+ **When to use:** Starting QA from scratch on a project, or doing a full gap-fill on an existing QA repo.
34
+
35
+ ```
36
+ /qa-start --dev-repo /path/to/project
37
+ /qa-start --dev-repo /path/to/project --qa-repo /path/to/tests
38
+ /qa-start --dev-repo /path/to/project --auto
39
+ ```
40
+
41
+ **Pipeline:**
42
+ ```
43
+ scan → map → analyze → [testid-inject] → plan → generate → validate → [e2e-run] → [bug-detective] → deliver
44
+ ```
45
+
46
+ **Produces:** SCAN_MANIFEST.md, 8 codebase map documents, QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md, test files, POMs, fixtures, VALIDATION_REPORT.md, E2E_RUN_REPORT.md, draft PR.
47
+
48
+ ---
49
+
50
+ ## Discovery & Analysis
51
+
52
+ ### /qa-map
53
+
54
+ **What it does:** Deep-scans the codebase with 4 parallel agents (testability, risk, patterns, existing tests) and produces 8 documents that become the shared context for all other commands. This is the "brain" of the system.
55
+
56
+ **When to use:** Before using `/create-test` on a mature project. Run it once, and every subsequent command benefits from the codebase knowledge.
57
+
58
+ ```
59
+ /qa-map
60
+ /qa-map --focus testability
61
+ /qa-map --focus risk
62
+ ```
63
+
64
+ **Produces:** TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md — all in `.qa-output/codebase/`.
65
+
66
+ ---
67
+
68
+ ### /qa-analyze
69
+
70
+ **What it does:** Scans and analyzes a repository without generating any tests. Produces assessment documents only — architecture overview, risk areas, test inventory with every test case specified, and a testing pyramid recommendation.
71
+
72
+ **When to use:** You want to understand what needs testing before committing to generation. Good for presenting a plan to the team before executing.
73
+
74
+ ```
75
+ /qa-analyze
76
+ /qa-analyze --dev-repo /path/to/project
77
+ /qa-analyze --dev-repo /path/to/project --qa-repo /path/to/tests
78
+ ```
79
+
80
+ **Produces:** SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, and either QA_REPO_BLUEPRINT.md (no QA repo) or GAP_ANALYSIS.md (QA repo provided).
81
+
82
+ ---
83
+
84
+ ### /qa-research
85
+
86
+ **What it does:** Researches the best testing stack, frameworks, and patterns for a specific project. Checks official docs, community best practices, and produces opinionated recommendations with confidence levels.
87
+
88
+ **When to use:** You're setting up testing for the first time and want to know which framework to use, or you're evaluating whether to switch from Jest to Vitest.
89
+
90
+ ```
91
+ /qa-research
92
+ /qa-research --focus api-testing
93
+ /qa-research --focus e2e-strategy
94
+ ```
95
+
96
+ **Produces:** TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md (depending on mode).
97
+
98
+ ---
99
+
100
+ ### /qa-gap
101
+
102
+ **What it does:** Compares a dev repo against its QA repo to find coverage gaps. Shows what's tested, what's missing, what's broken, and what's low quality.
103
+
104
+ **When to use:** You already have tests but suspect there are holes. Want a concrete list of what to add next.
105
+
106
+ ```
107
+ /qa-gap --dev-repo /path/to/project --qa-repo /path/to/tests
108
+ ```
109
+
110
+ **Produces:** GAP_ANALYSIS.md with coverage map, missing tests, broken tests, and prioritized recommendations.
111
+
112
+ ---
113
+
114
+ ### /qa-pyramid
115
+
116
+ **What it does:** Analyzes the distribution of your test suite against the ideal testing pyramid (60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E). Shows where you're heavy and where you're light.
117
+
118
+ **When to use:** You want to know if your test suite is balanced or if you're over-invested in E2E and under-invested in unit tests.
119
+
120
+ ```
121
+ /qa-pyramid ./tests
122
+ /qa-pyramid ./tests --dev-repo /path/to/project
123
+ ```
124
+
125
+ **Produces:** PYRAMID_ANALYSIS.md with current vs target distribution and an action plan.
126
+
127
+ ---
128
+
129
+ ## Test Creation
130
+
131
+ ### /create-test
132
+
133
+ **What it does:** Generates tests for a specific feature or module. Reads the codebase map (if available) to understand the project's code patterns, API contracts, and existing conventions. If E2E tests are generated and an app is running, opens a real browser, captures actual locators from the page, fixes any mismatches, and loops until tests pass.
134
+
135
+ **When to use:** Daily work. A new feature shipped and you need tests for it.
136
+
137
+ ```
138
+ /create-test login
139
+ /create-test "checkout flow"
140
+ /create-test "user API" --dev-repo /path/to/project
141
+ /create-test login --app-url http://localhost:3000
142
+ /create-test login --skip-run
143
+ ```
144
+
145
+ **Produces:** Test spec files, POMs, fixtures. E2E_RUN_REPORT.md if tests were run against the app.
146
+
147
+ ---
148
+
149
+ ### /qa-from-ticket
150
+
151
+ **What it does:** Fetches a ticket from Jira, Linear, GitHub Issues, or a file. Extracts acceptance criteria and edge cases. Maps each criterion to test cases with a traceability matrix. Generates test files and validates them.
152
+
153
+ **When to use:** You work from tickets and want every acceptance criterion to have a corresponding test before the feature ships.
154
+
155
+ ```
156
+ /qa-from-ticket https://company.atlassian.net/browse/PROJ-123
157
+ /qa-from-ticket #456
158
+ /qa-from-ticket ./tickets/feature-spec.md
159
+ /qa-from-ticket "As a user I want to reset my password via email"
160
+ ```
161
+
162
+ **Produces:** TEST_CASES_FROM_TICKET.md (traceability matrix), GENERATION_PLAN_TICKET.md, test files, VALIDATION_REPORT.md.
163
+
164
+ ---
165
+
166
+ ### /qa-pom
167
+
168
+ **What it does:** Generates Page Object Model files for given pages. Follows CLAUDE.md POM rules: one class per page, no assertions, locators as properties, extends shared base.
169
+
170
+ **When to use:** You have pages that need POMs but don't want to generate full test suites yet.
171
+
172
+ ```
173
+ /qa-pom ./src/pages
174
+ /qa-pom ./src/pages --framework playwright
175
+ ```
176
+
177
+ **Produces:** POM files in `pages/` directory with BasePage and feature pages.
178
+
179
+ ---
180
+
181
+ ### /qa-testid
182
+
183
+ **What it does:** Scans frontend source code, audits interactive elements for missing `data-testid` attributes, and injects them following the naming convention (`{context}-{description}-{element-type}` in kebab-case). Creates a separate branch for the changes.
184
+
185
+ **When to use:** Before writing E2E tests. You want every button, input, and link to have a stable test ID.
186
+
187
+ ```
188
+ /qa-testid ./src/components
189
+ /qa-testid ./src
190
+ ```
191
+
192
+ **Produces:** TESTID_AUDIT_REPORT.md (coverage score, proposed values) and modified source files with `data-testid` attributes.
193
+
194
+ ---
195
+
196
+ ## Validation & Fixing
197
+
198
+ ### /qa-validate
199
+
200
+ **What it does:** Validates test files against CLAUDE.md standards. Runs 4 static layers (syntax, structure, dependencies, logic) with auto-fix up to 3 loops. Optionally runs E2E tests against a live app to verify locators and assertions with real page data.
201
+
202
+ **When to use:** After writing or generating tests, before shipping. Or as a quality check on an existing test suite.
203
+
204
+ ```
205
+ /qa-validate ./tests
206
+ /qa-validate ./tests --classify
207
+ /qa-validate ./tests --run --app-url http://localhost:3000
208
+ ```
209
+
210
+ **Produces:** VALIDATION_REPORT.md. FAILURE_CLASSIFICATION_REPORT.md if `--classify` used. E2E_RUN_REPORT.md if `--run` used.
211
+
212
+ ---
213
+
214
+ ### /qa-fix
215
+
216
+ **What it does:** Diagnoses and fixes broken test files. Reads failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes test code errors.
217
+
218
+ **When to use:** Tests that were passing started failing after a deploy or code change.
219
+
220
+ ```
221
+ /qa-fix ./tests/e2e/checkout*
222
+ /qa-fix ./tests --error "timeout waiting for selector"
223
+ ```
224
+
225
+ **Produces:** Fixed test files. FAILURE_CLASSIFICATION_REPORT.md with evidence for each failure.
226
+
227
+ ---
228
+
229
+ ### /update-test
230
+
231
+ **What it does:** Improves existing tests without rewriting them. Upgrades locator tiers, makes assertions more specific, fixes naming conventions, adds missing test IDs.
232
+
233
+ **When to use:** Your tests work but don't follow current standards. You want incremental improvement, not a rewrite.
234
+
235
+ ```
236
+ /update-test ./tests
237
+ /update-test ./tests --scope locators
238
+ /update-test ./tests --scope assertions
239
+ ```
240
+
241
+ **Produces:** Updated test files with improvements applied.
242
+
243
+ ---
244
+
245
+ ## Reporting & Auditing
246
+
247
+ ### /qa-audit
248
+
249
+ **What it does:** Full 6-dimension quality audit of a test suite. Scores: Locator Quality (20%), Assertion Specificity (20%), POM Compliance (15%), Test Coverage (20%), Naming Convention (15%), Test Data Management (10%). Gives a weighted overall score.
250
+
251
+ **When to use:** You want a quality score for your test suite with concrete recommendations for improvement.
252
+
253
+ ```
254
+ /qa-audit ./tests
255
+ /qa-audit ./tests --dev-repo /path/to/project
256
+ ```
257
+
258
+ **Produces:** QA_AUDIT_REPORT.md with scores, critical issues, and effort-estimated recommendations (S/M/L).
259
+
260
+ ---
261
+
262
+ ### /qa-report
263
+
264
+ **What it does:** Generates a QA status report adapted to the audience. Team level gets file-level details. Management gets high-level metrics. Client gets a coverage summary.
265
+
266
+ **When to use:** Standups, sprint reviews, client updates.
267
+
268
+ ```
269
+ /qa-report ./tests
270
+ /qa-report ./tests --audience management
271
+ /qa-report ./tests --audience client
272
+ ```
273
+
274
+ **Produces:** QA_STATUS_REPORT.md with metrics, pyramid distribution, risk areas, recommendations.
275
+
276
+ ---
277
+
278
+ ### /qa-blueprint
279
+
280
+ **What it does:** Generates a complete QA repository structure blueprint — recommended stack, folder layout, config files, CI/CD pipeline, npm scripts, and definition of done.
281
+
282
+ **When to use:** You're starting a QA repo from scratch and want a solid structure before writing the first test.
283
+
284
+ ```
285
+ /qa-blueprint
286
+ /qa-blueprint --dev-repo /path/to/project
287
+ ```
288
+
289
+ **Produces:** SCAN_MANIFEST.md, QA_REPO_BLUEPRINT.md.
290
+
291
+ ---
292
+
293
+ ## Delivery
294
+
295
+ ### /qa-pr
296
+
297
+ **What it does:** Creates a draft PR from QA artifacts already on disk. Auto-detects git platform (GitHub, Azure DevOps, GitLab). Applies your team's branch naming convention (asks once, remembers forever). Shows what will be committed and waits for your confirmation before pushing.
298
+
299
+ **When to use:** After generating or fixing tests, you want to package them as a PR.
300
+
301
+ ```
302
+ /qa-pr --ticket PROJ-123 --title "login tests"
303
+ /qa-pr --scope e2e
304
+ /qa-pr --ticket PROJ-456 --title "checkout" --base develop
305
+ ```
306
+
307
+ **Produces:** Git branch (following your convention), commits, draft PR with summary. Returns the PR URL.
308
+
309
+ ---
310
+
311
+ ## Common Flows
312
+
313
+ ### New project, no tests
314
+ ```
315
+ /qa-start --dev-repo ./myproject --auto
316
+ ```
317
+
318
+ ### Mature project, new feature
319
+ ```
320
+ /qa-map # once
321
+ /create-test "password reset" # generates + runs
322
+ /qa-pr --ticket PROJ-123 "reset tests" # ships as PR
323
+ ```
324
+
325
+ ### From a Jira ticket
326
+ ```
327
+ /qa-from-ticket https://jira.company.com/browse/PROJ-456
328
+ /qa-pr --ticket PROJ-456 "login flow"
329
+ ```
330
+
331
+ ### Fix broken tests after deploy
332
+ ```
333
+ /qa-fix ./tests/e2e/checkout*
334
+ /qa-pr --ticket PROJ-789 "fix checkout tests"
335
+ ```
336
+
337
+ ### Quality check before release
338
+ ```
339
+ /qa-audit ./tests --dev-repo ./myproject
340
+ /qa-report ./tests --audience management
341
+ ```