TDD Workflow

This skill provides the Test-Driven Development methodology used by Conductor for task implementation.

Guiding Principles

1. The Plan is the Source of Truth: All work must be tracked in plan.md
2. The Tech Stack is Deliberate: Changes to the tech stack must be documented in tech-stack.md before implementation
3. Test-Driven Development: Write unit tests before implementing functionality
4. High Code Coverage: Aim for >80% code coverage for all modules
5. User Experience First: Every decision should prioritize user experience
6. Non-Interactive & CI-Aware: Prefer non-interactive commands. Use CI=true for watch-mode tools (tests, linters) to ensure single execution.

Standard Task Workflow

All tasks follow a strict lifecycle:

1. Select Task

Choose the next available task from plan.md in sequential order.

2. Mark In Progress

Before beginning work, edit plan.md and change the task from [ ] to [~].

3. Write Failing Tests (Red Phase)

• Create a new test file for the feature or bug fix.
• Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
• CRITICAL: Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.

4. Implement to Pass Tests (Green Phase)

• Write the minimum amount of application code necessary to make the failing tests pass.
• Run the test suite again and confirm that all tests now pass. This is the "Green" phase.

5. Refactor (Optional but Recommended)

• With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
• Rerun tests to ensure they still pass after refactoring.

6. Verify Coverage

Run coverage reports using the project's chosen tools. Target: >80% coverage for new code.

Example commands by language:

• Python: pytest --cov=app --cov-report=html
• JavaScript/TypeScript: npm test -- --coverage
• Go: go test -cover ./...

7. Document Deviations

If implementation differs from tech stack:

• STOP implementation
• Update tech-stack.md with new design
• Add dated note explaining the change
• Resume implementation

8. Commit Code Changes

• Stage all code changes related to the task.
• Propose a clear, concise commit message (e.g., feat(ui): Create basic HTML structure for calculator).
• Perform the commit.

9. Attach Task Summary with Git Notes

• Step 9.1: Get the hash of the just-completed commit (git log -1 --format="%H").
• Step 9.2: Draft note content including task name, summary of changes, files modified, and the "why".
• Step 9.3: Attach note: git notes add -m "<note content>" <commit_hash>

10. Get and Record Task Commit SHA

• Step 10.1: Read plan.md, find the completed task, update status from [~] to [x], and append the first 7 characters of the commit hash.
• Step 10.2: Write the updated content back to plan.md.

11. Commit Plan Update

• Stage the modified plan.md file.
• Commit with message: conductor(plan): Mark task '<task_name>' as complete

Phase Completion Verification and Checkpointing Protocol

Trigger: Execute immediately after completing a task that also concludes a phase in plan.md.

1. Announce Protocol Start

Inform the user that the phase is complete and verification has begun.

2. Ensure Test Coverage for Phase Changes

• Step 2.1: Find the Git commit SHA of the previous phase's checkpoint. If none exists, scope is all changes since first commit.
• Step 2.2: Execute git diff --name-only <previous_checkpoint_sha> HEAD to list files modified during this phase.
• Step 2.3: For each code file (excluding .json, .md, .yaml), verify a corresponding test file exists. If missing, create one.

3. Execute Automated Tests with Proactive Debugging

• Announce the exact shell command before execution (e.g., "Command: CI=true npm test").
• If tests fail, attempt to fix a maximum of two times. If still failing, stop and ask for guidance.

4. Propose Manual Verification Plan

Generate step-by-step instructions for the user to manually verify the phase.

Frontend example:

1. Start the development server: `npm run dev`
2. Open browser to: `http://localhost:3000`
3. Confirm you see: The new user profile page with name and email

Backend example:

1. Ensure the server is running
2. Execute: `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
3. Confirm response: JSON with status `201 Created`

5. Await Explicit User Feedback

Ask: "Does this meet your expectations? Please confirm with yes or provide feedback." PAUSE and await response. Do not proceed without explicit confirmation.

6. Create Checkpoint Commit

Stage all changes and commit: conductor(checkpoint): Checkpoint end of Phase X

7. Attach Verification Report using Git Notes

Draft and attach a detailed verification report including automated test command, manual steps, and user confirmation.

8. Get and Record Phase Checkpoint SHA

• Get the checkpoint commit hash.
• Update plan.md to append [checkpoint: <sha>] to the phase heading.
• Commit: conductor(plan): Mark phase '<PHASE NAME>' as complete

9. Announce Completion

Inform the user that the phase is complete with verification report attached as git note.

Quality Gates

Before marking any task complete, verify:

• All tests pass
• Code coverage meets requirements (>80%)
• Code follows project's code style guidelines
• All public functions/methods are documented
• Type safety is enforced
• No linting or static analysis errors
• Works correctly on mobile (if applicable)
• Documentation updated if needed
• No security vulnerabilities introduced

Commit Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Formatting, missing semicolons, etc.
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding missing tests
• chore: Maintenance tasks

Examples

git commit -m "feat(auth): Add remember me functionality"
git commit -m "fix(posts): Correct excerpt generation for short posts"
git commit -m "test(comments): Add tests for emoji reaction limits"

Definition of Done

A task is complete when:

1. All code implemented to specification
2. Unit tests written and passing
3. Code coverage meets project requirements
4. Documentation complete (if applicable)
5. Code passes all configured linting and static analysis checks
6. Works beautifully on mobile (if applicable)
7. Implementation notes added to plan.md
8. Changes committed with proper message
9. Git note with task summary attached to the commit