Workflow Patterns

Implement tasks systematically using TDD (Test-Driven Development) with phase checkpoints and verification protocols. Ensures quality at every step.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install workflow-patterns

WHAT This Skill Does

Provides a structured approach to implementing tasks:

• TDD cycle (red → green → refactor) for each task
• Quality gates (tests, coverage, linting) before marking complete
• Phase checkpoints requiring user approval
• Git commits with rich metadata for traceability

WHEN to Use

Use for:

• Implementing features from a plan
• Following TDD methodology
• Tasks requiring quality verification
• Projects with coverage requirements
• Team workflows needing traceability

Skip for:

• Quick fixes or trivial changes
• Exploratory prototyping
• Projects without test infrastructure

Keywords: TDD, implementation, testing, coverage, checkpoints, verification, red-green-refactor

The TDD Task Lifecycle

11 steps for each task:

Step 1: Select Next Task

Read the plan and identify the next pending [ ] task. Select tasks in order within the current phase. Do not skip ahead.

Step 2: Mark as In Progress

Update the plan to mark the task as [~]:

- [~] **Task 2.1**: Implement user validation

Step 3: RED — Write Failing Tests

Write tests that define expected behavior before implementation:

• Create test file if needed
• Cover happy path
• Cover edge cases
• Cover error conditions
• Run tests — they should FAIL

def test_validate_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

Step 4: GREEN — Implement Minimum Code

Write the minimum code 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 — must stay 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 added dependencies:

• Update tech-stack.md with new dependencies
• Note deviations in plan task comments
• Update spec if requirements changed

Step 8: Commit Implementation

Create focused commit:

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"

Step 9: Update Plan with SHA

Mark task complete with commit SHA:

- [x] **Task 2.1**: Implement user validation `abc1234`

Step 10: Commit Plan Update

git commit -m "docs: update plan - task 2.1 complete"

Step 11: Repeat

Continue to next task until phase is complete.

Phase Completion Protocol

When all tasks in a phase are complete:

1. Identify Changed Files

git diff --name-only <last-checkpoint-sha>..HEAD

2. Ensure Test Coverage

For each modified file:

• Verify tests exist for new/changed code
• Run coverage for modified modules
• Add tests if coverage < 80%

3. Run Full Test Suite

pytest -v --tb=short

All tests must pass.

4. Generate Verification Checklist

## Phase 1 Verification

- [ ] User can register with valid email
- [ ] Invalid email shows appropriate error
- [ ] Database stores user correctly

5. WAIT for User Approval

Present checklist:

Phase 1 complete. Please verify:
1. [x] Test suite passes (automated)
2. [x] Coverage meets target (automated)
3. [ ] Manual verification items (requires human)

Respond with 'approved' to continue.

Do NOT proceed without explicit approval.

6. Create Checkpoint Commit

git commit -m "checkpoint: phase 1 complete

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved"

7. Record Checkpoint SHA

Update plan checkpoints table:

## Checkpoints

| Phase   | SHA     | Date       | Status   |
|---------|---------|------------|----------|
| Phase 1 | def5678 | 2025-01-15 | verified |
| Phase 2 |         |            | pending  |

Quality Gates

Before marking any task complete:

| Gate | Requirement |

|------|-------------|

| Tests | All existing tests pass, new tests pass |

| Coverage | New code has 80%+ coverage |

| Linting | No linter errors |

| Types | Type checker passes (if applicable) |

| Security | No secrets in code, input validation present |

Git Commit Format

<type>(<scope>): <subject>

<body>

Task: <task-id>

Types:

• feat — New feature
• fix — Bug fix
• refactor — Code change without feature/fix
• test — Adding tests
• docs — Documentation
• chore — Maintenance

Handling Deviations

Scope Addition

Discovered requirement not in spec:

• Document in spec as new requirement
• Add tasks to plan
• Note addition in task comments

Scope Reduction

Feature deemed unnecessary:

• Mark tasks as [-] (skipped) with reason
• Update spec scope section
• Document decision rationale

Technical Deviation

Different approach than planned:

• Note deviation in task comment
• Update tech-stack.md if dependencies changed
• Document why original approach was unsuitable

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

Error Recovery

Tests Fail After GREEN

1. Do NOT proceed to REFACTOR
2. Identify which test started failing
3. Revert to last known GREEN state
4. Re-approach the implementation

Checkpoint Rejected

1. Note rejection reason in plan
2. Create tasks to address issues
3. Complete remediation tasks
4. Request checkpoint approval again

Blocked by Dependency

1. Mark task as [!] with blocker description
2. Check if other tasks can proceed
3. Document expected resolution

Task Status Symbols

| Symbol | Meaning |

|--------|---------|

| [ ] | Pending |

| [~] | In progress |

| [x] | Complete |

| [-] | Skipped |

| [!] | Blocked |

Best Practices

1. Never skip RED — Always write failing tests first
2. Small commits — One logical change per commit
3. Immediate updates — Update plan right after task completion
4. Wait for approval — Never skip checkpoint verification
5. Coverage discipline — Don't accept below target
6. Sequential phases — Complete phases in order
7. Document deviations — Note any changes from plan
8. Clean state — Each commit leaves code working

NEVER Do

1. NEVER skip the RED phase — writing tests first is non-negotiable in TDD
2. NEVER proceed past checkpoints without approval — wait for explicit user confirmation
3. NEVER commit code that doesn't pass tests — every commit must be a working state
4. NEVER accept coverage below 80% — add tests until threshold is met
5. NEVER hide deviations from the plan — document all changes from original spec
6. NEVER skip phases or reorder them — phases are sequential for a reason
7. NEVER forget to record commit SHAs — traceability requires linking tasks to commits