@cleocode/adapters 2026.4.24 → 2026.4.25

package/dist/providers/claude-code/install.d.ts

@@ -15,7 +15,8 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  *
  * Manages CLEO's integration with Claude Code by:
  * 1. Ensuring CLAUDE.md contains @-references to CLEO instruction files
- * 2. Registering the brain observation plugin in ~/.claude/settings.json
+ * 2. Installing adapter-provided commands to .claude/commands/
+ * 3. Registering the brain observation plugin in ~/.claude/settings.json
  *
  * @remarks
  * Installation is idempotent -- running install multiple times on the same
@@ -57,6 +58,16 @@ export declare class ClaudeCodeInstallProvider implements AdapterInstallProvider
      * @returns true if the file was created or modified
      */
     private updateInstructionFile;
+    /**
+     * Install Claude Code-specific commands to .claude/commands/ in the project.
+     *
+     * These commands extend CLEO's provider-neutral skills with Claude Code-specific
+     * operational patterns (Agent tool spawn templates, model assignment, context guardrails).
+     *
+     * @param projectDir - Project root directory
+     * @returns Array of installed command filenames
+     */
+    private installCommands;
     /**
      * Register the CLEO brain plugin in ~/.claude/settings.json.
      *

package/dist/providers/claude-code/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKjG;;;;;;;;;;;;GAYG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA0B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAiCvB"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAYjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAiCvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.4.24",
+  "version": "2026.4.25",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@cleocode/contracts": "2026.4.24",
-    "@cleocode/caamp": "2026.4.24"
+    "@cleocode/caamp": "2026.4.25",
+    "@cleocode/contracts": "2026.4.25"
   },
   "license": "MIT",
   "engines": {

package/src/providers/claude-code/commands/orchestrator.md

@@ -0,0 +1,132 @@
+# Orchestrator Mode (Claude Code)
+
+Load the `/ct-orchestrator` skill. You are now the Orchestrator.
+
+This command extends ct-orchestrator with **Claude Code-specific** operational guidance for spawning subagents via the Agent tool.
+
+## Session Startup
+
+```bash
+cleo session status              # Resume existing?
+cleo dash                        # Project overview
+cleo current                     # Active task?
+cleo orchestrate start --epic TXXX  # Full state + pipeline + next task
+```
+
+Then ask the human what they want to focus on today. Follow LOOM (RCASD -> IVTR) lifecycle for all work.
+
+## Agent Tool — Spawn Patterns
+
+In Claude Code, subagent execution uses the **Agent tool**. The prompt comes from `cleo orchestrate spawn`.
+
+### Team Lead (RCASD planning, validation, complex reasoning)
+
+```
+Agent({
+  description: "Team Lead: [epic domain] (T####)",
+  subagent_type: "cleo-subagent",
+  model: "sonnet",
+  prompt: "<resolved prompt from cleo orchestrate spawn T####>"
+})
+```
+
+### Worker (focused implementation, testing)
+
+```
+Agent({
+  description: "Worker: [task title] (T####)",
+  subagent_type: "cleo-subagent",
+  model: "haiku",
+  prompt: "<resolved prompt from cleo orchestrate spawn T####>"
+})
+```
+
+### Explorer (quick research, codebase investigation)
+
+```
+Agent({
+  description: "Explorer: [research topic] (T####)",
+  subagent_type: "cleo-subagent",
+  model: "haiku",
+  prompt: "<resolved prompt from cleo orchestrate spawn T####>"
+})
+```
+
+### Parallel Spawn (independent tasks in same wave)
+
+```
+// Spawn multiple agents in a single message for parallel execution
+Agent({
+  description: "Worker: Task A (T1001)",
+  subagent_type: "cleo-subagent",
+  model: "haiku",
+  run_in_background: true,
+  prompt: "<prompt A>"
+})
+Agent({
+  description: "Worker: Task B (T1002)",
+  subagent_type: "cleo-subagent",
+  model: "haiku",
+  run_in_background: true,
+  prompt: "<prompt B>"
+})
+```
+
+## Model Assignment
+
+| Role | Model | Rationale |
+|------|-------|-----------|
+| Orchestrator (you) | opus | Strategic coordination, HITL interface |
+| Team Leads | sonnet | Architecture, specs, validation |
+| Workers | haiku | Implementation, testing, focused changes |
+| Explorers | haiku | Quick research, codebase reads |
+
+Model assignment is an **optimization** — if a model tier is unavailable, use whatever is available. Never block on model selection.
+
+## Two-Step Spawn Flow
+
+```
+1. cleo orchestrate spawn T#### --json    → Get fully-resolved prompt
+2. Agent({ ..., prompt: <resolved> })      → Execute via Agent tool
+3. Wait for return message                 → "[Type] complete/partial/blocked..."
+4. cleo manifest show <id>                 → Read key_findings from manifest
+5. Next spawn or report to human
+```
+
+## Quality Gates
+
+### Before marking ANY task done:
+1. Manifest entry exists with key_findings
+2. Return message matches valid format
+3. Acceptance criteria explicitly verified (not assumed)
+4. No regressions in existing functionality
+
+### On failure (IVTR loop):
+1. Read manifest for failure details
+2. Add feedback to next spawn prompt
+3. Re-spawn worker with: original prompt + failure context + explicit checklist
+4. Max 2 retries — then escalate to HITL
+
+## Guardrails (Claude Code-Specific)
+
+| Rule | Enforcement |
+|------|-------------|
+| NEVER write code yourself | All code via Agent() spawns |
+| NEVER read full source files | Only manifests, task outputs, and spawn results |
+| NEVER use `run_in_background: false` for heavy work | Background workers protect your context |
+| NEVER call TaskOutput on subagent results | Read MANIFEST.jsonl via `cleo manifest show` |
+| ALWAYS use `subagent_type: "cleo-subagent"` | Ensures protocol injection |
+| ALWAYS include task ID in description | Traceability: "Worker: Auth module (T1586)" |
+| ALWAYS check `cleo orchestrate ready` before spawning | Dependency order enforcement |
+
+## Context Protection
+
+Your context window is precious. Protect it:
+
+| Strategy | How |
+|----------|-----|
+| Read manifests, not files | `cleo manifest show <id>` over reading source |
+| Keep task state in CLEO | `cleo show T####` to recall details on demand |
+| Background heavy workers | `run_in_background: true` for implementation tasks |
+| End sessions with notes | `cleo session end --note "handoff summary"` |
+| Delegate investigation | Spawn Explore agents for codebase questions |

package/src/providers/claude-code/install.ts

@@ -10,20 +10,29 @@
  * @task T5240
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 
 /** Lines that should appear in CLAUDE.md to reference CLEO. */
 const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
 
+/** Resolve the commands directory bundled with this adapter. */
+function getAdapterCommandsDir(): string {
+  // Works in both ESM (import.meta.url) and compiled output
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  return join(thisDir, 'commands');
+}
+
 /**
  * Install provider for Claude Code.
  *
  * Manages CLEO's integration with Claude Code by:
  * 1. Ensuring CLAUDE.md contains @-references to CLEO instruction files
- * 2. Registering the brain observation plugin in ~/.claude/settings.json
+ * 2. Installing adapter-provided commands to .claude/commands/
+ * 3. Registering the brain observation plugin in ~/.claude/settings.json
  *
  * @remarks
  * Installation is idempotent -- running install multiple times on the same
@@ -50,7 +59,13 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       details.instructionFile = join(projectDir, 'CLAUDE.md');
     }
 
-    // Step 2: Register plugin in ~/.claude/settings.json
+    // Step 2: Install adapter-provided commands to .claude/commands/
+    const commandsInstalled = this.installCommands(projectDir);
+    if (commandsInstalled.length > 0) {
+      details.commands = commandsInstalled;
+    }
+
+    // Step 3: Register plugin in ~/.claude/settings.json
     const pluginResult = this.registerPlugin();
     if (pluginResult) {
       details.plugin = pluginResult;
@@ -141,6 +156,37 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
     return true;
   }
 
+  /**
+   * Install Claude Code-specific commands to .claude/commands/ in the project.
+   *
+   * These commands extend CLEO's provider-neutral skills with Claude Code-specific
+   * operational patterns (Agent tool spawn templates, model assignment, context guardrails).
+   *
+   * @param projectDir - Project root directory
+   * @returns Array of installed command filenames
+   */
+  private installCommands(projectDir: string): string[] {
+    const adapterCommandsDir = getAdapterCommandsDir();
+    if (!existsSync(adapterCommandsDir)) {
+      return [];
+    }
+
+    const targetDir = join(projectDir, '.claude', 'commands');
+    mkdirSync(targetDir, { recursive: true });
+
+    const installed: string[] = [];
+    const files = readdirSync(adapterCommandsDir).filter((f) => f.endsWith('.md'));
+
+    for (const file of files) {
+      const src = join(adapterCommandsDir, file);
+      const dest = join(targetDir, file);
+      copyFileSync(src, dest);
+      installed.push(file);
+    }
+
+    return installed;
+  }
+
   /**
    * Register the CLEO brain plugin in ~/.claude/settings.json.
    *