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
# 1. Verify you have a task
cleo current
# 2. If no task, find or create one
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
# Check current branch
git branch --show-current
# Feature work (typical pattern)
main → feature/T123-description → PR → main
# Branch naming
feature/T123-auth-improvements # Task-prefixed
fix/T456-token-validation # Bug fix
Gate System (Simplified)
Not all gates apply to all changes. Follow the decision matrix.
G0: Pre-Flight Check
Always required.
# 1. Verify task context
cleo current
# MUST have a current task
# 2. Check branch
git branch --show-current
# MUST NOT be main/master
# 3. Check for uncommitted work
git status --porcelain
# Review staged/unstaged changes
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
# Full suite (when needed)
./tests/run-all-tests.sh
# Targeted tests (typical)
bats tests/unit/specific-feature.bats
bats tests/integration/workflow.bats
# Quick syntax check
bash -n scripts/*.sh lib/*.sh
G3: Commit
# 1. Get task info
task_id=$(cleo current --quiet)
# 2. Stage changes (be specific for atomic commits)
git add scripts/specific-file.sh lib/related.sh
# 3. Create commit with task reference
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)
# Push branch (CI runs full tests)
git push origin HEAD
# CI will run:
# - Full test suite
# - ShellCheck linting
# - JSON validation
# - Documentation drift check
# - Installation test
G5: Version Bump (Release Only)
Only for releases, not every commit.
# 1. Preview
./dev/bump-version.sh --dry-run patch
# 2. Execute
./dev/bump-version.sh patch
# 3. Validate
./dev/validate-version.sh
# 4. Reinstall locally
./install.sh --force
cleo version
G6: Tag & Release
GitHub Actions handles release creation.
# 1. Create annotated tag
git tag -a v${VERSION} -m "${TYPE}: ${SUMMARY}"
# 2. Push tag (triggers release workflow)
git push origin v${VERSION}
# 3. Push branch
git push origin HEAD
# GitHub Actions automatically:
# - Builds release tarball
# - Creates GitHub Release
# - Generates release notes
# - Uploads artifacts
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
# Task lifecycle
cleo current # Current task
cleo start T123 # Start task
cleo complete T123 # Mark done
# Find existing work
cleo find "query" # Search tasks
cleo list --status pending # Pending work
# Create new work
cleo add "Title" --parent T001 --description "..."
# Session management
cleo session status # Current session
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)
# 1. Verify task
cleo current
# Output: T1456 - Fix token validation
# 2. Make changes
# ... edit files ...
# 3. Run relevant test
bats tests/unit/auth.bats
# 4. Stage specific files
git add lib/auth.sh scripts/login.sh
# 5. Commit with task
git commit -m "$(cat <<'EOF'
fix(auth): prevent token expiry race condition
Task: T1456
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
# 6. Push (CI handles full tests)
git push origin HEAD
# 7. Mark task complete
cleo complete T1456
Example 2: Documentation Only
# 1. Verify task
cleo current # T1550 - Update README
# 2. Make doc changes
# ... edit docs ...
# 3. No tests needed (CI validates)
# 4. Commit
git add docs/ README.md
git commit -m "$(cat <<'EOF'
docs: update installation instructions
Task: T1550
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
# 5. Push
git push