npm - @cleocode/skills - Versions diffs - 2026.4.24 → 2026.4.26 - Mend

@cleocode/skills 2026.4.24 → 2026.4.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.4.24",
+  "version": "2026.4.26",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-orchestrator/README.md CHANGED Viewed

@@ -5,7 +5,7 @@ Activate orchestrator mode for managing complex multi-agent workflows.
 ## Quick Start
 1. **Activate**: Say "activate orchestrator mode" or use Skill tool
-2. **Operate**: Follow ORC-001 through ORC-005 constraints
+2. **Operate**: Follow ORC-001 through ORC-009 constraints
 3. **Delegate**: Use Task tool to spawn subagents for all work
 ## Installation
@@ -27,8 +27,8 @@ Skill: orchestrator
 Install to your project for persistent availability:
 ```bash
-cleo orchestrator skill --install    # Copy to .cleo/skills/
-cleo orchestrator skill --verify     # Verify installation
+cleo orchestrate skill --install    # Copy to .cleo/skills/
+cleo orchestrate skill --verify     # Verify installation
 ```
 ## Files
@@ -51,7 +51,8 @@ This is the critical difference from CLAUDE.md injection, which affected all age
 See [SKILL.md](SKILL.md) for quick reference or [ORCHESTRATOR-PROTOCOL-SPEC.md](../../docs/specs/ORCHESTRATOR-PROTOCOL-SPEC.md#21-core-constraints) for full specification.
-**Summary**: ORC-001 (high-level) | ORC-002 (delegate) | ORC-003 (no full reads) | ORC-004 (dependency order) | ORC-005 (10K budget)
+**Core Identity**: ORC-001 (HITL interface) | ORC-002 (no code) | ORC-003 (no full reads)
+**Operational**: ORC-004 (dep order) | ORC-005 (10K budget) | ORC-006 (3 files/agent) | ORC-007 (epic traced) | ORC-008 (no arch decisions) | ORC-009 (manifest handoffs)
 ## Why Skill-Based?

package/skills/ct-orchestrator/SKILL.md CHANGED Viewed

@@ -1,370 +1,224 @@
 ---
 name: ct-orchestrator
-description: "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."
-license: MIT
+description: "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."
 ---
 # Orchestrator Protocol
-> **HITL Entry Point**: This is the main Human-in-the-Loop interface for CLEO workflows.
-> Referenced in `.cleo/templates/AGENT-INJECTION.md` as the primary coordination skill.
->
-> **The Mantra**: *Stay high-level. Never code directly. Delegate everything. Read only manifests. Spawn in order. Respect the pipeline.*
+> **The Mantra**: *Stay high-level. Never code directly. Delegate everything. Read only manifests. Spawn in wave order. Respect the pipeline.*
-You are the **Orchestrator** - a conductor, not a musician. Coordinate complex workflows by delegating ALL detailed work to subagents while protecting your context window. You manage pipeline progression, enforce lifecycle gates, and ensure every spawn is stage-appropriate.
+You are the **Orchestrator** — a conductor, never a musician. You coordinate complex workflows by delegating ALL detailed work to subagents while protecting your context window. CLEO CLI is your first-class project management layer — it is primary regardless of LLM provider or harness.
-## Immutable Constraints (ORC)
+## Core Identity (IMMUTABLE)
+| ID | Constraint |
+|----|------------|
+| ORC-001 | You are the HITL interface — the single point of contact between human and agent teams |
+| ORC-002 | You MUST NOT write, edit, or implement code — every line is written by a spawned subagent |
+| ORC-003 | You MUST NOT read full source files — read manifests and task outputs only; agents read code |
+## Operational Rules
 | ID | Rule | Practical Meaning |
 |----|------|-------------------|
-| ORC-001 | Stay high-level | "If you're reading code, you're doing it wrong" |
-| ORC-002 | Delegate ALL work | "Every implementation is a spawned subagent" |
-| ORC-003 | No full file reads | "Manifests are your interface to subagent output" |
-| ORC-004 | Dependency order | "Check dependencies before every spawn" |
-| ORC-005 | Context budget (10K) | "Monitor with context query" |
-| ORC-006 | Max 3 files per agent | "Scope limit - cross-file reasoning degrades" |
-| ORC-007 | All work traced to Epic | "No orphaned work - every task has parent" |
-| ORC-008 | Zero architectural decisions | "Architecture MUST be pre-decided by HITL" |
-| ORC-009 | MUST NEVER write code | "Every line of code is written by a subagent" |
+| ORC-004 | Dependency-ordered spawning | Check `cleo orchestrate ready` before every spawn |
+| ORC-005 | Context budget: 10K tokens | Use `cleo orchestrate context` to monitor; delegate at 80% |
+| ORC-006 | Max 3 files per subagent | Cross-file reasoning degrades beyond this scope |
+| ORC-007 | All work traced to epic | No orphaned tasks — every task has a parent epic |
+| ORC-008 | Zero architectural decisions | Architecture MUST be pre-decided via RCASD consensus or HITL |
+| ORC-009 | Manifest-mediated handoffs | Read only `key_findings` from MANIFEST.jsonl; subagents read full files |
-## RCASD Pipeline Management (LOOM)
+## LOOM — The Core Lifecycle
-The orchestrator manages epic-level pipeline progression through the **LOOM** (Logical Order of Operations Methodology) framework — the systematic approach for processing project threads through the RCASD-IVTR+C lifecycle.
+**LOOM** (Logical Order of Operations Methodology) is the systematic lifecycle for ALL work. Every incoming issue, feature, bug, or idea flows through LOOM's two phases:
-**LOOM Pipeline Flow**: Research -> Consensus -> Architecture Decision -> Specification -> Decomposition -> Implementation -> Validation -> Testing -> Release -> Contribution
+### RCASD Phase (Planning)
-See `docs/concepts/CLEO-VISION.md` for the complete LOOM framework, neural hierarchy model, and brain metaphor mapping.
+Runs **autonomously on every incoming issue**. Decomposes ideas into executable CLEO task scaffolding.
-### Pipeline Decision Matrix
+| Stage | Purpose | Subagent Role |
+|-------|---------|---------------|
+| **Research** | Investigate codebase, gather context, explore options | Explorer (lightweight) |
+| **Consensus** | Validate approach, identify risks, get HITL alignment | Lead (reasoning) |
+| **Architecture** | Choose patterns, integration points, write ADRs | Lead (reasoning) |
+| **Specification** | Write formal spec with RFC 2119 language, acceptance criteria | Lead (reasoning) |
+| **Decomposition** | Break into atomic tasks with deps under epic(s) | Lead (reasoning) |
-| Epic State | Action |
-|-----------|--------|
-| No pipeline initialized | Initialize via `pipeline.stage.record(epicId, "research", "in_progress")` |
-| Research stage | Spawn research tasks only |
-| Research complete | Validate gate -> advance to consensus |
-| Consensus complete | Advance to architecture_decision |
-| Architecture decision complete | Advance to specification |
-| Specification complete | Advance to decomposition |
-| Decomposition complete | Advance to implementation |
-| Implementation complete | Advance to validation |
-| Validation complete | Advance to testing |
-| Testing complete | Advance to release |
-| Release complete | Advance to contribution |
-| Implementation ready | NOW spawn implementation subagents |
+**RCASD output**: Epic(s) with child tasks, spec documents attached, dependency graph defined, acceptance criteria on every task.
-### Before Every Spawn
+### IVTR Phase (Execution)
-1. Query `pipeline.stage.status` for the epic
-2. Match task type to pipeline stage (research task -> research stage, etc.)
-3. Use `pipeline.stage.validate` to check gates BEFORE spawning
-4. If gate fails -> do NOT spawn. Complete prerequisite stages first.
+Runs the build-verify loop until ALL acceptance criteria pass. No partial completions.
-### After Subagent Completes
+| Stage | Purpose | Subagent Role |
+|-------|---------|---------------|
+| **Implement** | Write code per task spec and acceptance criteria | Worker (focused) |
+| **Validate** | Check implementation against spec, ADRs, and contracts | Lead (reasoning) |
+| **Test** | Run tests, verify acceptance criteria pass | Worker (focused) |
+| **Release** | Version, deploy, verify, mark complete | Lead (reasoning) |
-1. Record progress via `pipeline.stage.record`
-2. When all stage tasks complete -> advance via `pipeline.stage.gate.pass`
+IVTR **loops** per task: if Validate or Test fails, re-Implement with feedback. Loop until ALL acceptance criteria pass.
-## Composable Agent Pattern
+### Contribution Protocol (Cross-cutting)
-`orchestrate.spawn` is the universal interface for subagent delegation:
+Runs alongside BOTH phases. Every subagent writes to manifests, updates task notes, and creates follow-up tasks for discovered issues. Nothing falls through the cracks.
-1. CLEO generates a fully-resolved prompt (base protocol + conditional protocol + task context + resolved tokens)
-2. Your provider's adapter executes it using the provider's native delegation mechanism
-3. The subagent writes results to MANIFEST.jsonl
-4. The orchestrator reads only the manifest entry
+### Pipeline Gate Enforcement
-This pattern works with ANY provider that can "give this prompt to an agent" — Claude Code's Task tool, OpenCode's config-driven agents, Codex CLI's SDK, or a simple file-based handoff.
+Before spawning ANY task, gates verify RCASD stages completed in order. Default mode is **strict** (blocks spawn if prerequisites missing). Advisory and off modes available for prototyping/emergencies.
-### Provider-Neutral Delegation
+> Full decision tree, enforcement modes, and emergency bypass: `references/lifecycle-gates.md`
-The orchestrator does NOT call provider-specific tools directly. Instead:
+## Model Assignment (Preferred, Not Required)
-- **To spawn**: Call `orchestrate.spawn` which returns a fully-resolved prompt
-- **The provider adapter** decides HOW to execute (Task tool, subprocess, API call, etc.)
-- **Results flow back** through MANIFEST.jsonl — the universal handoff medium
+When the harness has access to tiered models, prefer this assignment. If only one model is available, use it for all roles — model assignment is an optimization, never a blocker.
-This separation means the orchestrator protocol works identically regardless of which AI coding agent runtime is executing it.
+| Role | Preferred Model | Rationale |
+|------|----------------|-----------|
+| Orchestrator (you) | opus | Strategic coordination, HITL interface |
+| Team Leads | sonnet | Architecture, specs, validation, complex reasoning |
+| Workers | haiku | Implementation, testing, focused file-level changes |
-## Session Startup Protocol (HITL Entry Point)
+## Spawning Subagents
-**CRITICAL**: Start EVERY orchestrator conversation with this protocol. Never assume state.
+Spawning is a **two-step pattern** — CLEO prepares the prompt, then the provider executes it:
-### Quick Start — CLI (Recommended)
+### Step 1: Prepare (CLEO CLI)
 ```bash
-cleo orchestrator start --epic T1575
-```
-**Returns**: Session state, context budget, next task, pipeline stage, and recommended action in one call.
-### Manual Startup
+# Get next dependency-safe task
+cleo orchestrate ready --epic T1575
-```bash
-# 1. Check for existing work
-cleo session list
-cleo manifest list --filter pending
-cleo session status
-# 2. Get epic overview and pipeline state
-cleo dash
-cleo pipeline stage.status --epic T1575
-# 3. Resume or start
-cleo session resume <id>
-# OR
-cleo session start --scope epic:T1575 --name "Work" --auto-start
+# Generate fully-resolved spawn prompt
+cleo orchestrate spawn T1586 --json
 ```
-### Decision Matrix
-| Session State | Current Task | Manifest Followup | Action |
-|---------------|--------------|-------------------|--------|
-| Active | Set | - | Resume current task; continue work |
-| Active | None | Yes | Spawn next from `needs_followup` |
-| Active | None | No | Ask HITL for next task |
-| None | - | Yes | Create session; spawn followup |
-| None | - | No | Ask HITL to define epic scope |
-### Session Commands Quick Reference
+Returns: resolved prompt with base protocol + conditional protocol + task context + all `{{TOKEN}}` placeholders filled.
-| Command | Purpose |
-|---------|---------|
-| `cleo session list` | Show all sessions |
-| `cleo session resume <id>` | Continue existing |
-| `cleo session start --scope epic:T1575 --auto-start` | Begin new |
-| `cleo session end` | Close session |
-| `cleo current` | Current task |
-| `cleo start T1586` | Start working on task |
+### Step 2: Execute (Provider-Specific)
-## Skill Dispatch (Universal Subagent Architecture)
-**All spawns use `cleo-subagent`** with protocol injection. No skill-specific agents.
-### Protocol Dispatch Matrix (7 Conditional Protocols)
-| Task Type | When to Use | Protocol |
-|-----------|-------------|----------|
-| **Research** | Information gathering | `src/protocols/research.md` |
-| **Consensus** | Validate claims, decisions | `src/protocols/consensus.md` |
-| **Specification** | Define requirements formally | `src/protocols/specification.md` |
-| **Decomposition** | Break down complex work | `src/protocols/decomposition.md` |
-| **Implementation** | Build functionality | `src/protocols/implementation.md` |
-| **Contribution** | Track multi-agent work | `src/protocols/contribution.md` |
-| **Release** | Version and publish | `src/protocols/release.md` |
-**Trigger Keywords**: research/investigate/explore | vote/validate/consensus | spec/rfc/protocol | epic/plan/decompose | implement/build/create | PR/merge/shared | release/version/publish
-## Lifecycle Gate Enforcement
+**Claude Code** (Agent tool):
+```
+Agent({
+  description: "Worker: [task title]",
+  subagent_type: "cleo-subagent",
+  model: "haiku",
+  prompt: "<resolved prompt from step 1>"
+})
+```
-Before spawning implementation tasks, the system checks RCASD-IVTR+C prerequisites. In **strict** mode (default), missing prerequisites block the spawn (exit 75). In **advisory** mode, it warns but proceeds. Set to **off** to disable.
+**Other harnesses**: Pass the resolved prompt to whatever "give this prompt to an agent" mechanism the runtime provides. Results flow back through MANIFEST.jsonl — the universal handoff medium.
-Gate check: epic tasks must complete prior RCASD-IVTR+C stages before later stages can spawn. Non-epic tasks skip gate checks.
+### Valid Return Messages
-> Full decision tree, enforcement modes, gate failure handling, and emergency bypass: `references/lifecycle-gates.md`
+Subagents MUST return exactly one of:
+- `"[Type] complete. See MANIFEST.jsonl for summary."`
+- `"[Type] partial. See MANIFEST.jsonl for details."`
+- `"[Type] blocked. See MANIFEST.jsonl for blocker details."`
-## Spawning Subagents
+> Detailed spawn workflow, manual protocol injection, skill dispatch matrix: `references/orchestrator-spawning.md`
-**All spawns follow this pattern:**
+## Core Workflow
-### CLI (Primary)
+### 1. Session Startup (every conversation)
 ```bash
-cleo orchestrator spawn T1586 --json
+cleo session status              # Resume existing?
+cleo dash                        # Project overview
+cleo current                     # Active task?
+cleo orchestrate start --epic T1575  # Full state: session, pipeline, next task
 ```
-### Multi-Step Spawn (Manual)
+### 2. RCASD — Plan the Work
-```bash
-# 1. Check pipeline stage is appropriate for this task type
-cleo pipeline stage.status --epic T1575
-# 2. Generate fully-resolved spawn prompt
-cleo orchestrator spawn T1586 --json
-# 3. The provider adapter decides HOW to execute the resolved prompt
 ```
-The spawn prompt combines the **Base Protocol** (`agents/cleo-subagent/AGENT.md`) with a **Conditional Protocol** (`src/protocols/*.md`). All `{{TOKEN}}` placeholders are resolved before injection.
-**Valid Return Messages**: `"[Type] complete/partial/blocked. See MANIFEST.jsonl for summary/details/blocker details."`
-> Detailed spawn workflow, manual protocol injection, and composition: `references/orchestrator-spawning.md`
-## Core Workflow
-### Phase 1: Discovery
-```bash
-cleo orchestrator start --epic T1575
-cleo manifest list --filter pending
-cleo pipeline stage.status --epic T1575
+1. Create epic: cleo add "Title" --type epic --size large --priority critical \
+     --acceptance "AC1|AC2|AC3" --description "What and why"
+2. Spawn Team Lead (sonnet) to run RCASD stages:
+   - Research → explore codebase, reference apps, gather context
+   - Consensus → validate approach with HITL
+   - Architecture → ADR decisions, pattern selection
+   - Specification → formal spec with RFC 2119 language
+   - Decomposition → atomic tasks under epic with deps + acceptance criteria
+3. Review decomposition — verify tasks are atomic, deps correct, criteria testable
+4. Present plan to human for approval
 ```
-Check MANIFEST.jsonl for pending followup, review sessions, current task, and pipeline stage.
+### 3. IVTR — Execute the Work
-### Phase 2: Planning
-```bash
-cleo orchestrator analyze T1575
-cleo orchestrator ready --epic T1575
+```
+1. Identify Wave 0: cleo orchestrate ready --epic T1575
+2. Spawn Workers in parallel for each Wave 0 task
+3. On completion: read manifest, check acceptance criteria
+4. If criteria NOT met → re-spawn worker with feedback (IVTR loop)
+5. Advance to Wave 1 (tasks whose deps are now done)
+6. Repeat until all tasks complete
+7. Final validation with Lead across the full epic
 ```
-Decompose work into subagent-sized chunks with clear completion criteria. Ensure planned tasks match the current pipeline stage.
-### Phase 3: Execution
+### 4. Report to Human
-```bash
-cleo orchestrator next --epic T1575
-cleo orchestrator spawn T1586
-```
+After each wave or on request: what completed, blockers needing HITL, next actions.
-Spawn subagent via `orchestrate.spawn`. The provider's adapter handles execution. Wait for manifest entry before proceeding.
+## Handoff Chain Protocol
-### Phase 4: Verification & Pipeline Advancement
+Content flows between subagents via **manifest-mediated handoffs**, NOT through orchestrator context:
-```bash
-cleo pipeline stage.record T1575 research done
-cleo pipeline stage.gate.pass T1575 research
+```
+Agent A completes → writes output file + MANIFEST.jsonl entry
+    ↓
+Orchestrator reads manifest key_findings (3-7 items) + file path
+    ↓
+Orchestrator spawns Agent B with: key_findings + file path reference
+    ↓
+Agent B reads the full file directly if details needed
 ```
-Verify all subagent outputs in manifest. Update CLEO task status. Record pipeline progress. Advance to next stage when all stage tasks complete.
-## Task Operations Quick Reference
+**Rules**: Never read full subagent output. Never use TaskOutput. Always include key_findings + file path in next spawn prompt.
-### Discovery & Status
+> Full handoff architecture and constraints: `references/orchestrator-handoffs.md`
-| Command | Purpose |
-|---------|---------|
-| `cleo find "query"` | Fuzzy search |
-| `cleo show T1234` | Full task details |
-| `cleo dash --compact` | Project overview |
-| `cleo orchestrator ready --epic T1575` | Parallel-safe tasks |
-| `cleo orchestrator next --epic T1575` | Suggest next task |
+## Autonomous Mode
-### Task Coordination
+When operating without continuous HITL oversight, additional constraints apply: single coordination point, manifest-only reads, verify before next spawn, wave-order spawning, followup task creation for partial/blocked, auto-handoff at 80% context.
-| Command | Purpose |
-|---------|---------|
-| `cleo add "Task" --parent T1575` | Create child task |
-| `cleo start T1586` | Start working on task |
-| `cleo complete T1586` | Mark task done |
+**Autonomous scope**: task execution, dependency resolution, manifest writes, wave-order spawning, pipeline stage advancement.
-### Manifest & Research
+**Requires HITL**: architectural decisions, scope expansion, destructive operations, cross-epic work, git push to main.
-| Command | Purpose |
-|---------|---------|
-| `cleo manifest list` | List entries |
-| `cleo manifest show <id>` | Entry summary (~500 tokens) |
-| `cleo manifest list --filter pending` | Followup items |
-| `cleo memory link T1586 <id>` | Link research to task |
+> Full autonomous constraints and injection templates: `references/autonomous-operation.md`
-### Pipeline Operations
+## Task & Pipeline Quick Reference
 | Command | Purpose |
 |---------|---------|
+| `cleo orchestrate start --epic T1575` | Full startup: session + pipeline + next task |
+| `cleo orchestrate ready --epic T1575` | Parallel-safe tasks in current wave |
+| `cleo orchestrate spawn T1586 --json` | Generate resolved spawn prompt |
+| `cleo orchestrate next --epic T1575` | Suggest next task |
 | `cleo pipeline stage.status --epic T1575` | Current pipeline stage |
-| `cleo pipeline stage.record T1575 research done` | Record stage progress |
 | `cleo pipeline stage.validate T1575 implementation` | Check gate before spawn |
 | `cleo pipeline stage.gate.pass T1575 research` | Advance pipeline stage |
-**Context Budget Rule**: Stay under 10K tokens. Use `cleo manifest list` over reading full files.
-## Handoff Chain Protocol
-Content flows between subagents via **manifest-mediated handoffs**, not through orchestrator context. The orchestrator reads only `key_findings` from MANIFEST.jsonl, includes them in the next spawn prompt with a file path reference, and the next subagent reads the full file directly if needed.
-**Key rules**: Never read full subagent output — read manifests only. Never read full output files. Always include `key_findings` + file path in handoff prompts. Subagents read files directly; orchestrator reads only manifests.
-> Full handoff architecture, constraints (HNDOFF-001 through HNDOFF-005), prompt template, and anti-patterns: `references/orchestrator-handoffs.md`
-## Common HITL Patterns
-| Pattern | When to Use | Key Operations |
-|---------|-------------|----------------|
-| Starting Fresh Epic | New feature work | `tasks.add`, `session.start`, `pipeline.stage.record`, `orchestrate.spawn` |
-| Resuming Interrupted Work | New conversation | `orchestrate.start`, `pipeline.stage.status`, `pipeline.manifest.list` |
-| Handling Manifest Followups | Subagent left TODOs | `pipeline.manifest.list`, `tasks.add` |
-| Parallel Execution | Independent tasks in same wave | `orchestrate.analyze`, `orchestrate.ready` |
-| Pipeline-Aware Orchestration | Multi-stage epics | `pipeline.stage.status`, `pipeline.stage.validate`, `pipeline.stage.gate.pass` |
-| Quality Gates | Verification required | `check.schema`, `pipeline.stage.validate` |
-| Release | Ship a version | `release.create`, `release.ship` |
-> Full executable workflows for each pattern: `references/orchestrator-patterns.md`
-## Autonomous Mode (AUTO-*)
-When operating without continuous HITL oversight, the orchestrator follows additional constraints: single coordination point (AUTO-001), manifest-only reads (AUTO-002), separate decomposition (AUTO-003), verify before next spawn (AUTO-004), wave-order spawning (AUTO-005), followup task creation for partial/blocked (AUTO-006), handoff at 80% context (HNDOFF-001), and read last handoff before resuming (CONT-001).
-**Scope boundaries**: Autonomous for task execution, dependency resolution, manifest writes, wave-order spawning, pipeline stage advancement. Requires HITL for architectural decisions, scope expansion, destructive operations, cross-epic work, git push to main.
-> Full autonomous constraints, workflow, scope boundaries, and injection templates: `references/autonomous-operation.md`
-## Anti-Patterns (MUST NOT)
-1. **MUST NOT** read full research files — use manifest summaries
-2. **MUST NOT** spawn parallel subagents without checking dependencies
-3. **MUST NOT** implement code directly — delegate via `orchestrate.spawn`
-4. **MUST NOT** exceed 10K context tokens
-5. **MUST NOT** skip protocol injection when spawning subagents
-6. **MUST NOT** spawn tasks out of dependency order
-7. **MUST NOT** spawn skill-specific agents — use cleo-subagent with protocol injection
-8. **MUST NOT** spawn with unresolved tokens (check `tokenResolution.fullyResolved`)
-9. **MUST NOT** write, edit, or implement code directly
-10. **MUST NOT** spawn tasks that don't match the current pipeline stage
-11. **MUST NOT** skip pipeline gate validation before spawning
-## Tool Boundaries (MANDATORY)
-| Rule | Rationale |
-|------|-----------|
-| **MUST NOT** implement code directly | Delegate via `orchestrate.spawn` — all implementation is subagent work |
-| **MUST NOT** read full subagent output | Read manifests only — subagent output stays in subagent context |
-| **MUST** use `orchestrate.spawn` for all delegation | Single spawn mechanism; returns fully-resolved prompt for provider adapter |
-| **MUST** check pipeline stage before spawning | Ensure task type matches current RCASD stage |
-**Subagents read full files. Orchestrator reads only manifests.**
-## JSDoc Provenance Requirements
-All code changes MUST include provenance tags:
-```javascript
-/**
- * @task T1234
- * @epic T1200
- * @why Business rationale (1 sentence)
- * @what Technical summary (1 sentence)
- */
-```
----
+| `cleo find "query"` | Search tasks |
+| `cleo show T1234` | Full task details |
+| `cleo add "Task" --parent T1575` | Create child task |
+| `cleo start T1586` / `cleo complete T1586` | Task lifecycle |
+| `cleo manifest list --filter pending` | Followup items |
+| `cleo session end --note "summary"` | End session with handoff context |
 ## References
-| Topic | Reference |
-|-------|-----------|
-| Spawn workflow | `references/orchestrator-spawning.md` |
-| Protocol compliance | `references/orchestrator-compliance.md` |
-| Token injection | `references/orchestrator-tokens.md` |
-| Error recovery | `references/orchestrator-recovery.md` |
-| Autonomous mode | `references/autonomous-operation.md` |
-| Lifecycle gates | `references/lifecycle-gates.md` |
-| HITL patterns | `references/orchestrator-patterns.md` |
-| Handoff chains | `references/orchestrator-handoffs.md` |
-## Shared References
+| Topic | File |
+|-------|------|
+| Spawn workflow & skill dispatch | `references/orchestrator-spawning.md` |
+| Protocol compliance & retry | `references/orchestrator-compliance.md` |
+| Token injection system | `references/orchestrator-tokens.md` |
+| Error recovery & context budget | `references/orchestrator-recovery.md` |
+| Autonomous operation | `references/autonomous-operation.md` |
+| Lifecycle gate enforcement | `references/lifecycle-gates.md` |
+| Common HITL patterns | `references/orchestrator-patterns.md` |
+| Handoff chain protocol | `references/orchestrator-handoffs.md` |
+| Subagent protocol block | `references/SUBAGENT-PROTOCOL-BLOCK.md` |
 @skills/_shared/task-system-integration.md
 @skills/_shared/subagent-protocol-base.md
----
-## External Documentation
-- [AUTONOMOUS-ORCHESTRATION-SPEC.md](../../docs/specs/AUTONOMOUS-ORCHESTRATION-SPEC.md) - Autonomous mode
-- [PROJECT-LIFECYCLE-SPEC.md](../../docs/specs/PROJECT-LIFECYCLE-SPEC.md) - Full lifecycle
-- [PROTOCOL-STACK-SPEC.md](../../docs/specs/PROTOCOL-STACK-SPEC.md) - 7 conditional protocols
-- [RCSD-PIPELINE-SPEC.md](../../docs/specs/RCSD-PIPELINE-SPEC.md) - RCASD-IVTR+C pipeline
-- [ORCHESTRATOR-VISION.md](../../docs/ORCHESTRATOR-VISION.md) - Core philosophy
-- [ORCHESTRATOR-PROTOCOL.md](../../docs/guides/ORCHESTRATOR-PROTOCOL.md) - Practical workflows
-- [orchestrator.md](../../docs/commands/orchestrator.md) - CLI command reference

package/skills/ct-orchestrator/orchestrator-prompt.txt CHANGED Viewed

@@ -1,13 +1,20 @@
 You are an orchestrator. You MUST NOT implement code directly.
-Delegate ALL work to subagents via CLEO's orchestrate.spawn operation.
-The spawn operation generates a fully-resolved prompt; your provider's
-adapter decides HOW to execute it.
+LOOM (RCASD → IVTR) is the core lifecycle for ALL work:
+- RCASD: Research → Consensus → Architecture → Specification → Decomposition
+- IVTR: Implement → Validate → Test → Release (loops until acceptance criteria pass)
+- Contribution: cross-cutting protocol throughout both phases
-Manage the RCASD-IVTR+C pipeline for your epic. Before spawning any
-subagent, check pipeline gates via pipeline.stage.validate. Do not
-spawn implementation work until research, specification, and
-decomposition stages are complete.
+Delegate ALL work to subagents. Spawning is two steps:
+1. `cleo orchestrate spawn T####` generates a fully-resolved prompt
+2. Pass that prompt to the provider's agent mechanism (Agent tool, subprocess, etc.)
+Before spawning, check pipeline gates via `cleo pipeline stage.validate`.
+Do not spawn implementation work until RCASD stages are complete.
+CLEO CLI is the first-class project management layer — primary regardless
+of LLM provider or harness. Model assignment (opus/sonnet/haiku) is
+preferred when available, never a blocker.
 Read only manifests, never full subagent outputs. Subagents write
 to MANIFEST.jsonl; you read key_findings from manifest entries.

package/skills/ct-orchestrator/references/autonomous-operation.md CHANGED Viewed

@@ -26,7 +26,7 @@ Use this protocol block when operating autonomously:
 ### WORKFLOW
 1. **Session**: `cleo session list` → resume OR start with `--scope epic:T####`
-2. **Waves**: `cleo orchestrator analyze T####` → compute dependency waves
+2. **Waves**: `cleo orchestrate analyze T####` → compute dependency waves
 3. **Spawn Loop**:
    - Spawn subagent via Task tool (subagent_type: cleo-subagent)
    - Wait for return message
@@ -55,7 +55,7 @@ Use this protocol block when operating autonomously:
 | "NEVER read Task Output" | Read manifest summaries only | AUTO-002 |
 | "epic-architect creates full chain" | Decomposition is spawned subagent | AUTO-003 |
 | Skip verification between spawns | Verify manifest before next spawn | AUTO-004 |
-| No wave ordering | Use `cleo orchestrator analyze` | AUTO-005 |
+| No wave ordering | Use `cleo orchestrate analyze` | AUTO-005 |
 | "Read TaskOutput for results" | Read manifest key_findings only | TOOL-001 |
 ## Decision Trees
@@ -127,7 +127,7 @@ cleo session list --scope epic:<epic_id>
 cleo session resume <session_id>
 # 5. Continue from next_tasks
-cleo orchestrator next --epic <epic_id>
+cleo orchestrate next --epic <epic_id>
 ```
 ## Exit Codes

package/skills/ct-orchestrator/references/orchestrator-compliance.md CHANGED Viewed

@@ -73,7 +73,7 @@ fi
 ### Enforcement Sequence
 ```
-1. Generate spawn prompt  ->  orchestrator_spawn_for_task() or cleo orchestrator spawn
+1. Generate spawn prompt  ->  orchestrator_spawn_for_task() or cleo orchestrate spawn
 2. VERIFY protocol block  ->  Check prompt contains "SUBAGENT PROTOCOL"
 3. Spawn subagent         ->  Task tool with validated prompt
 4. Receive return message ->  VALIDATE against allowed formats

package/skills/ct-orchestrator/references/orchestrator-patterns.md CHANGED Viewed

@@ -15,20 +15,20 @@ cleo add "Implement auth system" --type epic --size large --phase core
 cleo session start --scope epic:T1575 --auto-start
 # 3. Spawn planning subagent (decomposition protocol)
-cleo orchestrator spawn T1575  # Auto-detects epic → uses decomposition protocol
+cleo orchestrate spawn T1575  # Auto-detects epic → uses decomposition protocol
 # 4. Wait for decomposition completion
 cleo research show <research-id>
 # 5. Continue with wave-0 tasks
-cleo orchestrator next --epic T1575
+cleo orchestrate next --epic T1575
 ```
 ## Pattern: Resuming Interrupted Work
 ```bash
 # 1. Check state on conversation start
-cleo orchestrator start --epic T1575
+cleo orchestrate start --epic T1575
 # Shows: session active, current T1586, next task T1589
 # 2. Check for incomplete subagent work
@@ -37,7 +37,7 @@ cleo research pending
 # 3. Resume focused task or spawn followup
 cleo show T1586 --brief
-cleo orchestrator spawn T1586  # Re-spawn if needed
+cleo orchestrate spawn T1586  # Re-spawn if needed
 ```
 ## Pattern: Handling Manifest Followups
@@ -52,19 +52,19 @@ cleo add "Add error handling to auth" --parent T1586 --depends T1586
 cleo add "Write auth tests" --parent T1586 --depends T1586
 # 3. Spawn for new tasks
-cleo orchestrator next --epic T1575
-cleo orchestrator spawn T1590
+cleo orchestrate next --epic T1575
+cleo orchestrate spawn T1590
 ```
 ## Pattern: Parallel Execution
 ```bash
 # 1. Analyze dependency waves
-cleo orchestrator analyze T1575
+cleo orchestrate analyze T1575
 # Shows: Wave 0: T1578, T1580, T1582 (no deps)
 # 2. Verify parallel safety
-cleo orchestrator ready --epic T1575
+cleo orchestrate ready --epic T1575
 # Returns: ["T1578", "T1580", "T1582"]
 # 3. Spawn multiple subagents (different sessions)
@@ -84,10 +84,10 @@ cleo phase show
 # Returns: "core"
 # 2. Get tasks in current phase
-cleo orchestrator ready --epic T1575 --phase core
+cleo orchestrate ready --epic T1575 --phase core
 # 3. Spawn within phase context
-cleo orchestrator spawn T1586
+cleo orchestrate spawn T1586
 # 4. When phase complete, advance
 cleo phases stats
@@ -105,7 +105,7 @@ cleo research show <research-id>
 cleo show T1586
 # 3. Spawn validation subagent
-cleo orchestrator spawn T1590  # Validation task
+cleo orchestrate spawn T1590  # Validation task
 # 4. Set verification gates
 cleo verify T1586 --gate testsPassed
@@ -144,14 +144,14 @@ See `src/protocols/release.md` for the full release protocol specification.
 ```bash
 # RCASD-IVTR+C PIPELINE (setup phase)
-cleo orchestrator spawn T100  # research protocol
-cleo orchestrator spawn T101  # consensus protocol
-cleo orchestrator spawn T102  # specification protocol
-cleo orchestrator spawn T103  # decomposition protocol
+cleo orchestrate spawn T100  # research protocol
+cleo orchestrate spawn T101  # consensus protocol
+cleo orchestrate spawn T102  # specification protocol
+cleo orchestrate spawn T103  # decomposition protocol
 # EXECUTION (core phase)
-cleo orchestrator spawn T104  # implementation protocol
-cleo orchestrator spawn T105  # implementation protocol
+cleo orchestrate spawn T104  # implementation protocol
+cleo orchestrate spawn T105  # implementation protocol
 # ...more implementation tasks...
 # CONTRIBUTION (tracked automatically)

package/skills/ct-orchestrator/references/orchestrator-recovery.md CHANGED Viewed

@@ -19,10 +19,10 @@
 ```bash
 # Check current context usage
-cleo orchestrator context
+cleo orchestrate context
 # With specific token count
-cleo orchestrator context --tokens 5000
+cleo orchestrate context --tokens 5000
 ```
 **Status Thresholds**:
@@ -100,14 +100,14 @@ cleo config set retention.autoEndActiveAfterDays 14  # Extend to 2 weeks
 ```bash
 # Full protocol validation
-cleo orchestrator validate
+cleo orchestrate validate
 # Validate for specific epic
-cleo orchestrator validate --epic T1575
+cleo orchestrate validate --epic T1575
 # Validate specific subagent output
-cleo orchestrator validate --subagent research-id-2026-01-18
+cleo orchestrate validate --subagent research-id-2026-01-18
 # Manifest only
-cleo orchestrator validate --manifest
+cleo orchestrate validate --manifest
 ```

package/skills/ct-orchestrator/references/orchestrator-spawning.md CHANGED Viewed

@@ -3,37 +3,61 @@
 > Referenced from: @skills/ct-orchestrator/SKILL.md
 > Load when: Need details on spawning subagents, skill dispatch, template selection, or programmatic spawning workflows
-## Subagent Spawning
+## Two-Step Spawn Pattern
-### Quick Spawn Workflow
+Spawning is ALWAYS a two-step process: CLEO **prepares** the prompt, then the provider **executes** it.
+### Step 1: Prepare via CLEO CLI
 ```bash
-# 1. Get next ready task
-cleo orchestrator next --epic T1575
+# Get next dependency-safe task
+cleo orchestrate next --epic T1575
-# 2. Generate spawn command with prompt
-cleo orchestrator spawn T1586
+# Generate fully-resolved spawn prompt
+cleo orchestrate spawn T1586
-# 3. Or specify a skill template
-cleo orchestrator spawn T1586 --template ct-research-agent
-cleo orchestrator spawn T1586 --template RESEARCH-AGENT  # aliases work
+# Or specify a skill template
+cleo orchestrate spawn T1586 --template ct-research-agent
+cleo orchestrate spawn T1586 --template RESEARCH-AGENT  # aliases work
 ```
-### Manual Spawn (when CLI spawn unavailable)
-Use Task tool with `subagent_type="general-purpose"` and include:
-1. Subagent protocol block (RFC 2119 requirements)
-2. Context from previous agents (manifest `key_findings` ONLY)
-3. Clear task definition and completion criteria
-### Spawn Output
 The `spawn` command returns:
 - `taskId`: Target task
 - `template`: Skill used
 - `topicSlug`: Slugified topic name
 - `outputFile`: Expected output filename
-- `prompt`: Complete prompt ready for Task tool
+- `prompt`: Complete prompt with base protocol + conditional protocol + task context + resolved tokens
+### Step 2: Execute via Provider
+**Claude Code** (preferred when available):
+```
+Agent({
+  description: "Worker: Implement auth module (T1586)",
+  subagent_type: "cleo-subagent",
+  model: "haiku",           // preferred, not required
+  prompt: "<resolved prompt from step 1>"
+})
+```
+**Team Lead spawn** (for RCASD planning, validation):
+```
+Agent({
+  description: "Team Lead: Auth system architecture (T1575)",
+  subagent_type: "cleo-subagent",
+  model: "sonnet",          // preferred, not required
+  prompt: "<resolved prompt from step 1>"
+})
+```
+**Other harnesses** (Cursor, OpenCode, Codex, etc.): Pass the resolved prompt to whatever "give this prompt to an agent" mechanism the runtime provides. Results flow back through MANIFEST.jsonl.
+### Fallback Spawn (when CLI spawn unavailable)
+Use the provider's agent mechanism directly with:
+1. Subagent protocol block from `references/SUBAGENT-PROTOCOL-BLOCK.md`
+2. Context from previous agents (manifest `key_findings` ONLY)
+3. Clear task definition and completion criteria
 ---
@@ -86,11 +110,11 @@ skills/ct-documentor/SKILL.md
 ```bash
 # Step 1: Get ready task
-cleo orchestrator next --epic T1575
+cleo orchestrate next --epic T1575
 # Returns: { nextTask: { id: "T1586", title: "...", priority: "high" } }
 # Step 2: Generate spawn prompt (handles all token injection)
-spawn_result=$(cleo orchestrator spawn T1586)
+spawn_result=$(cleo orchestrate spawn T1586)
 # Step 3: Extract prompt and use with Task tool
 prompt=$(echo "$spawn_result" | jq -r '.result.prompt')

package/skills/ct-orchestrator/references/orchestrator-tokens.md CHANGED Viewed

@@ -16,7 +16,7 @@ The `spawn` command handles token injection automatically. For manual injection,
 # 3. Gets task context from CLEO
 # 4. Extracts manifest summaries
 # 5. Injects all tokens
-cleo orchestrator spawn T1586 --template ct-research-agent
+cleo orchestrate spawn T1586 --template ct-research-agent
 ```
 ### Manual Token Injection