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-orchestrator agent (deep TDD expertise)
/sw:tdd:cycle command (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 approach
increment-planner - Increments can specify TDD as methodology
e2e-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-orchestrator agent (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