Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/skill-tdd
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Build features with tests-before-code rigor — use for new features needing test coverage
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> SKILL.md
skill-tdd.SKILL.md
---name: skill-tdd
paths:
- "**/*.test.*"
- "**/*.spec.*"
- "**/tests/**"
- "**/__tests__/**"
aliases:
- tdd
- test-driven-development
description: "Build features with tests-before-code rigor — use for new features needing test coverage"
trigger: |
Use when implementing any feature, bugfix, or behavior change.
Auto-invoke when user says "implement X", "add feature Y", "fix bug Z".
DO NOT use for: throwaway prototypes, config files, documentation.
---# Test-Driven Development (TDD)
## MANDATORY COMPLIANCE — DO NOT SKIP
**When this skill is invoked, you MUST run the TDD pipeline through `orchestrate.sh` (red → green → refactor) with real provider dispatch. You are PROHIBITED from:**
- Writing implementation before a failing test exists
- Simulating provider output instead of dispatching via `orchestrate.sh`
- Declaring the task "too small for TDD" and skipping the cycle without asking the user
- Marking work complete while any test is red or skipped
- Rationalizing that a direct edit is faster — the user invoked TDD for test-first discipline
## The Iron Law
<HARD-GATE>
## Phase 1.5: Adversarial Test Design Review (RECOMMENDED)
**After writing the initial test(s) but BEFORE verifying they fail, challenge the test design with a second provider.** A single-model test suite often has systematic blind spots — the same model that writes the tests will write implementation that trivially satisfies them. An adversarial review catches scenarios that would pass with a stub that doesn't actually work.
**If an external provider is available, dispatch the test specs for challenge:**
| "Deleting X hours is wasteful" | Sunk cost fallacy. Unverified code is debt. |
| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
| "TDD will slow me down" | TDD is faster than debugging. |
## Strategy Rotation
If the same test continues to fail after 2 fix attempts, examine the test itself — it may be incorrect. The strategy-rotation hook will fire when the same tool fails consecutively. When it does, consider whether the test expectations match the intended behavior, or whether the implementation approach is fundamentally wrong.
---
## Red Flags - STOP and Start Over
If you catch yourself:
- Writing code before test
- Test passes immediately (didn't watch it fail)
- Rationalizing "just this once"
- "I already manually tested it"
- "Keep as reference" or "adapt existing code"
- "This is different because..."
**ALL of these mean: Delete code. Start over with TDD.**
## Bug Fix Example
**Bug:** Empty email accepted
**RED:**
```typescript
test('rejects empty email', async () => {
const result = await submitForm({ email: '' });
expect(result.error).toBe('Email required');
});
```
**VERIFY RED:**
```bash
$ npm test
FAIL: expected 'Email required', got undefined
```
**GREEN:**
```typescript
function submitForm(data: FormData) {
if (!data.email?.trim()) {
return { error: 'Email required' };
}
// ...
}
```
**VERIFY GREEN:**
```bash
$ npm test
PASS
```
## Verification Checklist
Before marking work complete:
- [ ] Every new function/method has a test
- [ ] Watched each test fail before implementing
- [ ] Each test failed for expected reason
- [ ] Wrote minimal code to pass each test
- [ ] All tests pass
- [ ] Output clean (no errors, warnings)
**Can't check all boxes? You skipped TDD. Start over.**
## Integration with Claude Octopus
When using octopus workflows:
| Workflow | TDD Integration |
|----------|-----------------|
| `probe` (research) | Research testing patterns for the domain |
| `grasp` (define) | Define test requirements in spec |
| `tangle` (develop) | **Enforce TDD for each implementation task** |
| `ink` (deliver) | Verify all tests pass before delivery |
| `squeeze` (security) | Red team tests security controls |
## When Stuck
| Problem | Solution |
|---------|----------|
| Don't know how to test | Write the API you wish existed. Assert first. |
| Test too complicated | Design too complicated. Simplify interface. |
| Must mock everything | Code too coupled. Use dependency injection. |
| Test setup huge | Extract helpers. Still complex? Simplify design. |
## The Bottom Line
```
Production code exists → Test exists that failed first
