auto-tdd-executor
Combines Ralph Wiggum loops with structured feature plans for automated TDD-driven development. Crea
by Henry229|Open Source
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-promisematches exactly - Verify quality gate commands are correct
- Increase
--max-iterations
E2E tests keep failing
- Run
playwright-test-healeragent - 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
- Phase Sizing: 1-4 hours max per phase
- Test First: Always write tests before code
- Small Commits: Commit after each TDD cycle
- Beads Notes: Update notes regularly
- E2E Last: Run E2E only after unit tests pass