Autonomous Tdd Loop

Autonomous TDD Loop

This skill orchestrates a multi-agent workflow to implement code changes while

strictly enforcing test validation and code quality standards.

Requirements

• Ideally, an agents.md file at the root of the repository defines the

Verifier and Reviewer personas and test commands. If absent, the workflow

will prompt the user for this information.

The Workflow

When this skill is invoked, follow these exact phases in order:

Phase 0: Environment Check

Before invoking the Verifier or Reviewer subagents, you MUST verify the

environment:

• Check Documentation: Check if the repository contains an AGENTS.md,

agents.md, or REVIEW_GUIDELINES.md file at the root.

• Fallback to User: If none of these files exist, you MUST pause your

work and explicitly ask the user to provide the exact commands needed to

build and run tests for this project. Do not proceed until you have this

information.

• Use Commands: Use the commands provided by the user to instruct the

Verifier in subsequent phases, rather than guessing or assuming the

environment.

Phase 1: Applicability & Test Creation (Worker)

• Assess: Determine if a unit/regression test is applicable for the

user's goal. Also assess the validation scope (e.g., does this need a

full xcodebuild suite, or just a quick ./scripts/check_whitespace.sh?).

If a test is not applicable, state the reason, record your validation

scope, and skip to Phase 4.

• Write Test: Write a failing test for the issue. *Do not apply the fix

yet.*

• **Crucial Rule for Swift Concurrency / AsyncStream / URLSession

Cancellation:** When writing tests to verify that an AsyncStream

properly cleans up resources or cancels underlying network requests on

termination, do not mock delays that naturally finish the task.

Buffering in URLSession will mask timeouts, and naturally finishing a

mocked operation will trigger system cleanup that masks missing explicit

cancellation.

• Instead: Wrap the stream consumption in a consumer Task, yield or

Task.sleep for a tiny duration (e.g. 100ms) to allow initialization,

and explicitly call .cancel() on the consumer Task. Verify that the

underlying mocked resource receives the cancellation (e.g.,

stopLoading() is called).

Phase 2: Sanity Check 1 (Verifier)

• Invoke a Verifier subagent using invoke_subagent (Role: "Objective

Code Verifier").

• Instruction to Verifier: "Read the Root agents.md for this repo (or

use the test commands provided by the user) to find the test execution

command. Run the tests. Your ONLY goal is to verify that the specific test

I just added currently FAILS. Do not try to fix it. Return a binary

pass/fail result based on this."

• Wait for the Verifier's response. If the test does not fail, revise the

test until it does.

Phase 3: Implementation (Worker)

• Consult Guidelines: Read REVIEW_GUIDELINES.md (if it exists) to ensure

your implementation adheres to repository-specific coding standards.

• Apply Fix: Apply the code fix for the issue.

Phase 4: Sanity Check 2 (Verifier)

• Send a message to the existing Verifier subagent.
• Instruction to Verifier: "I have applied a fix. Please run the

tests/checks using the command from agents.md (or the commands provided

by the user), but optimize for the validation scope I determined in

Phase 1 (e.g., if it's just a whitespace fix, only run the style script

instead of the full test suite). Verify that the required checks now

PASS."

• If the Verifier reports failures, iterate on the implementation and repeat

this phase.

Phase 5: Strict TDD Revert Loop (Worker & Verifier)

*Skip this phase if no tests were added in Phase 1.*

• Temporarily comment out or revert the core logic of the fix.
• Send a message to the Verifier: "I have temporarily reverted the fix.

Run the tests again and confirm that the *exact same tests* fail again."

• Once the Verifier confirms the failure, uncomment/re-apply the fix.

Phase 6: Qualitative Review (Reviewer)

• Invoke a Reviewer subagent using invoke_subagent (Role: "Rigorous

Code Reviewer").

• Instruction to Reviewer: "Read the Root agents.md and any

REVIEW_GUIDELINES.md for this repo (if they exist). Perform a rigorous,

subjective code review on my changes. Focus on concurrency, memory

management, and API design. Flag any issues."

• Iterate with the Reviewer until it approves the changes based on the rubric.

Phase 7: Key Learnings & Completion

• Systemic Memory: If you encountered any systemic friction (e.g., a

flaky simulator, a recurring build quirk, misleading existing

documentation), append it to the .agents/MEMORY.md file in the workspace

root.

• Knowledge Migration: If the friction you just recorded is a permanent

quirk of the repository that all contributors should know about (rather

than a transient local machine issue), explicitly prompt the user: "I added

a note about [Topic] to your local .agents/MEMORY.md. I recommend we

permanently add this to the repository's agents.md file so all

contributors benefit from this knowledge. Would you like me to do that?"

• Changelog Update: Ensure you update the relevant product's CHANGELOG.md

file with a description of the change under a new top-level # Unreleased section.

• If the user requested PR creation, use the gh CLI to create a PR and wait

for CI/human feedback. Otherwise, notify the user that the loop is

complete.