run-tdd
Skill8 starsChanged 8 months agoMITView on GitHub
Write failing unit tests (RED), implement minimal code (GREEN), refactor with quality validation for Stages F-H of the VibeFlow docs-first workflow
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- analyze-codebaseSkill
- clarify-demandSkill
- create-feature-specSkill
- define-prdSkill
- define-tech-specSkill
- manage-workSkill
- prepare-releaseSkill
- record-decisionSkill
- validate-checkpointSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 20 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Stage F (RED): Create stubs + write failing unit tests
- Distinctive: line 26
Stage H (REFACTOR): Write integration tests + refactor + quality validation
- Distinctive: line 71
Create implementation stubs from Feature Spec API Design
- Distinctive: line 72
Write failing unit tests
- Distinctive: line 73
Verify tests fail with "not implemented" errors
- Distinctive: line 82
Check for contract changes (trigger G.1 if needed)
- Distinctive: line 83
Verify all unit tests pass
- Distinctive: line 91
Write integration tests for I/O boundaries
- Distinctive: line 113
If implementation reveals contract changes, STOP IMMEDIATELY and follow these steps:
- Distinctive: line 115
Document the discovered issue
- Distinctive: line 116
Update SPEC first (increment version)
- Distinctive: line 117
Create/update ADR if non-trivial
- Distinctive: line 118
Update Feature Spec API Design
- Distinctive: line 119
Update tests to new contract
- Distinctive: line 137
All tests must have categorization tags:
- Distinctive: line 150
Before completing Stage H, validate:
- Very specific: line 154
Test names use test_<what>_<condition>_<expected>
- Distinctive: line 165
No skipped tests without justification
- Distinctive: line 168
All tests have speed/scope tags
- Distinctive: line 169
No real API calls in "unit" tests
- Very specific: line 197
After completing each stage, update docs/workflow-state.yaml:
- Distinctive: line 218
After completing each stage, ask the user for permission before committing:
- Very specific: line 242
After each sub-stage commit, directly run /manage-work advance <ID>:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
run-tdd
TDD implementation cycle for Stages F-H of the VibeFlow docs-first workflow.
Purpose
This skill guides the TDD cycle:
- Stage F (RED): Create stubs + write failing unit tests
- Stage G (GREEN): Implement minimal code to pass tests
- Stage H (REFACTOR): Write integration tests + refactor + quality validation
Workflow
Stage F: RED
│
├── Create stubs from Feature Spec API Design
├── Write failing unit tests
├── Tests fail with NotImplementedError
└── Checkpoint #3: Tests Complete
│
▼
Stage G: GREEN
│
├── Implement minimal code to pass tests
├── If contracts change → Stage G.1
└── All unit tests pass
│
▼
Stage H: REFACTOR
│
├── Write integration tests for I/O
├── Pass integration tests
├── Refactor with tests green
├── Complete H.4 quality validation
└── Checkpoint #4: Implementation CompleteUsage
Start TDD Cycle
/run-tdd startGuides through the full TDD cycle starting with Stage F.
Stage F: RED Phase
/run-tdd red- Create implementation stubs from Feature Spec API Design
- Write failing unit tests
- Verify tests fail with "not implemented" errors
Stage G: GREEN Phase
/run-tdd green- Implement minimal code to pass unit tests
- Check for contract changes (trigger G.1 if needed)
- Verify all unit tests pass
Stage H: REFACTOR Phase
/run-tdd refactor- Write integration tests for I/O boundaries
- Refactor code while keeping tests green
- Complete H.4 quality validation
Validate Tests
/run-tdd validateRuns test quality validation (Stage H.4 checklist).
Handle Design Changes
/run-tdd g1Guides through Stage G.1 protocol when implementation reveals contract changes.
Stage G.1: Design Changes Protocol
If implementation reveals contract changes, STOP IMMEDIATELY and follow these steps:
- Document the discovered issue
- Update SPEC first (increment version)
- Create/update ADR if non-trivial
- Update Feature Spec API Design
- Update tests to new contract
- Resume implementation
Contract changes that trigger G.1:
- API/Interface signature changes
- Database schema changes
- Event format changes
- New external dependencies
- SLO changes
Changes that DON'T trigger G.1:
- Internal algorithms
- Private function names
- Error handling improvements (within taxonomy)
- Performance optimizations (within SLO)
Test Categorization
All tests must have categorization tags:
Speed/Scope (required):
unit/fast— All dependencies mocked, runs in msintegration/medium— Uses test DB, mocked external APIse2e/slow— Full workflow, multiple componentsreal_api— Makes real external API calls
Module (required):
- Tag with module name (e.g.,
accounts,generation,api)
Stage H.4 Quality Validation
Before completing Stage H, validate:
Organization:
- File structure follows conventions
- Test names use
test_<what>_<condition>_<expected> - Related tests grouped
Usefulness:
- Tests based on acceptance criteria
- Happy path, edge cases, error cases tested
- Tests validate behavior, not implementation
Code Quality:
- External dependencies mocked in unit tests
- AAA pattern clear
- No skipped tests without justification
Categorization:
- All tests have speed/scope tags
- No real API calls in "unit" tests
Reliability:
- Unit tests < 1s each
- Integration tests < 5s each
- Tests pass consistently (no flaky tests)
Quality Gate:
- 0-2 violations: PASS
- 3-5 violations: CONDITIONAL
- 6+ violations OR 2+ major: FAIL
Validation
scripts/validate_red.py— Validate Stage F (tests failing correctly)scripts/validate_green.py— Validate Stage G (tests passing)scripts/validate_refactor.py— Validate Stage H (integration + quality)scripts/check_coverage.py— Report test coverage
References
See references/:
tdd-policy.md— TDD policy and requirementstdd-guide.md— TDD workflow guidancestage-g1-protocol.md— Design change handling protocol
Manifest Update
After completing each stage, update docs/workflow-state.yaml:
Stage F (RED):
- Set
stage: F
Checkpoint #3 (after Stage F):
- Set
checkpoint: 3after passing validation - Criteria: Stubs exist matching Feature Spec API Design, unit tests exist and fail with NotImplementedError
Stage G (GREEN):
- Set
stage: G
Stage H (REFACTOR):
- Set
stage: H
Checkpoint #4 (after Stage H):
- Set
checkpoint: 4after passing validation - Criteria: All unit tests pass, integration tests pass, H.4 quality validation passes
Git Commit
After completing each stage, ask the user for permission before committing:
Stage F (RED):
git add <test-files> <stub-files> docs/workflow-state.yaml
git commit -m "feat(<module>): add failing tests and stubs (#ft-<ID>)"Stage G (GREEN):
git add <source-files> docs/workflow-state.yaml
git commit -m "feat(<module>): implement to pass tests (#ft-<ID>)"Stage H (REFACTOR):
git add <source-files> <test-files> docs/workflow-state.yaml
git commit -m "feat(<module>): add integration tests and refactor (#ft-<ID>)"Replace <module> with the actual module name, <ID> with the work item ID, and file placeholders with actual paths.
Auto-Advance
After each sub-stage commit, directly run /manage-work advance <ID>:
- After Stage F (RED) commit → advances F→G. The advance command will automatically validate Checkpoint #3 at the F→G boundary.
- After Stage G (GREEN) commit → advances G→H.
- After Stage H (REFACTOR) commit → advances H→DONE or I. The advance command will automatically validate Checkpoint #4 at the H→DONE/I boundary.
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.

