# CLI External Orchestration

> Parent hub for external CLI dispatch: routes to eight workflow modes through mode-registry.json; dispatches by workflowMode.

- Skill: `michelkerkmeester/cli-external-orchestration` (Agent Skill, multi-file: 101 files)
- Install (CLI): `npx get-skill add michelkerkmeester/cli-external-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/cli-external-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/cli-external-orchestration

---


<!-- 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, cli-deepseek-harness, dsh, dsh-headless, deepseek-harness, cli-mistral-vibe, mistral-vibe, vibe-cli, vibe-print-mode, vibe-headless, cross-ai, agent-delegation, executor-delegation -->

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

One skill, eight workflow modes, and 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, recursion bounds, and hard rules in its packet. The hub 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, 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/` |
| **cli-deepseek-harness** | workflow | DeepSeek Harness (`dsh`) CLI orchestration: pinned headless one-task dispatch over a closed two-route DeepSeek V4.1 Flash roster, JSON event stream, cross-AI validation. Experimental: LLM Gateway (the default, 2026-11-06) and OpenCode Go (when named, 2026-11-07) answered a keyed run. Fails closed when `dsh` is absent or not the pinned version | `cli-external-orchestration/cli-deepseek-harness/` |
| **cli-mistral-vibe** | workflow | Mistral Vibe (`vibe`) CLI orchestration: pinned print-mode one-task dispatch (`vibe -p`) over a closed two-alias `deepseek-flash` / `glm-flash` roster, `export.json` outcome record, cross-AI second opinions. Experimental: the pin is `vibe 3.1.2`, ACP (`vibe-acp`) is deferred, and behavior outside the saved captures stays UNKNOWN. Fails closed when `vibe` is absent, not the pinned version, or `MISTRAL_API_KEY` is unset | `cli-external-orchestration/cli-mistral-vibe/` |

### When NOT to Use

- The current runtime IS the target CLI — most modes refuse self-dispatch through their own guard (see that packet's §2); `cli-pi` is the exception and may be dispatched from inside Pi. 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

Stage one scores `hub-router.json` `routerSignals` against `vocabularyClasses`, then applies `routerPolicy.tieBreak` to select a workflow mode.
`vocabularyClasses` is the authored mode vocabulary. The vocabulary check at `.skilled/skills/sk-doc/sk-create-skill/scripts/ci-hub-vocabulary-source.cjs` fails on the `alias`, `stage-two`, `triggers` and `packets` legs.
The check's `stage-two-reverse` leg reports only.

Stage two lives in the root [`ROUTER.md`](./ROUTER.md), which maps each mode's CLI intent to the packet-local leaf resources it loads.
The hub selects a mode, and `ROUTER.md` selects that mode's leaves.

The advisor routes external CLI dispatch to the single identity `cli-external-orchestration`.
Resolve a mode with `node .skilled/bin/compiled-route.cjs --hub cli-external-orchestration --prompt "<task>"`.
Follow the decision: `route` loads `targets`, `clarify` and `defer` ask for disambiguation, and `reject` refuses.
`routerPolicy.defaultMode` is `null`, so a request with no dominant executor defers for clarification rather than selecting a default.
Run the compiled-routing directive in [`ROUTER.md`](./ROUTER.md) before selecting hub resources.

---

## 3. HOW IT WORKS

### Terms

- **`workflowMode`**: the public mode key this hub resolves to one CLI packet.
- **`packetKind`**: the axis a mode sits on, and every mode here is `workflow` because all eight orchestrate a CLI binary.
- **`backendKind`**: which backend runs the mode, recorded per mode in `mode-registry.json`.
- **`toolSurface`**: the tools a mode may and may not use, together with its `mutatesWorkspace` flag.
- **`advisorRouting`**: how the advisor finds the mode, which is `routingClass: "metadata"` throughout this hub, so the advisor routes the hub and the hub picks the mode.
- **`mode-registry.json`**: the registry that owns each mode's discriminator, packet folder, aliases and `advisorRouting`, plus the executor-delegation scorer's one list of CLI executors.
- **`hub-router.json`**: stage one's `routerPolicy`, `routerSignals` and `vocabularyClasses`.
- **`vocabularyClasses`**: the authored mode vocabulary that `routerSignals` are scored against.
- **`tieBreak`**: the `routerPolicy` order that ranks the eight modes when scores are close.
- **leaf resource**: a packet-qualified file that a selected mode loads, named in `RESOURCE_MAP` and dual-read to a typed pair through `leaf-manifest.json`.
- **`orderedBundle`**: the outcome where several explicitly requested executors route in `tieBreak` order.
- **`defer`**: the outcome where unclear or contradictory dispatch intent asks for disambiguation instead of defaulting to `cli-opencode`.

### 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
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-claude-code/
    SKILL.md
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-codex/
    SKILL.md
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-cursor/
    SKILL.md
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-devin/
    SKILL.md
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-pi/
    SKILL.md
    ROUTER.md
    README.md
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-deepseek-harness/
    SKILL.md
    ROUTER.md
    README.md
    hard-rules.json
    references/
    assets/
    manual-testing-playbook/
    changelog/
  cli-mistral-vibe/
    SKILL.md
    ROUTER.md
    README.md
    hard-rules.json
    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`).

**Version authority.** This file's `version` frontmatter is the hub's release version and matches the newest entry under `changelog/`; `description.json`, `mode-registry.json` and `hub-router.json` carry the same value, so every hub-root JSON routing file states the same release; `ROUTER.md` keeps its own document version.

### Recursion Guards Stay Packet-Local

Each mode's guard is runtime-signal-based (env var / process ancestry / lockfile or a documented heuristic), not path-based. The hub's routing layer does not affect it.
Two asymmetries are deliberate and preserved:
- `cli-opencode` carries a parallel-detached carve-out that `cli-claude-code` intentionally does not.
- `cli-pi` is exempt from the two layers that mean "the caller is inside this CLI". Pi has no in-process delegation left, so refusing those would leave a Pi session no way to hand work out.

The layers that bound a spawn chain, fan-out lineage and dispatch stack apply to every mode without exception.

---

## 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 a transport mode's policy surface minimal: `routingClass: "metadata"`, `mutatesWorkspace: false`, `Write`/`Edit`/`Task` forbidden, and the mode named in the `transport-axis` extension's `transports[]`. `tieBreak` lists workflow modes first, so a prompt that names no mode never resolves to a transport by ordering.
- 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. Treat `--help` as an incomplete summary.
- 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.
- For example, point a file-taking flag at a nonexistent path. A rejected enum fails first; an accepted one reaches the file error.
- Enums move between releases. 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 §9 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 from inside a fan-out lineage or a repeated dispatch stack — those bounds are non-negotiable for every mode. Whether being *inside* the target CLI also refuses is packet-owned, and `cli-pi` deliberately allows it.
- 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` or `transport` (every current mode is one of the two; a future mode may be neither — if it is read-only evidence it is a surface, and this hub would then need the surface-axis extension too).
- 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`, `cli-deepseek-harness/SKILL.md`, `cli-mistral-vibe/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/runtime/lib/scorer/executor-delegation.ts`.
- Constitutional CLI dispatch skill-preload rule: Read the target mode's `SKILL.md` before composing any dispatch prompt.
- Persona-injection contract (canonical): `../sk-prompt/assets/cli-prompt-quality-card.md` "Persona Injection" — every mode attaches the resolved agent persona on dispatch.

