tdd-workflow
Test-Driven Development workflow coordinator. Detects TDD intent and offers guided red-green-refactor cycle. Activates for TDD, test-driven, red-green-refactor, write tests first, test-first development, Kent Beck, TDD cycle.
When & Why to Use This Skill
This Claude skill acts as a specialized coordinator for Test-Driven Development (TDD), designed to streamline the Red-Green-Refactor workflow. It serves as an intelligent discovery hub that detects TDD intent, provides educational guidance on Kent Beck’s principles, and routes developers to the most appropriate tools—ranging from rigid guided cycles to advanced AI-driven orchestration for complex refactoring tasks.
Use Cases
- Feature Implementation with Discipline: Automatically guiding developers through the 'Red' phase (writing failing tests) before allowing implementation to ensure high code quality and requirement alignment.
- TDD Mentorship and Onboarding: Assisting developers new to TDD by providing real-time best practices, preventing common anti-patterns like over-engineering during the 'Green' phase.
- Legacy Code Refactoring: Utilizing the integrated TDD Orchestrator agent to establish safety nets and characterization tests when modifying complex, untested existing codebases.
- Workflow Automation: Seamlessly transitioning between testing and coding phases within the SpecWeave environment, ensuring that refactoring only occurs when tests are green.
| name | tdd-workflow |
|---|---|
| description | Test-Driven Development workflow coordinator. Detects TDD intent and offers guided red-green-refactor cycle. Activates for TDD, test-driven, red-green-refactor, write tests first, test-first development, Kent Beck, TDD cycle. |
TDD Workflow - Discovery & Coordination Skill
Purpose
This skill acts as a discovery hub for Test-Driven Development (TDD) in SpecWeave. It:
- ✅ Detects when users want to implement features with TDD
- ✅ Asks user preference for TDD workflow enforcement
- ✅ Routes to appropriate TDD tools (commands vs agent)
- ✅ Provides TDD education and best practices
NOT a full TDD implementation - delegates to:
tdd-orchestratoragent (deep TDD expertise)/sw:tdd:cyclecommand (enforced red-green-refactor)- Individual phase commands (
/sw:tdd:red,/sw:tdd:green,/sw:tdd:refactor)
When to Activate
Automatic activation when user mentions:
- "implement with TDD"
- "use test-driven development"
- "red-green-refactor"
- "write tests first"
- "test-first approach"
- "Kent Beck style"
- "TDD discipline"
Example triggers:
User: "Implement authentication with TDD"
User: "Use test-driven development for this feature"
User: "Let's do red-green-refactor for the payment module"
Workflow
Step 1: Detect TDD Intent
When activated, confirm user's TDD intent:
"I detected you want to use Test-Driven Development (TDD).
TDD follows the red-green-refactor cycle:
🔴 RED: Write a failing test first
🟢 GREEN: Write minimal code to make it pass
🔵 REFACTOR: Improve code while keeping tests green
Would you like to:"
Step 2: Offer TDD Options
Use AskUserQuestion tool to present choices:
Question: "How would you like to implement TDD for this feature?"
Options:
1. "Guided TDD Workflow (/sw:tdd:cycle)"
Description: "Full red-green-refactor cycle with gates between phases.
Can't proceed to GREEN without RED test. Most rigorous."
2. "Expert TDD Agent (tdd-orchestrator)"
Description: "Deep TDD expertise with flexible workflow.
Best for complex scenarios, property-based testing, legacy code."
3. "Manual TDD (I'll guide myself)"
Description: "I'll implement TDD discipline myself.
You provide TDD advice when needed."
Step 3: Route Based on Choice
Option 1: Guided TDD Workflow
Invoke: /sw:tdd:cycle
This command orchestrates:
1. /sw:tdd:red - Write failing test (blocks until red)
2. /sw:tdd:green - Implement minimal code (blocks until green)
3. /sw:tdd:refactor - Refactor safely (tests must stay green)
Benefits:
- Enforces discipline (gates prevent skipping phases)
- Perfect for beginners or teams learning TDD
- Integrates with SpecWeave increment workflow
Option 2: Expert TDD Agent
Invoke: tdd-orchestrator agent (via Task tool)
This agent provides:
- Multi-agent TDD workflow coordination
- Property-based testing (QuickCheck, Hypothesis)
- Mutation testing for test quality
- Legacy code refactoring with safety nets
- BDD/ATDD integration
- AI-assisted test generation
Benefits:
- Flexible workflow (not rigid gates)
- Advanced techniques (property-based, mutation)
- Best for experienced TDD practitioners
- Handles complex scenarios
Option 3: Manual TDD
Provide TDD best practices:
"I'll implement your feature while following TDD principles.
I'll ensure:
- Tests written before implementation
- Minimal code to pass tests
- Refactoring with test coverage
- Clear red→green→refactor progression
I'll notify you at each phase transition."
TDD Best Practices (Reference)
Red Phase 🔴
- Write the simplest test that fails
- Test should compile but fail on assertion
- Focus on WHAT, not HOW
- One test at a time
Green Phase 🟢
- Write minimal code to pass the test
- Embrace "fake it till you make it"
- Hardcoded values acceptable initially
- Get to green FAST
Refactor Phase 🔵
- Improve code structure
- Extract methods, remove duplication
- Tests must stay green
- Commit after each refactor
TDD Anti-Patterns to Avoid
- ❌ Writing implementation before test
- ❌ Writing multiple tests before implementation
- ❌ Over-engineering in GREEN phase
- ❌ Refactoring without tests passing
- ❌ Skipping refactor phase
Integration with SpecWeave
In Increment Workflow:
/sw:inc "Authentication feature" → spec.md created
↓
User: "Implement with TDD"
↓
tdd-workflow skill activates → offers options
↓
User chooses: Guided TDD Workflow
↓
/sw:tdd:cycle invoked
↓
Phase 1: RED - tests.md updated with failing tests
Phase 2: GREEN - tasks.md implementation
Phase 3: REFACTOR - code improvements
↓
Increment tasks completed with TDD discipline
With spec-driven-debugging:
Bug found → spec-driven-debugging activates
↓
Fix proposal includes: "Add regression test first (TDD RED phase)"
↓
tdd-workflow can coordinate test-first bug fixes
Commands Reference
Full Cycle
/sw:tdd:cycle- Complete red-green-refactor orchestration
Individual Phases
/sw:tdd:red- RED phase only (write failing test)/sw:tdd:green- GREEN phase only (make test pass)/sw:tdd:refactor- REFACTOR phase only (improve code)
When to Use Each
Use /sw:tdd:cycle when:
- ✅ Starting new feature from scratch
- ✅ Learning TDD or teaching team
- ✅ Want enforced discipline (gates)
- ✅ Working in increment-based workflow
Use individual commands when:
- ✅ Already in middle of TDD cycle
- ✅ Need to repeat a phase (e.g., multiple refactors)
- ✅ Want finer control over cycle
- ✅ Integrating with other workflows
Use tdd-orchestrator agent when:
- ✅ Complex scenarios (property-based testing)
- ✅ Legacy code refactoring
- ✅ Multi-agent coordination needed
- ✅ Advanced TDD techniques required
Example Interactions
Example 1: Beginner TDD User
User: "I want to implement user registration with TDD"
tdd-workflow:
Great! TDD (Test-Driven Development) follows red-green-refactor:
🔴 RED: Write failing test
🟢 GREEN: Make it pass
🔵 REFACTOR: Improve code
[Presents AskUserQuestion with 3 options]
User selects: "Guided TDD Workflow"
tdd-workflow:
Perfect! I'm invoking /sw:tdd:cycle to orchestrate your TDD workflow.
🔴 Starting RED phase...
Write a failing test for user registration. Let me create the test skeleton:
[Creates test file with failing test]
✅ Test written and failing. Run: npm test
❌ Expected failure confirmed.
Ready to proceed to GREEN phase? (type 'yes' or run /sw:tdd:green)
Example 2: Experienced TDD User
User: "Refactor auth module with TDD safety nets"
tdd-workflow:
I see you want to refactor with TDD discipline.
[Presents AskUserQuestion]
User selects: "Expert TDD Agent"
tdd-workflow:
Invoking tdd-orchestrator agent for advanced refactoring support...
[tdd-orchestrator agent takes over with:]
- Characterization tests for legacy code
- Golden master testing
- Seam identification
- Incremental refactoring with safety nets
Example 3: Mid-Cycle TDD
User: "I'm in GREEN phase, tests passing, ready to refactor"
tdd-workflow:
Great! Tests are passing. Time for REFACTOR phase.
You can:
1. Run /sw:tdd:refactor (guided refactoring)
2. Refactor manually (I'll verify tests stay green)
Which would you prefer?
User: "I'll refactor manually"
tdd-workflow:
Perfect! I'll monitor your refactoring:
✅ Tests passing before refactor
[User refactors code]
✅ Tests still passing after refactor
✅ TDD cycle maintained
Ready for next feature? Run /sw:tdd:cycle or continue manually.
Configuration
Optional: Customize TDD preferences in .specweave/config.yaml:
tdd:
default_workflow: "cycle" # Options: "cycle", "agent", "manual"
auto_activate: true # Auto-offer TDD on new features
gates_enabled: true # Enforce phase gates in cycle mode
mutation_testing: false # Enable mutation testing (requires setup)
Success Criteria
This skill succeeds when:
- ✅ Users are offered TDD workflow when appropriate
- ✅ TDD choice is explicit (not assumed)
- ✅ Clear routing to appropriate tool (command vs agent)
- ✅ TDD education embedded in workflow
- ✅ Flexible enough for beginners and experts
- ✅ Integrates seamlessly with SpecWeave increments
Related Skills & Agents
Skills:
spec-driven-debugging- Bug fixes can use TDD approachincrement-planner- Increments can specify TDD as methodologye2e-playwright- E2E tests can follow TDD for acceptance tests
Agents:
tdd-orchestrator- Deep TDD expertise (invoked by this skill)qa-lead- Test strategy overlaps with TDD principles
Commands:
/sw:tdd:cycle- Full red-green-refactor orchestration/sw:tdd:red,/sw:tdd:green,/sw:tdd:refactor- Individual phases
Summary
tdd-workflow is a lightweight discovery skill that:
- ✅ Detects TDD intent from user messages
- ✅ Asks user preference for TDD enforcement level
- ✅ Routes to appropriate tool (guided commands vs expert agent)
- ✅ Educates on TDD principles and best practices
- ✅ Integrates with SpecWeave increment workflow
Not a replacement for:
tdd-orchestratoragent (deep expertise)/sw:tdd-*commands (workflow enforcement)
Instead, it's the entry point that helps users choose the right TDD tool for their context.
Keywords: TDD, test-driven development, red-green-refactor, test-first, Kent Beck, TDD cycle, property-based testing, mutation testing, refactoring, test discipline