agentleFS
hardness1020hardness1020/VibeFlow/.claude/skills/run-tdd/SKILL.md

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

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
  1. Distinctive:

    Stage F (RED): Create stubs + write failing unit tests

    line 24
  2. Distinctive:

    Stage H (REFACTOR): Write integration tests + refactor + quality validation

    line 26
  3. Distinctive:

    Create implementation stubs from Feature Spec API Design

    line 71
  4. Distinctive:

    Write failing unit tests

    line 72
  5. Distinctive:

    Verify tests fail with "not implemented" errors

    line 73
  6. Distinctive:

    Check for contract changes (trigger G.1 if needed)

    line 82
  7. Distinctive:

    Verify all unit tests pass

    line 83
  8. Distinctive:

    Write integration tests for I/O boundaries

    line 91
  9. Distinctive:

    If implementation reveals contract changes, STOP IMMEDIATELY and follow these steps:

    line 113
  10. Distinctive:

    Document the discovered issue

    line 115
  11. Distinctive:

    Update SPEC first (increment version)

    line 116
  12. Distinctive:

    Create/update ADR if non-trivial

    line 117
  13. Distinctive:

    Update Feature Spec API Design

    line 118
  14. Distinctive:

    Update tests to new contract

    line 119
  15. Distinctive:

    All tests must have categorization tags:

    line 137
  16. Distinctive:

    Before completing Stage H, validate:

    line 150
  17. Very specific:

    Test names use test_<what>_<condition>_<expected>

    line 154
  18. Distinctive:

    No skipped tests without justification

    line 165
  19. Distinctive:

    All tests have speed/scope tags

    line 168
  20. Distinctive:

    No real API calls in "unit" tests

    line 169
  21. Very specific:

    After completing each stage, update docs/workflow-state.yaml:

    line 197
  22. Distinctive:

    After completing each stage, ask the user for permission before committing:

    line 218
  23. Very specific:

    After each sub-stage commit, directly run /manage-work advance <ID>:

    line 242

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 Complete

Usage

Start TDD Cycle

/run-tdd start

Guides through the full TDD cycle starting with Stage F.

Stage F: RED Phase

/run-tdd red
  1. Create implementation stubs from Feature Spec API Design
  2. Write failing unit tests
  3. Verify tests fail with "not implemented" errors

Stage G: GREEN Phase

/run-tdd green
  1. Implement minimal code to pass unit tests
  2. Check for contract changes (trigger G.1 if needed)
  3. Verify all unit tests pass

Stage H: REFACTOR Phase

/run-tdd refactor
  1. Write integration tests for I/O boundaries
  2. Refactor code while keeping tests green
  3. Complete H.4 quality validation

Validate Tests

/run-tdd validate

Runs test quality validation (Stage H.4 checklist).

Handle Design Changes

/run-tdd g1

Guides 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:

  1. Document the discovered issue
  2. Update SPEC first (increment version)
  3. Create/update ADR if non-trivial
  4. Update Feature Spec API Design
  5. Update tests to new contract
  6. 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 ms
  • integration / medium — Uses test DB, mocked external APIs
  • e2e / slow — Full workflow, multiple components
  • real_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 requirements
  • tdd-guide.md — TDD workflow guidance
  • stage-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: 3 after 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: 4 after 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>:

  1. After Stage F (RED) commit → advances F→G. The advance command will automatically validate Checkpoint #3 at the F→G boundary.
  2. After Stage G (GREEN) commit → advances G→H.
  3. After Stage H (REFACTOR) commit → advances H→DONE or I. The advance command will automatically validate Checkpoint #4 at the H→DONE/I boundary.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.