Spec-TDD Development Workflow

When developing ANY new feature or functionality, follow this strict workflow:

Workflow Steps

1. Write Specification FIRST (spec.md)

Use the specification skill to write specifications following project conventions.

The specification skill provides detailed guidelines for:

• Feature user story format (As a... I want... So that...)
• Requirements organization and naming (REQ-XXX-NNN)
• Requirement writing guidelines (atomic, testable, present tense)
• Scenario writing (Given/When/Then format)
• Proper spec structure and sections

After writing spec:

• Get user approval on spec before proceeding to tests

2. Write Tests SECOND (before implementation)

• Write tests based on the spec requirements
• One test per assertion (performance costs permitting)
• Test naming: test_should_{expected_behavior}
• Test files: tests/test_{feature}/test_{module}.rs

When to write unit tests vs acceptance tests:

• Unit tests: For isolated logic that doesn't require mocking
• Acceptance tests: For integration logic that requires mocking repositories, external services, or complex dependencies
• Rule: If a test requires mocking dependencies it should be an acceptance test instead
• Acceptance tests validate end-to-end behavior through actual API endpoints

3. Implement Code LAST

• Write minimal code to make tests pass
• Follow patterns from spec
• Reuse existing infrastructure where possible
• Update todo list as you work
• CRITICAL: Update spec requirement markers as you complete each requirement
  • After writing test: Mark test column with U (unit test) or A (acceptance test)
  • After implementing code: Mark code column with X (implemented)
  • Example: [O][O] → [U][O] (test written) → [U][X] (code implemented)

4. Run Tests to Verify Implementation

• CRITICAL: After completing implementation, ALWAYS run the tests
• All tests must pass before marking work as complete
• If tests fail, fix the implementation and re-run until all tests pass
• DO NOT claim work is complete without running and passing tests

Use the test-driven-development skill for language-specific test running instructions:

• The TDD skill contains detailed patterns for running tests
• For other languages: See corresponding files in test-driven-development/{language}.md

5. Run Pre-commit Hooks Before Completion

• CRITICAL: After tests pass, ALWAYS run pre-commit hooks
• Pre-commit hooks run linters, formatters, and static analysis tools
• Fix any issues raised by pre-commit hooks before marking work as complete
• DO NOT claim work is complete without running and passing pre-commit hooks

Run pre-commit hooks:

pre-commit run --all-files

Commit Workflow

Use the write-commit-message skill for git commit guidelines.

Do NOT Proceed Without

1. ❌ Do NOT write implementation code before spec
2. ❌ Do NOT write implementation code before tests
3. ❌ Do NOT skip writing tests
4. ❌ Do NOT write multiple assertions per test (unless justified)
5. ❌ Do NOT skip running tests after implementation
6. ❌ Do NOT skip running pre-commit hooks before completion
7. ✅ DO write spec → tests → implementation → run tests → run pre-commit in that order
8. ✅ DO get user approval on spec before proceeding
9. ✅ DO use TodoWrite to track progress
10. ✅ DO run tests and verify all pass
11. ✅ DO run pre-commit hooks and fix all issues