# Autonomous Tdd Loop

> Orchestrates a strict TDD loop across subagents to build features.

- Skill: `firebase/autonomous-tdd-loop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add firebase/autonomous-tdd-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/firebase/autonomous-tdd-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: firebase (https://skillmd.com/u/firebase)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/firebase/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.