@brunosps00/dev-workflow 0.7.0 → 0.8.1

package/scaffold/pt-br/templates/project-onepager.md

@@ -0,0 +1,129 @@
+---
+type: project-onepager
+schema_version: "1.0"
+status: draft
+date: YYYY-MM-DD
+shape: frontend | backend | fullstack
+languages: []
+frameworks: { web: '', api: '' }
+package_manager: ''
+monorepo: ''
+services: []
+---
+
+# Projeto: [Nome do projeto]
+
+## Proposito
+
+[Um paragrafo em linguagem de produto. Quem vai usar, qual problema resolve, como o sucesso se parece em 6-12 semanas. Evite linguagem de implementacao.]
+
+## Stack Selecionado
+
+| Camada | Escolha | Justificativa |
+|--------|---------|---------------|
+| Forma | frontend / backend / fullstack | [por que essa forma — superficie unica, API para parceiros, etc.] |
+| Frontend | Next.js / Vite+React / n/a | [por que esse framework — SSR, simplicidade SPA, etc.] |
+| Backend | FastAPI / ASP.NET Core minimal / Axum / Fastify / n/a | [por que — expertise do time, ecosystem, alvo de latencia] |
+| Database | Postgres / MySQL / SQLite / MongoDB / nenhum | [por que esse DB — relacional, JSON-heavy, transacional, etc.] |
+| Cache | Redis / Memcached / nenhum | [por que ou por que nao] |
+| Fila | BullMQ / Celery / RabbitMQ / LocalStack SQS / nenhum | [por que ou nao + sync vs async workers] |
+| Email — dev | MailHog (default) / Mailpit / smtp4dev / nenhum | [normalmente MailHog — captura only, nunca envia real] |
+| Email — prod | SMTP / SendGrid / Resend / Postmark / SES / nenhum | [por que esse provider — volume, deliverability, custo] |
+| Object storage | S3 / MinIO (dev) / GCS / nenhum | [por que ou nao] |
+| Search | Meilisearch / Typesense / Elasticsearch / nenhum | [por que esse engine — features, escala, simplicidade] |
+| Observability | Sentry / OTel + Jaeger / nenhum | [por que essa abordagem — so error tracking, tracing completo, etc.] |
+| Reverse proxy | Traefik / Caddy / nenhum | [normalmente so multi-host dev ou prod] |
+| Auth | NextAuth / Lucia / Clerk / fastapi-users / dotnet Identity / JWT custom / nenhum | [por que — social login, B2B, etc.] |
+| Linter / formatter | Biome / ESLint+Prettier / Ruff+Black / dotnet format / cargo fmt+clippy | [preferencia do time] |
+| Package manager | pnpm / npm / yarn / poetry / uv / cargo / dotnet | [preferencia do time] |
+| Monorepo orchestrator | pnpm workspaces / npm workspaces / Turborepo / Nx / n/a | [so para fullstack — caching/build] |
+| CI | GitHub Actions / nenhum | [normalmente GitHub Actions; pular so para repos nao-publicos] |
+
+## Servicos & Infra
+
+[Servicos gerados a partir da skill docker-compose-recipes. Preenchido pelo /dw-new-project.]
+
+| Servico | Porta (host) | UI | Credenciais default |
+|---------|--------------|----|--------------------|
+| postgres | 5432 | — | POSTGRES_USER=app, POSTGRES_PASSWORD=app, POSTGRES_DB=app |
+| redis | 6379 | — | (sem auth em dev) |
+| mailhog | 1025 (smtp), 8025 (UI) | http://localhost:8025 | (sem auth) |
+| ... | ... | ... | ... |
+
+## Diagrama da Arquitetura
+
+```
+[Diagrama ASCII da forma escolhida. Exemplos:]
+
+# So frontend
+[ Browser ] -> [ Next.js (apps/web) ]
+
+# Fullstack
+[ Browser ] -> [ Next.js (apps/web) ] -> [ FastAPI (apps/api) ] -> [ Postgres ]
+                                                                |-> [ Redis ]
+                                                                |-> [ MailHog ]
+
+# Com observability
+... -> [ FastAPI ] -> { OTLP } -> [ Jaeger ]
+```
+
+## Arquivos Gerados
+
+[Preenchido pelo /dw-new-project apos Fase 3 — lista de arquivos criados com origem.]
+
+```
+{{TARGET_DIR}}/
+├── apps/
+│   ├── web/                      (criado por `pnpm create next-app`)
+│   └── api/                      (scaffold inline — FastAPI)
+├── packages/
+│   └── shared/                   (criado pelo /dw-new-project)
+├── docker-compose.dev.yml        (composto a partir de .agents/skills/docker-compose-recipes/)
+├── .env.example                  (consolidado dos servicos selecionados)
+├── .gitignore                    (por stack)
+├── .dockerignore                 (por stack)
+├── .github/workflows/ci.yml      (CI com matrix por app)
+├── package.json                  (scripts raiz: dev:up/down/logs/reset)
+├── pnpm-workspace.yaml           (se pnpm workspaces)
+├── turbo.json                    (se Turborepo)
+├── README.md                     (Quick Start + tabela de portas Local Dev)
+└── .dw/
+    ├── rules/index.md            (seed — enriquecer depois via /dw-analyze-project)
+    └── spec/projects/<nome>.md   (este arquivo)
+```
+
+## Escopo MVP
+
+[A primeira feature menor que voce vai entregar. Pensada como user stories — vai dirigir a primeira rodada de /dw-create-prd.]
+
+- Como [persona], eu posso [acao] para que [beneficio]
+- Como [persona], eu posso [acao] para que [beneficio]
+
+Se voce ainda nao tem a primeira feature em mente, tudo bem — deixa placeholder e roda o /dw-create-prd quando tiver.
+
+## Nao Estou Fazendo (explicito)
+
+[Itens tentadores adiados. Forca disciplina de escopo.]
+
+- **[item 1]** — motivo: [fora do v1 porque...]
+- **[item 2]** — motivo: [pode virar v2 se a hipotese X validar]
+
+## Premissas-Chave
+
+- **[premissa sobre usuarios / mercado / escala]** — teste: [como validar]
+- **[premissa sobre latencia / volume / SLAs]** — teste: [load profile, metrica alvo]
+
+## Perguntas em Aberto
+
+[O que este one-pager nao consegue responder sozinho. Resolva antes do /dw-create-prd ou escale para um stakeholder.]
+
+- [pergunta 1]
+- [pergunta 2]
+
+## Proximo Passo
+
+Escolha UM:
+
+- **`/dw-create-prd`** — quando voce tem a primeira feature em mente e quer rascunhar o PRD em cima deste stack
+- **`/dw-analyze-project`** — apos primeiro commit substancial, para enriquecer `.dw/rules/` com convencoes por modulo
+- **`/dw-deps-audit --scan-only`** — para confirmar que nenhuma dep vulneravel veio dos templates `create-*`

package/scaffold/skills/api-testing-recipes/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: api-testing-recipes
+description: Validated API-testing snippets (.http, pytest+httpx, supertest, WebApplicationFactory, reqwest) used by /dw-run-qa and /dw-fix-qa when the project has no UI. Default format is .http (REST Client) for IDE portability.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# api-testing-recipes
+
+Curated library of **API-testing snippets** that `/dw-run-qa` and `/dw-fix-qa` use when a project is API-only (no Playwright). Each recipe is a ready-to-customize block per stack; the default is `.http` (REST Client) for maximum portability across IDEs.
+
+## Why a skill (not inline)
+
+- Each recipe is independently maintainable. Bumping `pytest` or `supertest` patterns is a one-file change.
+- Discoverable by AI agents in any project the user installs dev-workflow into.
+- Reusable by future commands (e.g., `dw-bench-api`, `dw-contract-test`) without duplication.
+
+## When to Use
+
+Read this skill when:
+
+- `/dw-run-qa` detected API mode (no UI deps in the manifest) or was invoked with `--api`.
+- `/dw-fix-qa` is retesting a bug whose `evidence_type` is `api-log`.
+- Generating a baseline test suite from an OpenAPI spec.
+- Authoring contract checks against a backend.
+
+Do NOT use when:
+
+- The project has a UI and `/dw-run-qa` is in UI mode → use Playwright MCP instead.
+- The user wants browser-level acceptance (forms, navigation, accessibility) — that's Playwright territory.
+
+## Available Recipes
+
+| Format | When to use | Recipe path |
+|--------|-------------|-------------|
+| `.http` (REST Client) — DEFAULT | Universal. Reads in VSCode (REST Client), JetBrains (HTTP Client), Neovim (rest.nvim, kulala), Zed. Stack-agnostic. Best for projects without an existing test runner, or when devs read tests in their IDE. | `recipes/http-rest-client.md` |
+| `pytest + httpx` | Python project (FastAPI, Starlette, Flask). Already runs `pytest` in CI. Async client matches FastAPI's async-first design. | `recipes/pytest-httpx.md` |
+| `supertest` (Node/TS) | Node/TS project (Fastify, Express, NestJS). Already runs `vitest`/`jest`. Integrates with the app's test setup. | `recipes/supertest-node.md` |
+| `WebApplicationFactory<T>` (.NET) | C# project (ASP.NET Core minimal API or MVC). Built-in support for in-process testing without HTTP overhead. | `recipes/dotnet-webapp-factory.md` |
+| `reqwest + tokio::test` (Rust) | Rust project (Axum, Actix-web, Rocket). Async client matches Axum's tower-based design. | `recipes/rust-reqwest.md` |
+
+Picking order:
+1. Default to `.http` unless the project already has an established test runner.
+2. If the project has a test runner (`pytest`, `vitest`, `dotnet test`, `cargo test`), prefer the stack-specific recipe so QA tests live alongside unit tests.
+3. The user can override during the interview/run with `--format=http|pytest|supertest|dotnet|rust`.
+
+## How to Compose
+
+The composing command (`/dw-run-qa` API mode) follows this loop:
+
+1. **Pick the recipe** based on the rules above.
+2. **Read the recipe file** (`recipes/<name>.md`) for the variable conventions, test-matrix shape, and an example block.
+3. **For each requirement (RF-XX) in the PRD**, derive a test matrix per `references/matrix-conventions.md`:
+   - 200 happy path
+   - 4xx — validation, auth, not found, conflict
+   - 5xx — server error (synthetic)
+   - Contract drift — response shape vs OpenAPI / TS types
+   - Authorization cross-tenant
+4. **Generate** one file per RF in `{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].<ext>` using the recipe's structure. Wire credentials via the patterns in `references/auth-patterns.md` (NEVER hardcode tokens).
+5. **Execute** each request:
+   - `.http` → `curl` (Bash) or the in-IDE runner during interactive review.
+   - Stack-specific → the project's test runner (`pytest <files>`, `vitest run <files>`, `dotnet test --filter`, `cargo test`).
+6. **Log** every request/response per `references/log-conventions.md` to `{{PRD_PATH}}/QA/logs/api/RF-XX-[slug].log` (one JSONL line per request).
+7. **Assert** per matrix expectation: status code, response shape (use `jq` for `.http`, framework matchers per stack), headers.
+8. **Mark** PASS/FAIL per RF, citing the log path as evidence.
+
+## OpenAPI-Driven Mode
+
+If the project exposes OpenAPI (`openapi.yaml`/`openapi.json` static, or `/openapi.json` in runtime for FastAPI), follow `references/openapi-driven.md` to:
+- Generate a baseline of 200/4xx tests per endpoint automatically.
+- Detect contract drift by diffing live responses against the spec.
+- Skip endpoints marked `x-internal: true` or those without examples.
+
+## Variable Conventions
+
+Every recipe uses three variable layers:
+
+- **`@base`** — base URL (`http://localhost:3000` in dev). Set once per file.
+- **`@token_admin` / `@token_user` / `@token_guest`** — credential tokens, captured from a login response or read from `.env` / `QA/test-credentials.md`.
+- **`@<resource>_id`** — IDs created during a multi-step flow (e.g., create → fetch → update → delete on the same RF).
+
+Per-recipe details in `references/auth-patterns.md`.
+
+## References
+
+- `references/matrix-conventions.md` — how to derive the {200, 4xx, 5xx, contract drift, authz cross-tenant} matrix from a PRD requirement.
+- `references/auth-patterns.md` — how to capture and reuse JWT / cookie / API-key credentials in scripts; refresh-token patterns; scoped credentials per role.
+- `references/openapi-driven.md` — generating a baseline test suite from an OpenAPI spec; detecting contract drift.
+- `references/log-conventions.md` — JSONL log shape (one line per request: timestamp, method, url, status, request_headers, request_body, response_headers, response_body, ms).
+
+## Rules
+
+- **Default to `.http`** unless the project already has a test runner.
+- **Never hardcode credentials**. Always use `@variable` references that resolve to env vars or files outside git.
+- **Always log request + response** so the bug evidence is reproducible without re-running.
+- **One file per RF**. Don't pile every requirement into one giant test file.
+- **PASS/FAIL per RF, never per request**. A request that returns 401 when the matrix says it should is a PASS for that case.
+
+## Inspired by
+
+Hand-curated by dev-workflow. `.http` syntax follows the JetBrains HTTP Client / VSCode REST Client conventions. Per-stack recipes adapt patterns from each ecosystem's official testing docs (FastAPI testing tutorial, NestJS testing recipes, Microsoft.AspNetCore.Mvc.Testing docs, Axum testing examples).

package/scaffold/skills/api-testing-recipes/recipes/dotnet-webapp-factory.md

@@ -0,0 +1,168 @@
+# Recipe: `WebApplicationFactory<T>` + xUnit (.NET)
+
+Use for ASP.NET Core minimal API or MVC. Microsoft's official integration-testing pattern. Runs the full pipeline (DI, middleware, filters) in-process — no Kestrel port, no flake.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF_XX_[Slug]Tests.cs`
+
+```csharp
+using System.Net;
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Xunit;
+
+namespace YourProject.QA.Api;
+
+public class RF_XX_CreateUserTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly WebApplicationFactory<Program> _factory;
+    private readonly string _tokenAdmin = Environment.GetEnvironmentVariable("QA_TOKEN_ADMIN") ?? "";
+    private readonly string _tokenOtherOrg = Environment.GetEnvironmentVariable("QA_TOKEN_OTHER_ORG") ?? "";
+
+    public RF_XX_CreateUserTests(WebApplicationFactory<Program> factory) => _factory = factory;
+
+    private HttpClient Client(string? token = null)
+    {
+        var c = _factory.CreateClient();
+        if (!string.IsNullOrEmpty(token))
+            c.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        return c;
+    }
+
+    private record CreateUserDto(string Email, string Name);
+    private record UserResponse(string Id, string Email, string Name, DateTime CreatedAt);
+
+    [Fact]
+    public async Task HappyPath_Returns201()
+    {
+        var r = await Client(_tokenAdmin).PostAsJsonAsync("/users",
+            new CreateUserDto($"qa-{Guid.NewGuid():N}@example.com", "QA"));
+        Assert.Equal(HttpStatusCode.Created, r.StatusCode);
+        var body = await r.Content.ReadFromJsonAsync<UserResponse>();
+        Assert.NotNull(body);
+        Assert.NotNull(body!.Id);
+    }
+
+    [Theory]
+    [InlineData("{\"name\":\"No email\"}", "email")]
+    [InlineData("{\"email\":\"no-name@x.com\"}", "name")]
+    [InlineData("{\"email\":\"not-an-email\",\"name\":\"X\"}", "email")]
+    public async Task Validation_Returns422_AndMentionsField(string payload, string field)
+    {
+        var content = new StringContent(payload, System.Text.Encoding.UTF8, "application/json");
+        var r = await Client(_tokenAdmin).PostAsync("/users", content);
+        Assert.Equal(HttpStatusCode.UnprocessableEntity, r.StatusCode);
+        var msg = await r.Content.ReadAsStringAsync();
+        Assert.Contains(field, msg.ToLower());
+    }
+
+    [Fact]
+    public async Task NoToken_Returns401()
+    {
+        var r = await Client().PostAsJsonAsync("/users", new CreateUserDto("x@y.com", "x"));
+        Assert.Equal(HttpStatusCode.Unauthorized, r.StatusCode);
+    }
+
+    [Fact]
+    public async Task CrossTenant_Returns403Or404()
+    {
+        if (string.IsNullOrEmpty(_tokenOtherOrg)) return;
+        // assume a known id from another tenant; in a real suite, create one in setup
+        var r = await Client(_tokenOtherOrg).GetAsync("/users/00000000-0000-0000-0000-000000000001");
+        Assert.True(r.StatusCode is HttpStatusCode.Forbidden or HttpStatusCode.NotFound);
+    }
+
+    [Fact]
+    public async Task Contract_HasRequiredFields_NoLeaks()
+    {
+        var create = await Client(_tokenAdmin).PostAsJsonAsync("/users",
+            new CreateUserDto($"contract-{Guid.NewGuid():N}@example.com", "Contract"));
+        var created = await create.Content.ReadFromJsonAsync<UserResponse>();
+        var get = await Client(_tokenAdmin).GetAsync($"/users/{created!.Id}");
+        Assert.Equal(HttpStatusCode.OK, get.StatusCode);
+
+        var raw = await get.Content.ReadAsStringAsync();
+        foreach (var field in new[] { "id", "email", "name", "created_at" })
+            Assert.Contains(field, raw, StringComparison.OrdinalIgnoreCase);
+        foreach (var leak in new[] { "password_hash", "internal_id", "_raw" })
+            Assert.DoesNotContain(leak, raw, StringComparison.OrdinalIgnoreCase);
+    }
+}
+```
+
+## Configuration
+
+Project file (`*.QA.csproj` or extend the existing test project):
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.*" />
+  <PackageReference Include="xunit" Version="2.9.*" />
+  <PackageReference Include="xunit.runner.visualstudio" Version="2.8.*" />
+  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.*" />
+</ItemGroup>
+<ItemGroup>
+  <InternalsVisibleTo Include="$(AssemblyName)" />
+</ItemGroup>
+```
+
+The `Program` class must be public (for `WebApplicationFactory<Program>`). For minimal APIs, add at the bottom of `Program.cs`:
+
+```csharp
+public partial class Program { }
+```
+
+## Running
+
+```bash
+# all RF tests
+dotnet test --filter FullyQualifiedName~YourProject.QA.Api
+
+# one RF
+dotnet test --filter FullyQualifiedName~RF_XX_CreateUserTests
+
+# log to QA/logs/api/
+dotnet test --filter FullyQualifiedName~YourProject.QA.Api \
+  --logger "console;verbosity=detailed" 2>&1 \
+  | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+Use a custom `DelegatingHandler` registered on the factory's client:
+
+```csharp
+public class LoggingHandler : DelegatingHandler
+{
+    private static readonly string LogPath = "QA/logs/api/RF-XX-create-user.log";
+
+    protected override async Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage req, CancellationToken ct)
+    {
+        var sw = Stopwatch.StartNew();
+        var res = await base.SendAsync(req, ct);
+        sw.Stop();
+        Directory.CreateDirectory(Path.GetDirectoryName(LogPath)!);
+        var entry = new {
+            ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+            method = req.Method.Method,
+            url = req.RequestUri?.ToString(),
+            status = (int)res.StatusCode,
+            ms = sw.ElapsedMilliseconds,
+        };
+        await File.AppendAllTextAsync(LogPath,
+            System.Text.Json.JsonSerializer.Serialize(entry) + "\n", ct);
+        return res;
+    }
+}
+```
+
+## Pros / cons
+
+- **Pro**: in-process — full DI graph, no port, deterministic.
+- **Pro**: `[Theory]` + `[InlineData]` covers the 4xx matrix.
+- **Pro**: same project as unit tests; `dotnet test` runs both.
+- **Con**: requires `Program` to be partial and public.
+- **Con**: tied to `Microsoft.AspNetCore.Mvc.Testing` package versions.

package/scaffold/skills/api-testing-recipes/recipes/http-rest-client.md

@@ -0,0 +1,130 @@
+# Recipe: `.http` (REST Client) — DEFAULT
+
+Universal API-testing format. One file per RF. Read by VSCode REST Client, JetBrains HTTP Client, Neovim rest.nvim/kulala, Zed Assistant. No test runner needed.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].http`
+
+```http
+### RF-XX [slug] — happy path
+# @name create_user
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{
+  "email": "qa-{{$randomInt 1 999999}}@example.com",
+  "name": "QA User"
+}
+
+> {%
+client.test("status is 201", () => client.assert(response.status === 201));
+client.test("response has id", () => client.assert(response.body.id != null));
+client.global.set("created_user_id", response.body.id);
+%}
+
+### RF-XX — 4xx validation: missing email
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{ "name": "No email" }
+
+> {%
+client.test("status is 422", () => client.assert(response.status === 422));
+client.test("error mentions email", () => client.assert(response.body.error.message.toLowerCase().includes("email")));
+%}
+
+### RF-XX — 4xx auth: missing token
+POST {{base}}/users
+Content-Type: application/json
+
+{ "email": "x@y.com", "name": "x" }
+
+> {%
+client.test("status is 401", () => client.assert(response.status === 401));
+%}
+
+### RF-XX — 4xx authz: cross-tenant access
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_other_org_admin}}
+
+> {%
+client.test("status is 403 or 404", () =>
+  client.assert(response.status === 403 || response.status === 404));
+%}
+
+### RF-XX — contract drift: response shape vs OpenAPI
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_admin}}
+
+> {%
+client.test("has required fields", () => {
+  ["id", "email", "name", "created_at"].forEach(f =>
+    client.assert(response.body[f] != null, `missing ${f}`));
+});
+client.test("no leaked internal fields", () => {
+  ["password_hash", "internal_id", "_raw"].forEach(f =>
+    client.assert(response.body[f] === undefined, `leaked ${f}`));
+});
+%}
+```
+
+## Variables
+
+Set once at the top of the file (or in a `http-client.env.json` next to it):
+
+```http
+@base = {{$dotenv API_BASE_URL}}
+@token_admin = {{$dotenv QA_TOKEN_ADMIN}}
+@token_user = {{$dotenv QA_TOKEN_USER}}
+@token_other_org_admin = {{$dotenv QA_TOKEN_OTHER_ORG}}
+```
+
+Or, if the project uses login-based auth, capture the token in a setup request and reference it in subsequent requests:
+
+```http
+### Setup — login as admin
+# @name login_admin
+POST {{base}}/auth/login
+Content-Type: application/json
+
+{ "email": "{{$dotenv QA_ADMIN_EMAIL}}", "password": "{{$dotenv QA_ADMIN_PASSWORD}}" }
+
+> {% client.global.set("token_admin", response.body.access_token); %}
+```
+
+## Execution from `dw-run-qa` (CLI fallback)
+
+When running outside an IDE (e.g., from the agent in headless mode), parse and execute via `curl`:
+
+```bash
+# For each ### block, extract method/url/headers/body and execute:
+curl -sS -X POST "$BASE/users" \
+  -H "Authorization: Bearer $TOKEN_ADMIN" \
+  -H "Content-Type: application/json" \
+  -d '{"email":"qa-1@example.com","name":"QA"}' \
+  -w '\n%{http_code} %{time_total}s\n' \
+  | tee -a "QA/logs/api/RF-XX-create-user.log"
+```
+
+The `dw-run-qa` agent does this loop automatically and writes to the JSONL log per `references/log-conventions.md`.
+
+## Assertions
+
+Use the inline `> {% ... %}` post-response handler when running in an IDE. For headless `curl` execution, use `jq`:
+
+```bash
+RESP=$(curl -sS ...)
+STATUS=$(echo "$RESP" | head -1 | awk '{print $2}')
+[ "$STATUS" = "201" ] || { echo "FAIL: expected 201, got $STATUS"; exit 1; }
+echo "$RESP" | jq -e '.id != null' >/dev/null || { echo "FAIL: missing id"; exit 1; }
+```
+
+## Pros / cons
+
+- **Pro**: zero install, opens in any IDE, devs read it without running a test runner.
+- **Pro**: each request is a single block, easy to copy-paste into incident tickets.
+- **Con**: no native fixture/teardown — multi-request flows rely on `client.global.set` for state.
+- **Con**: parallel execution requires per-block uniqueness in resource names (use `{{$randomInt}}` or `{{$timestamp}}`).

package/scaffold/skills/api-testing-recipes/recipes/pytest-httpx.md

@@ -0,0 +1,157 @@
+# Recipe: `pytest + httpx` (Python)
+
+Use when the project already runs `pytest` (FastAPI, Starlette, Flask + pytest-flask). The async client matches FastAPI's design and gives you fixtures + parametrize for free.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/test_RF_XX_[slug].py`
+
+```python
+"""RF-XX [slug] — API QA suite."""
+import os
+import pytest
+import httpx
+
+BASE = os.environ["API_BASE_URL"]
+TOKEN_ADMIN = os.environ["QA_TOKEN_ADMIN"]
+TOKEN_USER = os.environ["QA_TOKEN_USER"]
+TOKEN_OTHER_ORG = os.environ.get("QA_TOKEN_OTHER_ORG", "")
+
+
+@pytest.fixture
+async def client():
+    async with httpx.AsyncClient(base_url=BASE, timeout=10.0) as c:
+        yield c
+
+
+def auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}
+
+
+# ---------- happy path ----------
+
+@pytest.mark.asyncio
+async def test_create_user_happy_path(client):
+    r = await client.post("/users", headers=auth(TOKEN_ADMIN),
+                          json={"email": "qa@example.com", "name": "QA"})
+    assert r.status_code == 201, r.text
+    body = r.json()
+    assert body["id"]
+    assert body["email"] == "qa@example.com"
+    pytest.created_user_id = body["id"]   # share via module attr or use a fixture
+
+
+# ---------- 4xx validation ----------
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("payload, missing_field", [
+    ({"name": "No email"}, "email"),
+    ({"email": "no-name@x.com"}, "name"),
+    ({"email": "not-an-email", "name": "X"}, "email"),
+])
+async def test_create_user_validation(client, payload, missing_field):
+    r = await client.post("/users", headers=auth(TOKEN_ADMIN), json=payload)
+    assert r.status_code == 422, r.text
+    assert missing_field in r.json()["error"]["message"].lower()
+
+
+# ---------- 4xx auth ----------
+
+@pytest.mark.asyncio
+async def test_create_user_no_token(client):
+    r = await client.post("/users", json={"email": "x@y.com", "name": "x"})
+    assert r.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_create_user_expired_token(client):
+    r = await client.post("/users",
+                          headers={"Authorization": "Bearer expired.token.here"},
+                          json={"email": "x@y.com", "name": "x"})
+    assert r.status_code == 401
+
+
+# ---------- 4xx authz cross-tenant ----------
+
+@pytest.mark.asyncio
+async def test_get_user_other_org_denied(client):
+    if not TOKEN_OTHER_ORG:
+        pytest.skip("QA_TOKEN_OTHER_ORG not set")
+    r = await client.get(f"/users/{pytest.created_user_id}",
+                         headers=auth(TOKEN_OTHER_ORG))
+    assert r.status_code in (403, 404)
+
+
+# ---------- contract drift ----------
+
+@pytest.mark.asyncio
+async def test_get_user_contract(client):
+    r = await client.get(f"/users/{pytest.created_user_id}",
+                         headers=auth(TOKEN_ADMIN))
+    assert r.status_code == 200
+    body = r.json()
+    for field in ("id", "email", "name", "created_at"):
+        assert field in body, f"missing {field}"
+    for leaked in ("password_hash", "internal_id", "_raw"):
+        assert leaked not in body, f"leaked {leaked}"
+```
+
+## Configuration
+
+`pyproject.toml` (or `pytest.ini`):
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["QA/scripts/api"]
+```
+
+## Running
+
+```bash
+# all RF tests
+pytest QA/scripts/api/
+
+# one RF
+pytest QA/scripts/api/test_RF_01_create_user.py -v
+
+# capture log to QA/logs/api/
+pytest QA/scripts/api/ -v --tb=short 2>&1 | tee QA/logs/api/run-$(date +%F).log
+```
+
+## Logging request/response (for QA evidence)
+
+Wrap `client` to log every call:
+
+```python
+import json, time
+from pathlib import Path
+
+LOG = Path("QA/logs/api/RF-XX-create-user.log")
+
+class LoggingClient(httpx.AsyncClient):
+    async def request(self, method, url, **kw):
+        start = time.time()
+        r = await super().request(method, url, **kw)
+        ms = int((time.time() - start) * 1000)
+        LOG.parent.mkdir(parents=True, exist_ok=True)
+        with LOG.open("a") as f:
+            f.write(json.dumps({
+                "ts": time.time(),
+                "method": method,
+                "url": str(r.request.url),
+                "status": r.status_code,
+                "ms": ms,
+                "request_body": kw.get("json"),
+                "response_body": r.json() if r.headers.get("content-type", "").startswith("application/json") else None,
+            }) + "\n")
+        return r
+```
+
+## Pros / cons
+
+- **Pro**: parametrize covers the 4xx matrix in one block.
+- **Pro**: fixtures handle auth + setup/teardown cleanly.
+- **Pro**: integrates with existing `pytest` config + CI.
+- **Con**: not portable to non-Python projects.
+- **Con**: requires `httpx` and `pytest-asyncio` in dev deps.