/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:

1. Check Documentation: Check if the repository contains an AGENTS.md, agents.md, or REVIEW_GUIDELINES.md file at the root.
2. 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.
3. 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)

1. 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.
2. 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)

1. Invoke a Verifier subagent using invoke_subagent (Role: "Objective Code Verifier").
2. 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."
3. Wait for the Verifier's response. If the test does not fail, revise the test until it does.

Phase 3: Implementation (Worker)

1. Consult Guidelines: Read REVIEW_GUIDELINES.md (if it exists) to ensure your implementation adheres to repository-specific coding standards.
2. Apply Fix: Apply the code fix for the issue.

Phase 4: Sanity Check 2 (Verifier)

1. Send a message to the existing Verifier subagent.
2. 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."
3. 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.

1. Temporarily comment out or revert the core logic of the fix.
2. 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."
3. Once the Verifier confirms the failure, uncomment/re-apply the fix.

Phase 6: Qualitative Review (Reviewer)

1. Invoke a Reviewer subagent using invoke_subagent (Role: "Rigorous Code Reviewer").
2. 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."
3. Iterate with the Reviewer until it approves the changes based on the rubric.

Phase 7: Key Learnings & Completion

1. 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.
2. 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?"
3. 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.
4. 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.