tdd-first
Enforce a RED→GREEN→REFACTOR cycle for a feature. Writes failing tests BEFORE implementation, runs the test suite to confirm the red state, then invokes the implementer agent with the failing tests as
SKILL.mdskills/tdd-first/SKILL.md
GitHub/tdd-first — Test-First Implementation Protocol
When invoked, enforce the RED→GREEN→REFACTOR cycle. No implementation code is written until a test is red. This skill complements (does not replace) /design-first — run the concept-contract phase first, then this skill for the code phase.
Step 0: Preconditions
- Concept contract must exist for non-trivial features. If the
concept-gate.pyhook is active and no contract path is supplied, halt and tell the user to run/design-firstfirst. - Scope must be testable — if the change is purely visual (CSS tweak, template restructure) skip this skill and use
ui-ux-designerdirectly. - This skill is strongly recommended (but not mandatory) for:
- Any change under a root named by the
safety-critical.rootsslot of.claude/project-profile.md— read the slot, do not guess a path from a project name - Any change under a root named by the
auth.rootsslot - Any new EF Core migration or repository query
- Any change to the domain's rule-evaluation pipeline — its evaluators, its field resolvers, or the component that sequences them
- Any change under a root named by the
Step 1: Identify the test surface
Ask the user (or infer from the contract):
- What behavior is changing? Name it as a single sentence.
- What would a correct implementation produce that a broken one does not? This is the test assertion.
- What test project houses this? Match the layer against the
test.rootsslot of.claude/project-profile.md— one backend suite per layer — or, for a frontend change,src/app/**/*.spec.tsunder the owningfrontend.rootsentry.
Write the answers to a scratch file at .claude/tdd-scratch-<timestamp>.md so the subsequent agents can read it without losing context.
Step 2: RED — write the failing test
Launch senior-test-engineer with this contract:
TASK: Write failing test(s) for <behavior>. DO NOT write implementation code.
The implementation is intentionally absent or incorrect.
CONTEXT: <link to concept contract>
FILES_TO_ADD: <specific test file paths>
CONSTRAINTS:
- Follow project test conventions (xUnit + Moq for .NET, Jasmine + signals testing for Angular)
- Test must FAIL with a clear assertion message, not a null-ref or compile error
- Cover: happy path + at least one edge case + one error path
- If the behavior depends on the clock, on randomness, or on an external service client, mock those dependencies properly
PRIOR_FINDINGS:
contract_path: <path>
contract_status: approved
phase: RED # this field signals test-engineer NOT to suggest fixing the code
Step 3: Run the test suite and confirm RED
Run the tests and verify they FAIL:
- .NET:
dotnet test <project-path> --filter "FullyQualifiedName~<test-class>" - Angular:
ng test <project-name> --include="<spec-path>" --watch=false --browsers=ChromeHeadless
Halt conditions:
- Tests pass → you wrote the wrong test. Return to Step 2.
- Tests error-out (compile/DI failure) instead of failing-with-assertion → return to Step 2 and fix the test setup. A green-via-compile-error is not a valid RED state.
- Tests fail but the message is unclear ("Expected True but got False") → return to Step 2 and make the assertion message diagnostic.
Record the RED confirmation in the scratch file with the actual failing output.
Step 4: GREEN — implement the minimum code
Launch the appropriate implementer agent (dotnet-backend-architect, angular-senior-dev, ingestion-data-architect) with:
TASK: Make the failing tests in <test-file-paths> pass. Write the MINIMUM code required.
CONTEXT: Tests were authored in the RED phase of a TDD cycle. Implementation must satisfy the test's assertion without over-engineering.
CONSTRAINTS:
- Do NOT modify the tests (those are the contract)
- Do NOT add features not covered by a failing test
- If you find a test is wrong, HALT and report — do not "fix" the test silently
PRIOR_FINDINGS:
contract_path: <path>
contract_status: approved
phase: GREEN
failing_tests: <paths>
red_output: <captured output from Step 3>
Step 5: Run the test suite and confirm GREEN
Re-run the same test command. All previously-red tests must now pass. Other tests must still pass.
Halt conditions:
- Target tests still red → implementer failed. Return to Step 4 with the new red output.
- Target tests green BUT other tests red → implementer introduced a regression. Return to Step 4 with the regression output.
- Target tests green BUT build broken → return to Step 4.
Record the GREEN confirmation in the scratch file.
Step 6: REFACTOR (optional but recommended)
Launch fullstack-code-reviewer via the Agent tool — never review the GREEN implementation inline in the main session. The implementer's reasoning from Step 4 is still primed in the main context; only a fresh agent instance can judge the code without that bias.
TASK: Review the GREEN implementation for quality issues — duplication, naming, error handling,
project-convention violations — that can be refactored WITHOUT breaking any test.
FILES: <implementation files>
CONSTRAINTS:
- No behavior change. The test suite must stay green.
- Suggest refactors inline; do not auto-apply.
PRIOR_FINDINGS:
phase: REFACTOR
tests_green: true
If the reviewer suggests refactors, apply them one at a time and re-run the tests after each. Abort if any test goes red.
Second-pass review = spawn fresh, never SendMessage
If a second review pass is needed after refactors land, spawn a new fullstack-code-reviewer instance — do NOT SendMessage to the Step 6 reviewer. Its prior findings prime the second pass with the implementer's context and defeat the isolation that makes the review valuable.
Safety-critical paths: also spawn the domain reviewer
For changes under any root named by the safety-critical.roots, auth.roots or migration.root slots of .claude/project-profile.md, spawn the matching domain reviewer (the project's live-action safety reviewer, security-auditor, migration-safety-reviewer) as an additional Agent-tool invocation — not a replacement for fullstack-code-reviewer. Each reviewer is an independent isolated instance. Step 7's /verify-before-done Step 5.5 will refuse to PASS without these HANDOFFs in scope.
Step 7: Final verification + cleanup
- Run
/verify-before-done(if available) or manually:- Build passes for all affected projects
- Full test suite passes (not just the target tests)
- No uncommitted auto-generated files (check
**/generated/underfrontend.root-container, andmigration.root)
- Delete the
.claude/tdd-scratch-<timestamp>.mdfile or move it to.claude/tdd-history/if you want to keep the audit trail. - Report the HANDOFF for the calling context, including:
- Final test count (red → green delta)
- Refactors applied
- Files changed
Anti-patterns (halt and restart if you catch yourself doing these)
- Writing tests AFTER implementation and calling it TDD — that's test-last, not test-first. Doesn't count.
- Making tests pass by weakening the assertion — if
Assert.Equal(5, x)becomesAssert.True(x > 0)to get green, you've bypassed the cycle. - Skipping Step 3 (RED confirmation) — an unverified RED may already be GREEN by accident, making the implementer's work a no-op.
- Implementing beyond the test — "while I'm here I'll also add…" → new tests first, separate cycle.
- Silently editing the test in the GREEN phase — if the test is wrong, halt and escalate.
- Reviewing the GREEN implementation inline in the main session — the implementer's reasoning is primed in the main context. Inline review is biased review. Spawn
fullstack-code-reviewervia theAgenttool. SendMessage-ing the prior reviewer for a second pass — the prior instance carries its own findings + the implementer's context. Spawn a new instance.
Integration with the project's existing flow
This skill slots into the project's dev flow as follows:
/design-first → concept contract approved
→ /tdd-first (THIS SKILL)
→ senior-test-engineer (RED)
→ run tests → confirm red
→ dotnet-backend-architect OR angular-senior-dev (GREEN)
→ run tests → confirm green
→ fullstack-code-reviewer (REFACTOR, optional)
→ /verify-before-done
→ (domain-specific reviewers: security-auditor, trading-safety-reviewer, etc.)
→ commit
When to NOT use this skill
- Pure visual / CSS / template polish — use
ui-ux-designerdirectly. - Single-line typo / config bump — trivial change, skip the protocol.
- Exploratory spike / proof-of-concept — TDD hurts when you don't know what you're building yet; use
design-firstbrainstorming first, then TDD the concrete feature. - External data-source integration where you can't mock the provider — fall back to integration tests with recorded fixtures; still test-first, just not unit-level.