Development Workflow

Core Principles

1. plan.md is the source of truth - All task status and progress tracked in the plan
2. Test-Driven Development - Red → Green → Refactor cycle with 80% coverage target
3. CI/CD Compatibility - All changes must pass automated pipelines before merge
4. Incremental Progress - Small, verifiable commits with clear purpose

Task Lifecycle

Step 1: Task Selection

• Review plan.md for next pending task
• Verify dependencies are complete
• Confirm understanding of acceptance criteria

Step 2: Progress Marking

• Update task status in plan.md from [ ] to [~]
• Note start time if tracking velocity

Step 3: Red Phase (Write Failing Tests)

• Write test(s) that define expected behavior
• Verify test fails for the right reason
• Keep tests focused and minimal

Step 4: Green Phase (Make Tests Pass)

• Write minimum code to pass tests
• Avoid premature optimization
• Focus on correctness over elegance

Step 5: Refactor Phase

• Improve code structure without changing behavior
• Apply relevant style guide conventions
• Remove duplication and clarify intent

Step 6: Coverage Verification

• Run coverage report
• Ensure new code meets 80% threshold
• Add edge case tests if coverage gaps exist

Step 7: Deviation Documentation

• If implementation differs from spec, document why
• Update spec if change is permanent
• Flag for review if uncertain

Step 8: Code Commit

• Stage related changes only
• Write clear commit message referencing task
• Format: [track-id] task: description

Step 9: Git Notes (Optional)

• Add implementation notes for complex changes
• Reference relevant decisions or trade-offs

Step 10: Plan Update

• Mark task as [x] completed in plan.md
• Update any affected downstream tasks
• Note blockers or follow-up items

Step 11: Plan Commit

• Commit plan.md changes separately
• Format: [track-id] plan: mark task X complete

Phase Completion Protocol

Checkpoint Commits

At the end of each phase:

1. Ensure all phase tasks are [x] complete
2. Run full test suite
3. Verify coverage meets threshold
4. Create checkpoint commit: [track-id] checkpoint: phase N complete

Test Verification

{{TEST_COMMAND}}
{{COVERAGE_COMMAND}}

Manual Approval Gates

Phases requiring approval before proceeding:

• Architecture changes
• API contract modifications
• Database schema changes
• Security-sensitive implementations

Quality Assurance Gates

All code must pass these criteria before merge:

Development Commands

Environment Setup

{{SETUP_COMMAND}}

Development Server

{{DEV_COMMAND}}

Pre-Commit Checks

{{PRE_COMMIT_COMMAND}}

Full Validation

{{VALIDATE_COMMAND}}

Workflow Diagram

┌─────────────┐
│ Select Task │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Mark [~]    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ RED: Write  │
│ Failing Test│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ GREEN: Make │
│ Test Pass   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ REFACTOR    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Verify      │
│ Coverage    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Commit Code │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Mark [x]    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Commit Plan │
└─────────────┘