/api-aqa-flow

name: api-aqa-flow
description: "Workflow for backend API test automation: TMS / Issue Tracker test cases → automated API tests, HITL-gated."
tags: ["workflow"]
baseSchema: docs/schemas/workflow.md

<api_aqa_flow>

<description_and_purpose>

End-to-end backend API test automation from test case input to working automated tests.

Prerequisite: Rosetta Prep Steps.

**Terminology.** External systems are named by role throughout this workflow and its phases: **Test Management System (TMS)**, **Issue Tracker**, and **Wiki**. TestRail, Jira, and Confluence are canonical examples only — adapt identifiers, URLs, requests, calls, and query syntax to the systems resolved for the current project (from repository-root `gain.json`, explicit user input, recognizable URLs/handles, and available integrations).

**At completion the user has:** corrected, passing API test files in the repository; the per-session artifacts under `plans/api-aqa-{IDENTIFIER}/` (`raw-data.md`, `api-analysis.md`, `analysis.md`, `test-specs.md`, `execution-report.md`); and `agents/TEMP/<FEATURE>/api-aqa-state.md` recording phase completion, metrics, and HITL approvals.

</description_and_purpose>

<workflow_phases>

• **Phases 0→7 MUST run in order**; sanctioned skips per `<skip_rules>` only.
• All Rosetta prep steps MUST be FULLY completed, SKILL `load-project-context` loaded and fully executed.
• NO ASSUMPTIONS: never assume endpoints, payloads, auth mechanisms, or response schemas — ask the user when missing.
• MUST ALWAYS use todo tasks ledger, ASAP. Prioritize ACCURACY over SPEED. Proactively use available tools/MCPs, if question can be answered from code or MCP call - do that first.
• **Drive loop (owned by this workflow):** execute phases in order — for each: APPLY PHASE its phase file → update `agents/TEMP/<FEATURE>/api-aqa-state.md` → verify the phase-output gate → next; keep todos matched to the active phase; never batch-load future phases; never skip without approval (`<skip_rules>`). When a phase delegates work to subagents, dispatch per USE SKILL `orchestration`.
• **Phase-output gate (verify before advancing):** each phase's mandatory artifact must exist and pass its phase-file completion gate before the next phase starts — notably **Phase 4: every `ATC-NNN` in `test-specs.md` traces to a Phase 3 source** (a `raw-data.md` test case and/or an `analysis.md` `G[N]`/`C[N]`/`A[N]` finding); also Phase 1 `raw-data.md`, Phase 2 `api-analysis.md`, and Phase 6 `execution-report.md` present and non-placeholder.

<skip_rules>

This block owns ONLY the api-aqa-flow-specific skip rules below: a set of **always-in-force carve-outs** plus a single **verification-failure unilateral-start override** (the only no-ask deviation; its preconditions are in the table further down). The carve-outs bind unconditionally; the override is subordinate to them. Gate-execution mechanics (how to run an approval gate, token handling) are owned by USE SKILL `hitl` — defer to it; not restated here.

• **Always-in-force carve-outs** (the override never suppresses these):

1. Per-phase HITL gates (Phases 3-7 marked `type="HITL"`) — explicit user approval per the `hitl` skill. 2. NO ASSUMPTIONS rule (above) — every non-skip-gate decision. 3. Safety / destructive confirmations — file deletion, edits outside `plans/api-aqa-{IDENTIFIER}/`, comparable irreversible actions.

• **Verification-failure unilateral-start override** — subordinate to the `hitl` skill + the carve-outs above; the only no-ask deviation, applies only at this skip-verification gate.

| Precondition (ALL true, independently verified) | Action | |---|---| | (a) user asserts Phases 0-2 complete this turn AND (b) `agents/TEMP/<FEATURE>/api-aqa-state.md` marks them complete AND (c) `raw-data.md` + `api-analysis.md` exist under `plans/api-aqa-{IDENTIFIER}/` | **Print (a)/(b)/(c) each with its concrete evidence** (user-assertion quote · the api-aqa-state rows · the two artifact paths), then skip Phases 0-2 and resume at Phase 3. Any precondition not showable with concrete evidence → treat as uncertain (last row). | | Any of (a)/(b)/(c) false AND user instruction unambiguous | Print failing conditions; begin Phase 0 same turn. | | Any precondition uncertain | Fall back to normal HITL ask. **Ambiguity defaults to ASK.** |

</skip_rules>

<execution_policy>

• If user did not specify preferences, perform all steps except optional.
• MUST follow JIT phase-by-phase: do not load/act IN ADVANCE.
• User CAN customize: specific phases, already-done phases, specific goals, specific cases — LISTEN and ADOPT.
• USE SKILL `coding` before implementation or correction work that touches repository test code or shared utilities.
• **Repository coding standards:** follow `<coding_standards_precedence>`.
• Prefer extending existing test files and utilities over creating new ones.
• **Overall workflow done when:** every phase required for this run is marked complete in `agents/TEMP/<FEATURE>/api-aqa-state.md`, expected artifacts for those phases exist under `plans/api-aqa-{IDENTIFIER}/` (and related paths named in phase docs), and the user accepts the last test outcome or explicitly stops the run.

</execution_policy>

<project_config_loading phase="0" applies="ALL" subagent="discoverer" role="AQA project config loader" subagent_required_model="claude-sonnet-5, gpt-5.4-medium, gemini-3.1-pro, grok-4.5, gpt-5.6-terra" type="HITL-CONDITIONAL">

• APPLY PHASE `api-aqa-flow-project-config-loading.md`
• Input: user request. Output: project config file, initial data file, session directory at `plans/api-aqa-{IDENTIFIER}/`.
• HITL gate: **ASK USER FOR PROJECT INFO** if config does not already exist.
• Required skills: `qa-structure`, `sensitive-data` (redaction at intake)
• Recommended skills: `questioning` (config-missing interview)
• Update `agents/TEMP/<FEATURE>/api-aqa-state.md`; Phase 0 is not complete until its output spot-check passes.

</project_config_loading>

<data_collection phase="1" ap