Workflow Patterns

Workflow Patterns

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

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: GateRequirementTestsAll existing tests pass, new tests passCoverageNew code has 80%+ coverageLintingNo linter errorsTypesType checker passes (if applicable)SecurityNo 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

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

Tests Fail After GREEN

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

Checkpoint Rejected

Note rejection reason in plan Create tasks to address issues Complete remediation tasks Request checkpoint approval again

Blocked by Dependency

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

Task Status Symbols

SymbolMeaning[ ]Pending[~]In progress[x]Complete[-]Skipped[!]Blocked

Best Practices

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

NEVER Do

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