Execute Tdd Tasks

Execute TDD Tasks Skill

This skill orchestrates autonomous execution of TDD task pairs generated by /create-tdd-tasks. It is the TDD counterpart to the standard execute-tasks skill, reusing its session management, wave infrastructure, and execution context sharing while adding TDD-specific agent routing, RED-GREEN-REFACTOR verification, and per-task compliance reporting.

The key difference from standard execute-tasks: this skill routes TDD tasks to the tdd-executor agent (from tdd-tools) which runs a 6-phase TDD workflow, while routing non-TDD tasks to the standard task-executor agent. It verifies TDD compliance (RED verified, GREEN verified, refactored) per task pair and reports aggregate results.

CRITICAL: Complete ALL 9 steps. The workflow is not complete until Step 9: Update CLAUDE.md is evaluated. After completing each step, immediately proceed to the next step without waiting for user prompts (except Step 4 which requires user confirmation).

Plugin Context

This skill is part of the tdd-tools plugin and uses agents from the same plugin:

• tdd-executor agent (Opus) -- 6-phase TDD workflow per task
• test-writer agent (Sonnet) -- parallel test generation (used by tdd-executor internally)

For non-TDD tasks, this skill routes to the task-executor agent from sdd-tools (soft cross-plugin dependency). Since TDD tasks are always generated from SDD tasks via /create-tasks, the sdd-tools plugin is expected to be installed when this skill runs.

Core Principles

1. TDD Compliance First

Every TDD task pair must complete the RED-GREEN-REFACTOR cycle:

• RED: Tests are written and verified to fail before any implementation exists
• GREEN: Implementation is written that makes all tests pass with zero regressions
• REFACTOR: Code is cleaned up while keeping all tests green

2. Strategic Parallelism

Maximize execution throughput without violating TDD sequencing:

• PARALLEL: Multiple test-writing tasks (RED phase) run simultaneously across features
• SEQUENTIAL: Within a single TDD pair, RED must complete before GREEN can start (enforced by dependencies)

3. Reuse execute-tasks Infrastructure

Session management, wave execution, context sharing, and progress tracking all reuse the same patterns from execute-tasks. See references/tdd-execution-workflow.md for TDD-specific extensions.

4. Honest TDD Reporting

Report per-task compliance with the full RED-GREEN-REFACTOR cycle:

• red_verified: Whether tests failed as expected before implementation
• green_verified: Whether all tests pass after implementation
• refactored: Whether code was cleaned up while maintaining green tests
• coverage_delta: Change in test coverage percentage (if measurable)

Orchestration Workflow

This skill orchestrates TDD task execution through a 9-step loop that mirrors the standard execute-tasks orchestration with TDD-specific extensions. See references/tdd-execution-workflow.md for the full TDD wave execution details and references/tdd-verification-patterns.md for TDD phase verification rules.

Step 1: Load References

Read the TDD-specific reference files:

Read: ${CLAUDE_PLUGIN_ROOT}/skills/execute-tdd-tasks/references/tdd-execution-workflow.md
Read: ${CLAUDE_PLUGIN_ROOT}/skills/execute-tdd-tasks/references/tdd-verification-patterns.md

Parse arguments from the invocation:

• --task-group -- Filter tasks to a specific group
• --max-parallel -- Override max concurrent agents per wave
• --retries -- Override retry attempts per task (default: 3)

Step 2: Load and Classify Tasks

Use TaskList to retrieve all tasks. If --task-group was provided, filter to tasks where metadata.task_group matches.

Classify each task by type:

| Detection | Type | Agent | Source | |-----------|------|-------|--------| | metadata.tdd_mode == true AND metadata.tdd_phase == "red" | TDD test task | tdd-executor | tdd-tools (same plugin) | | metadata.tdd_mode == true AND metadata.tdd_phase == "green" | TDD implementation task | tdd-executor | tdd-tools (same plugin) | | No tdd_mode metadata or tdd_mode == false | Non-TDD task | task-executor | sdd-tools (cross-plugin, soft dependency) |

Count and report:

• Total tasks (pending + in_progress + completed)
• TDD pairs identified (test + implementation tasks)
• Non-TDD tasks
• Already completed tasks

Handle edge cases:

• No tasks found: Report "No tasks found for group '{group}'. Use /create-tdd-tasks to generate TDD task pairs from your SDD tasks." and stop.
• All completed: Report a summary of completed tasks including TDD compliance and stop.
• No unblocked tasks: Report which tasks exist and what's blocking them.

Step 3: Build Execution Plan

Resolve max_parallel using precedence:

1. --max-parallel CLI argument (highest priority)
2. max_parallel in .claude/agent-alchemy.local.md
3. Default: 5

Resolve retries using precedence:

1. --retries CLI argument (highest priority)
2. Default: 3

Read .claude/agent-alchemy.local.md if it exists, for TDD-specific settings:

• tdd.strictness -- strict, normal (default), or relaxed
• tdd.coverage-threshold -- Minimum coverage target (default: 80)

Build the dependency graph from all pending tasks (TDD and non-TDD):

1. Collect all pending tasks and their blockedBy relationships
2. Run topological sort to assign dependency levels
3. Assign tasks to waves by dependency level (Wave 1 = no dependencies, Wave 2 = depends only on Wave 1, etc.)
4. Sort within waves by priority: critical > high > medium > low > unprioritized
5. Break ties by "unblocks most others"
6. Cap each wave at max_parallel tasks

Annotate waves with TDD phase labels:

The dependency structure from create-tdd-tasks naturally produces alternating test/implementation waves:

Wave 1: [Test-A, Test-B, Test-C]         -- RED phase (parallel test generation)
Wave 2: [Impl-A, Impl-B, Impl-C]         -- GREEN phase (parallel implementation)
Wave 3: [Test-D, Test-E, Non-TDD-F]      -- RED phase + non-TDD tasks (mixed)
Wave 4: [Impl-D, Impl-E]                  -- GREEN phase

Detect circular dependencies: If tasks remain unassigned after topological sorting, they form a cycle. Report the cycle and attempt to break at the weakest link.

Validate TDD pair cross-references: For each TDD task, verify its paired_task_id references a valid task. Log warnings for orphaned pairs.

Step 4: Present Execution Plan and Confirm

Display the TDD execution plan:

EXECUTION PLAN (TDD Mode)

Tasks to execute: {count} ({tdd_pairs} TDD pairs, {non_tdd} non-TDD tasks)
Retry limit: {retries} per task
Max parallel: {max_parallel} per wave
TDD Strictness: {strict|normal|relaxed}

WAVE 1 ({n} tasks -- RED phase):
  1. [{id}] Write tests for {subject} (RED, paired: #{impl_id})
  2. [{id}] Write tests for {subject} (RED, paired: #{impl_id})

WAVE 2 ({n} tasks -- GREEN phase):
  3. [{id}] {subject} (GREEN, paired: #{test_id})
  4. [{id}] {subject} (GREEN, paired: #{test_id})

WAVE 3 ({n} tasks -- mixed):
  5. [{id}] {subject} (non-TDD)
  6. [{id}] Write tests for {subject} (RED, paired: #{impl_id})

{Additional waves...}

BLOCKED (unresolvable dependencies):
  [{id}] {subject} -- blocked by: {blocker ids}

COMPLETED:
  {count} tasks already completed

Use AskUserQuestion to confirm:

questions:
  - header: "Confirm TDD Execution"
    question: "Ready to execute {count} tasks in {wave_count} waves (max {max_parallel} parallel) with TDD enforcement ({strictness} mode)?"
    options:
      - label: "Yes, start TDD execution"
        description: "Proceed with the TDD execution plan above"
      - label: "Cancel"
        description: "Abort without executing any tasks"
    multiSelect: false

If the user selects "Cancel", report "Execution cancelled. No tasks were modified." and stop.

Step 5: Initialize Execution Directory

Generate a task_execution_id using three-tier resolution:

1. IF --task-group was provided: {task_group}-tdd-{YYYYMMDD}-{HHMMSS}
2. ELSE IF all open tasks share the same metadata.task_group: {task_group}-tdd-{YYYYMMDD}-{HHMMSS}
3. ELSE: tdd-session-{YYYYMMDD}-{HHMMSS}

Clean stale live session: Follow the same procedure as execute-tasks:

1. Check if .claude/sessions/__live_session__/ contains leftover files
2. If found, archive to .claude/sessions/interrupted-{YYYYMMDD}-{HHMMSS}/
3. Reset any in_progress tasks from the interrupted session to pending

Concurrency guard: Check for .claude/sessions/__live_session__/.lock. Follow the same lock protocol as execute-tasks.

Create session files in .claude/sessions/__live_session__/:

1. execution_plan.md -- Save the TDD execution plan from Step 5
2. execution_context.md -- Initialize with TDD-extended template:

```markdown # Execution Context

## Project Patterns

## Key Decisions

## Known Issues

## File Map

## TDD Compliance | Task Pair | Test Task | Impl Task | RED | GREEN | Refactored | Coverage Delta | |-----------|-----------|-----------|-----|-------|------------|----------------|

## Task History

```

1. task_log.md -- Initialize with standard table headers:

```markdown # Task Execution Log

| Task ID | Subject | Type | Status | Attempts | Duration | Token Usage | |---------|---------|------|--------|----------|----------|-------------| ```

1. tasks/ -- Empty subdirectory for archiving completed task files
2. progress.md -- Initialize with status template:

```markdown # Execution Progress (TDD Mode) Status: Initializing Wave: 0 of {totalwaves} Max Parallel: {maxparallel} TDD Strictness: {strictness} Updated: {ISO 8601 timestamp}

## Active Tasks

## Completed This Session ```

1. execution_pointer.md at $HOME/.claude/tasks/{CLAUDE_CODE_TASK_LIST_ID}/execution_pointer.md -- Absolute path to .claude/sessions/__live_session__/

Step 6: Initialize Execution Context

Read .claude/sessions/__live_session__/execution_context.md (created in Step 6).

If a prior execution session's context exists, look in .claude/sessions/ for the most recent timestamped subfolder and merge relevant learnings (Project Patterns, Key Decisions, Known Issues, File Map) into the new execution context.

Context compaction: If Task History has 10+ entries from merged sessions, compact older entries into a summary paragraph and keep the 5 most recent in full.

Step 7: Execute Loop

Execute tasks in waves with TDD-aware agent routing. No user interaction between waves.

8a: Initialize Wave

1. Identify all unblocked tasks (pending status, all dependencies completed)
2. Sort by priority (critical > high > medium > low > unprioritized)
3. Take up to max_parallel tasks for this wave
4. If no unblocked tasks remain, exit the loop

8b: Snapshot Execution Context

Read .claude/sessions/__live_session__/execution_context.md and hold as baseline for this wave. All agents read from the same snapshot.

8c: Launch Wave Agents

1. Mark all wave tasks as in_progress via TaskUpdate
2. Record wave_start_time
3. Update progress.md with active tasks
4. Launch all wave agents simultaneously using parallel Task tool calls in a single message turn with run_in_background: true.

Record the background task_id mapping: After the Task tool returns for each agent, record the mapping {task_list_id → background_task_id} from each response. The background_task_id is needed later to call TaskOutput for process reaping and usage extraction.

Route each task to the correct agent:

For TDD tasks (metadata.tdd_mode == true), launch the tdd-executor agent (same plugin):

Task:
  subagent_type: tdd-executor
  mode: bypassPermissions
  run_in_background: true
  prompt: |
    Execute the following TDD task.

    Task ID: {id}
    Task Subject: {subject}
    Task Description:
    ---
    {full description}
    ---

    Task Metadata:
    - Priority: {priority}
    - Complexity: {complexity}
    - TDD Phase: {tdd_phase}
    - Paired Task ID: {paired_task_id}
    - TDD Strictness: {strictness}

    CONCURRENT EXECUTION MODE
    Context Write Path: .claude/sessions/__live_session__/context-task-{id}.md
    Result Write Path: .claude/sessions/__live_session__/result-task-{id}.md
    Do NOT write to execution_context.md directly.
    Do NOT update progress.md -- the orchestrator manages it.
    Write your learnings to the Context Write Path above instead.

    RESULT FILE PROTOCOL
    As your VERY LAST action (after writing context-task-{id}.md), write a compact
    result file to the Result Write Path above. TDD format includes a TDD Compliance
    section with RED Verified, GREEN Verified, Refactored, and Coverage Delta fields.
    After writing the result file, return ONLY: DONE: [{id}] {subject} - {PASS|PARTIAL|FAIL}

    {If GREEN phase, include paired test task result data:}
    PAIRED TEST TASK OUTPUT:
    ---
    {test task result file content and context}
    ---
    The tests written by the paired test task are already on disk.
    Your job is to implement code that makes these tests pass (GREEN phase),
    then refactor while keeping tests green (REFACTOR phase).

    {If retry attempt:}
    RETRY ATTEMPT {n} of {max_retries}
    Previous TDD phase that failed: {RED|GREEN|REFACTOR}
    Previous attempt failed with:
    ---
    {previous failure details from result file}
    ---

    TDD-specific retry guidance:
    - If RED failed (tests cannot run): Check test syntax, imports, and framework config
    - If RED warned (tests passed unexpectedly): Verify tests target new behavior, not existing code
    - If GREEN failed (tests still failing): Re-read test assertions, try different implementation approach
    - If GREEN failed (regressions): Identify regression cause, fix without breaking new tests
    - If REFACTOR failed: Revert to pre-refactor state, try smaller refactoring steps

    Instructions (follow in order):
    1. Read the TDD execution and verification references
    2. Read .claude/sessions/__live_session__/execution_context.md for prior learnings
    3. Understand the task requirements and explore the codebase
    4. Execute the 6-phase TDD workflow (Understand, Write Tests, RED, Implement, GREEN, Complete)
    5. Verify TDD compliance (RED verified, GREEN verified, refactored)
    6. Update task status if PASS (mark completed)
    7. Write learnings to .claude/sessions/__live_session__/context-task-{id}.md
    8. Write result to .claude/sessions/__live_session__/result-task-{id}.md
    9. Return: DONE: [{id}] {subject} - {PASS|PARTIAL|FAIL}

For non-TDD tasks (no tdd_mode metadata), launch the standard task-executor agent from sdd-tools (cross-plugin, resolved globally):

Task:
  subagent_type: task-executor
  mode: bypassPermissions
  run_in_background: true
  prompt: |
    Execute the following task.

    Task ID: {id}
    Task Subject: {subject}
    Task Description:
    ---
    {full description}
    ---

    Task Metadata:
    - Priority: {priority}
    - Complexity: {complexity}
    - Source Section: {source_section}

    CONCURRENT EXECUTION MODE
    Context Write Path: .claude/sessions/__live_session__/context-task-{id}.md
    Result Write Path: .claude/sessions/__live_session__/result-task-{id}.md
    Do NOT write to execution_context.md directly.
    Do NOT update progress.md -- the orchestrator manages it.
    Write your learnings to the Context Write Path above instead.

    RESULT FILE PROTOCOL
    As your VERY LAST action (after writing context-task-{id}.md), write a compact
    result file to the Result Write Path above. Standard format with status, verification
    summary, files modified, and issues sections.
    After writing the result file, return ONLY: DONE: [{id}] {sub

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sequenzia](https://github.com/sequenzia)
- **Source:** [sequenzia/agent-alchemy](https://github.com/sequenzia/agent-alchemy)
- **License:** MIT
- **Homepage:** https://sequenzia.github.io/agent-alchemy

Install and usage instructions live in the source repository linked above.