mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 09:37:15 +00:00
feat: add Conductor plugin for Context-Driven Development
Add comprehensive Conductor plugin implementing Context-Driven Development methodology with tracks, specs, and phased implementation plans. Components: - 5 commands: setup, new-track, implement, status, revert - 1 agent: conductor-validator - 3 skills: context-driven-development, track-management, workflow-patterns - 18 templates for project artifacts Documentation updates: - README.md: Updated counts (68 plugins, 100 agents, 110 skills, 76 tools) - docs/plugins.md: Added Conductor to Workflows section - docs/agents.md: Added conductor-validator agent - docs/agent-skills.md: Added Conductor skills section Also includes Prettier formatting across all project files.
This commit is contained in:
Seth Hobson
623
conductor/skills/workflow-patterns/SKILL.md
Normal file
623
conductor/skills/workflow-patterns/SKILL.md
Normal file
@@ -0,0 +1,623 @@
|
||||
---
|
||||
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 | Checkpoint SHA | Date | Status |
|
||||
| ------- | -------------- | ---------- | -------- |
|
||||
| Phase 1 | def5678 | 2025-01-15 | verified |
|
||||
| Phase 2 | | | pending |
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
- One logical change per commit
|
||||
- Complete thought, not work-in-progress
|
||||
- Tests should pass after every commit
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user