v1.0.0 to v1.0.0

2 added, 587 removed. Audit A to A.

---

name: workflow-patterns

description: Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding the verification protocol.

version: 1.0.0

---

# 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 `[~]`:

- ```markdown

- - [~] **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:

- ```python

- 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:

- ```bash

- 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:

- ```bash

- 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:

- ```bash

- 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:

- ```markdown

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

- ```

- ### Step 11: Commit Plan Update

- Commit the plan status update:

- ```bash

- git add conductor/tracks/*/plan.md

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

- Track: user-auth_20250115"

- ```

- ## 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:

- ```bash

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

- ```

- ### Ensure Test Coverage

- For each modified file:

- 1. Identify corresponding test file

- 2. Verify tests exist for new/changed code

- 3. Run coverage for modified modules

- 4. Add tests if coverage < 80%

- ### Run Full Test Suite

- Execute complete test suite:

- ```bash

- pytest -v --tb=short

- ```

- All tests must pass before proceeding.

- ### Generate Manual Verification Steps

- Create checklist of manual verifications:

- ```markdown

- ## Phase 1 Verification Checklist

- - [ ] User can register with valid email

- - [ ] Invalid email shows appropriate error

- - [ ] Database stores user correctly

- - [ ] API returns expected response codes

- ```

- ### WAIT for User Approval

- Present verification checklist to user:

- ```

- Phase 1 complete. Please verify:

- 1. [ ] Test suite passes (automated)

- 2. [ ] Coverage meets target (automated)

- 3. [ ] Manual verification items (requires human)

- Respond with 'approved' to continue, or note issues.

- ```

- Do NOT proceed without explicit approval.

- ### Create Checkpoint Commit

- After approval, create checkpoint commit:

- ```bash

- git add -A

- git commit -m "checkpoint: phase 1 complete - user-auth_20250115

- Verified:

- - All tests passing

- - Coverage: 87%

- - Manual verification approved

- Phase 1 tasks:

- - [x] Task 1.1: Setup database schema

- - [x] Task 1.2: Implement user model

- - [x] Task 1.3: Add validation logic"

- ```

- ### Record Checkpoint SHA

- Update plan.md checkpoints table:

- ```markdown

- ## Checkpoints

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

- | Phase 1 | def5678 | 2025-01-15 | verified |

- ```

- ## 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

- ```

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

- <body>

- <footer>

- ```

- 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:

- ```bash

- git notes add -m "<detailed summary>"

- ```

- View notes:

- ```bash

- 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:

- ```markdown

- - [x] **Task 1.1**: Setup schema `abc1234`

- - [x] **Task 1.2**: Add model `def5678`

- ```

- 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:

- ```bash

- # Revert to end of Phase 1

- git revert --no-commit <phase-2-commits>...

- git commit -m "revert: rollback to phase 1 checkpoint"

- ```

- For review:

- ```bash

- # See what changed in Phase 2

- git diff <phase-1-sha>..<phase-2-sha>

- ```

- ## 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:

- ```markdown

- - [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

- ### Failed Tests After GREEN

- If tests fail after reaching GREEN:

- 1. Do NOT proceed to REFACTOR

- 2. Identify which test started failing

- 3. Check if refactoring broke something

- 4. Revert to last known GREEN state

- 5. Re-approach the implementation

- ### Checkpoint Rejection

- If user rejects a checkpoint:

- 1. Note rejection reason in plan.md

- 2. Create tasks to address issues

- 3. Complete remediation tasks

- 4. Request checkpoint approval again

- ### Blocked by Dependency

- If task cannot proceed:

- 1. Mark task as `[!]` with blocker description

- 2. Check if other tasks can proceed

- 3. Document expected resolution timeline

- 4. 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:

- 1. Run existing tests (should pass)

- 2. Add new tests for refactored code

- 3. Migrate test cases to new structure

- 4. Remove old tests only after new tests pass

- ### Regression Prevention

- After any change:

- 1. Run full test suite

- 2. Check for unexpected failures

- 3. Investigate any new failures

- 4. Fix regressions before proceeding

- ## Checkpoint Verification Details

- ### Automated Verification

- Run before requesting approval:

- ```bash

- # 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:

- ```markdown

- ## 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:

+ ## Detailed patterns and worked examples

- - One logical change per commit

- - Complete thought, not work-in-progress

- - Tests should pass after every commit

+ Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.

## Best Practices

1. **Never skip RED**: Always write failing tests first

2. **Small commits**: One logical change per commit

3. **Immediate updates**: Update plan.md right after task completion

4. **Wait for approval**: Never skip checkpoint verification

5. **Rich git notes**: Include context that helps future understanding

6. **Coverage discipline**: Don't accept coverage below target

7. **Quality gates**: Check all gates before marking complete

8. **Sequential phases**: Complete phases in order

9. **Document deviations**: Note any changes from original plan

10. **Clean state**: Each commit should leave code in working state

11. **Fast feedback**: Run relevant tests frequently during development

12. **Clear blockers**: Address blockers promptly, don't work around them