aganesy/qfai-implement

<!-- QFAI Skill Body (SSOT) - This file is intended to be referenced by tool-specific wrappers (e.g., GitHub/Claude/Codex skills). - Keep wrappers thin and route users to this skill body. -->

/qfai-implement - Unified TDD Micro-cycle

[DRIFT-PROTOCOL:MANDATORY]

Spec Auto-Discovery Protocol

When no explicit argument is given, detect the candidate spec and constrain execution to one spec only.

One-Spec-at-a-Time Guarantee

• Auto-discovery selects at most one spec for this run.
• This protocol does NOT enable multi-spec parallel execution.
• If multiple candidate specs are detected, do not start implementation until the user selects exactly one spec.

User Selection Flow

• Single spec detected: announce the detected spec and ask for confirmation when scope is ambiguous.
• Multiple specs detected: display the candidates and require the user to choose one spec.
• Zero specs detected: stop and ask the user to provide the target spec explicitly.

User Questions (AskUserQuestion Protocol)

• When a question to the user is needed (e.g., exception handling, scope confirmation), the agent MUST use AskUserQuestion if the tool is available.
• When AskUserQuestion supports structured choices (radio/multi-select), the agent MUST prefer structured choices over free-text input.
• If AskUserQuestion is technically unavailable, present the same question as a normal message with explicit numbered choices. The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints). The reason for unavailability MUST be stated.

CRITICAL CONSTRAINTS (Read First)

• This skill processes one test at a time from test-list.md.
• Each item goes through the full TDD micro-cycle: write a failing test first, then make it pass, then refactor.
• The execution ledger is located at .qfai/specs/spec-XXXX/tdd/test-list.md.
• Items are processed serially by default. Parallel processing is allowed only when items target independent SUT slices with no shared state.
• Status transitions follow a strict forward-only lifecycle: todo -> red -> green -> refactor -> done.
• The exception status can be reached from any active status when an anomaly is detected.
• Backward transitions are prohibited (e.g., green -> red is not allowed).
• Completed items (done) are skipped on re-execution.
• When all items are done, report "nothing to do" and exit.

Goal

Execute the TDD micro-cycle for each pending item in test-list.md, transitioning each through Red -> Green -> Refactor -> Done, producing tested production code aligned with the spec.

Visual Review Guard

• Review rendered output, screenshot evidence, or HTML output before closing any UI-affecting item.
• Read the DDP (Design Direction Pack) first whenever implementation touches UI or critique-driven behavior.
• Read order: DDP -> Design Token -> UI Contract -> HTML Mock -> Flow.
• If code intent and rendered output diverge, treat the rendered/HTML result as the blocking review input and reconcile before DONE.

Non-goals

• Writing spec artifacts (use /qfai-sdd).
• Writing acceptance tests (use /qfai-atdd).
• Running validation gates (use /qfai-verify).
• Parallel execution across multiple specs simultaneously.

Execution Ledger: test-list.md

The execution ledger at .qfai/specs/spec-XXXX/tdd/test-list.md tracks progress with these required columns:

| Column | Description | | --------- | -------------------------------------------------------- | | TDD-ID | Unique identifier for the TDD item (e.g., TDD-0001) | | TC-Refs | References to test cases from 06_Test-Cases.md | | Layer | Test layer (Unit, Integration, etc.) | | Test file | Path to the test file | | Selector | Test selector/description for targeted execution | | Status | Current lifecycle status | | DR-ID | Decision Record ID for exception items (blank otherwise) | | Evidence | RED/GREEN command+result pairs proving the TDD cycle |

Status Lifecycle

Valid status values: todo, red, green, refactor, done, exception.

Allowed transitions:

• todo -> red (write a failing test)
• red -> green (make the test pass with minimal code)
• green -> refactor (improve code quality while keeping tests green)
• refactor -> done (item complete)
• Any active status -> exception (anomaly detected; record DR-ID in DR-ID column)

Backward transitions are prohibited. Attempting green -> red must produce: "Backward transition prohibited: green -> red".

Exception Handling

When transitioning to exception:

• A DR-ID (Decision Record ID) must be recorded in the DR-ID column.
• If the DR-ID column is empty, emit error: "exception status requires DR-ID in DR-ID column".

Required Process

Phase: Red (Write Failing Test)

1. Read test-list.md and select the first item with Status = todo.
2. Transition status to red.
3. Write a failing test based on the TC-Refs specification.
4. Run the test and watch it fail — confirm the test actually fails for the expected reason.
5. If the test unexpectedly passes, transition to exception and record the anomaly.

Phase: Green (Make It Pass)

1. Write the minimum production code to make the failing test pass.
2. Run the test and watch it pass.
3. Transition status to green.
4. If the test still fails after implementation, investigate and fix. Do not skip to refactor.

Phase: Refactor

1. Improve code quality (naming, structure, duplication removal) while keeping all tests green.
2. Run the full relevant test suite to confirm nothing broke.
3. Transition status to refactor.
4. Submit for completion review (completion-reviewer) and code quality review (implementation-reviewer).
5. After all routed blocking reviewers return PASS, run checkpoint verification, then transition to done.

Completion

1. After processing all items, update test-list.md with final statuses.
2. If all items are done, report "All items complete".
3. If some items are exception, report them with their DR-IDs.

Sub-agent Delegation (MANDATORY)

Orchestrator Protocol (MUST)

• Orchestrator reads test-list.md, determines the next pending item, and delegates each TDD phase.
• Orchestrator MUST NOT write test or production code directly.
• Orchestrator updates test-list.md status after each phase completes.

Formal Sub-agent Roster

This skill delegates through the centralized routing policy in .qfai/assistant/steering/agent-routing.yml.

• delivery-planner
  • reads test-list.md, selects the next pending item, enforces Red-Green-Refactor ordering, and decides parallel safety
• frontend-engineer / backend-engineer
  • implement the selected item only, write the failing test first, write minimal passing code, and refactor without unrelated changes
• qa-gatekeeper
  • is the sole authority for validating RED/GREEN observation evidence and completion gate evidence
• implementation-reviewer
  • reviews code quality, maintainability, backend correctness, and hidden coupling
• completion-reviewer
  • verifies spec alignment, drift-protocol compliance, and final DoD
• product-surface-reviewer
  • reviews UI-affecting implementation when the item changes surface behavior

Handoff Contracts

All agent-to-agent transitions follow these contracts:

1. delivery-planner selects the next item and assigns it to the appropriate implementation agent.
2. Implementation agent submits RED/GREEN execution evidence to qa-gatekeeper.
3. qa-gatekeeper confirms or rejects the RED/GREEN observation.
4. After GREEN, implementation agent submits the item to completion-reviewer for spec alignment and to implementation-reviewer for code quality review.
5. product-surface-reviewer is added when the item affects UI behavior or rendered output.
6. Only after all routed blocking reviewers pass may the item transition to done.

Capability Probe (MUST)

1. Run one harmless Probe Task once at stage start.
2. If subagents are unavailable, explicitly ask for Simulation mode approval.
3. Without explicit approval, stop the stage.

Simulation mode (Opt-in only)

• Allowed only when user explicitly states Simulation mode allowed.
• Record both:
  • Subagents: simulated (reason: <why unavailable>)
  • User approval: <quote or reference>

Work Orders Summary

Every major artifact in this stage MUST include this table schema:

| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) | | ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- | | 1 | role | task | refs | refs | PASS/REVISE |

Reviewer Gate (MUST)

• Delegate final completion gate to an independent Reviewer.
• Reviewer checks Drift Protocol compliance and alignment with .qfai/assistant/steering/test-layers.md.
• Test volume floors/ratios are not gates; they are signals.
• Do not declare DONE until Reviewer returns PASS; otherwise apply REVISE.

Parallelization Policy

• Default: Serial execution. Items are processed one test at a time in test-list.md order.
• Exception: When items target completely independent SUT modules with no shared state, parallel processing may be used with explicit user approval.
• Serial execution ensures that each test is written and verified in isolation before moving to the next.
• delivery-planner is the sole authority for authorizing parallel dispatch.

Allow conditions (all must be true)

• Independent SUT (no shared source files under test)
• Independent test files (no shared test files or fixtures)
• No shared state (no shared database, global variable, singleton, or DI container)
• No sequential dependency (Slice B does not depend on Slice A output)
• Worktree or branch separation is available
• Post-merge integration verify plan exists

Deny conditions (any one blocks parallel dispatch)

• Same behavior Red/Green/Refactor cycle across slices
• Same public API surface modified by multiple slices
• Shared fixture, shared mock, shared DI container, shared global setup
• Sequential dependency: "A must finish before B has meaning"
• Independence claim cannot be explained with concrete file/module evidence

Post-parallel integration verify

• After parallel slices complete and merge, run integration verify on the merged result
• If integration verify fails, flag all slices for re-examination and roll back the merge
• If integration verify passes, state transitions back to delivery-planner for sequential flow

Completion Contract (Shared)

Item completion checklist (10-point gate)

An item in test-list.md may transition to done only when ALL of the following are satisfied:

1. Corresponding TDD-ID has been selected and is in progress
2. A failing test was added first (test-first)
3. RED was observed — qa-gatekeeper confirmed the test failed for the expected reason (watch it fail)
4. Minimal production code was written to make the test pass
5. GREEN was observed — qa-gatekeeper confirmed the test passes after implementation (watch it pass)
6. Refactor was performed and GREEN was re-confirmed after refactor
7. completion-reviewer returned PASS (spec / completion review gate)
8. implementation-reviewer returned PASS (code quality review gate)
9. test-list.md Status and Evidence columns are updated with fresh evidence
10. Checkpoint verification passed

Spec completion conditions

The skill may declare "this spec's implementation is complete" only when:

• All TC-* from 06_Test-Cases.md with applicable layer are present in test-list.md
• Each item reached done or valid exception (with DR-ID)
• 0 blocking reviewer issues remain
• Checkpoint verification passed
• No unresolved Change Request or waiver dependency exists

Completion prohibition conditions

Completion MUST NOT be declared when any of the following are true:

• No RED fresh evidence exists for the item
• No GREEN fresh evidence exists for the item
• Either reviewer (completion-reviewer or implementation-reviewer) has not been run or returned FAIL
• Items with todo, red, green, or refactor status still exist (for spec-level completion)
• Parallel slices were used but integration verify has not been run post-merge
• Checkpoint boundary was reached but verification was not executed

Evidence (MANDATORY)

Create/update: .qfai/evidence/implement-spec-XXXX.md

Required sections:

• Objective
• Items processed (TDD-ID, TC-Refs, final status)
• Test results summary
• Exception items (if any) with DR-IDs
• Commands executed

Per-item evidence contract (fresh evidence required)

Each TDD item MUST have fresh evidence containing at minimum:

• TDD-ID — the item identifier
• TC-ref — reference to the test case(s)
• RED command — the exact command executed to observe failure
• RED result — the failure output (result completeness is best-effort; truncated output is acceptable)
• GREEN command — the exact command executed to observe success
• GREEN result — the success output
• Refactor verify command — the exact command re-executed after refactor
• Refactor verify result — the output confirming GREEN is maintained
• Spec review — completion-reviewer result (PASS or FAIL)
• Code quality review — implementation-reviewer result (PASS or FAIL)

Evidence hard rules

• Status-only evidence (e.g., "Status: PASS" with no command) is invalid and MUST be rejected
• Both command and result are required; "should pass" or "looks good" alone is not acceptable
• Stale evidence from a previous run MUST NOT be reused to claim completion for a new cycle
• Empty evidence entries are rejected: minimum evidence per TDD item must be met

FINAL CHECKLIST (Check Last)

• [ ] CRITICAL CONSTRAINTS were followed.
• [ ] Each item was processed one test at a time.
• [ ] Red phase: test was written and confirmed to fail.
• [ ] Green phase: minimal code was written and test confirmed to pass.
• [ ] Refactor phase: code improved with tests still passing.
• [ ] test-list.md statuses are accurate.
• [ ] No backward transitions occurred.
• [ ] Exception items have DR-IDs recorded.
• [ ] All tests pass.

Completion Checklist (MUST)

• [ ] This skill's Definition of Done is satisfied.
• [ ] Required artifacts were produced or updated (if applicable).
• [ ] 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.

• Verify gates: /qfai-verify. Action: run qfai validate --fail-on error and confirm all gates pass.
• Spec updates needed: /qfai-sdd. Action: update spec artifacts if implementation revealed scope changes.
• Acceptance tests: /qfai-atdd. Action: ensure acceptance test coverage aligns with implementation.