Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation. - Implementing tasks from a track's plan.md - Following TDD red-green-refactor cycle
Workflow Patterns
Guide for implementing tasks using Conductor's TDD workflow, managing phase checkpoints, handling git commits, and executing the verification protocol that ensures quality throughout implementation.
When to Use This Skill
Implementing tasks from a track's plan.md
Following TDD red-green-refactor cycle
Completing phase checkpoints
Managing git commits and notes
Understanding quality assurance gates
Handling verification protocols
Recording progress in plan files
TDD Task Lifecycle
Follow these 11 steps for each task:
Step 1: Select Next Task
Read plan.md and identify the next pending [ ] task. Select tasks in order within the current phase. Do not skip ahead to later phases.
Step 2: Mark as In Progress
Update plan.md to mark the task as [~]:
- [~] **Task 2.1**: Implement user validation
Commit this status change separately from implementation.
Step 3: RED - Write Failing Tests
Write tests that define the expected behavior before writing implementation:
Create test file if needed
Write test cases covering happy path
Write test cases covering edge cases
Write test cases covering error conditions
Run tests - they should FAIL
Example:
def test_validate_user_email_valid():
user = User(email="test@example.com")
assert user.validate_email() is True
def test_validate_user_email_invalid():
user = User(email="invalid")
assert user.validate_email() is False
Step 4: GREEN - Implement Minimum Code
Write the minimum code necessary to make tests pass:
Focus on making tests green, not perfection
Avoid premature optimization
Keep implementation simple
Run tests - they should PASS
Step 5: REFACTOR - Improve Clarity
With green tests, improve the code:
Extract common patterns
Improve naming
Remove duplication
Simplify logic
Run tests after each change - they should remain GREEN
Step 6: Verify Coverage
Check test coverage meets the 80% target:
pytest --cov=module --cov-report=term-missing
If coverage is below 80%:
Identify uncovered lines
Add tests for missing paths
Re-run coverage check
Step 7: Document Deviations
If implementation deviated from plan or introduced new dependencies:
Update tech-stack.md with new dependencies
Note deviations in plan.md task comments
Update spec.md if requirements changed
Step 8: Commit Implementation
Create a focused commit for the task:
git add -A
git commit -m "feat(user): implement email validation
- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage
Task: 2.1
Track: user-auth_20250115"
Commit message format:
Type: feat, fix, refactor, test, docs, chore
Scope: affected module or component
Summary: imperative, present tense
Body: bullet points of changes
Footer: task and track references
Step 9: Attach Git Notes
Add rich task summary as git note:
git notes add -m "Task 2.1: Implement user validation
Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module
Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)
Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"
Step 10: Update Plan with SHA
Update plan.md to mark task complete with commit SHA:
- [x] **Task 2.1**: Implement user validation abc1234``
Step 11: Commit Plan Update
Commit the plan status update:
LHOST_PH_3
Phase Completion Protocol
When all tasks in a phase are complete, execute the verification protocol:
Identify Changed Files
List all files modified since the last checkpoint:
git diff --name-only <last-checkpoint-sha>..HEAD
Ensure Test Coverage
For each modified file:
Identify corresponding test file
Verify tests exist for new/changed code
Run coverage for modified modules
Add tests if coverage < 80%
Run Full Test Suite
Execute complete test suite:
pytest -v --tb=short
All tests must pass before proceeding.
Generate Manual Verification Steps
Create checklist of manual verifications:
LHOST_PH_4
WAIT for User Approval
Present verification checklist to user:
LHOST_PH_5
Do NOT proceed without explicit approval.
Create Checkpoint Commit
After approval, create checkpoint commit:
LHOST_PH_6
Record Checkpoint SHA
Update plan.md checkpoints table:
LHOST_PH_7
Quality Assurance Gates
Before marking any task complete, verify these gates:
Passing Tests
All existing tests pass
New tests pass
No test regressions
Coverage >= 80%
New code has 80%+ coverage
Overall project coverage maintained
Critical paths fully covered
Style Compliance
Code follows style guides
Linting passes
Formatting correct
Documentation
Public APIs documented
Complex logic explained
README updated if needed
Type Safety
Type hints present (if applicable)
Type checker passes
No type: ignore without reason
No Linting Errors
Zero linter errors
Warnings addressed or justified
Static analysis clean
Mobile Compatibility
If applicable:
Responsive design verified
Touch interactions work
Performance acceptable
Security Audit
No secrets in code
Input validation present
Authentication/authorization correct
Dependencies vulnerability-free
Git Integration
Commit Message Format
LHOST_PH_8
Types:
feat: New feature
fix: Bug fix
refactor: Code change without feature/fix
test: Adding tests
docs: Documentation
chore: Maintenance
Git Notes for Rich Summaries
Attach detailed notes to commits:
git notes add -m "<detailed summary>"
View notes:
git log --show-notes
Benefits:
Preserves context without cluttering commit message
Enables semantic queries across commits
Supports track-based operations
SHA Recording in plan.md
Always record the commit SHA when completing tasks:
LHOST_PH_9
This enables:
Traceability from plan to code
Semantic revert operations
Progress auditing
Verification Checkpoints
Why Checkpoints Matter
Checkpoints create restore points for semantic reversion:
Revert to end of any phase
Maintain logical code state
Enable safe experimentation
When to Create Checkpoints
Create checkpoint after:
All phase tasks complete
All phase verifications pass
User approval received
Checkpoint Commit Content
Include in checkpoint commit:
All uncommitted changes
Updated plan.md
Updated metadata.json
Any documentation updates
How to Use Checkpoints
For reverting:
LHOST_PH_10
Handling Deviations
During implementation, deviations from the plan may occur. Handle them systematically:
Types of Deviations
Scope Addition Discovered requirement not in original spec.
Document in spec.md as new requirement
Add tasks to plan.md
Note addition in task comments
Scope Reduction Feature deemed unnecessary during implementation.
Mark tasks as [-] (skipped) with reason
Update spec.md scope section
Document decision rationale
Technical Deviation Different implementation approach than planned.
Note deviation in task completion comment
Update tech-stack.md if dependencies changed
Document why original approach was unsuitable
Requirement Change Understanding of requirement changes during work.
Update spec.md with corrected requirement
Adjust plan.md tasks if needed
Re-verify acceptance criteria
Deviation Documentation Format
When completing a task with deviation:
LHOST_PH_11
Error Recovery
Failed Tests After GREEN
If tests fail after reaching GREEN:
Do NOT proceed to REFACTOR
Identify which test started failing
Check if refactoring broke something
Revert to last known GREEN state
Re-approach the implementation
Checkpoint Rejection
If user rejects a checkpoint:
Note rejection reason in plan.md
Create tasks to address issues
Complete remediation tasks
Request checkpoint approval again
Blocked by Dependency
If task cannot proceed:
Mark task as [!] with blocker description
Check if other tasks can proceed
Document expected resolution timeline
Consider creating dependency resolution track
TDD Variations by Task Type
Data Model Tasks
RED: Write test for model creation and validation
GREEN: Implement model class with fields
REFACTOR: Add computed properties, improve types
`### API Endpoint Tasks`
RED: Write test for request/response contract
GREEN: Implement endpoint handler
REFACTOR: Extract validation, improve error handling
`### Integration Tasks`
RED: Write test for component interaction
GREEN: Wire components together
REFACTOR: Improve error propagation, add logging
`### Refactoring Tasks`
RED: Add characterization tests for current behavior
GREEN: Apply refactoring (tests should stay green)
REFACTOR: Clean up any introduced complexity
Working with Existing Tests
When modifying code with existing tests:
Extend, Don't Replace
Keep existing tests passing
Add new tests for new behavior
Update tests only when requirements change
Test Migration
When refactoring changes test structure:
Run existing tests (should pass)
Add new tests for refactored code
Migrate test cases to new structure
Remove old tests only after new tests pass
Regression Prevention
After any change:
Run full test suite
Check for unexpected failures
Investigate any new failures
Fix regressions before proceeding
Checkpoint Verification Details
Automated Verification
Run before requesting approval:
# Test suite
pytest -v --tb=short
# Coverage
pytest --cov=src --cov-report=term-missing
# Linting
ruff check src/ tests/
# Type checking (if applicable)
mypy src/
Manual Verification Guidance
For manual items, provide specific instructions:
## Manual Verification Steps
### User Registration
1. Navigate to /register
2. Enter valid email: test@example.com
3. Enter password meeting requirements
4. Click Submit
5. Verify success message appears
6. Verify user appears in database
### Error Handling
1. Enter invalid email: "notanemail"
2. Verify error message shows
3. Verify form retains other entered data
Performance Considerations
Test Suite Performance
Keep test suite fast:
Use fixtures to avoid redundant setup
Mock slow external calls
Run subset during development, full suite at checkpoints
Commit Performance
Keep commits atomic:
One logical change per commit
Complete thought, not work-in-progress
Tests should pass after every commit
Best Practices
Never skip RED: Always write failing tests first
Small commits: One logical change per commit
Immediate updates: Update plan.md right after task completion
Wait for approval: Never skip checkpoint verification
Rich git notes: Include context that helps future understanding