api-aqa-flow

name	api-aqa-flow
description	Workflow for backend API test automation: TMS / Issue Tracker test cases → automated API tests, HITL-gated.

<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="inherit" type="HITL-CONDITIONAL">

• APPLY SKILL FILE phases/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" applies="ALL" subagent="discoverer" role="AQA data collector" subagent_required_model="inherit">

• APPLY SKILL FILE phases/api-aqa-flow-data-collection.md
• Input: project config + initial data. Output: plans/api-aqa-{IDENTIFIER}/raw-data.md (test cases, documentation, existing test patterns).
• Required skills: data-collection (TMS + Wiki collector), qa-knowledge (code_analysis mode — existing-test + backend-source scan), reverse-engineering, qa-structure
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 1 is not complete until its output spot-check passes. </data_collection>

<api_spec_analysis phase="2" applies="ALL" subagent="discoverer" role="API spec analyst" subagent_required_model="inherit">

• APPLY SKILL FILE phases/api-aqa-flow-api-spec-analysis.md
• Input: raw data + project config. Output: plans/api-aqa-{IDENTIFIER}/api-analysis.md (endpoint contracts, auth, data dependencies).
• Required skills: qa-knowledge (code_analysis mode — API-contract extraction), reverse-engineering, sensitive-data, qa-structure
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 2 is not complete until its output spot-check passes. </api_spec_analysis>

<gap_and_requirements_clarification phase="3" applies="ALL" subagent="architect" role="Test requirements analyst" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE phases/api-aqa-flow-gap-and-requirements-clarification.md
• Input: raw data + API analysis. Output: plans/api-aqa-{IDENTIFIER}/analysis.md (gaps, contradictions, ambiguities resolved).
• HITL gate: WAIT FOR USER ANSWERS before Phase 4.
• Required skills: qa-knowledge (gap_analysis mode), qa-structure
• Recommended skills: questioning
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 3 is not complete until its output spot-check passes. </gap_and_requirements_clarification>

<test_case_specification phase="4" applies="ALL" subagent="architect" role="Test specification author" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE phases/api-aqa-flow-test-case-specification.md
• Input: all phase 1-3 outputs. Output: plans/api-aqa-{IDENTIFIER}/test-specs.md (Given-When-Then scenarios).
• HITL gate: WAIT FOR EXPLICIT USER APPROVAL before Phase 5; comments, questions, suggestions, and review feedback are not approval.
• Required skills: qa-knowledge (scenario_design mode), sensitive-data, qa-structure
• Recommended skills: hitl
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 4 is not complete until its output spot-check passes. </test_case_specification>

<test_implementation phase="5" applies="ALL" subagent="engineer" role="Test automation engineer" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE phases/api-aqa-flow-test-implementation.md
• Input: approved test specs + existing patterns + API analysis. Output: implemented test files.
• HITL gate: STOP AND WAIT — user must provide actual execution results (output, report path, or pass/fail); confirmation alone does not satisfy this gate.
• Required skills: qa-knowledge (implementation_modes — API impl), qa-structure
• Recommended skills: testing, coding (repo conventions)
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 5 is not complete until its output spot-check passes. </test_implementation>

<execution_and_report_analysis phase="6" applies="ALL" subagent="engineer" role="Test failure analyst" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE phases/api-aqa-flow-execution-and-report-analysis.md
• Input: test execution report (user-provided or from agents/user-instructions/). Output: plans/api-aqa-{IDENTIFIER}/execution-report.md (failure analysis).
• HITL gate: WAIT FOR USER TO PROVIDE TEST EXECUTION RESULTS.
• Required skills: qa-knowledge (test_execution_triage mode), sensitive-data, qa-structure
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 6 is not complete until its output spot-check passes. </execution_and_report_analysis>

<test_corrections phase="7" applies="ALL" subagent="engineer" role="Test correction engineer" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE phases/api-aqa-flow-test-correction.md
• Input: execution report + test files + test specs. Output: corrected test files.
• HITL gate: WAIT FOR EXPLICIT USER APPROVAL before applying changes; comments, questions, suggestions, and review feedback are not approval.
• Required skills: qa-knowledge (correction mode), qa-structure
• Recommended skills: coding (authors the proposed/applied edits), debugging (root-cause alignment), hitl
• Update agents/TEMP/<FEATURE>/api-aqa-state.md; Phase 7 is not complete until its output spot-check passes. </test_corrections>

</workflow_phases>

<coding_standards_precedence> Conflict rule is binary: if guidance from a loaded skill conflicts with repository markdown (docs/CONTEXT.md, docs/ARCHITECTURE.md, agents/IMPLEMENTATION.md — or the paths gain.json configures — and project_description.md if present) on naming, structure/layout, tooling, or test patterns, repository markdown wins and the conflicting skill snippet is ignored for that decision. If there is no conflict, apply both. gain.json wins for file locations. Example: if a skill suggests /tests/api/ but docs/ARCHITECTURE.md requires /qa/api/tests/, use /qa/api/tests/. </coding_standards_precedence>

<failure_handling>

• Phase-file load failure (APPLY PHASE for a required phase returns nothing): retry once, then stop, record in agents/TEMP/<FEATURE>/api-aqa-state.md, ask the user — never improvise an undocumented phase.
• Missing prior artifact: do not fabricate; with user agreement re-run the producing phase, or stop and ask the user to restore it.
• Unreadable agents/TEMP/<FEATURE>/api-aqa-state.md: pause, rebuild minimal phase pointers from plans/api-aqa-{IDENTIFIER}/ when possible, then ask the user to confirm.
• State-note example (phase-file load failure): Phase 5 blocked: APPLY SKILL FILE phases/api-aqa-flow-test-implementation.md returned nothing at 2026-05-25T15:00Z; awaiting user action. </failure_handling>

<state_file>

agents/TEMP/<FEATURE>/api-aqa-state.md carries: header (Last Updated / Current Phase 0-7 / Test Case Source / Feature / IDENTIFIER — matching the Phase 0 stub; API Base URL is appended once Phase 2 resolves it) + 8-row ## Phase Completion Status checklist (one row per phase 0-7) + per-phase append blocks. Each phase file owns its own state-update snippet (the delta it appends after running) — this workflow does not restate the full template.

</state_file>

Subagents: discoverer · architect · engineer · executor (optional, mechanical actions).

Cross-phase skills: qa-structure (paths / identifier / state-file shape) and qa-knowledge (modes, taxonomies, artifact skeletons — loads its own assets at point of use).

Integrations: TMS, Issue Tracker, and Wiki per <description_and_purpose> Terminology.

</api_aqa_flow>