qualiow-exploratory-testing 1.3.0 → 2.2.0

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 (106) hide show
  1. package/.claude-plugin/marketplace.json +26 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/.env.example +27 -0
  4. package/CHANGELOG.md +259 -0
  5. package/README.md +472 -204
  6. package/agents/qa-diff-indexer-agent.md +81 -0
  7. package/agents/qa-gather-agent.md +41 -0
  8. package/agents/qa-page-mapper-agent.md +74 -0
  9. package/agents/qa-reporting-agent.md +103 -0
  10. package/{scripts → bin}/doctor-mobile.sh +57 -18
  11. package/bin/mcli +15 -9
  12. package/bin/mobile-cli.mjs +574 -286
  13. package/bin/qualiow +30 -0
  14. package/{scripts → bin}/setup-mobile.sh +56 -19
  15. package/bin/wadb +10 -4
  16. package/bin/wk-ios +29 -17
  17. package/bin/wkeval.mjs +7 -1
  18. package/data/domains/_default.yml +1 -1
  19. package/data/knowledge/changelog.yml +30 -12
  20. package/data/knowledge/manifest.yml +355 -127
  21. package/data/knowledge/releases/v0.1.0/entries/technique-business-logic-race-conditions.yml +1 -1
  22. package/data/knowledge/releases/v0.1.0/release.yml +8 -1
  23. package/data/knowledge/releases/v0.6.0/entries/technique-async-callback-contracts.yml +98 -0
  24. package/data/knowledge/releases/v0.6.0/entries/technique-exactly-once-verification.yml +116 -0
  25. package/data/knowledge/releases/v0.6.0/release.yml +30 -0
  26. package/data/security/SECURITY-POLICY.md +273 -0
  27. package/data/targets/_default.yml +1 -1
  28. package/data/targets/_example-api-only.yml +80 -0
  29. package/data/targets/_example-mobile-emulation.yml +2 -2
  30. package/data/targets/_example-native-mobile.yml +2 -2
  31. package/data/targets/_example-sim-android-chrome.yml +1 -1
  32. package/data/targets/_example-sim-ios-safari.yml +1 -1
  33. package/data/templates/api-probe-matrix.md +3 -3
  34. package/data/templates/bug-report.md +29 -151
  35. package/data/templates/coverage-map.md +9 -6
  36. package/data/templates/expected-behaviour.md +3 -2
  37. package/data/templates/session-charter.md +3 -0
  38. package/data/templates/session-report.md +57 -80
  39. package/dist/cli/index.js +2286 -701
  40. package/dist/index.d.ts +637 -81
  41. package/dist/index.js +2058 -228
  42. package/docs/BACKEND-VERIFICATION.md +39 -9
  43. package/docs/GETTING-STARTED.md +300 -121
  44. package/docs/MOBILE-SETUP.md +149 -18
  45. package/hooks/hooks.json +27 -0
  46. package/hooks/scripts/read-guard.mjs +95 -0
  47. package/hooks/scripts/secret-patterns.d.mts +8 -0
  48. package/hooks/scripts/secret-patterns.mjs +136 -0
  49. package/hooks/scripts/write-guard.mjs +87 -0
  50. package/package.json +33 -18
  51. package/skills/qa-explore/SKILL.md +32 -25
  52. package/skills/qa-explore/phases/00-setup.md +76 -42
  53. package/skills/qa-explore/phases/01-auth.md +32 -15
  54. package/skills/qa-explore/phases/02-charter.md +16 -5
  55. package/skills/qa-explore/phases/03-discovery.md +93 -27
  56. package/skills/qa-explore/phases/04-journeys.md +2 -2
  57. package/skills/qa-explore/phases/05-features.md +39 -24
  58. package/skills/qa-explore/phases/06-edge-cases.md +24 -13
  59. package/skills/qa-explore/phases/07-reporting.md +102 -142
  60. package/skills/qa-explore/references/context-integration.md +1 -1
  61. package/skills/qa-explore/references/delegation-rules.md +82 -0
  62. package/skills/qa-explore/references/output-contract.md +192 -0
  63. package/skills/qa-explore/references/paths.md +108 -0
  64. package/skills/qa-explore/references/playwright-agents-integration.md +61 -84
  65. package/skills/qa-explore/references/security-rules.md +70 -25
  66. package/skills/qa-explore/references/session-rules.md +2 -1
  67. package/skills/qa-explore/references/severity-guide.md +31 -4
  68. package/skills/qa-explore-cleanup/SKILL.md +51 -15
  69. package/skills/qa-explore-feedback/SKILL.md +23 -5
  70. package/skills/qa-explore-mobile/SKILL.md +86 -64
  71. package/skills/qa-explore-mobile/phases/00-setup.md +71 -62
  72. package/skills/qa-explore-mobile/phases/01-auth.md +28 -31
  73. package/skills/qa-explore-mobile/phases/02-charter.md +8 -4
  74. package/skills/qa-explore-mobile/phases/03-discovery.md +17 -11
  75. package/skills/qa-explore-mobile/phases/04-journeys.md +6 -6
  76. package/skills/qa-explore-mobile/phases/05-features.md +9 -9
  77. package/skills/qa-explore-mobile/phases/06-edge-cases.md +35 -40
  78. package/skills/qa-explore-mobile/phases/07-reporting.md +108 -60
  79. package/skills/qa-explore-mobile/references/mobile-edges.md +26 -26
  80. package/skills/qa-explore-quick/SKILL.md +71 -26
  81. package/skills/qa-explore-report/SKILL.md +65 -35
  82. package/skills/qa-gather/SKILL.md +44 -8
  83. package/skills/qa-knowledge-add/SKILL.md +25 -9
  84. package/skills/qa-knowledge-list/SKILL.md +37 -40
  85. package/skills/qa-target-setup/SKILL.md +63 -41
  86. package/skills/qa-verify-backend/SKILL.md +31 -19
  87. package/skills/qa-verify-backend/phases/00-setup.md +57 -12
  88. package/skills/qa-verify-backend/phases/01-ac-decomposition.md +2 -2
  89. package/skills/qa-verify-backend/phases/02-static-review.md +11 -0
  90. package/skills/qa-verify-backend/phases/03-live-verification.md +5 -3
  91. package/skills/qa-verify-backend/phases/03b-api-verification.md +24 -9
  92. package/skills/qa-verify-backend/phases/04-e2e-trigger.md +18 -2
  93. package/skills/qa-verify-backend/phases/05-reporting.md +72 -12
  94. package/skills/qa-verify-backend/references/api-probes.md +28 -1
  95. package/skills/qa-verify-backend/references/payload-verification.md +1 -1
  96. package/skills/qa-verify-backend/references/release-readiness.md +1 -1
  97. package/skills/qa-verify-backend/references/safety-rules.md +13 -8
  98. package/data/domains/_default.md +0 -181
  99. package/data/domains/ecommerce.md +0 -192
  100. package/data/domains/fintech.md +0 -200
  101. package/data/domains/identity.md +0 -88
  102. package/data/domains/marketing.md +0 -194
  103. package/data/domains/saas.md +0 -197
  104. package/dist/cli/index.d.ts +0 -1
  105. package/dist/cli/index.js.map +0 -1
  106. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,185 +1,386 @@
1
- # @qualiow/exploratory-testing
1
+ # qualiow-exploratory-testing
2
2
 
3
- qualiow -- AI-powered exploratory testing skills using Claude Code + Playwright CLI.
3
+ AI-powered exploratory testing for **web**, **mobile** and **backend/API** — Claude Code skills, a QA knowledge base, and the CLI that wires them into a project.
4
4
 
5
- Claude acts as a Principal QA Engineer: it explores web applications systematically, finds bugs, and generates structured reports. No test scripts, no framework -- just AI reasoning, browser commands, and QA heuristics.
5
+ Claude acts as a Principal QA Engineer: it understands the business first, risk-ranks what
6
+ matters, explores systematically, and writes bug reports an executive can act on. No test
7
+ scripts and no framework — AI reasoning, browser/device commands, and QA heuristics.
6
8
 
7
- ## How to Install This Project
9
+ | Surface | Driver | Skill |
10
+ |---------|--------|-------|
11
+ | Web app in a desktop browser | `playwright-cli` | `/qa-explore`, `/qa-explore-quick` |
12
+ | Native iOS/Android app, or a web app in **real** Simulator Safari / Emulator Chrome | `bin/mobile-cli.mjs` (Maestro shim) | `/qa-explore-mobile` |
13
+ | Acceptance criteria with no UI at all — tables, streams, queues, IAM, HTTP endpoints | `git show`, read-only `aws-cli`, authenticated `fetch` | `/qa-verify-backend` |
8
14
 
9
- ### Prerequisites
15
+ ## Requirements
10
16
 
11
- - Node.js >= 18
12
- - Playwright CLI (`npm install @playwright/cli`)
13
- - Claude Code (for running exploratory sessions)
17
+ - **Node.js >= 22.4** (`node --version`)
18
+ - **Claude Code** — the skills run as slash commands inside it
19
+ - `playwright-cli` ships as a dependency of this package; nothing extra to install for the
20
+ web path. Mobile needs the iOS/Android toolchains — see [docs/MOBILE-SETUP.md](docs/MOBILE-SETUP.md).
14
21
 
15
- ### Quick Start
22
+ ## Install
16
23
 
17
- ```bash
18
- # install globally
19
- npm install -g @qualiow/exploratory-testing
24
+ Three supported paths. Pick one.
25
+
26
+ ### 1. npm (recommended for a project)
20
27
 
21
- # initialize in your project
28
+ ```bash
29
+ npm install -g qualiow-exploratory-testing
30
+ cd my-project
22
31
  qualiow init
32
+ ```
33
+
34
+ `qualiow init` copies into the current project:
35
+
36
+ | Copied | To |
37
+ |--------|----|
38
+ | the 11 skills | `.claude/skills/qa-*/` |
39
+ | the four sub-agents | `.claude/agents/` |
40
+ | knowledge base, domain profiles (`*.yml`), templates, security policy | `data/` |
41
+ | `_default.yml` target (with `--include-examples`: the `_example-*.yml` templates and `testers-ai.yml`) | `data/targets/` |
42
+ | the mobile driver, `setup-mobile.sh`, `doctor-mobile.sh` (executable) | `qa/bin/` |
43
+ | the credential template | `qa/.env.example` |
23
44
 
24
- # run your first session
25
- /qa-explore https://your-app.com
45
+ It also creates `output/{sessions,bugs,context}`, `.auth/` and `qa/`, and appends a
46
+ `# Qualiow` block to `.gitignore` (`.auth/`, `.env`, `qa/.env`, `output/sessions/*/`,
47
+ `!output/sessions/INDEX.md`, `output/context/*.md`, `data/targets/local-*.yml`,
48
+ `.playwright-cli/`, `*.trace.zip`, `*.webm`).
49
+
50
+ Re-running `init` is a no-op — existing files are kept unless you pass `--force`, and
51
+ `--dry-run` prints the plan without writing anything. Add `--hooks` to install the two guard
52
+ hooks into the project as well — see [Hooks](#hooks).
53
+
54
+ ```bash
55
+ cp qa/.env.example qa/.env # credentials live here, never in YAML
56
+ npx playwright-cli install --skills # optional: the official Playwright skill alongside
57
+ /qa-explore https://your-app.com # inside Claude Code
26
58
  ```
27
59
 
28
- ### Local Development
60
+ ### 2. Claude Code plugin
61
+
62
+ ```bash
63
+ claude plugin marketplace add willcoliveira/qualiow-exploratory-testing-skills
64
+ claude plugin install qualiow@qualiow
65
+ ```
66
+
67
+ The repository is its own marketplace (`.claude-plugin/marketplace.json`), so those two
68
+ commands are the whole install. For development against a local checkout, point Claude Code
69
+ at the directory instead:
70
+
71
+ ```bash
72
+ claude --plugin-dir /path/to/qualiow-exploratory-testing-skills
73
+ ```
74
+
75
+ Skills appear namespaced: `/qualiow:qa-explore`, `/qualiow:qa-verify-backend`, and so on.
76
+ Data (knowledge, domains, templates, targets) resolves from `${CLAUDE_PLUGIN_ROOT}/data/`
77
+ unless the project you are in has its own `data/` or `qa/` directory, which wins.
78
+
79
+ `bin/` lands on `PATH` only for **marketplace** installs — with `--plugin-dir`, call the
80
+ driver by its full path, `${CLAUDE_PLUGIN_ROOT}/bin/mcli`.
81
+
82
+ Under a plugin install the `qualiow` CLI runs through `bin/qualiow`, a launcher shim: it uses
83
+ the local build when the checkout has one, and otherwise fetches the published npm package
84
+ with `npx`, pinned to the version in `.claude-plugin/plugin.json`. A plugin install has no
85
+ `dist/`, so the first run of that path needs network.
86
+
87
+ ### 3. Git checkout (contributors, dogfooding)
29
88
 
30
89
  ```bash
31
- # clone the repository
32
90
  git clone https://github.com/willcoliveira/qualiow-exploratory-testing-skills.git
33
91
  cd qualiow-exploratory-testing-skills
34
-
35
- # install dependencies
36
92
  npm install
37
-
38
- # build
39
93
  npm run build
40
-
41
- # run tests
42
94
  npm test
43
95
  ```
44
96
 
45
- ## How to Run the CLI
97
+ `.claude/skills/` and `.claude/agents/` are canonical. `skills/` and `agents/` are generated
98
+ mirrors (shipped to npm and used by the plugin) kept in sync by `npm run sync:plugin`; CI
99
+ fails on drift, so never hand-edit the mirrors.
100
+
101
+ ## CLI
102
+
103
+ The CLI is the plumbing around the skills — project setup, config validation, session
104
+ listing, report export. **The exploratory sessions themselves run inside Claude Code**, not
105
+ from the shell.
106
+
107
+ | Command | Flags | What it does |
108
+ |---------|-------|--------------|
109
+ | `qualiow init` | `--include-examples` `--force` `--dry-run` `--hooks` | Install skills, sub-agents, data, `qa/bin/` and the output tree into the current project. Idempotent. `--hooks` also copies the guard scripts to `qa/hooks/` and merges the hook and permission entries into `.claude/settings.json` |
110
+ | `qualiow explore [url]` | `-t <target>` `-c <context>` `--time-box 45m` `--dry-run` | **Pre-flight only.** Validates the inputs, creates the session directory skeleton, and prints the `/qa-explore … --session <dir>` command to paste into Claude Code. It does not drive a browser |
111
+ | `qualiow validate` | `--targets` `--domains` `--knowledge` `--kb` `--all` | Validate configs against their schemas; exits 1 on any failure. `--all` also checks a project-local `qa/target.yml` and cross-checks the knowledge base against its manifest |
112
+ | `qualiow list <type>` | `sessions` \| `knowledge` \| `targets` \| `domains`; for `knowledge` also `--domain` `--tag` `--type` `--entry <id>` `--changelog` `--stats` | List what is installed or recorded. `list knowledge --entry <id>` prints that entry's YAML; `--changelog` and `--stats` read the knowledge changelog and the manifest counts |
113
+ | `qualiow report` | `-s <id>\|latest` `-f md\|html\|json\|jira` `-o <file>` `--stdout` | Export an existing session. `md` writes `session-summary.md`; html/json/jira carry the confidentiality header and pass through redaction |
114
+ | `qualiow kb <sync\|check>` | — | Regenerate or validate `data/knowledge/manifest.yml` from the release files |
115
+ | `qualiow kb digest` | `--for explore\|backend\|mobile` `--domain <id>` `--tag <t...>` `--entry <id>` `--data <dir>` `--max-lines <n>` | Print a compact digest of the knowledge entries a session needs, instead of the manifest and the entries read whole. `--entry <id>` prints one entry in full |
116
+ | `qualiow session finalize <dir\|latest>` | `--check` `--redact` | Close a session: validate it against the output contract, then append the INDEX row, the bug rows and the metrics line. `--check` writes nothing; `--redact` rewrites files that still carry a secret |
117
+ | `qualiow session list` | — | The session listing, same as `list sessions` |
118
+ | `qualiow session archive <dir>` | `--remove` | Tar the session directory; `--remove` also deletes it and marks its INDEX row archived |
119
+ | `qualiow session delete <dir>` | `--yes` | Remove a session directory and its index rows. Dry-run until `--yes` |
120
+ | `qualiow session prune` | `--older-than <days>` `--yes` | The same, for every session older than N days |
121
+ | `qualiow --version` | — | Print the package version |
122
+
123
+ `qualiow gather` was **removed in 2.0.0** — it was a stub that wrote nothing. Use the
124
+ `/qa-gather` skill, which does the real work.
125
+
126
+ A global install also puts the mobile helpers on `PATH`: `mcli`, `wadb`, `wk-ios`,
127
+ `qualiow-doctor-mobile`, `qualiow-setup-mobile`.
128
+
129
+ ### Token routing
130
+
131
+ Work with a fixed contract belongs to the CLI, not to the model. A session loads the
132
+ knowledge base through `qualiow kb digest` instead of reading `data/knowledge/manifest.yml`
133
+ and the five always-load entries (~964 lines) whole, and it ends with
134
+ `qualiow session finalize`, so the INDEX and `all-bugs.md` rows and the metrics line are
135
+ never hand-written; `/qa-knowledge-list` and `/qa-explore-cleanup` are wrappers around
136
+ `list knowledge` and `session …`.
137
+
138
+ Below the CLI sits a second tier, new in 2.2.0: bulk reads that need light judgement go to a
139
+ cheap sub-agent that returns a bounded, cited digest rather than a whole file.
140
+
141
+ Everything that requires judgement stays where it is: severity, priority, business impact,
142
+ the bug reports themselves, the charter and risk ranking, what is *missing*, the AC verdicts,
143
+ the executive summary and the reflection. The list of what is never delegated, and the read
144
+ thresholds that route the rest, is
145
+ [`skills/qa-explore/references/delegation-rules.md`](skills/qa-explore/references/delegation-rules.md).
146
+
147
+ ### Sub-agents
148
+
149
+ Four sub-agents ship with the pack, in `.claude/agents/` (mirrored to `agents/`). Each one
150
+ reads or writes on the session's behalf and hands back a bounded result:
151
+
152
+ | Sub-agent | Model | Returns | Called by |
153
+ |-----------|-------|---------|-----------|
154
+ | `qa-gather-agent` | `sonnet` | the requirements context file, with `[GAP]` and `[ASSUMPTION]` markers where a source was silent | `/qa-gather`, which runs entirely inside it |
155
+ | `qa-reporting-agent` | `sonnet`, `effort: low` | `session-report.md` assembled from the phase files and `phase-7-notes.md`, then `qualiow session finalize`; a summary of at most eight lines | the reporting phase of `/qa-explore`, `/qa-explore-mobile` and `/qa-verify-backend`, and `/qa-explore-report` |
156
+ | `qa-diff-indexer-agent` | `haiku`, `effort: low` | a table of file → symbols or resources → line ranges → candidate AC ids, plus the files that map to no AC and the ACs that map to no file | the static-review phase of `/qa-verify-backend`, when the diff crosses the gate |
157
+ | `qa-page-mapper-agent` | `haiku`, `effort: low` | a map of one raw snapshot: forms and their fields, navigation text → ref, interactive controls, visible error and empty-state text, hidden/disabled counts | the discovery phase of `/qa-explore`, for a snapshot too large to read |
158
+
159
+ **None of them returns a verdict.** No severity, no priority, no business impact, no "this is
160
+ a bug", no `PASS`/`FAIL`. They extract, index and assemble; the session decides. A delegate
161
+ that volunteers a judgement has exceeded its brief and that part of its answer is discarded.
162
+
163
+ Quick sessions write their own report — spinning up an agent costs more than it saves for a
164
+ 15-minute session.
165
+
166
+ ### Hooks
167
+
168
+ Two `PreToolUse` hooks enforce what the delegation rules ask for, and they are scoped to
169
+ qualiow-owned paths so they never interfere with ordinary coding in the same project:
170
+
171
+ - **`read-guard.mjs`** (matcher `Read`) fires only for `data/knowledge/manifest.yml`,
172
+ `data/knowledge/releases/**`, `output/sessions/*/phase-*.md` and
173
+ `output/sessions/*/snapshots/*`. A whole-file read of one of those over
174
+ `QUALIOW_READ_MAX_LINES` lines (default 300) is denied, with the cheaper route named in the
175
+ reason — `qualiow kb digest`, `qualiow list knowledge --entry <id>`, a `Grep` plus a `Read`
176
+ with `offset`/`limit`, or `qa-page-mapper-agent`. A `Read` that already carries `offset` or
177
+ `limit` passes untouched.
178
+ - **`write-guard.mjs`** (matcher `Write|Edit|MultiEdit`) fires only for files under `output/`
179
+ and never inside `snapshots/`. It denies content matching the same redaction list the
180
+ formatters and `qualiow session finalize` apply, naming the categories it matched, so a
181
+ secret is caught before it reaches disk rather than after.
182
+
183
+ Set `QUALIOW_HOOKS=off` to disable both, and `QUALIOW_READ_MAX_LINES` to move the threshold —
184
+ in `.claude/settings.json` under `env`:
185
+
186
+ ```json
187
+ { "env": { "QUALIOW_HOOKS": "off", "QUALIOW_READ_MAX_LINES": "500" } }
188
+ ```
46
189
 
47
- | Command | Description |
48
- |---------|-------------|
49
- | `qualiow init` | Initialize qualiow in the current project |
50
- | `qualiow explore [url]` | Run an exploratory testing session |
51
- | `qualiow validate` | Validate all configuration files (targets, knowledge, domains) |
52
- | `qualiow report` | Generate a report from an existing session |
53
- | `qualiow list <type>` | List sessions, knowledge, targets, or domains |
54
- | `qualiow gather` | Gather and analyze requirements for testing context |
190
+ **Plugin installs get the hooks by default** — `hooks/hooks.json` ships with the plugin and is
191
+ discovered without any configuration. **npm projects opt in** with `qualiow init --hooks`,
192
+ which copies the scripts to `qa/hooks/` and merges into `.claude/settings.json` the two hook
193
+ entries plus `permissions.allow` rules for `Bash(playwright-cli:*)`,
194
+ `Bash(npx playwright-cli:*)` and `Bash(qualiow:*)`. The merge is by exact string, so running
195
+ it twice changes nothing and hooks you already had are left alone. `docs/GETTING-STARTED.md`
196
+ carries the same snippet for anyone who would rather write it by hand.
55
197
 
56
- ## How to Run Exploratory Sessions
198
+ Do not enable both in one project. The plugin's hooks and the project's copies would both
199
+ run — a harmless double deny, and two node processes per tool call for nothing.
57
200
 
58
- ### Full session (45 minutes)
201
+ ## Running sessions
202
+
203
+ ### Full session (45 minutes, 8 phases)
59
204
 
60
205
  ```bash
61
- # explore a public site by URL
62
- /qa-explore https://testers.ai/testing/
206
+ /qa-explore https://testers.ai/testing/ # any public site
207
+ /qa-explore --target company-staging # a saved target config
208
+ /qa-explore --target company-staging --context output/context/TICKET-123-context.md
63
209
  ```
64
210
 
211
+ Setup 2 min · Auth 2 · Charter 5 · Discovery 6 · Journeys 10 · Features 10 · Edge cases 6 ·
212
+ Reporting 4. Findings are written to disk between phases so context never overflows.
213
+
214
+ ### Quick session (15 minutes, one page or feature)
215
+
65
216
  ```bash
66
- # explore using a saved target configuration
67
- /qa-explore --target company-staging
217
+ /qa-explore-quick https://app.example.com/checkout
68
218
  ```
69
219
 
70
- ### Quick focused session (15 minutes)
220
+ Quick sessions produce the same artefacts as a full one — `session-report.md`,
221
+ `bugs/BUG-NNN.md`, `stats.json`, an `INDEX.md` row — so every downstream skill can read them.
222
+
223
+ ### Gather requirements first
71
224
 
72
225
  ```bash
73
- # check a single page or feature
74
- /qa-explore-quick https://app.example.com/checkout
226
+ /qa-gather # files, URLs, tickets, pasted text
75
227
  ```
76
228
 
77
- ### Mobile session (simulator/emulator)
229
+ Writes `output/context/<TICKET>-context.md`, which `/qa-explore` and `/qa-verify-backend`
230
+ consume via `--context`.
78
231
 
79
- Runs a full exploratory session on an iOS Simulator or Android Emulator — either a
80
- **native app** (the installed app is the system under test) or a **mobile web app in the
81
- real device browser** (iOS Simulator Safari / Android Emulator Chrome — the genuine
82
- engines, which Playwright cannot drive). The mode comes from the target config.
232
+ `/qa-gather` runs in the `qa-gather-agent` sub-agent, which starts with the invocation and
233
+ nothing else, so **everything it needs must be in the same message**: the file paths, the
234
+ URLs, or the pasted text itself. It cannot ask a follow-up question; whatever a source leaves
235
+ unsaid comes back as a `[GAP]` or `[ASSUMPTION]` marker in the context file.
83
236
 
84
- #### 1. One-time machine setup
237
+ ### After a session
85
238
 
86
239
  ```bash
87
- # installs everything scriptable: Maestro, JDK 17, Android SDK + Google-Play AVD
88
- # (qa_pixel_api35), ios-webkit-debug-proxy, and the qa-iphone simulator device
89
- scripts/setup-mobile.sh # add --android or --ios to scope; --yes for non-interactive
240
+ /qa-explore-report output/sessions/2026-09-08-1813-explore-parabank # regenerate/reformat
241
+ /qa-explore-feedback # false positives, missed bugs
242
+ /qa-explore-cleanup # archive or delete old sessions
243
+ /qa-target-setup # configure a new target
244
+ /qa-knowledge-add # teach it a new heuristic
245
+ /qa-knowledge-list # browse the knowledge base
90
246
  ```
91
247
 
92
- Two iOS steps are genuinely manual (the script prints them if needed):
248
+ ### What a session leaves behind
93
249
 
94
- ```bash
95
- # a) install Xcode from the App Store, then:
96
- sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
97
- sudo xcodebuild -license accept
98
- # b) if no iOS runtime is installed:
99
- xcodebuild -downloadPlatform iOS
100
- # then re-run scripts/setup-mobile.sh --ios (creates the qa-iphone simulator)
250
+ Every session — web, quick, mobile or backend — lands in
251
+ `output/sessions/<YYYY-MM-DD-HHmm>-<kind>-<slug>/`, where `kind` is `explore`, `quick`,
252
+ `mobile` or `backend`:
253
+
254
+ ```
255
+ output/sessions/2026-09-08-1813-explore-parabank/
256
+ charter.md # what is being tested and why
257
+ session-log.md # real-time findings with WHY reasoning
258
+ phase-3-discovery.md # phase artefacts (file number == phase number)
259
+ phase-4-journeys.md
260
+ phase-5-features.md
261
+ phase-6-edge-cases.md
262
+ bugs/BUG-001.md # one bug = one report
263
+ screenshots/BUG-001.png
264
+ snapshots/ # raw page snapshots — working files, never part of the report
265
+ videos/
266
+ session-report.md # executive summary, coverage map, recommendations
267
+ stats.json
101
268
  ```
102
269
 
103
- #### 2. Verify readiness (read-only, run before every first session on a machine)
270
+ Plus a row in `output/sessions/INDEX.md`
271
+ (`| Date | Kind | Target | Bugs | Duration | Status | Report |`) and an entry in
272
+ `output/bugs/all-bugs.md` — both written by `qualiow session finalize`, which validates the
273
+ session first and refuses one with a missing confidentiality header or an unredacted secret.
274
+ Bug reports open with the two-line confidentiality blockquote and the headline
275
+ `# BUG-NNN: [Component] fails [Condition] causing [Impact]`.
276
+
277
+ ### Project-local configuration
278
+
279
+ `/qa-target-setup` writes `qa/target.yml` (project-local, one target per repo) or, with
280
+ `--shared`, `data/targets/<id>.yml`. Resolution order is:
104
281
 
105
- ```bash
106
- scripts/doctor-mobile.sh # or --ios / --android; fix each ✗ until READY
282
+ ```
283
+ --target <name> → qa/target.yml → data/targets/_default.yml
107
284
  ```
108
285
 
109
- #### 3. Create a target and run
286
+ Credentials come from `qa/.env`, falling back to `.env`. The env var names the shipped
287
+ configs reference: `QA_USER`, `QA_PASS`, `QA_TOKEN`, `QA_AWS_PROFILE`, `QA_AWS_REGION`,
288
+ `QA_API_TOKEN`, `EXAMPLE_API_KEY`. Never put a secret in a YAML file — reference it by
289
+ variable name.
110
290
 
111
- Copy a template from `data/targets/`, rename it, and point it at your app:
291
+ ## Mobile sessions
112
292
 
113
- | Template | What it tests | Driver |
114
- |----------|---------------|--------|
115
- | `_example-native-mobile.yml` | An installed iOS/Android app (native mode) | mobile-cli (Maestro) |
116
- | `_example-sim-ios-safari.yml` | A mobile web app in REAL iOS Simulator Safari | mobile-cli (Maestro) |
117
- | `_example-sim-android-chrome.yml` | A mobile web app in REAL Android Emulator Chrome | mobile-cli (Maestro) |
118
- | `_example-mobile-emulation.yml` | A mobile web app via Playwright device emulation (no simulator) | `/qa-explore` (playwright-cli) |
293
+ `/qa-explore-mobile` runs a full exploratory session on an iOS Simulator or Android
294
+ Emulator — either a **native app** (the installed app is the system under test) or a **web
295
+ app in the real device browser** (Simulator Safari / Emulator Chrome — the genuine engines,
296
+ which Playwright cannot drive). The mode comes from the target config.
297
+
298
+ ### 1. One-time machine setup
119
299
 
120
300
  ```bash
121
- /qa-explore-mobile --target my-mobile-target # real sim/emulator (native or web)
122
- /qa-explore --target my-emulation-target # Playwright mobile emulation
301
+ bin/setup-mobile.sh # both platforms
302
+ bin/setup-mobile.sh --android # or --ios to scope
303
+ bin/setup-mobile.sh --yes --allow-curl-bash # non-interactive, incl. the curl|bash installers
123
304
  ```
124
305
 
125
- #### 4. Driving the device manually (what the skill does under the hood)
306
+ It installs everything scriptable — Maestro (pinned via `MAESTRO_VERSION`, default 2.10.0),
307
+ JDK 17, Android cmdline-tools + platform-tools + a Google-Play system image, the standard AVD
308
+ `qa_pixel_api35`, the `qa-iphone` simulator device, and `ios-webkit-debug-proxy` — and prints
309
+ the two genuinely manual iOS steps (installing Xcode, downloading an iOS runtime).
126
310
 
127
- ```bash
128
- # Android: boot the standard AVD # iOS: boot the standard simulator
129
- ~/Library/Android/sdk/emulator/emulator \
130
- -avd qa_pixel_api35 -no-snapshot & xcrun simctl boot qa-iphone && open -a Simulator
311
+ ### 2. Preflight
131
312
 
132
- export MOBILE_CLI_STATE=/tmp/my-target-state.json # isolate this session's device/app state
133
- bin/mcli set-device emulator-5554 # or the iOS sim UDID (xcrun simctl list devices)
134
- bin/mcli set-app com.android.chrome # or com.apple.mobilesafari, or your app's id
135
- bin/mcli launch
136
- bin/mcli open-url https://staging.m.example.com # web mode only
137
- bin/mcli snapshot # page/app as tappable refs e1, e2, ...
138
- bin/mcli fill e4 my-username
139
- bin/mcli snapshot # ALWAYS re-snapshot after the keyboard appears
140
- bin/mcli click e7
141
- bin/mcli screenshot /tmp/evidence.png
142
- bin/mcli logs --errors --since 60
143
- bin/mcli --help # full command surface
313
+ ```bash
314
+ bin/doctor-mobile.sh # or --ios / --android / --quiet
144
315
  ```
145
316
 
146
- iOS Safari web targets additionally get real JS/DOM access via the WebKit bridge:
317
+ Read-only. Installs nothing; prints `✓`/`✗` with the exact fix command for each gap, and
318
+ checks Node >= 22.4, python3, Maestro >= 2.6.0 and `ios-webkit-debug-proxy`.
319
+
320
+ ### 3. Pick a target template
147
321
 
148
322
  ```bash
149
- bin/wk-ios 'document.title' # eval JS in the sim's Safari
150
- bin/wk-ios 'document.querySelectorAll(".cart_item").length' # exact-DOM assertions
151
- bin/wk-ios --stop # stop the proxy after the session
323
+ cp data/targets/_example-sim-ios-safari.yml data/targets/local-my-app.yml
152
324
  ```
153
325
 
154
- Notes that save time:
155
- - **Never `relaunch-clean` a web target** — it wipes the logged-in browser profile.
156
- - SSO/MFA logins are done **once, by hand, on the device**; the browser profile persists
157
- the session. There is no transferable `storage_state` on a real device browser.
158
- - Use `bin/wadb` for raw adb commands (logcat, `pm`, `am`) — it sets `ANDROID_HOME` for you.
159
- - Full setup guide + troubleshooting: `docs/MOBILE-SETUP.md`.
160
-
161
- ### Generate or regenerate a report
326
+ | Template | What it tests | Driver |
327
+ |----------|---------------|--------|
328
+ | `_example-native-mobile.yml` | An installed iOS/Android app (native mode) | mobile-cli (Maestro) |
329
+ | `_example-sim-ios-safari.yml` | A mobile web app in **real** iOS Simulator Safari | mobile-cli (Maestro) |
330
+ | `_example-sim-android-chrome.yml` | A mobile web app in **real** Android Emulator Chrome | mobile-cli (Maestro) |
331
+ | `_example-mobile-emulation.yml` | A mobile web app via Playwright device emulation (no simulator) | `/qa-explore` (playwright-cli) |
162
332
 
163
333
  ```bash
164
- # regenerate report for an existing session
165
- /qa-explore-report output/sessions/2026-03-28-parabank
334
+ /qa-explore-mobile --target local-my-app # real sim/emulator, native or web
335
+ /qa-explore --target local-my-emulation # Playwright mobile emulation
166
336
  ```
167
337
 
168
- ### Add knowledge to the base
338
+ ### 4. Driving the device by hand
339
+
340
+ The skill runs `bin/mcli` (or `qa/bin/mcli` in an init'ed project, or `mcli` on `PATH`).
341
+ Everything it does is available to you directly:
169
342
 
170
343
  ```bash
171
- # add new heuristics, techniques, or documentation
172
- /qa-knowledge-add
344
+ bin/mcli boot qa_pixel_api35 # or an iOS sim name / UDID
345
+ bin/mcli --state /tmp/my-run.json set-device emulator-5554 --platform android
346
+ bin/mcli set-app com.android.chrome # or com.apple.mobilesafari, or your app id
347
+ bin/mcli launch
348
+ bin/mcli open-url https://staging.m.example.com # web mode (alias of deep-link)
349
+ bin/mcli snapshot # a11y tree as refs e1, e2, … (refs expire after 60 s)
350
+ bin/mcli fill e4 my-username # Maestro inputText
351
+ bin/mcli snapshot # ALWAYS re-snapshot after the keyboard appears
352
+ bin/mcli click e7
353
+ bin/mcli fill-id login-btn "pass" # tap + type by testID, no snapshot needed
354
+ bin/mcli wait-text "Dashboard" 15
355
+ bin/mcli press HOME # BACK | ENTER | HOME | TAB | ESCAPE
356
+ bin/mcli screenshot evidence.png # no app required
357
+ bin/mcli logs --errors --since 60 # logcat / simctl log; logs-clear on Android
358
+ bin/mcli record-start run.mp4 && bin/mcli record-stop # mp4 on both platforms
359
+ bin/mcli info # resolved state + which state file is in use
360
+ bin/mcli --help
173
361
  ```
174
362
 
175
- ### Set up a new target
363
+ Exit codes: `0` ok · `1` command failed · `2` usage · `3` stale/unknown ref (re-run
364
+ `snapshot`) · `4` no device or app set.
365
+
366
+ iOS Safari web targets also get real JS/DOM access through the WebKit bridge (needs
367
+ `ios-webkit-debug-proxy`, `python3` and Node >= 22.4; `WK_IOS_PORT` overrides the port):
176
368
 
177
369
  ```bash
178
- # configure authentication, scope, and domain for a target app
179
- /qa-target-setup
370
+ bin/wk-ios 'document.title'
371
+ bin/wk-ios 'document.querySelectorAll(".cart_item").length'
372
+ bin/wk-ios --stop
180
373
  ```
181
374
 
182
- ## How to Verify Backend Acceptance Criteria
375
+ Notes that save time:
376
+
377
+ - **Never `relaunch-clean` a web target** — it wipes the logged-in browser profile.
378
+ - SSO/MFA logins are done **once, by hand, on the device**. There is no transferable
379
+ `storage_state` for a real device browser.
380
+ - `bin/wadb` is raw `adb` with `ANDROID_HOME` and JDK 17 resolved for you.
381
+ - Full guide and troubleshooting: **[docs/MOBILE-SETUP.md](docs/MOBILE-SETUP.md)**.
382
+
383
+ ## Backend, API and infrastructure verification
183
384
 
184
385
  Not every acceptance criterion is visible in a browser. `/qa-verify-backend` covers tickets
185
386
  whose ACs live below the UI — tables and streams, queue consumers, Lambda triggers, IAM
@@ -187,22 +388,21 @@ policies, webhooks, IaC, and the service's own HTTP endpoints — and produces a
187
388
  traceability matrix** instead of a pass/fail claim.
188
389
 
189
390
  ```bash
190
- # Copy the template, point it at your service, then verify a ticket branch
191
- cp data/targets/_example-backend.yml data/targets/local-my-service.yml
391
+ cp data/targets/_example-backend.yml data/targets/local-my-service.yml # service behind a UI
392
+ cp data/targets/_example-api-only.yml data/targets/local-my-api.yml # HTTP API, no UI
192
393
 
193
394
  /qa-verify-backend --target local-my-service --context output/context/TICKET-123-context.md
194
- /qa-verify-backend --target local-my-service --static-only # no cloud credentials
195
- /qa-verify-backend --target local-my-service --api-only --parity local-my-service-staging
395
+ /qa-verify-backend --target local-my-service --static-only # no cloud credentials
396
+ /qa-verify-backend --target local-my-service --no-e2e # skip the write path
397
+ /qa-verify-backend --target local-my-api --api-only --parity local-my-api-staging
196
398
  ```
197
399
 
198
- It runs four lanes:
199
-
200
400
  | Lane | What it does |
201
401
  |------|--------------|
202
402
  | **Static** | Reads the implementation branch against each AC with `git show` (never checks out) — spec drift, scope creep, failure paths, identity propagation, producer/consumer contract breaks |
203
403
  | **Live** | Read-only `aws-cli` probes, one per AC, raw output saved as evidence. Never mutates; hard stop on production |
204
404
  | **API** | Calls the service's own endpoints from the already-authenticated page, with a written case matrix covering everything the browser's guards prevent. Read-only, limited to the target's `api.probe_allowlist` |
205
- | **End-to-end** | Drives the real write path in a non-production environment, then re-probes the data layer — including same-tick writes, deletes, bulk saves, a second identity, and DLQ depth |
405
+ | **End-to-end** | Drives the real write path in a non-production environment, then re-probes the data layer — same-tick writes, deletes, bulk saves, a second identity, DLQ depth |
206
406
 
207
407
  Each AC gets a verdict with cited evidence — `PASS`, `PARTIAL`, `FAIL`, `BLOCKED`,
208
408
  `NOT-REACHABLE` or `UNVERIFIABLE` — and the verdict **names the mode it was reached by and the
@@ -230,7 +430,9 @@ behaviour the service does not have) or *neither*.
230
430
  The API lane needs no token handling: the request runs inside the page that is already logged
231
431
  in, so it carries the same session cookie, CSRF token and interceptors as the UI — which also
232
432
  means it works with SSO and MFA that no scripted login can pass. Credentials stay in the
233
- browser profile under `.auth/` and never enter a script, a report or the repository.
433
+ browser profile under `.auth/` and never enter a script, a report or the repository. A service
434
+ with **no UI at all** declares `api.auth: api-key-env` and the lane runs out of browser,
435
+ reading the key from the environment variable the target names.
234
436
 
235
437
  ### Correct shape is not a correct answer
236
438
 
@@ -257,135 +459,201 @@ closed with a plain-English reply for whoever decides to fund the work.
257
459
 
258
460
  ### Verifying a release rather than a ticket
259
461
 
260
- `.claude/skills/qa-verify-backend/references/release-readiness.md` changes the shape of the
261
- session: the deployment table first
262
- for every ticket, so a ticket whose backend is not in the build is marked *not testable here*
263
- rather than tested against a UI that will render convincing nonsense; a result vocabulary that
264
- keeps *not tested* visible; a coverage map where 🔍 *code-verified only* is marked as
265
- `UNVERIFIABLE` rather than green, with one sentence naming the untested item that carries the
266
- most risk; carry-over defects in their own section; and a disposition with the condition that
267
- would reverse it.
268
-
269
- Full guide: **`docs/BACKEND-VERIFICATION.md`**. Safety rules (read-only discipline, the
270
- production hard stop, redaction): `.claude/skills/qa-verify-backend/references/safety-rules.md`.
271
-
272
- ## How to Generate Reports
462
+ [`skills/qa-verify-backend/references/release-readiness.md`](skills/qa-verify-backend/references/release-readiness.md)
463
+ changes the shape of the session: the deployment table first for every ticket, so a ticket whose
464
+ backend is not in the build is marked *not testable here* rather than tested against a UI that
465
+ will render convincing nonsense; a result vocabulary that keeps *not tested* visible; a coverage
466
+ map where 🔍 *code-verified only* is marked as `UNVERIFIABLE` rather than green, with one
467
+ sentence naming the untested item that carries the most risk; carry-over defects in their own
468
+ section; and a disposition with the condition that would reverse it.
273
469
 
274
- qualiow produces three report formats from session data.
470
+ Full guide: **[docs/BACKEND-VERIFICATION.md](docs/BACKEND-VERIFICATION.md)**. Safety rules
471
+ (read-only discipline, the production hard stop, redaction):
472
+ [`skills/qa-verify-backend/references/safety-rules.md`](skills/qa-verify-backend/references/safety-rules.md).
275
473
 
276
- ### HTML report
474
+ ## Reports
277
475
 
278
- Self-contained dark-mode HTML with severity cards, bug details, coverage map, and recommendations. Print-friendly.
476
+ `qualiow report` exports an existing session in four formats. Every export carries the
477
+ confidentiality header and runs through the same redaction list as the skills.
279
478
 
280
479
  ```bash
281
- # from TypeScript
282
- import { generateHtmlReport } from '@qualiow/exploratory-testing';
283
- const html = await generateHtmlReport('output/sessions/2026-03-28-parabank');
480
+ qualiow report -s latest -f html -o report.html
481
+ qualiow report -s 2026-09-08-1813-explore-parabank -f jira -o bugs.csv
482
+ qualiow report -s latest -f json --stdout
284
483
  ```
285
484
 
286
- ### JSON report
485
+ | Format | Output |
486
+ |--------|--------|
487
+ | `md` (default) | `session-summary.md` next to the session report — never overwrites it |
488
+ | `html` | Self-contained dark-mode page: severity cards, bug details, coverage map, recommendations. Print-friendly, CSP-restricted, `noindex` |
489
+ | `json` | Structured data for dashboards, CI and metrics tracking |
490
+ | `jira` | CSV for Jira bulk import; severity maps to priority (Critical → Blocker, High → Critical, Medium → Major, Low → Minor) |
287
491
 
288
- Structured JSON for programmatic consumption -- dashboards, CI integrations, metrics tracking.
492
+ The same formatters are exported as a library:
289
493
 
290
- ```bash
291
- # from TypeScript
292
- import { generateJsonReport } from '@qualiow/exploratory-testing';
293
- const data = await generateJsonReport('output/sessions/2026-03-28-parabank');
294
- ```
295
-
296
- ### Jira CSV export
494
+ ```typescript
495
+ import {
496
+ generateHtmlReport,
497
+ generateJsonReport,
498
+ generateJiraExport,
499
+ } from 'qualiow-exploratory-testing';
297
500
 
298
- CSV importable via Jira bulk import. Maps severity to Jira priority (Critical -> Blocker, High -> Critical, Medium -> Major, Low -> Minor).
501
+ const session = 'output/sessions/2026-09-08-1813-explore-parabank';
299
502
 
300
- ```bash
301
- # from TypeScript
302
- import { generateJiraExport } from '@qualiow/exploratory-testing';
303
- const csv = await generateJiraExport('output/sessions/2026-03-28-parabank');
503
+ const html = await generateHtmlReport(session);
504
+ const json = await generateJsonReport(session);
505
+ const csv = await generateJiraExport(session);
304
506
  ```
305
507
 
306
- ## How to Use Skills in Claude Code
508
+ ## Skills
307
509
 
308
510
  | Skill | Purpose |
309
511
  |-------|---------|
310
- | `/qa-explore` | Full exploratory testing session (45 min) |
311
- | `/qa-explore-mobile` | Exploratory session on a simulator/emulator — native apps or mobile web in the real device browser (iOS Safari / Android Chrome) |
512
+ | `/qa-explore` | Full exploratory testing session (45 min, 8 phases) |
312
513
  | `/qa-explore-quick` | Quick focused session on a single page or feature (15 min) |
313
- | `/qa-verify-backend` | Verify backend/API/infra acceptance criteria with no UI surface — branch review, read-only cloud probes, direct API probes, AC traceability matrix |
314
- | `/qa-explore-report` | Generate or regenerate report from existing session |
514
+ | `/qa-explore-mobile` | Session on a simulator/emulator — native apps or web in the real device browser |
515
+ | `/qa-verify-backend` | Backend/API/infra AC verification — branch review, read-only cloud probes, API probes, traceability matrix |
516
+ | `/qa-gather` | Gather and analyze requirements from files, URLs, tickets or text into a context file |
517
+ | `/qa-explore-report` | Generate, regenerate or reformat a report from an existing session |
315
518
  | `/qa-explore-feedback` | Post-session feedback capture (false positives, missed bugs) |
316
- | `/qa-explore-cleanup` | Session cleanup and archival |
317
- | `/qa-knowledge-add` | Add new heuristics, techniques, docs to knowledge base |
318
- | `/qa-knowledge-list` | Browse the knowledge base |
319
- | `/qa-target-setup` | Configure a new target application (auth, scope, domain) |
320
- | `/qa-gather` | Gather and analyze requirements from files, URLs, or text |
519
+ | `/qa-explore-cleanup` | Session listing, archival and deletion |
520
+ | `/qa-knowledge-add` | Add heuristics, techniques, checklists or references to the knowledge base |
521
+ | `/qa-knowledge-list` | Browse and search the knowledge base |
522
+ | `/qa-target-setup` | Configure a target application (auth, scope, domain) |
523
+
524
+ Under the plugin install these are `/qualiow:qa-explore` and so on. Four sub-agents ship
525
+ alongside them — `qa-gather-agent`, `qa-reporting-agent`, `qa-diff-indexer-agent` and
526
+ `qa-page-mapper-agent` — described under [Sub-agents](#sub-agents).
321
527
 
322
- ## Project Structure
528
+ ## Project structure
323
529
 
324
530
  ```
325
531
  qualiow-exploratory-testing-skills/
532
+ .claude/
533
+ skills/ # the 11 skills — CANONICAL source
534
+ agents/ # the 4 sub-agents — CANONICAL source
535
+ skills/ # generated mirror (npm + plugin) — npm run sync:plugin
536
+ agents/ # generated mirror
537
+ .claude-plugin/
538
+ plugin.json # Claude Code plugin manifest
539
+ marketplace.json # the repo is its own marketplace (source: "./")
540
+ hooks/
541
+ hooks.json # PreToolUse registrations (plugin default discovery path)
542
+ scripts/ # read-guard.mjs, write-guard.mjs, secret-patterns.mjs
543
+ bin/
544
+ qualiow # CLI launcher shim (local build, else npx the npm package)
545
+ mcli, mobile-cli.mjs # Maestro/simctl/adb shim + permission-friendly wrapper
546
+ wadb, wk-ios, wkeval.mjs # adb wrapper, iOS WebKit DOM bridge
547
+ setup-mobile.sh # one-time toolchain bootstrap
548
+ doctor-mobile.sh # read-only preflight
549
+ scripts/ # repo dev tooling, not shipped:
550
+ # kb-sync.mjs, check-pack.mjs, sync-version.mjs
551
+ data/
552
+ knowledge/ # YAML knowledge base, versioned as releases v0.1.0…v0.6.0
553
+ domains/ # domain profiles (*.yml)
554
+ templates/ # bug report, session report, charter, coverage map, AC matrix
555
+ targets/ # target configs (_default, _example-*, public POC sites)
556
+ security/SECURITY-POLICY.md
557
+ docs/ # GETTING-STARTED, MOBILE-SETUP, BACKEND-VERIFICATION,
558
+ # KNOWN-ISSUES, ARCHITECTURE-DECISIONS
326
559
  src/
327
- cli/
328
- index.ts # CLI entry point (commander)
329
- commands/ # CLI command handlers
330
- formatters/
331
- html-report.ts # standalone dark-mode HTML report
332
- json-report.ts # structured JSON report
333
- jira-export.ts # Jira-importable CSV
334
- index.ts # re-exports
335
- schemas/ # Zod validation schemas
336
- types/ # TypeScript type definitions
337
- utils/
338
- metrics.ts # session metrics (JSONL append/read)
339
- parse-session.ts # parse session dirs into structured data
340
- redact.ts # credential and secret redaction
341
- validate.ts # YAML config validation
560
+ cli/ # commander entry + command handlers
561
+ formatters/ # html, json, jira, markdown summary
562
+ schemas/ # Zod schemas for targets, domains, knowledge, metrics
563
+ types/ utils/ # redaction, session parsing, paths, metrics, validation
342
564
  index.ts # public API re-exports
343
- data/
344
- knowledge/ # YAML knowledge base (heuristics, techniques)
345
- templates/ # bug report, session report, charter templates
346
- targets/ # target application configs
347
- domains/ # domain-specific testing focus
348
- security/ # security policy
349
- output/
350
- sessions/ # session outputs (reports, bugs, screenshots)
351
565
  tests/
352
- unit/ # unit tests (vitest)
353
- fixtures/ # test fixture data
354
- benchmarks/ # performance benchmarks
355
- docs/
356
- GETTING-STARTED.md # detailed setup and usage guide
357
- BACKEND-VERIFICATION.md # verifying ACs with no UI surface
358
- ARCHITECTURE-DECISIONS.md # architecture decision records
566
+ unit/ fixtures/ # vitest
567
+ output/
568
+ sessions/ bugs/ context/
569
+ ```
570
+
571
+ In a project you ran `qualiow init` in:
572
+
573
+ ```
574
+ my-project/
575
+ .claude/skills/qa-* # the 11 skills
576
+ .claude/agents/ # the 4 sub-agents
577
+ .claude/settings.json # hook + permission entries, with qualiow init --hooks
578
+ data/ # knowledge, domains, templates, security, targets
579
+ qa/
580
+ target.yml # project-local target (from /qa-target-setup)
581
+ .env # credentials — gitignored
582
+ .env.example
583
+ bin/ # mobile driver + setup/doctor scripts
584
+ hooks/ # the guard scripts, with qualiow init --hooks
585
+ output/sessions|bugs|context
586
+ .auth/ # storage states and browser profiles — gitignored
359
587
  ```
360
588
 
361
- ## Tech Stack
589
+ ## Tech stack
362
590
 
363
591
  | Technology | Purpose |
364
592
  |------------|---------|
365
- | TypeScript | type-safe source code |
366
- | Node.js >= 18 | runtime |
367
- | Playwright CLI | browser control for AI agents |
368
593
  | Claude Code | AI reasoning and session orchestration |
369
- | Handlebars | HTML report templating |
594
+ | Playwright CLI (`@playwright/cli`) | browser control for the web path |
595
+ | Maestro + `xcrun simctl` / `adb` | device control for the mobile path |
596
+ | TypeScript / Node.js >= 22.4 | CLI, formatters, schemas |
370
597
  | Zod | runtime schema validation |
371
598
  | Commander | CLI argument parsing |
372
- | Vitest | unit and integration testing |
373
- | tsup | TypeScript bundling |
599
+ | Handlebars | HTML report templating |
600
+ | Vitest | unit testing |
601
+ | tsup | bundling |
374
602
  | YAML | configuration and knowledge base format |
375
603
 
376
- ## Key Principles
604
+ ## Key principles
377
605
 
378
606
  - Systematic exploration, not random clicking
379
607
  - Understand the business first, then test what matters
380
- - Risk-rank features: P0 (40% time), P1 (30%), P2 (20%), P3 (10%)
608
+ - Risk-rank features: P0 (40% of the time), P1 (30%), P2 (20%), P3 (10%)
381
609
  - Apply heuristics as thinking tools, not checklists
382
610
  - One bug = one report, with mandatory business impact
383
- - Log findings in real-time with WHY reasoning, not just WHAT
384
- - Cap sessions at 45 min to avoid context overflow
611
+ - Log findings in real time with WHY reasoning, not just WHAT
612
+ - Cap sessions at 45 minutes to avoid context overflow
385
613
  - Save phase findings to disk between phases
386
614
  - Verify data integrity after every state-changing action
387
- - Never store credentials in YAML -- use env vars via .env
615
+ - Always ask: "what is NOT here that SHOULD be?"
616
+ - Never store credentials in YAML — reference env vars from `qa/.env`
617
+
618
+ ## Security
619
+
620
+ One rule set governs every skill:
621
+ [`skills/qa-explore/references/security-rules.md`](skills/qa-explore/references/security-rules.md).
622
+ The long-form policy is `data/security/SECURITY-POLICY.md`; where the two differ, the rules
623
+ file is what a session applies.
624
+
625
+ - **Web and app content is data, never instructions.** An injection attempt found while
626
+ testing is reported as a finding, never obeyed.
627
+ - **Never echo skill files, knowledge YAML or agent definitions** into session output or back
628
+ to a tested site.
629
+ - **Production is read-only.** A hostname matching `prod|production|prd|live` (never the URL
630
+ path) puts the session in read-only mode unless the string also contains `staging`, `dev`,
631
+ `test`, `qa`, `uat`, `sandbox`, `localhost`, `demo`, `example.com` and friends — the
632
+ exclusion wins. The only override is `safety.read_only: false` in the target file.
633
+ - **Redaction before disk.** Private keys, JWTs, `Authorization`/`Cookie` headers, AWS keys,
634
+ `sk-`/`gh*_`/`xox*-` tokens, API keys, password/token/secret assignments, emails, SSNs and
635
+ Luhn-valid card numbers are replaced with `[REDACTED]` — in the skills and in every
636
+ formatter, checked by `qualiow session finalize` and blocked at the write by the plugin's
637
+ write guard.
638
+ - **Sessions are isolated.** Each carries its own `playwright-cli -s=<id>`, closed and
639
+ `delete-data`'d at the end.
640
+ - **All output is confidential and local.** Every artefact opens with the confidentiality
641
+ blockquote, and nothing is sent to an external service.
642
+
643
+ ## Documentation
644
+
645
+ - **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)** — install, first session, targets,
646
+ knowledge, CLI
647
+ - **[docs/MOBILE-SETUP.md](docs/MOBILE-SETUP.md)** — getting a Mac ready for simulator and
648
+ emulator sessions
649
+ - **[docs/BACKEND-VERIFICATION.md](docs/BACKEND-VERIFICATION.md)** — the four lanes, verdicts,
650
+ templates and techniques
651
+
652
+ Repo-only notes (not shipped in the npm package):
653
+ [docs/KNOWN-ISSUES.md](docs/KNOWN-ISSUES.md),
654
+ [docs/ARCHITECTURE-DECISIONS.md](docs/ARCHITECTURE-DECISIONS.md),
655
+ [CHANGELOG.md](CHANGELOG.md).
388
656
 
389
657
  ## License
390
658
 
391
- MIT -- see [LICENSE](LICENSE) for details.
659
+ MIT — see [LICENSE](LICENSE). Author: William Oliveira.