Auto TDD Executor

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

Core Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                       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

┌─────────────────────────────────────────────────────────────────────┐
│                         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

Command	Description
/auto-tdd-start	Initialize project with Beads issues from plan
/auto-tdd-run	Execute current phase with TDD + E2E
/auto-tdd-e2e	Run E2E tests with Playwright agents
/auto-tdd-status	Show progress and remaining phases

Prerequisites

# 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

# 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

Launch 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

# 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)

/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

# 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

project/
├── .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