How to Use the TDD Workflow Skill in ECC: A Complete Guide to Test‑Driven Development

The TDD Workflow skill in ECC enforces a disciplined test‑driven development cycle through RED‑GREEN‑refactor gates, mandatory 80% code coverage, and semantic Git checkpoints.

The ECC (Effective Codebase Companion) repository by affaan‑m provides knowledge‑based skills rather than executable libraries. The TDD Workflow skill, defined in skills/tdd-workflow/SKILL.md, guides developers and AI agents through a rigorous TDD lifecycle—from capturing user journeys to verifying coverage—using standard npm scripts and semantic Git commits.

The Seven Phases of the TDD Workflow Skill

The skill organizes development into seven distinct phases that enforce test‑first discipline. Each phase maps to specific sections in skills/tdd-workflow/SKILL.md and must be completed sequentially.

1. Write User Journeys

Capture functional intent using the standard "As a… I want… so that…" format. This phase appears in the User Journeys section of SKILL.md at line 65. Defining the journey establishes a business‑level goal that drives all subsequent test design.

2. Generate Test Cases

Derive concrete test cases (unit, integration, and Playwright E2E) from the user journey. The Generate Test Cases block at line 74 provides skeletons for Jest, Vitest, or Playwright. This step creates the executable specifications that validate the implementation.

3. RED Gate: Force Test Failure

Run the test suite and confirm that new tests fail. According to SKILL.md line 97, the RED gate guarantees that the test truly captures missing functionality rather than passing vacuously. Execute:

npm test

The failure must be intentional and diagnostic.

4. Implement Minimal Code

Write the smallest amount of production code necessary to move the test from red to green. The Implement Code snippet at line 26 emphasizes focused implementations that satisfy the specific assertion, not future‑proof over‑engineering.

5. GREEN Gate: Verify Success

Re‑run the test suite to confirm all tests pass. The GREEN gate at line 38 validates that the feature works as intended. Only after this confirmation should you proceed to cleanup.

6. Refactor While Green

Clean up implementation details—improving readability, removing duplication, or optimizing performance—while keeping the test suite green. The Refactor section at line 54 permits structural improvements only when the safety net of passing tests is active.

7. Verify Coverage Thresholds

Execute the coverage script and enforce a minimum of 80% code coverage. The Verify Coverage directive at line 66 requires running:

npm run test:coverage

If coverage falls below the threshold, add edge‑case tests for error handling, empty inputs, or boundary conditions until the report satisfies the requirement.

Git Checkpoint Strategy

The skill mandates semantic Git checkpoints after each RED, GREEN, and optional refactor step. As documented at line 50 of SKILL.md, these commits create an auditable history that can be rolled back or bisected.

Use conventional commit prefixes:

• test: when adding or modifying test files during the RED phase
• fix: or feat: when implementing code to pass tests during the GREEN phase
• refactor: when cleaning up code without changing behavior

Example workflow:

# RED phase

git add src/lib/searchMarkets.test.ts
git commit -m "test: add unit test for semantic search markets"

# GREEN phase

git add src/lib/searchMarkets.ts
git commit -m "fix: implement searchMarkets to satisfy test"

# Refactor phase

git add src/lib/searchMarkets.ts
git commit -m "refactor: simplify market result generation"

Practical Implementation: Building a Search Feature

The following example demonstrates the complete workflow using a semantic search utility. This pattern applies to any TypeScript or JavaScript project using ECC.

Step 1: Create the Failing Unit Test (RED)

Create src/lib/searchMarkets.test.ts with a specification that intentionally fails because the implementation does not yet exist:

// src/lib/searchMarkets.test.ts
import { searchMarkets } from './searchMarkets';

describe('Semantic Search', () => {
  it('returns relevant markets for a query', async () => {
    const results = await searchMarkets('election');
    expect(results).toHaveLength(3);
    expect(results[0].name).toContain('election');
  });
});

Run the test to satisfy the RED gate:

npm test

Step 2: Implement Minimal Code (GREEN)

Create src/lib/searchMarkets.ts with the smallest viable implementation:

// src/lib/searchMarkets.ts
export async function searchMarkets(query: string) {
  // Minimal stub to satisfy the test
  return [
    { id: '1', name: `${query} results 1` },
    { id: '2', name: `${query} results 2` },
    { id: '3', name: `${query} results 3` },
  ];
}

Re‑run tests to confirm the GREEN gate:

npm test

Commit the changes:

git add src/lib/searchMarkets.ts src/lib/searchMarkets.test.ts
git commit -m "fix: implement searchMarkets to satisfy semantic search test"

Step 3: Refactor and Verify Coverage

Improve the implementation while maintaining behavior:

// src/lib/searchMarkets.ts
export async function searchMarkets(query: string) {
  const base = `${query} results`;
  return Array.from({ length: 3 }, (_, i) => ({
    id: `${i + 1}`,
    name: `${base} ${i + 1}`,
  }));
}

Verify coverage meets the 80% threshold:

npm run test:coverage

If the report shows gaps, add tests for edge cases (empty strings, special characters, error states). Once green and covered, commit:

git add src/lib/searchMarkets.ts
git commit -m "refactor: clean up searchMarkets implementation"

Summary

• The TDD Workflow skill in ECC is defined in skills/tdd-workflow/SKILL.md and provides a knowledge‑based guide rather than executable code.
• The workflow enforces a RED‑GREEN‑refactor loop with explicit gates at lines 97 (RED), 38 (GREEN), and 54 (refactor).
• 80% code coverage is mandatory and verified via npm run test:coverage as specified at line 66.
• Semantic Git checkpoints after each phase provide traceability and rollback capability (line 50).
• The skill is language‑agnostic but expects standard npm scripts (npm test) and works seamlessly with Jest, Vitest, or Playwright.

Frequently Asked Questions

What is the ECC TDD Workflow skill and where is it located?

The ECC TDD Workflow skill is a knowledge artifact stored at skills/tdd-workflow/SKILL.md in the affaan‑m/ECC repository. Unlike traditional libraries, it contains no executable code; instead, it provides step‑by‑step instructions for executing test‑driven development with strict coverage and Git discipline.

How does the RED gate prevent false positives in ECC TDD?

The RED gate, defined at line 97 of SKILL.md, requires developers to run tests immediately after writing them and confirm they fail. This ensures the test is actually exercising the intended functionality rather than passing due to incorrect assertions or stubbed dependencies. A test that never fails cannot verify that implementation changes cause it to pass.

What happens if my code coverage drops below 80% during the workflow?

The skill blocks completion of the TDD cycle until coverage meets the 80% threshold specified at line 66. You must add additional test cases covering edge cases, error paths, or boundary conditions, then re‑run npm run test:coverage. Only when the report shows the required percentage can you proceed to the final Git checkpoint.

Can I use the TDD Workflow skill with testing frameworks other than Jest?

Yes. While the examples in SKILL.md reference Jest, Vitest, and Playwright, the skill is framework‑agnostic. It requires only that your package.json defines standard npm scripts (npm test for execution and npm run test:coverage for coverage reporting). Any testing tool that exposes these CLI commands integrates seamlessly with the ECC TDD Workflow skill.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}