ct-dev-workflow

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.

141 stars

bykryptobaseddev

View on GitHub Installation ↓

Best use case

ct-dev-workflow is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using ct-dev-workflow should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/ct-dev-workflow/SKILL.md --create-dirs "https://raw.githubusercontent.com/kryptobaseddev/cleo/main/packages/skills/skills/ct-dev-workflow/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/ct-dev-workflow/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How ct-dev-workflow Compares

Feature / Agent	ct-dev-workflow	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

Related Guides

AI Agents for Coding

Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.

Cursor vs Codex for AI Workflows

Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.

Top AI Agents for Productivity

See the top AI agent skills for productivity, workflow automation, operational systems, documentation, and everyday task execution.

SKILL.md Source

# 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

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

```bash
# 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.**

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

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

```bash
# 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)

```bash
# 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.

```bash
# 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.**

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

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

1. MUST write workflow summary to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
2. MUST append ONE line to: `{{MANIFEST_PATH}}`
3. MUST return ONLY: "Workflow complete. See MANIFEST.jsonl for summary."
4. MUST NOT return full commit/release details in response

---

## Complete Workflow Examples

### Example 1: Bug Fix (Typical)

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

```bash
# 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 origin HEAD

# 6. Complete
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

1. **Always have a task** before making changes
2. **Always include task reference** in commit message
3. **Never commit to main/master** directly
4. **Run relevant tests** locally, not always full suite
5. **Let CI validate** with full test suite on push
6. **Use tags for releases** - GitHub Actions handles the rest
7. **One logical change** per commit (atomic)
8. **Conventional commit format** with task reference

Related Skills

signaldock-connect

141

from kryptobaseddev/cleo

Connect any AI agent to SignalDock for agent-to-agent messaging. Use when an agent needs to: (1) register on api.signaldock.io, (2) install the signaldock runtime CLI, (3) send/receive messages to other agents, (4) set up SSE real-time streaming, (5) poll for messages, (6) check inbox, or (7) connect to the SignalDock platform. Triggers on: "connect to signaldock", "register agent", "send message to agent", "agent messaging", "signaldock setup", "install signaldock", "agent-to-agent".

ct-validator

141

from kryptobaseddev/cleo

Compliance validation for verifying systems, documents, or code against requirements, schemas, or standards. Performs schema validation, code compliance checks, document validation, and protocol compliance verification with detailed pass/fail reporting. Use when validating compliance, checking schemas, verifying code standards, or auditing protocol implementations. Triggers on validation tasks, compliance checks, or quality verification needs.

ct-task-executor

141

from kryptobaseddev/cleo

General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.

ct-stickynote

141

from kryptobaseddev/cleo

Quick ephemeral sticky notes for project-wide capture before formal classification

ct-spec-writer

141

from kryptobaseddev/cleo

Technical specification writing using RFC 2119 language for clear, unambiguous requirements. Creates protocol specifications, technical requirements, API specifications, and architecture documents with testable requirements and compliance criteria. Use when writing specifications, defining protocols, documenting requirements, or creating API contracts. Triggers on specification tasks, protocol definition needs, or requirement documentation.

ct-skill-validator

141

from kryptobaseddev/cleo

Validates an existing skill folder against the full CLEO standard and ecosystem. Use when auditing skills for structural compliance, verifying a skill fits into the CLEO ecosystem and constitution, running quality A/B evals, or preparing a skill for distribution. Runs a 3-phase validation loop — structural, ecosystem fit, and quality eval — then presents all findings as an HTML report opened in the user's browser. Iterates until all required phases pass.

ct-skill-creator

141

from kryptobaseddev/cleo

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

ct-research-agent

141

from kryptobaseddev/cleo

Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase analysis. Synthesizes findings into actionable recommendations with proper citation and task traceability. Use when conducting research, investigating best practices, gathering technical information, or analyzing existing implementations. Triggers on research tasks, investigation needs, or information discovery requests.

ct-release-orchestrator

141

from kryptobaseddev/cleo

Orchestrates the full release pipeline: version bump, then changelog, then commit, then tag, then conditionally forks to artifact-publish and provenance based on release config. Parent protocol that composes ct-artifact-publisher and ct-provenance-keeper as sub-protocols: not every release publishes artifacts (source-only releases skip it), and artifact publishers delegate signing and attestation to provenance. Use when shipping a new version, running cleo release ship, or promoting a completed epic to released status.

ct-provenance-keeper

141

from kryptobaseddev/cleo

Generates in-toto v1 attestations, SLSA-level provenance records, SBOMs (CycloneDX or SPDX), and sigstore/cosign signatures for published artifacts. Invoked by ct-artifact-publisher as a delegation for signing and attestation. Records the full commit, then build, then artifact, then attestation, then registry chain in .cleo/releases.json and rejects publishes whose digest does not match the attestation. Triggers when artifact-publish reaches the provenance step or when a release needs SLSA L2+ attestation.

ct-orchestrator

141

from kryptobaseddev/cleo

Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to "orchestrate", "orchestrator mode", "run as orchestrator", "delegate to subagents", "coordinate agents", "spawn subagents", "multi-agent workflow", "context-protected workflow", "agent farm", "HITL orchestration", "pipeline management", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime.

ct-memory

141

from kryptobaseddev/cleo

Brain memory protocol with progressive disclosure for anti-hallucination and context recall