Automatic TDD Skill Enforcement Before Implementation

[xdlkc]

Summary

Add a mechanism to automatically enforce TDD skill invocation before writing any implementation code, preventing agents from skipping test-first development even when TDD is mandated in project configuration.

Problem

Current Behavior

Even when a project's CLAUDE.md explicitly requires TDD:

### Development: TDD (Test-Driven Development)

When implementing features, you **MUST** use the `test-driven-development` skill:
- RED: Write failing tests first
- GREEN: Write minimal code to pass
- REFACTOR: Clean up while keeping tests green

The agent can still:

1. Skip invoking superpowers:test-driven-development
2. Write implementation code first
3. Add tests afterwards (violating TDD principles)

Real-World Example

User request: "Add integration tests for todos, the todo items are not clickable"

Expected flow:

1. Invoke superpowers:test-driven-development
2. Write failing tests for TODO API (PUT /api/todos/:id)
3. Run tests, confirm RED
4. Write minimal implementation
5. Run tests, confirm GREEN

Actual flow:

1. Directly wrote backend API implementation
2. Wrote frontend service code
3. Added tests AFTER implementation ❌

Root Cause Analysis

1. No enforcement mechanism - TDD skill is advisory only
2. "Problem-solving mode" - Agent jumps to implementation when seeing bugs
3. using-superpowers gaps - Even with "1% chance" rule, implementation triggers aren't caught

Proposed Solutions

Option 1: PreToolUse Hook for Edit/Write (Recommended)

Add a hook that fires before Edit or Write tools on non-test files:

// hooks/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-guard.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# hooks/tdd-guard.sh

FILE_PATH="$CLAUDE_TOOL_ARG_FILE_PATH"

# Skip if editing test files
if [[ "$FILE_PATH" == *".test."* ]] || [[ "$FILE_PATH" == *"/test/"* ]] || [[ "$FILE_PATH" == *"/tests/"* ]]; then
  exit 0
fi

# Skip if editing config/docs
if [[ "$FILE_PATH" == *.md ]] || [[ "$FILE_PATH" == *.json ]] || [[ "$FILE_PATH" == *.yaml ]]; then
  exit 0
fi

# Check if TDD skill was invoked in this session
if [[ -z "$SUPERPOWERS_TDD_INVOKED" ]]; then
  echo "⚠️ TDD Guard: You're editing production code without invoking superpowers:test-driven-development first."
  echo "Please invoke the TDD skill and write failing tests before implementation."
  exit 1
fi

Pros:

• Blocks implementation before tests exist
• Works automatically without user intervention
• Leverages existing hooks infrastructure

Cons:

• Requires session state tracking
• May need escape hatch for legitimate non-TDD edits

Option 2: Skill Chain in brainstorming/writing-plans

Modify brainstorming and writing-plans skills to explicitly require TDD:

## After the Design

**Implementation (if continuing):**
- Ask: "Ready to set up for implementation?"
- Use superpowers:using-git-worktrees to create isolated workspace
- Use superpowers:writing-plans to create detailed implementation plan
- **⚠️ MANDATORY: Invoke superpowers:test-driven-development before ANY code**

Pros:

• Non-invasive documentation change
• Follows existing skill chain pattern

Cons:

• Still advisory, not enforced
• Agent can skip if not using brainstorming first

Option 3: Add Implementation Triggers to using-superpowers

Add explicit implementation detection to using-superpowers:

## Implementation Detection

When you're about to:
- Add a new function/method
- Fix a bug
- Modify existing behavior
- Add API endpoints

**STOP. These are implementation triggers.**

Before ANY implementation:
1. Invoke `superpowers:test-driven-development`
2. Write failing test
3. Confirm RED
4. Then proceed

Pros:

• Centralizes enforcement in one skill
• Explicit trigger list

Cons:

• Relies on agent self-enforcement
• No technical barrier

Option 4: New implementation-guard Skill

Create a new skill that must be invoked before implementation:

---
name: implementation-guard
description: MUST invoke before writing ANY implementation code - enforces TDD workflow
---

# Implementation Guard

## Purpose

This skill enforces TDD by blocking implementation until tests exist.

## Checklist (All Required)

Before writing implementation code:

- [ ] Identified the feature/fix to implement
- [ ] Invoked `superpowers:test-driven-development`
- [ ] Wrote failing test(s)
- [ ] Ran tests and confirmed RED
- [ ] Ready to write minimal GREEN code

## Enforcement

If any box is unchecked, DO NOT write implementation code.

Return to the unchecked step and complete it first.

Pros:

• Explicit checkpoint skill
• Clear checklist format

Cons:

• Adds another skill to invoke
• Still relies on voluntary invocation

Recommended Approach

Combine Options 1 + 2:

1. Add PreToolUse hook (Option 1) - Technical enforcement
2. Update brainstorming skill (Option 2) - Process guidance

This provides both:

• Hard guard: Hook blocks implementation without TDD
• Soft guide: Skill chain reminds at design phase

Implementation Details

Required Changes

1. New file: hooks/tdd-guard.sh
2. Modify: hooks/hooks.json - add PreToolUse matcher
3. Modify: skills/brainstorming/SKILL.md - add TDD requirement
4. Modify: skills/writing-plans/SKILL.md - add TDD requirement
5. Optional: Session state tracking for TDD invocation

Session State Tracking Options

# Option A: Environment variable (set by TDD skill)
export SUPERPOWERS_TDD_INVOKED=1

# Option B: Temp file marker
touch /tmp/.superpowers-tdd-session-$(date +%Y%m%d)

# Option C: Check conversation context for TDD skill invocation
# (Would require tool access in hook)

Alternatives Considered

Approach	Why It Doesn't Work
Documentation-only	Already tried, agent still skips TDD
User responsibility	Users may not remember to enforce
Per-project CLAUDE.md	Can specify TDD requirement, but no enforcement mechanism exists

Additional Context

• superpowers version: 4.1.1
• Related skills: test-driven-development, brainstorming, writing-plans, using-superpowers
• Hooks infrastructure: Already exists in hooks/hooks.json

Acceptance Criteria

• Agent cannot write to non-test production files without TDD skill invocation
• Clear error message when TDD guard blocks an edit
• Escape hatch for legitimate non-TDD scenarios (config files, docs, etc.)
• Skill chain updated to remind about TDD before implementation

---

Labels: enhancement, tdd, hooks, enforcement

[obra]

Closing — as of v5.0, superpowers honors CLAUDE.md instructions. You can enforce TDD by adding instructions to your CLAUDE.md like "Always write tests before implementation code."

— Claude Opus 4.6, Claude Code 2.1.72