tdd-workflow
Skill8 starsChanged 43 days agoMITView on GitHub
Test-Driven Development workflow for implementing features with tests first; enforces the two-commit audit trail (failing-test commit, then green commit) and shows-your-work verification for agent-driven work.
129 other projects use a version of this.
Adopted by
Most recently taken up by
- rajdeepbhattacharyya25-pixel/agents-for-antigravity-their own version, first seen Nov 15, 2026
- wolverin0/claude-skillstheir own version, first seen Nov 11, 2026
- Rojios/everything-claude-codetheir own version, first seen Nov 8, 2026
- lhbsaa/apex-unifiedtheir own version, first seen Nov 8, 2026
- ahmadvahidi/skill-atlastheir own version, first seen Nov 8, 2026
- mahsumaktas/agent-evolution-kittheir own version, first seen Nov 8, 2026
Used with
Projects with it also use brand-discovery, configure-ecc and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ysyecustSkillbrand-discovery
Use when a brand needs to discover or articulate its identity through structured multi-session interviews. Covers purpose, positioning, audience, personality, voice, narrative, and founder-brand tension across 8 modules using laddering, 5 Whys, and projective techniques. Produces a resumable session with disk-persisted state and a master brandbook (90_SYNTHESIS.md).
Also in 6 projects that use this
royaluniondesign-sysSkillconfigure-ecc
Interactive installer for Everything Claude Code — guides users through selecting and installing skills and rules to user-level or project-level directories, verifies paths, and optionally optimizes installed files.
Also in 12 projects that use this
junimnjwSkillralphinho-rfc-pipeline
RFC-driven multi-agent DAG execution pattern with quality gates, merge queues, and work unit orchestration.
Also in 12 projects that use this
loulanyueSkillnuxt4-patterns
Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.
Also in 10 projects that use this
royaluniondesign-sysSkillcontent-hash-cache-pattern
Cache expensive file processing results using SHA-256 content hashes — path-independent, auto-invalidating, with service layer separation.
Also in 16 projects that use this
RojiosSkilldart-flutter-patterns
Production-ready Dart and Flutter patterns covering null safety, immutable state, async composition, widget architecture, popular state management frameworks (BLoC, Riverpod, Provider), GoRouter navigation, Dio networking, Freezed code generation, and clean architecture.
Also in 7 projects that use this
Other versions129 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 129
- affaan-m/ECC★ 246ksame name
- vudovn/ag-kit★ 8.2ksame name
- vudovn/antigravity-kit★ 8.2ksame name
- xu-xiang/everything-claude-code-zh★ 1.9ksame name
- loulanyue/awesome-claude-notes★ 272same name
- ab604/claude-code-r-skills★ 202same name
- cloudnative-co/claude-code-starter-kit★ 153same name
- xenitV1/Antigravity-Workflows★ 130same name
- cohen-liel/hivemind★ 108same name
- travisjneuman/.claude★ 106same name
119 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- context/CLAUDE.mdCLAUDE.md
- api-designSkill
- backendSkill
- cavemanSkill
- commitSkill
- evaluator-optimizerSkill
- frontend-design-systemSkill
- interactive-live-testingSkill
- module-planningSkill
- multi-agent-orchestrationSkill
- plan-featureSkill
- prSkill
- ralph-loopSkill
- review-boardSkill
- reviewSkill
- systematic-debuggingSkill
- verification-before-completionSkill
- verificationSkill
- work-recordingSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 118 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Description: Test-Driven Development workflow with two-commit audit trail and test-runner-based verification
- Distinctive: line 23
Every claim of "passing" must be backed by a verbatim test runner output block, never narrative.
- Distinctive: line 162
After every TDD micro-cycle, the skill MUST produce this evidence block:
- Very specific: line 191
If the audit shows a feat(...) commit with no preceding test(...) commit, the implementation agent must:
- Distinctive: line 194
Write the failing test first.
- Distinctive: line 195
Commit the test (verify RED, capture output).
- Distinctive: line 197
Commit again with a fresh SHA.
- Distinctive: line 205
When this skill is invoked in a multi-agent orchestration:
- Very specific: line 299
When this skill is invoked on a task that falls under "skip TDD", respond with a short note ("this task is out of TDD scope per …
“Common” is measured: kept by at least 6 in 10 of the 118 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
TDD Workflow Skill
Skill Metadata
- Name: tdd-workflow
- Description: Test-Driven Development workflow with two-commit audit trail and test-runner-based verification
- User Invocable: Yes (via
/tdd) - Companion rule:
.claude/rules/tdd-discipline.md(the why and the boundaries)
Overview
This skill implements the canonical Red-Green-Refactor cycle (Kent Beck, 2002) with the additions required for AI-agent-driven development. The discipline is stack-agnostic; examples below use TypeScript / Node / Vitest / Zod, but the cycle and audit rules apply equally to any language and test runner.
- Each phase ends with a commit, producing an audit trail.
- The trail is verifiable via
git logand re-running the test at each commit SHA. - Subagents are isolated so the test author and the implementation author do not collude through a shared context window.
- Every claim of "passing" must be backed by a verbatim test runner output block, never narrative.
The cycle target is 1 to 10 minutes per micro-iteration (Beck). If a phase takes longer, the step was too large; split it.
Adapt the runner commands to your project's test toolchain. The examples below use Vitest; substitute Jest, Mocha, pytest, go test, or your framework's equivalent.
TDD Cycle (with audit commits)
RED GREEN REFACTOR
┌─────────────────────────────┐ ┌──────────────────────────┐ ┌─────────────────────────┐
│ 1. Write failing test │ │ 1. Smallest prod change │ │ 1. Restructure │
│ 2. Run tests, see RED │ │ 2. Run tests, see GREEN │ │ 2. Run tests, GREEN │
│ 3. Capture failure output │ │ 3. Capture pass output │ │ 3. Run type-check │
│ 4. Commit TEST FILE ONLY │--│ 4. Commit PROD CODE ─│--│ 4. Commit refactor │
│ test(scope): add spec │ │ feat(scope): implement│ │ refactor(scope): ... │
│ │ │ │ │ │
│ Artifact: SHA + red output │ │ Artifact: SHA + green │ │ Artifact: SHA + green │
└─────────────────────────────┘ └──────────────────────────┘ └─────────────────────────┘Workflow Steps
Step 1, RED: Write the failing test
Objective: produce a test that describes the new behavior and fails for the right reason (an assertion failure, not a missing module).
// apps/<service>/src/application/use-cases/<feature>/handler.spec.ts
import { describe, it, expect, vi } from 'vitest';
import { ApproveSubmissionHandler } from './handler';
describe('ApproveSubmissionHandler', () => {
it('approves a pending submission and emits an outbox command', async () => {
const submissionRepo = {
findById: vi.fn().mockResolvedValue({ id: 'sub-1', status: 'PENDING' }),
updateStatus: vi.fn().mockResolvedValue(undefined),
};
const outboxRepo = { create: vi.fn().mockResolvedValue({ id: 'cmd-1' }) };
// [CUSTOMIZE: replace with your transaction/unit-of-work primitive]
const db = { $transaction: async (fn: any) => fn({}) };
const handler = new ApproveSubmissionHandler(submissionRepo, outboxRepo, db);
const result = await handler.execute({ submissionId: 'sub-1', actorId: 'u-1' });
expect(result.approved).toBe(true);
expect(outboxRepo.create).toHaveBeenCalled();
});
});Verify RED:
# [CUSTOMIZE: replace with your runner invocation]
npx vitest run src/application/use-cases/<feature>
# Expected: AssertionError OR Cannot find module './handler'
# Both qualify as RED for the FIRST test in a new file (compile failures count
# per Uncle Bob's Three Laws). After the file exists, subsequent RED steps
# MUST be assertion failures, not compile errors.Capture the failure output verbatim. This is the artifact you will paste into the output report.
Commit (test file ONLY):
git add apps/<service>/src/application/use-cases/<feature>/handler.spec.ts
git commit -m "test(<scope>): add failing spec for <Feature> happy path"Step 2, GREEN: Minimal production code
Objective: simplest possible change that turns the bar green. Hardcoding, copy-paste, literal returns; all permitted. The next failing test forces generalization.
// apps/<service>/src/application/use-cases/<feature>/handler.ts
export class ApproveSubmissionHandler {
constructor(
private readonly submissionRepo: ISubmissionRepository,
private readonly outboxRepo: IOutboxRepository,
// [CUSTOMIZE: replace with your ORM/transaction primitive]
private readonly db: { $transaction: Function },
) {}
async execute(input: { submissionId: string; actorId: string }) {
return this.db.$transaction(async (tx: unknown) => {
const sub = await this.submissionRepo.findById(input.submissionId);
if (!sub) throw new SubmissionNotFoundError(input.submissionId);
await this.submissionRepo.updateStatus(sub.id, 'APPROVED', tx);
await this.outboxRepo.create(
{ commandType: 'ApproveSubmission', payload: { id: sub.id } },
tx,
);
return { approved: true };
});
}
}Verify GREEN:
npx vitest run src/application/use-cases/<feature>
# Expected: 1 passed
npx tsc --noEmit
# Expected: no errorsCapture the passing output verbatim. Required artifact for the output report.
Commit (production code):
git add apps/<service>/src/application/use-cases/<feature>/handler.ts
git commit -m "feat(<scope>): implement <Feature> to satisfy spec"Step 3, REFACTOR: Improve under green
Objective: clean up structure without changing behavior. Skip if no refactor is needed.
# After refactoring, re-verify all stays green
npx vitest run src/application/use-cases/<feature>
npx tsc --noEmit
npx eslint src/application/use-cases/<feature>Commit (refactor, if any):
git add apps/<service>/src/application/use-cases/<feature>/
git commit -m "refactor(<scope>): extract <thing> into private helper"The "show your work" rule (THE critical addition for agent use)
After every TDD micro-cycle, the skill MUST produce this evidence block:
RED commit: <sha> test(<scope>): add failing spec for <Feature>
test output: 1 failed (AssertionError)
GREEN commit: <sha> feat(<scope>): implement <Feature> to satisfy spec
test output: 1 passed
REFACTOR commit (optional): <sha> refactor(<scope>): ...
test output: 1 passedVerification command that an agent or reviewer can run independently:
# Show the last few commits touching the use case
git log --oneline -5 -- apps/<service>/src/application/use-cases/<feature>/
# Expected: feat commit must come AFTER a test commit for the same scope.
# If the feat commit appears with no preceding test commit, TDD was not followed.Show failing test output verbatim
The RED commit's artifact is the verbatim test runner stdout/stderr containing the assertion failure. Narrative like "the test failed as expected" is REJECTED. The orchestrator (or reviewer agent) re-runs the test command at the RED commit SHA and confirms a non-zero exit with the expected assertion message. Without this verbatim block, the dispatch is treated as failed and re-dispatched.
This matches the .claude/rules/ai-agent-engineering.md "Show Your Work" requirement: every claim ships with a verifiable artifact, never with narrative alone.
Rollback rule
If the audit shows a feat(...) commit with no preceding test(...) commit, the implementation agent must:
- Revert the implementation commit (
git revert <sha>). - Write the failing test first.
- Commit the test (verify RED, capture output).
- Re-apply the implementation (verify GREEN, capture output).
- Commit again with a fresh SHA.
This is non-negotiable for production-touching code.
Subagent isolation protocol (prevents test-implementation collusion)
When this skill is invoked in a multi-agent orchestration:
┌──────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR receives "implement feature X via TDD" │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Phase 1: DISPATCH `tester` AGENT │
│ │
│ Input: acceptance criteria, port contract, file layout │
│ Forbidden: implementation strategy, "how" the code works │
│ Output: failing test file + commit SHA + test runner red output │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Phase 2: DISPATCH `impl` AGENT │
│ │
│ Input: failing test commit SHA + the test file + port contract │
│ Goal: make the test pass with minimal change, commit, stop │
│ Output: implementation commit SHA + test runner green output │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Phase 3: DISPATCH `reviewer` AGENT │
│ │
│ Input: both commit SHAs + the diff │
│ Verify: test commit precedes impl commit; test asserts behavior; │
│ impl is minimal; both runs produced expected output │
│ Output: APPROVED / REJECTED with evidence │
└──────────────────────────────────────────────────────────────────────┘This three-agent handoff is the orchestrated equivalent of the human pair "driver writes test, navigator writes code." Both Kent Beck's original cycle and Anthropic's "evaluator-optimizer" pattern in Building Effective AI Agents recommend this separation.
Reference: .claude/skills/multi-agent-orchestration/SKILL.md.
Test patterns by component
Use case handler tests (most common pattern in layered backend)
describe('<UseCase>Handler', () => {
// Happy path
it('does <expected behavior> when <condition>', async () => {});
// Edge cases
it('handles <edge case>', async () => {});
// Error cases (typed DomainError subclasses)
it('throws <SpecificError> when <invariant violated>', async () => {});
// Idempotency (mandatory for outbox-producing use cases)
it('is idempotent when called twice with the same idempotencyKey', async () => {});
});Integration tests (real database, mocked external HTTP)
Wire the real use case with in-memory or test-database repositories, real domain primitives, and mocked external services. The shape: stand up the infrastructure once per suite, reset state between tests, assert on side-effects (rows written, events emitted) not just return values.
Controller / route handler tests
describe('<Resource>Controller', () => {
it('POST /resource returns 201 with valid input', () => {});
it('POST /resource returns 400 with invalid input (schema rejects)', () => {});
it('POST /resource returns 401 without token', () => {});
it('POST /resource returns 403 when role insufficient', () => {});
});Frontend component tests (Vitest + Testing Library)
describe('<Component>', () => {
it('renders the empty state', () => {});
it('calls onSubmit with form values', async () => {});
it('shows loading state while submitting', () => {});
it('shows error message on submission failure', () => {});
});When to skip TDD
See companion rule .claude/rules/tdd-discipline.md "When NOT to TDD" section. Summary: spike code with planned discard, configuration files, prose docs, throwaway scripts, generated code, trivial dependency-injection wiring, style-only frontend changes.
When this skill is invoked on a task that falls under "skip TDD", respond with a short note ("this task is out of TDD scope per tdd-discipline.md, proceeding without R-G-R cycle") and then proceed with the appropriate workflow.
Invocation
Manual
/tdd <feature-name>Example
/tdd approve-submissionOutput report format
## TDD Session: <feature-name>
### Audit trail
| Phase | Commit SHA | Message | Test result |
|---|---|---|---|
| RED | 8b1d... | test(<scope>): add failing spec for <Feature> | 1 failed (AssertionError) |
| GREEN | 7f2a... | feat(<scope>): implement <Feature> to satisfy spec | 1 passed |
| REFACTOR | a3c5... | refactor(<scope>): extract helper | 1 passed |
### Test output verbatim (RED)
```
FAIL src/application/use-cases/<feature>/handler.spec.ts > Handler > approves and emits command
AssertionError: expected undefined to be true
...
Test Files 1 failed (1)
Tests 1 failed (1)
```
### Test output verbatim (GREEN)
```
PASS src/application/use-cases/<feature>/handler.spec.ts (1 test)
Test Files 1 passed (1)
Tests 1 passed (1)
```
### Implementation files
- apps/<service>/src/application/use-cases/<feature>/handler.ts
- apps/<service>/src/application/use-cases/<feature>/handler.spec.ts
### Verification (re-runnable)
```bash
git log --oneline -3 -- apps/<service>/src/application/use-cases/<feature>/
npx vitest run src/application/use-cases/<feature>
```
### Coverage (vitest --coverage)
- Statements: 96%
- Branches: 92%
- Functions: 100%Failure modes detection
"Agent wrote tests after the fact"
Symptom: git log shows a single commit containing both test and production code. Or shows feat(...) first, then a later test(...) commit for the same scope.
Action: REJECT. Revert. Restart from RED.
"Test never actually failed"
Symptom: the test commit's runner output shows 0 failures.
Action: REJECT. The test is not driving anything. Either it has the wrong assertion or the production code already satisfied it. Tighten the assertion.
"Test failed for the wrong reason"
Symptom: the test commit's runner output shows Cannot find module or SyntaxError rather than AssertionError.
Action: ACCEPTABLE only for the very first test in a new file (per Uncle Bob's "compilation failures count as failures"). For subsequent tests, the failure must be an assertion failure.
"Narrative pass, no output block"
Symptom: agent reports "tests pass" without pasting verbatim runner output.
Action: REJECT. Re-dispatch with explicit "produce test output block" instructions. The orchestrator independently re-runs the command and confirms exit 0.
"Implementation is too large"
Symptom: the GREEN commit changes 200+ lines for a single test.
Action: REJECT. The test was too coarse-grained. Split into smaller tests, each driving a small slice of implementation.
Commands
# [CUSTOMIZE: adapt these to your test toolchain]
# Vitest (TypeScript / Node)
npx vitest run # all packages
npx vitest run --project <service> # one service
npx vitest run path/to/file.spec.ts # one file
npx vitest # watch mode (TDD inner loop)
npx vitest run --coverage # with coverage report
# Type and lint after green
npx tsc --noEmit
npx eslint <path>
# Frontend (Vitest + Testing Library)
cd <frontend-app> && npm test # unit/component tests
cd <frontend-app> && npx playwright test # end-to-end
# Jest alternative
npx jest --testPathPattern=<path>
npx jest --coverage
# pytest (Python)
pytest path/to/test_feature.py -v
pytest --cov=src
# go test
go test ./path/to/package/... -v
go test ./... -coverRelated
.claude/rules/tdd-discipline.md, companion rule (the why and the boundaries)..claude/rules/testing-pyramid.md, what to test at each layer..claude/rules/production-grade-code.md, typed errors used in failure-case tests..claude/rules/ai-agent-engineering.md, the "show your work" protocol that this skill operationalizes..claude/skills/multi-agent-orchestration/SKILL.md, agent dispatch protocol..claude/agents/tester/AGENT.md, agent that writes the RED commit..claude/agents/reviewer/AGENT.md, agent that audits the trail.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

