@brunosps00/dev-workflow 0.8.0 → 0.8.1

package/README.md

@@ -63,10 +63,10 @@ Executes a one-off change with workflow guarantees (validation, atomic commit) w
 ### Quality
 
 #### `/dw-run-qa`
-Validates the implementation against PRD, TechSpec, and Tasks using Playwright MCP for E2E browser automation. Tests happy paths, edge cases, negative flows, and regressions while verifying WCAG 2.2 accessibility compliance. Generates a QA report, documents bugs with screenshot evidence, and detects stub/placeholder pages.
+Validates the implementation against PRD, TechSpec, and Tasks. **Mode-aware**: in UI mode, drives Playwright MCP for E2E browser tests with happy paths, edge cases, negative flows, regressions, WCAG 2.2 accessibility, and screenshot evidence. In API mode (auto-detected when no UI deps are in the manifest, or forced via `--api`), composes per-RF `.http` / pytest+httpx / supertest / WebApplicationFactory / reqwest scripts from the bundled `api-testing-recipes` skill, executes them, and writes JSONL request/response logs to `QA/logs/api/` as evidence. The matrix expands to {200 happy / 4xx validation/auth/authz/not-found/conflict / 5xx / contract drift / cross-tenant denial}. Optional `--from-openapi` adds a baseline derived from the project's OpenAPI spec. Generates a QA report, documents bugs with mode-aware evidence, and detects stub/placeholder pages (UI) or unmapped spec endpoints (API).
 
 #### `/dw-fix-qa`
-Fixes bugs found during QA testing with evidence-driven retesting via Playwright MCP. Runs iterative cycles of identify, fix, retest, updating `QA/bugs.md` and `QA/qa-report.md` with status and retest evidence including screenshots and logs.
+Fixes bugs found during QA testing with evidence-driven retesting. **Mode-aware**: in UI mode replays the failing flow via Playwright MCP and saves a retest screenshot; in API mode replays the failing `.http`/recipe and appends a `verdict: PASS|FAIL` JSONL line to `QA/logs/api/BUG-NN-retest.log`. Runs iterative cycles of identify, fix, retest, updating `QA/bugs.md` and `QA/qa-report.md` with status and mode-correct evidence.
 
 #### `/dw-review-implementation`
 Compares documented requirements (PRD + TechSpec + Tasks) against actual code as a Level 2 review. Maps each requirement to endpoints and tasks with evidence, identifies gaps, partial implementations, and extra undocumented code. Does not execute fixes — waits for user instruction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/commands/dw-fix-qa.md

@@ -2,8 +2,9 @@
 You are an AI assistant specialized in post-QA bug fixing with evidence-driven retesting.
 
 <critical>Use Context7 MCP to look up technical documentation needed during fixes</critical>
-<critical>Use Playwright MCP to retest corrected flows</critical>
+<critical>In UI mode, use Playwright MCP to retest corrected flows. In API mode, use the bundled `api-testing-recipes` skill to replay the original `.http`/recipe and append a new line to the JSONL log under `QA/logs/api/`.</critical>
 <critical>Update artifacts inside {{PRD_PATH}}/QA/ after each cycle</critical>
+<critical>Detect mode by reading the bug entry's `Mode:` field (`ui` or `api`) — every bug created by `/dw-run-qa` records the mode used at QA time. If the field is missing (legacy bug), fall back to the project-level mode auto-detection used by `/dw-run-qa` Step 0.</critical>
 
 ## When to Use
 - Use when fixing bugs identified during QA testing with iterative retesting until stable
@@ -17,9 +18,10 @@ You are an AI assistant specialized in post-QA bug fixing with evidence-driven r
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
-- `dw-verify`: **ALWAYS** — invoked before marking any bug as `Fixed` or `Closed` in `QA/bugs.md`. Without a VERIFICATION REPORT PASS (test + lint + build) **and** retest evidence, status stays `Reopened` or `Under review`.
-- `webapp-testing`: support for structuring retests, captures, and scripts when complementary to Playwright MCP
-- `vercel-react-best-practices`: use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression
+- `dw-verify`: **ALWAYS** — invoked before marking any bug as `Fixed` or `Closed` in `QA/bugs.md`. Without a VERIFICATION REPORT PASS (test + lint + build) **and** retest evidence (screenshot in UI mode OR JSONL log line in API mode), status stays `Reopened` or `Under review`.
+- `webapp-testing`: (UI mode) support for structuring retests, captures, and scripts when complementary to Playwright MCP
+- `vercel-react-best-practices`: (UI mode) use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression
+- `api-testing-recipes`: **(API mode — ALWAYS)** source of the recipe used at QA time. Re-execute the original `.http`/pytest/supertest/etc. file for the bug's RF; append the retest result to a fresh JSONL log under `QA/logs/api/BUG-NN-retest.log`
 
 ## Input Variables
 
@@ -32,8 +34,8 @@ When available in the project under `./.agents/skills/`, use these skills as ope
 Execute an iterative cycle of:
 1. Identify open bugs in `QA/bugs.md`
 2. Fix in code with minimum impact
-3. Retest via Playwright MCP
-4. Update status, evidence, scripts, and QA report
+3. Retest via the right tool for the bug's mode — Playwright MCP (UI) or `api-testing-recipes` recipe (API)
+4. Update status, evidence (screenshot OR JSONL log line), scripts, and QA report
 5. Repeat until blocking bugs are closed
 
 ## Reference Files
@@ -44,9 +46,12 @@ Execute an iterative cycle of:
 - QA Test Credentials: `.dw/templates/qa-test-credentials.md`
 - Bugs: `{{PRD_PATH}}/QA/bugs.md`
 - QA Report: `{{PRD_PATH}}/QA/qa-report.md`
-- Evidence: `{{PRD_PATH}}/QA/screenshots/`
-- Logs: `{{PRD_PATH}}/QA/logs/`
-- Playwright Scripts: `{{PRD_PATH}}/QA/scripts/`
+- Evidence — UI (screenshots): `{{PRD_PATH}}/QA/screenshots/`
+- Logs — UI (console/network): `{{PRD_PATH}}/QA/logs/`
+- Logs — API (JSONL request/response): `{{PRD_PATH}}/QA/logs/api/`
+- Playwright Scripts (UI mode): `{{PRD_PATH}}/QA/scripts/`
+- API Test Scripts (API mode): `{{PRD_PATH}}/QA/scripts/api/`
+- API-testing recipes (skill): `.agents/skills/api-testing-recipes/`
 
 ## Required Flow
 
@@ -73,9 +78,12 @@ Execute an iterative cycle of:
 - Maintain compatibility with PRD/TechSpec and project patterns
 - Validate build/lint/minimal local tests after each fix block
 
-### 3. E2E Retest (Playwright MCP)
+### 3. Mode-Aware Retest
+
+For each fixed bug, pick the branch matching the bug's `Mode:` field (recorded by `/dw-run-qa` Step 0).
+
+#### 3-UI (UI mode) — Playwright MCP
 
-For each fixed bug:
 1. Reproduce the original scenario
 2. Execute the corrected flow
 3. Validate expected behavior
@@ -89,9 +97,20 @@ For each fixed bug:
 7. Record in the QA report which user/profile was used in the retest
 8. If the retest requires persistent auth, request inspection beyond MCP, or more faithful real-browser reproduction, record this in the report
 
+#### 3-API (API mode) — `api-testing-recipes` recipe
+
+1. Read `.agents/skills/api-testing-recipes/SKILL.md` and locate the recipe used at QA time (the original `RF-XX-[slug].<ext>` references it in its header comment).
+2. Locate the failing JSONL line in `QA/logs/api/RF-XX-[slug].log` via the bug's `Evidence path:` field.
+3. Re-execute the SAME `.http` block (or test case) — same recipe, same matrix tier — that produced the failure. Use the same credentials/role mapping.
+4. Save the retest script as a separate file for traceability:
+   - `QA/scripts/api/BUG-[NN]-retest.<ext>` (e.g., `BUG-03-retest.http` or `test_BUG_03_retest.py`)
+5. Append a fresh JSONL line to `QA/logs/api/BUG-[NN]-retest.log` per `references/log-conventions.md`. Required fields: `ts`, `rf` = `BUG-[NN]`, `case` = same as the original failure, `verdict` = `PASS` (closes the bug) or `FAIL` (cycle continues).
+6. Assert: the original failure no longer reproduces AND the bug's expected behavior holds. Both must be true to mark `verdict: PASS`.
+7. Record in the QA report which user/profile/token was used in the retest (token role, NOT the token value).
+
 ### 3.5. Final Verification Before Status Change
 
-<critical>Invoke the `dw-verify` skill before changing any bug's status to `Fixed` or `Closed`. The VERIFICATION REPORT (test + lint + build) must be PASS **and** Playwright retest evidence must be saved. Without both, the status does not change.</critical>
+<critical>Invoke the `dw-verify` skill before changing any bug's status to `Fixed` or `Closed`. The VERIFICATION REPORT (test + lint + build) must be PASS **and** retest evidence must be saved — a screenshot under `QA/screenshots/` (UI mode) OR a `verdict: "PASS"` JSONL line under `QA/logs/api/` (API mode). Without both, the status does not change.</critical>
 
 ### 4. Update Artifacts
 
@@ -100,7 +119,9 @@ Update `QA/bugs.md` for each bug:
 ```markdown
 - **Status:** Fixed (awaiting validation) | Reopened | Closed
 - **Retest:** PASSED/FAILED on [YYYY-MM-DD]
-- **Retest Evidence:** `QA/screenshots/BUG-[NN]-retest-PASS.png`
+- **Retest Evidence:**
+  - UI mode: `QA/screenshots/BUG-[NN]-retest-PASS.png`
+  - API mode: `QA/logs/api/BUG-[NN]-retest.log#L<line>`
 ```
 
 Update `QA/qa-report.md`:

package/scaffold/en/commands/dw-run-qa.md

@@ -9,7 +9,7 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 ## Pipeline Position
 **Predecessor:** `/dw-run-plan` or `/dw-run-task` | **Successor:** `/dw-code-review` (auto-fixes bugs internally before completing)
 
-<critical>Use the Playwright MCP to execute all E2E tests</critical>
+<critical>In UI mode, use the Playwright MCP for all E2E tests. In API mode (no UI in the project, OR `--api` flag), use the bundled `api-testing-recipes` skill to generate `.http` / pytest+httpx / supertest / WebApplicationFactory / reqwest scripts and capture request/response logs as evidence.</critical>
 <critical>Verify ALL requirements from the PRD and TechSpec before approving</critical>
 <critical>QA is NOT complete until ALL checks pass</critical>
 <critical>Document ALL bugs found with screenshot evidence</critical>
@@ -20,9 +20,10 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
-- `webapp-testing`: support for structuring test flows, retests, screenshots, and logs when complementary to Playwright MCP
-- `vercel-react-best-practices`: use only if the frontend under test is React/Next.js and there is indication of regression related to rendering, fetching, hydration, or perceived performance
-- `ui-ux-pro-max`: use when validating design consistency, color palettes, typography, spacing, and visual hierarchy against industry standards
+- `webapp-testing`: (UI mode) support for structuring test flows, retests, screenshots, and logs when complementary to Playwright MCP
+- `vercel-react-best-practices`: (UI mode) use only if the frontend under test is React/Next.js and there is indication of regression related to rendering, fetching, hydration, or perceived performance
+- `ui-ux-pro-max`: (UI mode) use when validating design consistency, color palettes, typography, spacing, and visual hierarchy against industry standards
+- `api-testing-recipes`: **(API mode — ALWAYS)** validated snippets for `.http`, pytest+httpx, supertest, WebApplicationFactory, reqwest. Composes per-RF test files in `QA/scripts/api/` and JSONL logs in `QA/logs/api/` per its references
 
 ## Analysis Tools
 
@@ -38,12 +39,13 @@ When available in the project under `./.agents/skills/`, use these skills as ope
 ## Objectives
 
 1. Validate implementation against PRD, TechSpec, and Tasks
-2. Execute E2E tests with Playwright MCP
-3. Cover positive, negative, boundary, and relevant regression scenarios
-4. Verify accessibility (WCAG 2.2)
-5. Perform visual checks
-6. Document bugs found
-7. Generate final QA report
+2. **Detect mode** (UI vs API-only) and pick the right execution path
+3. Execute E2E tests via Playwright MCP (UI mode) OR via the `api-testing-recipes` skill (API mode)
+4. Cover positive, negative, boundary, and relevant regression scenarios
+5. Verify accessibility (UI mode = WCAG 2.2; API mode = error-shape and surface contracts)
+6. Perform visual checks (UI mode only — skipped in API mode)
+7. Document bugs found
+8. Generate final QA report
 
 ## File Locations
 
@@ -56,10 +58,13 @@ When available in the project under `./.agents/skills/`, use these skills as ope
 - Evidence folder (required): `{{PRD_PATH}}/QA/`
 - Output Report: `{{PRD_PATH}}/QA/qa-report.md`
 - Bugs found: `{{PRD_PATH}}/QA/bugs.md`
-- Screenshots: `{{PRD_PATH}}/QA/screenshots/`
-- Logs (console/network): `{{PRD_PATH}}/QA/logs/`
-- Playwright test scripts: `{{PRD_PATH}}/QA/scripts/`
+- Screenshots (UI mode): `{{PRD_PATH}}/QA/screenshots/`
+- Logs — UI (console/network): `{{PRD_PATH}}/QA/logs/`
+- Logs — API (JSONL request/response): `{{PRD_PATH}}/QA/logs/api/`
+- Playwright test scripts (UI mode): `{{PRD_PATH}}/QA/scripts/`
+- API test scripts (API mode — `.http` / pytest+httpx / supertest / etc.): `{{PRD_PATH}}/QA/scripts/api/`
 - Consolidated checklist: `{{PRD_PATH}}/QA/checklist.md`
+- API-testing recipes (skill): `.agents/skills/api-testing-recipes/`
 
 ## Multi-Project Context
 
@@ -74,6 +79,43 @@ Refer to `.dw/rules/` for project-specific URLs and frameworks.
 
 ## Process Steps
 
+### 0. Mode Detection (UI vs API) -- Required FIRST
+
+Decide whether the project has a testable UI or is API-only before any browser/API setup. The chosen mode drives every subsequent step.
+
+**Auto-detection (same matrix used by `/dw-dockerize`):**
+
+| Signal | UI mode | API mode |
+|--------|---------|----------|
+| `package.json` deps | `next`, `vite`, `react`, `vue`, `svelte`, `@angular/*`, `nuxt`, `astro`, `solid-js`, `remix` | none of the above |
+| `pyproject.toml` / `requirements*.txt` | `jinja2`, `django` (full), `flask` + `flask_login`/`render_template` | `fastapi`, `flask` (JSON only), `starlette`, `litestar` |
+| `*.csproj` | `Microsoft.AspNetCore.Mvc`, Razor, Blazor | `Microsoft.AspNetCore.Mvc.Core` only, minimal API templates |
+| `Cargo.toml` | `yew`, `leptos`, `dioxus`, `sycamore` | `axum`, `actix-web`, `rocket`, `warp` (no template engine) |
+
+If NO UI signals match → **API mode**. If at least one matches → **UI mode** (default).
+
+**Manual override (flags):**
+
+- `--api` forces API mode (useful when running headless API tests inside a fullstack project where the UI is irrelevant for this run).
+- `--ui` forces UI mode (raises a clear error if no UI dep is detected — this prevents accidentally running browser tests against a backend-only repo).
+- `--from-openapi <path-or-url>` adds an OpenAPI baseline on top of API mode (see `.agents/skills/api-testing-recipes/references/openapi-driven.md`).
+
+**Effect on subsequent steps:**
+
+| Step | UI mode | API mode |
+|------|---------|----------|
+| 2 — Environment Preparation | full Playwright + browser setup | API client setup, no browser; create `QA/scripts/api/` and `QA/logs/api/` |
+| 3 — Menu Page Verification | required, blocking | **skipped** |
+| 4 — E2E Tests | Playwright MCP | `api-testing-recipes` skill (recipe per stack) |
+| 5 — Accessibility | WCAG 2.2 with browser tools | API-surface checks (error shape, status semantics, leak detection) |
+| 6 — Visual Checks | required (mobile + desktop) | **skipped** |
+| 7-8 — Bug Documentation + Report | screenshots as evidence | JSONL logs as evidence (`evidence_type: api-log`) |
+| 9 — Fix-Retest Loop | unchanged shape; replays Playwright | unchanged shape; replays the recipe and writes new log line |
+
+Record the chosen mode in the QA report frontmatter (`mode: ui | api | mixed`). When in doubt, ask the user before proceeding — never silently fall back.
+
+<critical>If neither UI nor API signal is detectable (e.g., empty repo), abort with: "Cannot determine QA mode. Run `/dw-analyze-project` first OR pass `--ui` or `--api` explicitly."</critical>
+
 ### 1. Documentation Analysis (Required)
 
 - Read the PRD and extract ALL numbered functional requirements (RF-XX)
@@ -109,9 +151,11 @@ If NO credentials are found, STOP and ask the user before continuing. Do NOT gue
 - Confirm the page loaded correctly with `browser_snapshot`
 - If persistent session, auth import, or network inspection beyond MCP is needed, complement with `webapp-testing`
 
-### 3. Menu Page Verification (Required -- Execute BEFORE RF tests)
+### 3. Menu Page Verification (UI mode only -- Required, Execute BEFORE RF tests)
 
-<critical>BEFORE testing individual RFs, verify that EACH menu item in the module leads to a FUNCTIONAL and UNIQUE page. This verification is blocking -- if it fails, QA CANNOT be approved.</critical>
+**In API mode, this step is SKIPPED.** API surfaces have no menus; the equivalent check (every advertised endpoint exists and answers) is folded into Step 4-API.
+
+<critical>(UI mode) BEFORE testing individual RFs, verify that EACH menu item in the module leads to a FUNCTIONAL and UNIQUE page. This verification is blocking -- if it fails, QA CANNOT be approved.</critical>
 
 For each menu item in the module:
 1. Navigate to the page via `browser_navigate`
@@ -146,7 +190,11 @@ digraph menu_check {
 }
 ```
 
-### 4. E2E Tests with Playwright MCP (Required)
+### 4. E2E Tests (Required, mode-aware)
+
+This step has two branches; pick the one matching the mode chosen in Step 0.
+
+#### 4-UI (UI mode) -- Playwright MCP
 
 Use Playwright MCP tools to test each flow:
 
@@ -179,6 +227,39 @@ For each functional requirement from the PRD:
 <critical>It is not enough to validate only the happy path. Each requirement must be exercised against its boundary states and most likely regressions</critical>
 <critical>If a requirement cannot be fully validated via E2E, QA must be marked as REJECTED or BLOCKED, never APPROVED</critical>
 
+#### 4-API (API mode) -- `api-testing-recipes` skill
+
+Use the bundled `api-testing-recipes` skill to compose tests. The skill picks the right recipe per stack (default `.http` / REST Client; `pytest+httpx`, `supertest`, `WebApplicationFactory`, `reqwest` per language) and writes scripts and JSONL logs as evidence.
+
+Process:
+
+1. **Read** `.agents/skills/api-testing-recipes/SKILL.md` and select the recipe that matches the project's primary backend stack. Default to `recipes/http-rest-client.md` unless the project already runs `pytest`/`vitest`/`dotnet test`/`cargo test`, in which case prefer the matching stack-specific recipe so QA tests live alongside unit tests.
+2. **For each functional requirement (RF-XX) in the PRD**, derive the matrix per `.agents/skills/api-testing-recipes/references/matrix-conventions.md`:
+   - 200 happy path
+   - 4xx -- validation (missing field, wrong type, out of range)
+   - 4xx -- auth (no token, expired, malformed)
+   - 4xx -- authorization (valid token, wrong role)
+   - 4xx -- not found
+   - 4xx -- conflict
+   - 5xx -- server error (only if synthetically reproducible)
+   - **Contract drift** (response shape vs OpenAPI / TS types) -- mandatory
+   - **Authorization cross-tenant** (token from another org) -- mandatory if multi-tenant
+3. **Generate one file per RF** at `{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].<ext>` using the recipe's structure. Wire credentials via the patterns in `.agents/skills/api-testing-recipes/references/auth-patterns.md` (NEVER hardcode tokens).
+4. **Execute** each request (`curl` for `.http`; the project's runner for stack-specific). For EACH request, append a JSONL line to `{{PRD_PATH}}/QA/logs/api/RF-XX-[slug].log` per `references/log-conventions.md`. Redact `Authorization`/`Cookie`/`X-API-Key` headers and any response field matching `password*`/`secret*`/`*_hash`/`token*`.
+5. **Assert** per matrix expectation:
+   - Status code matches expected
+   - Response body matches schema (use `jq` for `.http` mode, framework matchers per stack)
+   - Required headers present (e.g., `Content-Type: application/json`)
+   - No leaked internal fields
+6. **Mark the requirement** as PASSED or FAILED with a one-line summary citing the log file path and (if FAILED) the failing JSONL line number.
+7. **Optional**: if the project exposes an OpenAPI spec (`openapi.yaml`, `openapi.json`, runtime `/openapi.json`), follow `references/openapi-driven.md` to generate a baseline. Add the `--from-openapi <path-or-url>` flag to make this explicit.
+
+OpenAPI baseline note: if `--from-openapi` is used, the generated tests live alongside hand-derived ones with filename pattern `openapi-RF-XX-[path-slug].<ext>`. Tag any unmapped spec endpoint as a documentation gap in the QA report (`openapi-no-rf-*`).
+
+<critical>(API mode) Every endpoint that mutates or reads tenant-scoped data MUST have a cross-tenant denial test. Skipping is allowed only for explicitly single-tenant systems and must be recorded as a `pytest.skip`/`it.skip`/equivalent with a reason.</critical>
+<critical>(API mode) Logs are evidence. Every PASS or FAIL claim in the QA report must cite a JSONL line under `QA/logs/api/`. No log = no evidence = QA cannot be APPROVED.</critical>
+<critical>(API mode) NEVER hardcode tokens or credentials in committed scripts. Use `@variable`/env-var references.</critical>
+
 ### 4.1. Required Minimum Matrix per Requirement
 
 For each RF, QA must explicitly answer:
@@ -201,9 +282,9 @@ Examples of edge cases that must be considered whenever relevant:
 - re-entrance/repeated actions
 - API failures, loading, and intermediate states
 
-### 5. Accessibility Checks (Required)
+### 5. Accessibility / API-Surface Checks (Required, mode-aware)
 
-Verify for each screen/component (WCAG 2.2):
+In **UI mode**, verify each screen/component against WCAG 2.2:
 
 - [ ] Keyboard navigation works (Tab, Enter, Escape)
 - [ ] Interactive elements have descriptive labels
@@ -217,13 +298,26 @@ Verify for each screen/component (WCAG 2.2):
 Use `browser_press_key` to test keyboard navigation.
 Use `browser_snapshot` to verify labels and semantic structure.
 
-### 6. Visual Checks (Required)
+**In API mode**, the WCAG checklist above is REPLACED by API-surface checks:
+
+- [ ] Every endpoint returns the correct `Content-Type` header
+- [ ] Errors follow a consistent shape (e.g., `{ "error": { "code": "...", "message": "..." } }`)
+- [ ] `401` (auth missing/invalid) is distinct from `403` (auth present but unauthorized)
+- [ ] Error responses do NOT leak stack traces, internal IDs, SQL fragments, or environment hints
+- [ ] Sensitive fields (`password*`, `*_hash`, `secret*`, `token*`) NEVER appear in any response body
+- [ ] Rate-limited endpoints return `429` with a `Retry-After` header (when applicable)
+
+Each check FAILED becomes a HIGH severity bug in `QA/bugs.md` with `evidence_type: api-log` pointing to the failing JSONL line.
+
+### 6. Visual Checks (UI mode only -- Required)
+
+**In API mode, this step is SKIPPED.** The QA report omits the "Visual" section entirely.
 
 - Capture screenshots of main screens with `browser_take_screenshot` and save to `{{PRD_PATH}}/QA/screenshots/`
 - Check layouts in different states (empty, with data, error, loading)
 - Document visual inconsistencies found
 
-### 6.1. Mobile Validation (Required)
+### 6.1. Mobile Validation (UI mode only -- Required)
 
 <critical>ALL visual checks MUST include tests at mobile viewport (375px) IN ADDITION to desktop (1440px). QA approval REQUIRES that BOTH resolutions are functional and visually acceptable. If the mobile layout is broken, unusable, or visually degraded, QA CANNOT be approved.</critical>
 
@@ -246,13 +340,15 @@ For each bug found, create an entry in `{{PRD_PATH}}/QA/bugs.md`:
 
 - **Severity:** High/Medium/Low
 - **Affected RF:** RF-XX
-- **Component:** [component/page]
+- **Component:** [component/page or endpoint path]
+- **Mode:** ui | api
 - **Steps to Reproduce:**
   1. [step 1]
   2. [step 2]
 - **Expected Result:** [what should happen]
 - **Actual Result:** [what happens]
-- **Screenshot:** `QA/screenshots/[file].png`
+- **Evidence type:** screenshot | api-log
+- **Evidence path:** `QA/screenshots/[file].png` (UI mode) OR `QA/logs/api/RF-XX-[slug].log#L<line>` (API mode)
 - **Status:** Open
 ```
 
@@ -296,10 +392,15 @@ Generate report in `{{PRD_PATH}}/QA/qa-report.md`:
 [Final QA assessment]
 ```
 
-### 9. QA Fix-Retest Loop (Automatic)
+### 9. QA Fix-Retest Loop (Automatic, mode-aware)
 
 <critical>QA does NOT end at the first report. If bugs are found, enter an automatic fix-retest loop until QA is APPROVED or explicitly BLOCKED.</critical>
 
+**Mode-aware behavior:** the loop's structure (max 5 cycles, atomic commit per fix, regression checks, exit criteria) is identical in both modes. What changes is the EVIDENCE replayed:
+
+- UI mode: re-run the Playwright flow, capture new `BUG-NN-retest.png` screenshot.
+- API mode: re-run the same `.http`/recipe via the recipe's runner, append a new line to `QA/logs/api/BUG-NN-retest.log` with `verdict: "PASS"` (closes the bug) or `verdict: "FAIL"` (keeps the cycle going).
+
 After generating the initial QA report:
 
 ```dot

package/scaffold/pt-br/commands/dw-fix-qa.md

@@ -2,8 +2,9 @@
 Você é um assistente IA especializado em correção de bugs pós-QA com reteste orientado por evidências.
 
 <critical>Use Context7 MCP para consultar documentação técnica necessária durante correções</critical>
-<critical>Use Playwright MCP para retestar os fluxos corrigidos</critical>
+<critical>Em modo UI, use Playwright MCP para retestar os fluxos corrigidos. Em modo API, use a skill bundled `api-testing-recipes` para reexecutar a `.http`/recipe original e anexar nova linha ao log JSONL em `QA/logs/api/`.</critical>
 <critical>Atualize os artefatos dentro de {{PRD_PATH}}/QA/ a cada ciclo</critical>
+<critical>Detecte modo lendo o campo `Modo:` da entrada do bug (`ui` ou `api`) — todo bug criado pelo `/dw-run-qa` registra o modo usado no QA. Se o campo estiver ausente (bug legado), caia para a auto-detecção de modo do projeto usada pelo `/dw-run-qa` Etapa 0.</critical>
 
 ## Quando Usar
 - Use para corrigir bugs identificados durante testes de QA com reteste iterativo até estabilizar
@@ -17,9 +18,10 @@ Você é um assistente IA especializado em correção de bugs pós-QA com retest
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte operacional sem substituir este comando:
 
-- `dw-verify`: **SEMPRE** — invocada antes de marcar qualquer bug como `Corrigido` ou `Fechado` no `QA/bugs.md`. Sem VERIFICATION REPORT PASS (test + lint + build) + evidência de reteste, o status permanece `Reaberto` ou `Em análise`.
-- `webapp-testing`: suporte para estruturar retestes, capturas e scripts quando complementar ao Playwright MCP
-- `vercel-react-best-practices`: use apenas se a correção afetar frontend React/Next.js e houver risco de regressão de renderização, hidratação, fetching ou performance
+- `dw-verify`: **SEMPRE** — invocada antes de marcar qualquer bug como `Corrigido` ou `Fechado` no `QA/bugs.md`. Sem VERIFICATION REPORT PASS (test + lint + build) + evidência de reteste (screenshot em modo UI OU linha JSONL em modo API), o status permanece `Reaberto` ou `Em análise`.
+- `webapp-testing`: (modo UI) suporte para estruturar retestes, capturas e scripts quando complementar ao Playwright MCP
+- `vercel-react-best-practices`: (modo UI) use apenas se a correção afetar frontend React/Next.js e houver risco de regressão de renderização, hidratação, fetching ou performance
+- `api-testing-recipes`: **(modo API — SEMPRE)** fonte da recipe usada no QA. Re-execute o arquivo `.http`/pytest/supertest/etc. original do RF do bug; anexe o resultado do reteste a um log JSONL fresco em `QA/logs/api/BUG-NN-retest.log`
 
 ## Variáveis de Entrada
 
@@ -32,8 +34,8 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como sup
 Executar ciclo iterativo de:
 1. Identificar bugs em aberto no `QA/bugs.md`
 2. Corrigir no código com menor impacto possível
-3. Retestar via Playwright MCP
-4. Atualizar status, evidências, scripts e relatório de QA
+3. Retestar via ferramenta certa para o modo do bug — Playwright MCP (UI) ou recipe `api-testing-recipes` (API)
+4. Atualizar status, evidências (screenshot OU linha JSONL), scripts e relatório de QA
 5. Repetir até encerrar bugs bloqueantes
 
 ## Arquivos de Referência
@@ -44,9 +46,12 @@ Executar ciclo iterativo de:
 - Credenciais de Teste QA: `.dw/templates/qa-test-credentials.md`
 - Bugs: `{{PRD_PATH}}/QA/bugs.md`
 - Relatório QA: `{{PRD_PATH}}/QA/qa-report.md`
-- Evidências: `{{PRD_PATH}}/QA/screenshots/`
-- Logs: `{{PRD_PATH}}/QA/logs/`
-- Scripts Playwright: `{{PRD_PATH}}/QA/scripts/`
+- Evidências — UI (screenshots): `{{PRD_PATH}}/QA/screenshots/`
+- Logs — UI (console/rede): `{{PRD_PATH}}/QA/logs/`
+- Logs — API (JSONL request/response): `{{PRD_PATH}}/QA/logs/api/`
+- Scripts Playwright (modo UI): `{{PRD_PATH}}/QA/scripts/`
+- Scripts de teste API (modo API): `{{PRD_PATH}}/QA/scripts/api/`
+- Receitas de API testing (skill): `.agents/skills/api-testing-recipes/`
 
 ## Fluxo Obrigatório
 
@@ -73,9 +78,12 @@ Executar ciclo iterativo de:
 - Manter compatibilidade com PRD/TechSpec e padrões do projeto
 - Validar build/lint/testes locais mínimos após cada bloco de correção
 
-### 3. Reteste E2E (Playwright MCP)
+### 3. Reteste Mode-Aware
+
+Para cada bug corrigido, escolha o branch conforme o campo `Modo:` do bug (registrado pelo `/dw-run-qa` Etapa 0).
+
+#### 3-UI (modo UI) — Playwright MCP
 
-Para cada bug corrigido:
 1. Reproduzir cenário original
 2. Executar fluxo corrigido
 3. Validar comportamento esperado
@@ -89,9 +97,20 @@ Para cada bug corrigido:
 7. Registrar no relatório de QA qual usuário/perfil foi usado no reteste
 8. Se o reteste exigir auth persistente, inspeção além do MCP, ou reprodução mais fiel em navegador real, registrar no relatório
 
+#### 3-API (modo API) — recipe `api-testing-recipes`
+
+1. Leia `.agents/skills/api-testing-recipes/SKILL.md` e localize a recipe usada no QA (o `RF-XX-[slug].<ext>` original referencia ela no comentário do header).
+2. Localize a linha JSONL que falhou em `QA/logs/api/RF-XX-[slug].log` via o campo `Caminho da evidência:` do bug.
+3. Re-execute o MESMO bloco `.http` (ou caso de teste) — mesma recipe, mesma camada da matriz — que produziu a falha. Use a mesma credencial/role.
+4. Salve o script do reteste em arquivo separado para rastreabilidade:
+   - `QA/scripts/api/BUG-[NN]-retest.<ext>` (ex.: `BUG-03-retest.http` ou `test_BUG_03_retest.py`)
+5. Anexe nova linha JSONL em `QA/logs/api/BUG-[NN]-retest.log` segundo `references/log-conventions.md`. Campos obrigatórios: `ts`, `rf` = `BUG-[NN]`, `case` = igual à falha original, `verdict` = `PASS` (fecha o bug) ou `FAIL` (ciclo continua).
+6. Asserte: a falha original não reproduz mais E o comportamento esperado do bug acontece. Os dois precisam ser verdade para marcar `verdict: PASS`.
+7. Registre no relatório de QA qual usuário/perfil/token foi usado no reteste (role do token, NÃO o valor).
+
 ### 3.5. Verificação Final Antes de Atualizar Status
 
-<critical>Invocar a skill `dw-verify` antes de mudar o status de qualquer bug para `Corrigido` ou `Fechado`. O VERIFICATION REPORT (test + lint + build) deve ser PASS **e** a evidência de reteste do Playwright deve estar salva. Sem os dois, o status não muda.</critical>
+<critical>Invocar a skill `dw-verify` antes de mudar o status de qualquer bug para `Corrigido` ou `Fechado`. O VERIFICATION REPORT (test + lint + build) deve ser PASS **e** a evidência de reteste deve estar salva — screenshot em `QA/screenshots/` (modo UI) OU linha JSONL com `verdict: "PASS"` em `QA/logs/api/` (modo API). Sem os dois, o status não muda.</critical>
 
 ### 4. Atualização de Artefatos
 
@@ -100,7 +119,9 @@ Atualizar `QA/bugs.md` para cada bug:
 ```markdown
 - **Status:** Corrigido (aguardando validação) | Reaberto | Fechado
 - **Reteste:** PASSOU/FALHOU em [YYYY-MM-DD]
-- **Evidência Reteste:** `QA/screenshots/BUG-[NN]-retest-PASS.png`
+- **Evidência Reteste:**
+  - modo UI: `QA/screenshots/BUG-[NN]-retest-PASS.png`
+  - modo API: `QA/logs/api/BUG-[NN]-retest.log#L<linha>`
 ```
 
 Atualizar `QA/qa-report.md`: