| name | ct-dev-workflow |
| description | Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs. |
| version | 3.0.0 |
| tier | 2 |
| core | false |
| category | specialist |
| protocol | contribution |
| dependencies | [] |
| sharedResources | ["subagent-protocol-base","task-system-integration"] |
| compatibility | ["claude-code","cursor","windsurf","gemini-cli"] |
| license | MIT |
Development Workflow Context Injection
Protocol: @src/protocols/contribution.md
Type: Context Injection (cleo-subagent)
Version: 3.0.0
Purpose
Context injection for development workflow tasks spawned via cleo-subagent. Provides domain expertise for atomic commits with task traceability, conventional commit messages, and systematic release processes.
Core Principle: Task-Driven Development
CRITICAL: NO code changes or commits without a tracked task.
Every commit MUST be traceable to a CLEO task. This ensures:
- Work is planned and tracked
- Changes are reviewable and reversible
- Progress is measurable
- Context is preserved for future agents
Immutable Constraints (WORKFLOW)
| ID | Rule | Enforcement |
|---|
| WF-001 | Task required | NO commits without CLEO task reference |
| WF-002 | Branch discipline | NO commits to main/master |
| WF-003 | Atomic commits | ONE logical change per commit |
| WF-004 | Conventional format | <type>(<scope>): <description> |
| WF-005 | Tests before push | Relevant tests MUST pass |
Task Tracking Integration
Before Any Work
cleo current
cleo find "relevant query"
cleo add "Task title" --description "What you're doing" --parent T001
cleo start T123
Commit Message Format
MUST include task reference:
<type>(<scope>): <description>
<body explaining why>
Task: T123
Co-Authored-By: Claude <noreply@anthropic.com>
Example:
fix(auth): prevent token expiry race condition
The refresh token was being invalidated before the new access
token was validated, causing intermittent auth failures.
Task: T1456
Co-Authored-By: Claude <noreply@anthropic.com>
Branch & Subagent Awareness
Single Branch Reality
Subagents share the parent session's branch. This means:
- All work happens on the same branch
- No parallel feature branches from subagents
- Commits are sequential, not parallel
- Worktrees needed for true branch isolation
Branch Strategy
git branch --show-current
main → feature/T123-description → PR → main
feature/T123-auth-improvements
fix/T456-token-validation
Gate System (Simplified)
Not all gates apply to all changes. Follow the decision matrix.
G0: Pre-Flight Check
Always required.
cleo current
git branch --show-current
git status --porcelain
G1: Classify Change
| Type | Description | Tests Needed | Version Bump |
|---|
feat | New feature | Related tests | MINOR |
fix | Bug fix | Regression test | PATCH |
docs | Documentation | None | None |
refactor | Code restructure | Affected tests | PATCH |
test | Test additions | The new tests | None |
chore | Maintenance | None | None |
perf | Performance | Perf tests | PATCH |
security | Security fix | Security tests | PATCH |
G2: Testing (Smart Scope)
NOT always full test suite. CI runs full tests on push.
| Change Type | Test Scope | Command |
|---|
feat | Related module tests | bats tests/unit/feature.bats |
fix | Regression + affected | bats tests/unit/affected.bats |
docs | None (CI validates) | Skip |
refactor | Affected modules | bats tests/unit/module*.bats |
test | The new tests only | bats tests/unit/new.bats |
chore | Syntax check only | bash -n scripts/*.sh |
When to run full suite locally:
- Before release (version bump)
- Major refactoring
- Cross-cutting changes
- User explicitly requests
./tests/run-all-tests.sh
bats tests/unit/specific-feature.bats
bats tests/integration/workflow.bats
bash -n scripts/*.sh lib/*.sh
G3: Commit
task_id=$(cleo current --quiet)
git add scripts/specific-file.sh lib/related.sh
git commit -m "$(cat <<'EOF'
fix(auth): prevent token expiry race condition
The refresh token was being invalidated before validation.
Task: T1456
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
G4: Push (Triggers CI)
git push origin HEAD
G5: Version Bump (Release Only)
Only for releases, not every commit.
./dev/bump-version.sh --dry-run patch
./dev/bump-version.sh patch
./dev/validate-version.sh
./install.sh --force
cleo version
G6: Tag & Release
GitHub Actions handles release creation.
git tag -a v${VERSION} -m "${TYPE}: ${SUMMARY}"
git push origin v${VERSION}
git push origin HEAD
Quick Decision Matrix
What Tests to Run?
| Change | Local Tests | Rely on CI |
|---|
| Single file fix | Related unit test | Yes |
| New feature | Feature tests | Yes |
| Docs only | None | Yes |
| Schema change | Schema tests | Yes |
| Cross-cutting refactor | Full suite | Yes |
| Release prep | Full suite | Yes |
Do I Need a Version Bump?
| Change | Bump | Tag |
|---|
feat | minor | Yes |
fix | patch | Yes |
docs | No | No |
refactor | patch | Yes |
test | No | No |
chore | No | No |
perf | patch | Yes |
security | patch | Yes |
Task System Integration
@skills/_shared/task-system-integration.md
CLEO Integration Commands
cleo current
cleo start T123
cleo complete T123
cleo find "query"
cleo list --status pending
cleo add "Title" --parent T001 --description "..."
cleo session status
cleo session end --note "Completed X, Y, Z"
Subagent Protocol
@skills/_shared/subagent-protocol-base.md
Output Requirements
- MUST write workflow summary to:
{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
- MUST append ONE line to:
{{MANIFEST_PATH}}
- MUST return ONLY: "Workflow complete. Manifest appended to pipeline_manifest."
- MUST NOT return full commit/release details in response
Complete Workflow Examples
Example 1: Bug Fix (Typical)
cleo current
bats tests/unit/auth.bats
git add lib/auth.sh scripts/login.sh
git commit -m "$(cat <<'EOF'
fix(auth): prevent token expiry race condition
Task: T1456
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git push origin HEAD
cleo complete T1456
Example 2: Documentation Only
cleo current
git add docs/ README.md
git commit -m "$(cat <<'EOF'
docs: update installation instructions
Task: T1550
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git push origin HEAD
cleo complete T1550
Anti-Patterns
| Pattern | Problem | Solution |
|---|
| No task reference | Untracked work | Create/find task first |
| Committing to main | Bypass review | Use feature branches |
| Running full tests always | Slow iteration | Use smart test scope |
| Skipping CI | Missing validations | Always push, let CI run |
| Manual release creation | Inconsistent releases | Use tag, GH Actions |
| Giant commits | Hard to review/revert | Atomic commits |
| Vague commit messages | Lost context | Conventional + task ref |
Critical Rules Summary
- Always have a task before making changes
- Always include task reference in commit message
- Never commit to main/master directly
- Run relevant tests locally, not always full suite
- Let CI validate with full test suite on push
- Use tags for releases - GitHub Actions handles the rest
- One logical change per commit (atomic)
- Conventional commit format with task reference
