/ct-dev-workflow

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.1.31
protocol: contribution
dependencies: []
sharedResources:
  - subagent-protocol-base
  - task-system-integration
compatibility:
  - claude-code
  - cursor
  - windsurf
  - gemini-cli
license: MIT
metadata:
  version: 3.1.31
  tier: core
  install: harness
  covers:
    - .github/workflows/release-prepare.yml
    - packages/cleo/src/cli/commands/hook.ts
    - packages/core/src/init.ts
    - packages/cleo/src/cli/commands/init.ts
    - packages/core/src/git/hooks-install.ts
    - packages/core/src/hooks.ts
    - packages/core/templates/git-hooks/**
    - packages/contracts/src/git-hooks.ts
  lastReviewed: 2026-10-24
  stability: stable

Development Workflow Context Injection

Opt-in unified-hook releases use the numbered `vYYYY.MM.N-canary.N` channel through the normal release plan/open and OIDC workflow. The release-preparation workflow accepts this channel explicitly; publication stays on `canary` and does not advance to `latest`. Preserve registry retries and installed-package soak checks. Stable promotion needs the separately retained, source-bound live harness and hosted VidaPeps pilot evidence; missing or unavailable verification holds it. The stable target may follow the canary base when npm has already advanced, but every receipt must still bind to the exact canary and implementation digest. Reject backward targets and prerelease targets; use the normal stable pipeline.

Before editing, inspect focus/briefing authority and coverage. Missing evidence means UNKNOWN impact; current static coverage does not prove every runtime caller. Task start, verification, completion, and handoff expose assessed coverage. Preserve these limitations in PR and handoff claims, and recheck after source changes. Use the repair matrix and sourced foreground resolutions; verify postconditions and retain receipt recovery. Record actionable learning rather than empty traces.

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

---

Git hook compatibility (T13349)

Init, upgrade and explicit Git hook installation share the ownership-aware installer. Resolve the effective hook directory through Git, including `core.hooksPath` and linked worktrees. Preserve foreign hooks and customized managed hooks; a CLEO marker alone never authorizes replacement. Refresh only exact shipped legacy bodies or receipt-owned content, using locked atomic writes and hash-guarded rollback. Report conflicts with the suggested integration snippet.

Receipts and locks stay in Git-private common metadata, including when `core.hooksPath` selects tracked files. Default installation preserves hook paths inside the checkout. Use `cleo init --git-hooks-only --allow-tracked-hooks-path` only after reviewing the tracked destination; this opt-in still preserves foreign and customized hooks. Init warnings carry the exact opt-in command.

The pre-push wrapper spools Git stdin once for task IDs and shared project checks. Besides Merge/Revert/fixup!/squash!/amend!, commit-msg and pre-push accept the exact subject `initial: cleo init` (the empty commit `cleo init` makes so HEAD resolves; T13577), only on a parentless first commit (T13582); a later commit with that subject, or any longer or different subject, still needs a task ID. A template change adds the previously shipped hash to `legacy-hashes.json` so installed copies refresh.

`cleo init` and `cleo upgrade` no longer seed the CleoOS hub (Pi extensions, CANT workflows, justfile) into the global CLEO home (T13994, ADR-098); only the deprecated `cleo admin scaffold-hub` still does. It probes CLEO_PROJECT_HOOK_V1 before invoking the implemented CLI adapter; missing or incompatible runners warn and allow. `cleo hook run --probe -- execution` answers EXEC or INERT (older builds answer V1; stable builds before 2026.10.17 are inert). Every ungated push, including a hooks-inert `cleo` first on PATH, prints one pre-push stderr line `WARNING: push NOT gated by project hooks: <reason>`, flagging a checkout whose activation is on (T13774). Verify nested checkout paths, linked worktrees, custom hook paths, historical release bodies and corrupt receipts with focused Git fixtures before changing this delivery path.

The fourth managed hook, `post-merge` (T14010), never blocks. In shell, before starting anything, it requires the `cleo.nexusReindexOnMerge` git marker and HEAD on the base branch; otherwise it starts no process. When both hold it starts `cleo nexus reindex-on-merge` detached. That command runs one at a time per p