Cli External Orchestration

---
name: cli-external-orchestration
description: "Parent hub for external CLI dispatch: routes to six workflow modes through mode-registry.json. Holds no per-mode logic; dispatches by workflowMode."
allowed-tools: [Bash, Read, Glob, Grep]
version: 1.4.2.0
metadata:
  author: OpenCode
  family: cli
---

<!-- Keywords: cli-external-orchestration, mode-registry, hub-router, workflowMode, packetKind, cli-opencode, opencode-cli, opencode-run, cli-claude-code, claude-code, claude-cli, cli-codex, codex-cli, codex-exec, cli-cursor, cursor-cli, cursor-agent, composer, cli-devin, devin-cli, cli-pi, pi-cli, pi-agent, pi.dev, cross-ai, agent-delegation, executor-delegation -->

# CLI External Dispatch Hub (cli-external-orchestration)

One skill, six workflow modes, one shared `family: cli` identity. `cli-external-orchestration` is the public, advisor-routable home for every external CLI dispatch orchestrator in this repo. Before routing, the hub reads `hub-router.json` to resolve a `workflowMode`, then delegates through `mode-registry.json`. This hub holds NO per-mode logic — each mode keeps its own dispatch contract, self-invocation guard, and hard rules in its packet, and the hub only routes by `workflowMode`.

---

## 1. WHEN TO USE

Use this skill (through the hub) for any cross-AI CLI dispatch. Invoke it as `cli-external-orchestration`; the hub classifies the request, resolves a mode key, and loads the matching nested packet.

| Mode | Kind | Use it for | Packet |
|------|------|-----------|--------|
| **cli-opencode** | workflow | OpenCode CLI orchestration: external dispatch, in-OpenCode parallel/detached sessions, full plugin/skill/MCP/Spec-Kit-Memory runtime, small-model dispatch (DeepSeek, Kimi, MiniMax, MiMo, GLM) | `cli-external-orchestration/cli-opencode/` |
| **cli-claude-code** | workflow | Claude Code CLI orchestration: Anthropic-backed extended thinking, surgical code editing, structured JSON-schema output, agent delegation, cross-AI second opinions | `cli-external-orchestration/cli-claude-code/` |
| **cli-codex** | workflow | Codex CLI orchestration: OpenAI-backed coding, review, and web research; fails closed when `codex` is absent | `cli-external-orchestration/cli-codex/` |
| **cli-cursor** | workflow | Cursor CLI orchestration: cursor-agent-backed coding, Composer-model dispatch, read-only plan/ask modes; fails closed when `cursor-agent` is absent | `cli-external-orchestration/cli-cursor/` |
| **cli-devin** | workflow | Devin CLI orchestration: Cognition-backed coding, cloud handoff, subagent delegation, MCP host integration; fails closed when `devin` is absent | `cli-external-orchestration/cli-devin/` |
| **cli-pi** | workflow | Pi CLI orchestration: guarded headless print, JSON event, RPC, native-resource, and community-package dispatch; fails closed when `pi` is absent | `cli-external-orchestration/cli-pi/` |

### When NOT to Use

- The current runtime IS the target CLI — each mode's own self-invocation guard refuses self-dispatch (see that packet's §2); this hub does no dispatch itself and carries no guard of its own.
- Application-code implementation or review, or measured design-reference extraction with no CLI-dispatch need — use `sk-code` / `sk-design-md-generator` directly.
- A quick in-process task with no cross-AI handoff — dispatching to an external CLI process is unnecessary overhead.

---

## 2. SMART ROUTING

Routing is two-stage. Stage 1 (hub → mode): the compiled router / `hub-router.json` scores the request and resolves it to one workflow mode — or an ordered bundle — per `mode-registry.json`. Stage 2 (mode → leaves): the surface router below maps the request's CLI-dispatch intent to the exact packet-local leaf resources that mode loads. The two layers stay separate: the hub never emits leaf paths, and the surface router never re-decides the mode. The surface router is a first-class document at the hub root — `ROUTER.md` — carrying the intent model, the machine-readable `INTENT_SIGNALS` / `RESOURCE_MAP` block, and the how-to-read rules.

> **Compiled routing (default-on, flag-gated, additive).** Resolve the mode via the compiled router contract first:
> ```bash
> node .opencode/bin/compiled-route.cjs --hub cli-external-orchestration --prompt "<task>"
> ```
> Follow the returned decision — `route` (use its `targets`), `clarify`/`defer` (disambiguate), `reject` (refuse). On a `{"servingAuthority":"legacy"}` sentinel or any error, use the routing below. The front door self-gates on serving-authority. Compiled routing is now the default for `cli-external-orchestration`; set `SPECKIT_COMPILED_ROUTING=0` to force legacy routing fleet-wide — the explicit kill-switch.

### Two-Axis Model

- `packetKind: "workflow"` — `cli-opencode`, `cli-claude-code`, `cli-codex`, `cli-cursor`, `cli-devin`, and `cli-pi` orchestrate a CLI binary and their dispatched writes land in THIS repo's workspace (`mutatesWorkspace:true`). None is a transport packet: all classify intent, choose/confirm a provider, and conduct the dispatched session. (`cli-cursor`'s native worktree/cloud-worker surfaces are opt-in escape hatches, not its default dispatch shape.)
- Zero extensions: no surface-axis, no transport-axis, no runtime-loop. All six modes are primary, independently-routable dispatch workflows.

### Routing Rule

```text
read hub-router.json
  -> score routerSignals and vocabularyClasses
  -> apply routerPolicy.tieBreak
  -> read mode-registry.json for packetKind, backendKind, toolSurface, and advisorRouting
  -> load the selected packet(s)
```

### Outcomes

- `single`: one dominant executor signal routes to one mode.
- `orderedBundle`: multiple explicitly requested executors route in tie-break order.
- `defer`: unclear or contradictory dispatch intent asks for disambiguation — the router does not silently default to `cli-opencode` on genuine ambiguity.

### Surface Router — per-mode leaf sets

Stage 2 of routing lives in `ROUTER.md` at the hub root, next to `SKILL.md` and `README.md`. It defines the per-mode leaf-intent model (all six modes, plus the deliberate absence: a bare CLI-dispatch phrase that names no executor fires no intent and defers at the hub), the machine-readable `DEFAULT_RESOURCE` / `INTENT_SIGNALS` / `RESOURCE_MAP` block that the deterministic router-replay and benchmarks parse, and the how-to-read rules (dominant intent → one leaf set; near-tied intents → deduped union, the `orderedBundle` outcome; no keyword match → hub `defer`, never a silent default to `cli-opencode`). Every `RESOURCE_MAP` path is packet-qualified and converts to the canonical `(workflowMode, leafResourceId)` pair at the one contract boundary.

`ROUTER.md` stays a separate document on purpose: the router-replay contract resolves the hub's mode from `hub-router.json` and reads the leaf sets from the surface document — the machine block must not move into `SKILL.md` (the replay would treat it as the hub's own router and lose the mode projection) or into `hub-router.json` (schema handoff-ambiguity rule).

### Executor Delegation

A prompt naming a specific executor (e.g. "use cli-opencode", "delegate to opencode", "get a claude code second opinion", "delegate to codex", "delegate to cursor", "delegate to devin", "delegate to pi", or a small model that dispatches through one) is resolved by the system-skill-advisor's executor-delegation scorer, which sources its alias table from THIS hub's `mode-registry.json` — keyed by each mode's `packetSkillName` — and resolves to `cli-opencode`, `cli-claude-code`, `cli-codex`, `cli-cursor`, `cli-devin`, or `cli-pi`. See `system-skill-advisor/mcp-server/lib/scorer/executor-delegation.ts`.

---

## 3. HOW IT WORKS

### Layout

```text
cli-external-orchestration/
  SKILL.md
  README.md
  mode-registry.json
  hub-router.json
  description.json
  graph-metadata.json
  changelog/
  feature-catalog/
  manual-testing-playbook/
  benchmark/
  leaf-manifest.json
  ROUTER.md
  cli-opencode/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-claude-code/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-codex/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-cursor/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-devin/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-pi/
    SKILL.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
```

### Companion Metadata

- `mode-registry.json` owns `workflowMode`, `packetKind`, `backendKind`, `toolSurface`, packet folder identity, alias phrases, and `advisorRouting`. It is also the executor-delegation scorer's source of truth for which CLI executors exist.
- `hub-router.json` owns `routerPolicy`, `routerSignals`, `vocabularyClasses`.
- `description.json` owns advisor-facing summary fields.
- `graph-metadata.json` owns the one skill-graph identity node for the whole hub (`family: cli`).

### Self-Invocation Guards Stay Packet-Local

Each mode's self-invocation guard is runtime-signal-based (env var / process ancestry / lockfile or a documented heuristic), not path-based, so it is unaffected by this hub's routing layer. `cli-opencode` additionally carries a parallel-detached carve-out that `cli-claude-code` intentionally does not — that asymmetry is preserved.

---

## 4. RULES

### ✅ ALWAYS

- Resolve packets through `mode-registry.json`; never hardcode packet roots in prose-only logic.
- Keep `SKILL.md` thin: routing, invariants, and navigation only.
- Keep every packet in `modes[]` and give every packet a `packetKind`.
- Keep exactly one `graph-metadata.json`, at the hub root.
- Keep `hub-router.json` signal keys and registry `workflowMode` values bidirectionally aligned.
- Keep the surface router's `RESOURCE_MAP` in sync with `leaf-manifest.json` — the leaf sets dual-read to canonical typed pairs at the one contract boundary (`sk-doc/sk-create-skill/scripts/lib/leaf-resource-contract.cjs`).
- Keep every `RESOURCE_MAP` path packet-qualified (`<packet>/references|assets/…`) and resolving on disk.
- Treat the installed binary as the authority for flags and enum values, and `--help` as an incomplete summary of it. A value this skill documents but help omits is not thereby fabricated — several CLIs here accept aliases and legacy names their help text never prints. Before changing or reporting a documented flag value as invalid, probe the binary with an argument that forces parse-time validation without starting a billable session (e.g. pointing a file-taking flag at a nonexistent path: a rejected enum fails first, an accepted one reaches the file error). Enums also move between releases, so re-probe after an upgrade instead of trusting a recorded result.
- Read the target mode's `SKILL.md` before composing any dispatch prompt (constitutional cli-dispatch-skill-preload rule) — the advisor recommendation alone does not waive this.
- Attach the resolved agent persona to every external-CLI dispatch (AGENTS.md §7 runtime agent dir; the right agent per subtask, never a bare task) — each mode's `SKILL.md` carries the native-surface-vs-inline mechanic, and the canonical contract is `../sk-prompt/assets/cli-prompt-quality-card.md` "Persona Injection".

### ⛔ NEVER

- Never add a second packet array.
- Never add packet-local `graph-metadata.json` files.
- Never let any mode dispatch itself — the self-invocation guard is packet-owned and non-negotiable.
- Never let the executor CLI (the HOW) override the calling skill's own workflow (the WHAT) — "use cli-opencode gpt-5.5 high" still runs inside the caller's skill-owned route.

### ⚠️ ESCALATE IF

- A packet cannot be classified as `workflow` (all six current modes are; a future mode may not be).
- Router signals, vocabulary classes, and registry modes cannot be made bidirectionally consistent.
- The executor-delegation scorer resolves a delegation prompt to `cli-external-orchestration` itself instead of a real executor — that is the exact silent-misroute failure mode ADR-005 rewrote the scorer to prevent; report it rather than working around it.

---

## 5. REFERENCES

- Registry: `mode-registry.json`.
- Router: `hub-router.json`.
- Surface router: `ROUTER.md`.
- Advisor description: `description.json`.
- Skill graph identity: `graph-metadata.json`.
- Workflow packets: `cli-opencode/SKILL.md`, `cli-claude-code/SKILL.md`, `cli-codex/SKILL.md`, `cli-cursor/SKILL.md`, `cli-devin/SKILL.md`, `cli-pi/SKILL.md`.
- Per-mode provider/model/invocation catalogs: each mode's `references/providers-and-models.md` is the dedicated single-source index of that mode's providers, model ids, personas/effort tiers, and dispatch shapes.
- Executor-delegation scorer (hub-aware, sources from this hub's registry): `../system-skill-advisor/mcp-server/lib/scorer/executor-delegation.ts`.
- Constitutional CLI dispatch skill-preload rule: the retired constitutional rule docs.
- Persona-injection contract (canonical): `../sk-prompt/assets/cli-prompt-quality-card.md` "Persona Injection" — every mode attaches the resolved agent persona on dispatch.