---

name: auto-tdd-executor description: Combines Ralph Wiggum loops with structured feature plans for automated TDD-driven development. Creates phase-based plans with quality gates, then executes each phase using Ralph loops with Beads for persistent state tracking. Includes E2E testing with Playwright agents. Use for automated overnight development, complex feature implementation, or when you want AI to iterate until tests pass.

Auto TDD Executor

Automated TDD development with Ralph Wiggum loops, Beads persistence, and Playwright E2E testing.

Core Architecture

Copy┌──────────────────────────────────────────────────────────────────────┐
│                       Auto TDD Executor                              │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────┐  │
│  │   Feature   │───▶│   Ralph     │───▶│        Beads            │  │
│  │   Planner   │    │   Wiggum    │    │     (Persistence)       │  │
│  └─────────────┘    └─────────────┘    └─────────────────────────┘  │
│         │                  │                        │                │
│         ▼                  ▼                        ▼                │
│    Phase-based        TDD Loop               Survives context       │
│    Quality Gates    Red-Green-Refactor          compaction          │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                    E2E Test Phase                               │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │ │
│  │  │  Playwright │  │  Playwright │  │  Playwright │            │ │
│  │  │   Planner   │  │  Generator  │  │   Healer    │            │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘            │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Complete Workflow

Copy┌─────────────────────────────────────────────────────────────────────┐
│                         Full Development Loop                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. PLAN                                                             │
│     └─▶ /auto-tdd-start                                             │
│         └─▶ Create Beads issues from plan                           │
│                                                                      │
│  2. IMPLEMENT (TDD)                              ┌───────────────┐  │
│     └─▶ /auto-tdd-run                           │               │  │
│         ├─▶ 🔴 RED: Write failing tests ────────┤   Ralph       │  │
│         ├─▶ 🟢 GREEN: Implement minimal code ───┤   Wiggum      │  │
│         ├─▶ 🔵 REFACTOR: Improve quality ───────┤   Loop        │  │
│         └─▶ ✅ Unit Tests Pass ─────────────────┘               │  │
│                      │                                              │
│  3. E2E TEST         ▼                                              │
│     └─▶ /auto-tdd-e2e                           ┌───────────────┐  │
│         ├─▶ playwright-test-planner ────────────┤   Parallel    │  │
│         ├─▶ playwright-test-generator ──────────┤   Agents      │  │
│         └─▶ If fail: playwright-test-healer ────┘               │  │
│                      │                                              │
│                      ├─── FAIL ──▶ Back to Step 2 (fix bugs)       │
│                      │                                              │
│                      ▼                                              │
│  4. QUALITY GATE                                                     │
│     └─▶ scripts/quality-gate.sh                                     │
│         ├─▶ Unit Tests                                              │
│         ├─▶ Lint                                                    │
│         ├─▶ Type Check                                              │
│         ├─▶ Build                                                   │
│         └─▶ E2E Tests                                               │
│                      │                                              │
│                      ├─── FAIL ──▶ Back to Step 2                   │
│                      │                                              │
│                      ▼                                              │
│  5. COMMIT                                                           │
│     └─▶ git add . && git commit -m "Phase complete"                 │
│     └─▶ git push                                                    │
│     └─▶ bd close $ISSUE_ID                                          │
│                      │                                              │
│                      ▼                                              │
│  6. NEXT PHASE ──────┴──▶ Repeat from Step 2                        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Commands

Prerequisites

Copy# 1. Ralph Wiggum plugin
/plugin install ralph-wiggum@anthropics

# 2. Beads CLI
npm install -g @beads/bd
bd init

# 3. Playwright (for E2E)
npm install -D @playwright/test
npx playwright install

Quick Start

Copy# 1. Create plan document
# Use feature-planner skill or create .doc/plans/PLAN_<feature>.md

# 2. Initialize beads issues
/auto-tdd-start

# 3. Execute phases (repeat until done)
/auto-tdd-run

# 4. Check status
/auto-tdd-status

Playwright Agent Integration

playwright-test-planner

• Explores the application UI
• Creates test scenarios for user flows
• Outputs: specs/test.plan.md

playwright-test-generator

• Reads test plan
• Generates Playwright test files
• Outputs: tests/<suite>/<test>.spec.ts

playwright-test-healer

• Debugs failing tests
• Updates selectors and assertions
• Fixes flaky tests

Parallel Execution

CopyLaunch 3 Task tools in parallel:

1. subagent_type="playwright-test-generator" (Auth tests)
2. subagent_type="playwright-test-generator" (User tests)
3. subagent_type="playwright-test-generator" (API tests)

Quality Gate Script

Copy# Run all checks
./scripts/quality-gate.sh

# With options
./scripts/quality-gate.sh --verbose --skip-e2e

Returns:

• Exit 0 + "QUALITY_GATE_PASSED" if all pass
• Exit 1 + "QUALITY_GATE_FAILED" if any fail

TDD Prompt Template (Simplified)

Copy/ralph-loop "
═══ PHASE: [Title] ═══
Issue: [ISSUE_ID]

CONTEXT: bd show [ISSUE_ID]

TDD:
🔴 RED: Write tests → npm test → Expect FAIL
🟢 GREEN: Implement → npm test → Expect PASS
🔵 REFACTOR: Clean → npm test → Confirm PASS

QUALITY GATE:
npm test && npm run lint && npm run type-check && npm run build

ON PASS:
git add . && git commit -m 'Complete: [Title]'
bd close [ISSUE_ID]
<promise>PHASE_COMPLETE</promise>
" --max-iterations 50 --completion-promise "PHASE_COMPLETE"

Beads Integration

Copy# Create phase issue
bd create "Phase 1: Core Models" -t task -p 1

# Set dependencies
bd dep add <phase2> <phase1> --type blocks

# Update progress
bd update <id> --notes "Progress: 50%"

# Close on completion
bd close <id> --reason "Quality gate passed"

# Check what's ready
bd ready

Directory Structure

Copyproject/
├── .beads/              # Beads database
├── docs/plans/          # Plan documents
│   └── PLAN_<feature>.md
├── specs/               # E2E test plans
│   └── test.plan.md
├── tests/               # E2E test files
│   ├── seed.spec.ts
│   └── <suite>/
│       └── <test>.spec.ts
├── src/                 # Implementation
└── scripts/
    └── quality-gate.sh  # Quality gate automation

Troubleshooting

Ralph loop never completes

• Check --completion-promise matches exactly
• Verify quality gate commands are correct
• Increase --max-iterations

E2E tests keep failing

• Run playwright-test-healer agent
• Check if app is running (npm run dev)
• Verify selectors haven't changed

Context loss mid-phase

• Beads preserves state: bd show <id>
• Git commits preserve code
• Restart Ralph with same prompt

Quality gate fails

• Run ./scripts/quality-gate.sh --verbose
• Fix one issue at a time
• Rerun until all pass

Best Practices

1. Phase Sizing: 1-4 hours max per phase
2. Test First: Always write tests before code
3. Small Commits: Commit after each TDD cycle
4. Beads Notes: Update notes regularly
5. E2E Last: Run E2E only after unit tests pass