Unified implementation skill that orchestrates the full TDD micro-cycle (Red/Green/Refactor) one test at a time using test-list.md as the execution ledger.

2026-05-293

qfai-prototyping

aganesy/QFAI

Iterate one prototype through up to 10 cycles of generate-capture-review against a frozen DESIGN.md, focusing on information architecture, navigation flow, usability, and functionality.

2026-05-293

qfai-verify

aganesy/QFAI

Run and document quality gates (repo + qfai validate/report), fix until PASS.

2026-05-293

name	qfai-atdd
title	QFAI ATDD (Executable acceptance tests)
description	Implement automated acceptance tests (E2E/API/Integration) aligned with US/TC/CON-API obligations from specs and contracts.
argument-hint	<spec-id> [--auto]
allowed-tools	["Read","Glob","Write","TodoWrite","Task","Bash"]
roles	["orchestrator","delivery-planner","test-design-analyst","qa-strategist","acceptance-test-engineer","devops-ci-engineer","completion-reviewer","qa-gatekeeper","implementation-reviewer"]
routing-profile	runtime-heavy
mode	execution-focused

/qfai-atdd — Implement Automated Acceptance Tests (ATDD)

[DRIFT-PROTOCOL:MANDATORY]

User Questions (AskUserQuestion Protocol)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#user-questions-askuserquestion-protocol.

Skill-specific examples:

test scope decisions
runtime environment confirmation

FORMAT SSOT (Mandatory)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#format-ssot-mandatory.

Inputs Priority (Preflight)

When unsure, read inputs in this order:

P1: .qfai/assistant/constitution/*
P2: .qfai/assistant/manifest/* + .qfai/assistant/catalog/*
P3: .qfai/specs/<spec-id>/01_Spec.md (Primary SSOT / Consumer View)
P4: specs/contracts obligations
- .qfai/specs/<spec-id>/02_User-stories.md (US)
- .qfai/specs/<spec-id>/03_Acceptance-Criteria.md (AC)
- .qfai/specs/<spec-id>/05_Examples.md (EX)
- .qfai/specs/<spec-id>/06_Test-Cases.md (TC)
- .qfai/contracts/api/** (CON-API)
- .qfai/contracts/ui/** and .qfai/contracts/design/** when the target spec is UI-bearing
P5: .qfai/specs/<spec-id>/09_delta.md (Decision Records; if no spec yet, state "not applicable")
P6: legacy artifacts (optional only)
- .qfai/specs/<spec-id>/scenario.feature
- coverage ledger files

Do not read discussion-pack UI/UX sidecars. UI-bearing acceptance tests consume only specs and contracts normalized by /qfai-sdd.

Read Set Contract (Mandatory)

Default Mode:
- .qfai/specs/<spec-id>/01_Spec.md
- .qfai/specs/<spec-id>/03_Acceptance-Criteria.md
- .qfai/specs/<spec-id>/05_Examples.md
- .qfai/specs/<spec-id>/06_Test-Cases.md
Escalation Mode:
- allowed only when 01_Spec.md Escalation Hook signals ambiguity / conflict / missing constraint / trade-off
- read only .qfai/specs/_policies/01_Objective.md and .qfai/specs/_policies/08_Decisions.md
Do not read _policies/** by default.

Sub-agent Delegation (MANDATORY)

Follow .qfai/assistant/constitution/shared-skill-delegation-baseline.md.

Orchestrator Protocol (MUST)

Follow the shared baseline.
Orchestrator MUST NOT self-approve.
Orchestrator MUST NOT generate the primary artifact first draft.

Capability Probe (MUST)

No additional overrides.

Delegation Failure (Hard Stop)

No additional overrides.
Do not simulate roles. If the first required delegation fails, stop the stage and report remediation.

Work Orders Summary

Use the shared schema.

Stage Minimum Roles (MUST)

Delegate: test-design-analyst defines coverage and layer ownership.
Delegate: acceptance-test-engineer implements E2E, API, and integration acceptance tests.
Delegate: devops-ci-engineer captures execution evidence when CI/runtime proof is needed.
Integrate: orchestrator consolidates delegated outputs and presents results.
Gate: completion-reviewer is delegated independently and returns only PASS or REVISE.
Orchestrator must not draft the primary artifact body and must not self-approve.

Reviewer Gate (MUST)

Follow .qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-gate-baseline.
Final completion gate MUST be delegated to an independent completion-reviewer.
ATDD-specific reviewer checks:
- coverage obligations met: E2E covers US, Integration covers TC, API covers CON-API;
- Coverage Depth Matrix is reviewed and no unjustified X cells remain;
- validation evidence exists and qfai validate --profile atdd --fail-on error passes;
- Drift Protocol is enforced;
- test-layer policy is checked against .qfai/assistant/catalog/test-layers.md;
- coverage floors and ratios are signals, not gates;
- scenario.feature and coverage ledgers remain optional legacy inputs, not completion gates.
Route specialist reviewers from .qfai/assistant/manifest/agent-routing.yml.
Default ATDD review set:
- completion-reviewer
- qa-gatekeeper
Add implementation-reviewer only when helper/runtime support code changed.
Do not declare DONE until all routed blocking reviewers return PASS.

Work order template (copy/paste)

Use the shared template.

Reviewer response template

Use the shared template.

Required field: Status (PASS/REVISE).

Stage 0 — Steering completion refresh (mandatory)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#stage-0---steering-completion-refresh-mandatory.

Delta Rejected Guard (Mandatory)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#delta-rejected-guard-mandatory.

CRITICAL CONSTRAINTS (Read First)

Do NOT declare completion based on unit/component tests.
10_Plan.md is the primary How SSOT for execution phases.
If 10_Plan.md is missing, stop and run owner planning flow before proceeding.
Completion gate is validation with zero errors (qfai validate --profile atdd --fail-on error).
Coverage obligations are mandatory:
- tests/e2e/** must cover all required US-*.
- tests/integration/** must cover all required TC-*.
- tests/api/** must cover all required CON-API-*.
Forbidden references:
- tests/api/** must not contain QFAI:SPEC-XXXX:TC-YYYY.
- tests/e2e/** must not contain QFAI:SPEC-XXXX:TC-YYYY.
Unknown references (US/TC/CON-API not declared) must be treated as errors.
Floors/ratios are planning signals only, not gates.
Legacy scenario.feature or coverage ledgers may exist but are not mandatory inputs for completion.
Evidence file is required under .qfai/evidence/ and must not be committed.

Completion Contract (Shared)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#completion-contract-shared. Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol for validate, doctor, and quality-gate failures.

Goal

Turn specs/contracts obligations (US / TC / CON-API) into runnable acceptance tests in this repository.

Scope (ATDD only)

In scope: E2E, API, Integration.
Out of scope: Unit and Component (/qfai-implement).

Non-goals

Unit/Component test implementation.
Product feature changes beyond what is needed for ATDD test execution.

Mandatory Outputs

Test Volume Estimate (signal table with evidence)
Coverage Depth Matrix (per spec; see references/test-case-depth-checklist.md)
Coverage obligations checklist (US / TC / CON-API)
Implemented tests per layer (E2E/API/Integration)
Reviewer notes (PASS or concrete rework list)
Evidence file: .qfai/evidence/atdd-<spec-id>.md

Volume Signals (mandatory, not gates)

E2E signal: number of required US-*
API signal: number of declared CON-API-*
Integration signal: number of required TC-*
When signals are low/high, propose options and recommendation; do not fail solely on signal values.

Estimator output table (required)

Layer	Raw count	Signal	Evidence
E2E	#US	E2E_s	user stories
API	#CON	API_s	API contracts
Integration	#TC	INT_s	test cases

Annotation obligations (mandatory)

Every generated ATDD test MUST include QFAI annotations by layer:

tests/e2e/**: QFAI:SPEC-XXXX:US-YYYY
tests/integration/**: QFAI:SPEC-XXXX:TC-YYYY
tests/api/**: QFAI:CON-API-XXXX

Notes:

AC annotations are optional in code.
QFAI:CON-API-* in E2E is not forbidden, but contract guarantee belongs to API tests.

Success Criteria (Definition of Done)

All required US are covered by E2E tests.
All required TC are covered by integration tests.
All required CON-API are covered by API tests.
Validation passes: qfai validate --profile atdd --fail-on error.
Repository quality gates (format/lint/type/tests/pack) pass with evidence.
Evidence file exists and includes work orders + reviewer notes.
Completion is approved by a reviewer who did not implement tests.

Not-done criteria

Any required US / TC / CON-API remains uncovered.
Forbidden references remain.
Tests exist but were never executed.
Validation evidence is missing or failing.
Coverage Depth Matrix is missing or contains unjustified ❌ cells (normal-path-only coverage is incomplete).

Failure handling (mandatory)

If blocked/unknown, stop and raise a Decision Record.
Do not declare completion when any gate is FAIL; iterate until PASS.

Evidence (MANDATORY)

Create and update: .qfai/evidence/atdd-<spec-id>.md

Required sections:

Objective
Inputs reviewed (files/paths)
Decisions made (with rationale)
Work performed (what changed, where)
Commands executed + key outputs
Test volume estimate
Coverage obligations checklist
Work Orders Summary
Execution logs
Gaps / Open risks
Final status (PASS/FAIL) + who confirmed

Template:

# ATDD Evidence: <spec-id>

## Objective

## Inputs reviewed (files/paths)

## Decisions made (with rationale)

## Work performed (what changed, where)

## Commands executed + key outputs

## Test volume estimate

## Coverage obligations checklist

## Work Orders Summary

## Execution logs

## Gaps / Open risks

## Final status (PASS/FAIL) + who confirmed

ATDD Work Orders (mandatory)

Test Case Depth Analyst: test-design-analyst evaluates test cases using references/test-case-depth-checklist.md, produces Coverage Depth Matrix, flags gaps in boundary/error/edge coverage.
Test Volume Estimator: compute US/TC/CON signals with evidence.
ATDD E2E Implementer: implement required US coverage.
ATDD API Implementer: implement required CON-API coverage.
ATDD Integration Implementer: implement required TC coverage.
Reviewer: validate coverage obligations + gate results + Coverage Depth Matrix (non-edit).
Runtime Gatekeeper: run suites and capture logs.

Completion Separation (mandatory)

Implementation and completion approval must be separate.
Reviewer must be non-edit (PASS or REVISE only).

Stage Gates (Do not skip)

P0: Plan and obligations checklist prepared.
P1: Layer assignment validated.
P2: E2E implementation completed.
P3: API implementation completed.
P4: Integration implementation completed.
P5: Validation gate passed.
P6: Runtime evidence captured.
P7: Repo quality gates passed.
P8: Reviewer confirms completion.

Completion Criteria (Final Gate)

Before declaring completion:

Confirm required US / TC / CON-API coverage is complete.

Run:

qfai validate --profile atdd --fail-on error

Run repository standard gates:
- format check
- lint
- typecheck
- tests
- pack/verify (if distributed)
Record exact commands and outcomes.

If commands cannot be run due to environment limits, request user execution and do not assume PASS.

Output

Acceptance test implementation files (with required annotations)
Runbook snippet (copy-paste command)
Verification evidence summary
Gate results (PASS/FAIL)

DONE Declaration (Mandatory Output)

When declaring DONE, include:

Referenced inputs (instructions/steering and spec delta)
DR-IDs referenced (or "none")
Confirmation that no rejected options were reintroduced (or RE-OPEN DR-IDs)

FINAL CHECKLIST (Check Last)

CRITICAL CONSTRAINTS were followed.
Evidence file exists and is complete.
Mandatory checks were executed and recorded.
No untracked gaps remain (or they are explicitly documented).
Completion approved by an independent reviewer.

Completion Checklist (MUST)

This skill's Definition of Done is satisfied.
Required artifacts were produced or updated.
Open questions were logged to the proper OQ file (if applicable).
The completion message was presented to the user.
Next actions were enumerated for all available options.

Completion Message & Next Actions (MUST)

When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.

Proceed (recommended): /qfai-implement. Action: run unified TDD micro-cycle (Red/Green/Refactor) one test at a time from test-list.md.
Acceptance tests need fixes: rerun /qfai-atdd. Action: close uncovered US / TC / CON-API obligations and rerun validation.

Default Autopilot Policy

The skill collapses avoidable per-session prompts to 0-1 by classifying every decision into one of three named buckets:

auto-decide:
- output formatting
- ID / sequence numbering
- append-vs-create on subject overlap
- equivalent-option pick
ask-user:
- CREATE / DELETE / SPLIT / MERGE / SUPERSEDE / UPDATE:REMOVE triage operations (each with a prompt template that names the target and rationale)
- destructive operations (rm / overwrite / force-push)
- version-pin changes (package.json#version, branch pin)
- scope expansions outside the active envelope
hard-required:
- companyName
- brand intent
- primarySpecId (when absent from inputs)

A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it. Widening triggers a Reviewer-Gate finding.

project_memory:

Coverage obligations stay layer-pinned: tests/e2e/** must cover all required US; tests/integration/** all required TC; tests/api/** all required CON-API.
Forbidden references guard the test-layer policy: tests/api/** must not carry QFAI:SPEC-XXXX:TC-YYYY annotations; tests/e2e/** likewise.
Floor / ratio signals are planning hints, never gates; legacy scenario.feature / coverage ledger files remain optional inputs.