Cli Opencode

OpenCode CLI Orchestrator - Full-Runtime Cross-AI Dispatch

> CRITICAL — SELF-INVOCATION PROHIBITED > > This skill dispatches to the OpenCode CLI binary (opencode). If the agent currently reading this skill is itself running inside OpenCode (TUI / acp / serve / run modes — detection signals listed in §2), the skill MUST refuse to load and return the documented error message instead of generating any opencode invocation. The only exception is an explicit "parallel detached" request that intentionally spawns a SEPARATE session with its own session id and state directory. > > A running CLI skill never dispatches itself. The cli-X skills are for cross-AI delegation only — never self-invocation.

Orchestrate OpenCode's opencode run from external AI assistants (Claude Code, OpenCode, raw shell) AND from inside an existing OpenCode session for parallel detached workers. Three documented use cases keep the cycle risk explicit while giving every dispatch path a copy-paste invocation shape.

Core Principle: The calling AI stays the conductor. Delegate to OpenCode for what it does best — full plugin, skill, MCP, and Spec Kit Memory runtime in a one-shot dispatch. Validate and integrate the output.

---

1. WHEN TO USE

Activation Triggers

• Full plugin / skill / MCP runtime (use case 1) — calling AI is Claude Code / OpenCode / Copilot / raw shell AND the task needs the project's full Spec Kit Memory database, Code Graph semantic index, structural code graph, or every plugin/skill/MCP tool in a one-shot dispatch. Includes @deep-research / @deep-review agent loops with externalized state under .opencode/specs/.
• Parallel detached session (use case 2) — operator already inside OpenCode (TUI / web / serve / acp) AND wants a SEPARATE session with its own session id and state directory for ablation, worker farm, or parallel research. Prompt explicitly mentions "parallel detached", "ablation suite", "worker farm", "parallel research", "spawn detached", or "share URL".
• Agent dispatch — task matches a specialized OpenCode agent. Primary agents (directly invokable via --agent): general, plan (built-in), orchestrate. Generic subagents fully dispatched via the orchestrate primary: context, review, write, debug, ai-council. Command-owned loop executors (deep-research, deep-review, deep-improvement, prompt-improver) are owned end-to-end by their parent /deep:* command; orchestrate may perform exactly one bounded hand-off dispatch to a recognized loop request, but never manages the loop itself. See §3 "OpenCode Agent Delegation" for the full contract.
• Cross-repo dispatch — session in repo A dispatches into repo B's plugin/skill/MCP runtime via --dir or remote OpenCode server via --attach .

When NOT to Use

• You ARE OpenCode already. If your runtime is OpenCode (detection signal: $OPENCODE_CONFIG_DIR or any OPENCODE_* env var set, opencode in process ancestry, or ~/.opencode/state//lock present), this skill refuses to load. Self-invocation creates a circular dispatch loop and burns tokens for no value. The cli-X family is exclusively for cross-AI delegation. The single legitimate exception is an explicit "parallel detached" request that intentionally spawns a SEPARATE session id and state directory (use case 2); without that qualifier, the smart router refuses per ADR-001.
• Simple, quick tasks where opencode run overhead is not worth it.
• Tasks that only need a raw model dispatch — use a sibling cli-* skill.
• Tasks requiring interactive TUI or web UI (use opencode directly instead of opencode run).
• Context already loaded and understood by the calling AI.
• Tasks where the OpenCode binary is not installed at the expected path.

---

2. SMART ROUTING

Prerequisite Detection

# Verify OpenCode CLI is available
command -v opencode || echo "Not installed. Run: brew install opencode (macOS) or curl -fsSL https://opencode.ai/install | bash"

Self-Invocation Guard (ADR-001)

Before any dispatch, run the layered ADR-001 detection: Layer 1 env-var lookup for any OPENCODE_*, Layer 2 process-ancestry probe for an opencode parent, Layer 3 a best-effort ~/.opencode/state//lock probe. A positive on any layer refuses the dispatch unless the prompt carries explicit parallel-session keywords (use case 2), which permits a SEPARATE session id and state directory instead. Full bash + python detection: [references/self-invocation-guard.md](./references/self-invocation-guard.md). Decision tree + refusal text: [references/integration-patterns.md](./references/integration-patterns.md) §5.

Resource Loading Levels

| Level | When to Load | Resources | | ----------- | ----------------------- | ------------------------------ | | ALWAYS | Every skill invocation | references/cli-reference.md, assets/prompt-quality-card.md | | CONDITIONAL | If intent signals match | Intent-mapped reference docs | | ON_DEMAND | Only on explicit request| Extended templates and patterns |

Smart Router

Intent-specific dictionaries (used by the shared helper functions in [system-spec-kit/references/cli/shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md)):

• Pattern 1: Runtime Discovery - discover_markdown_resources() recursively scans existing references/ and assets/ folders with base.exists() safeguards.
• Pattern 2: Existence-Check Before Load - load_if_available() uses _guard_in_skill(), inventory, and seen so raw loads, missing files, duplicate loads, and path escapes are rejected.
• Pattern 3: Not applicable here - cli-opencode has flat resource folders, not keyed references// or assets// subdirectories. Routing selects from RESOURCE_MAP by intent signal rather than by runtime resource key.
• Pattern 4: Multi-Tier Graceful Fallback - low-confidence intent scores return UNKNOWN_FALLBACK with a disambiguation checklist; missing intent resources still return always-load baseline docs plus a clear notice.

INTENT_SIGNALS = {
    "EXTERNAL_DISPATCH":  {"weight": 4, "keywords": ["delegate to opencode", "opencode run", "from claude code", "from opencode", "from copilot", "external runtime", "full plugin runtime", "hand this off to opencode", "hand off to opencode", "send this to opencode", "dispatch to opencode", "run this through opencode", "let opencode handle this", "opencode's full runtime", "full runtime dispatch", "one-shot dispatch", "invoke opencode", "kick this off in opencode", "have opencode take care of this", "get opencode to run this", "pass this over to opencode", "opencode has access to every tool", "opencode has the whole toolchain", "since opencode has all the plugins", "opencode can load every skill", "ask opencode to handle this", "opencode should handle this", "offload this to opencode", "outsource this to opencode", "forward this to opencode", "route this to opencode", "push this to opencode", "opencode has everything loaded", "opencode has the whole toolset", "opencode cli", "run externally", "full toolset", "handle this externally", "external ai assistant", "run in opencode", "hand off externally"]},
    "PARALLEL_DETACHED":  {"weight": 4, "keywords": ["parallel detached", "ablation suite", "worker farm", "parallel research", "spawn detached", "share url", "share-url", "detached session", "separate session id", "own state directory", "spin up a new session", "background opencode session", "run this in the background", "fan out workers", "concurrent sessions", "isolated session", "run these in parallel", "spin off a few workers", "kick off several sessions at once", "run copies side by side", "fire off multiple runs at the same time", "farm this out to multiple workers", "run a bunch of these concurrently", "distribute the work across sessions", "batch this across sessions", "start several sessions at once", "spin up another instance", "new opencode instance", "run it as its own session", "own separate session", "side session", "run this independently", "additional worker", "background job", "separate instance", "own instance", "parallel run", "concurrent run", "session of its own", "spin up a worker", "worker pool", "run in parallel"]},
    "CROSS_AI_HANDBACK":  {"weight": 4, "keywords": ["spec kit", "spec-kit", "spec_kit", "code graph", "memory_search", "session_bootstrap", "skill advisor", "cross-ai handback", "hand back to opencode", "bridge back to opencode", "opencode as a bridge", "non-anthropic cli", "project's memory database", "structural code index", "use the skill advisor"]},
    "AGENT_DISPATCH":     {"weight": 4, "keywords": ["delegate", "agent", "deep-research", "deep-review", "ai-council", "review agent", "context agent", "dispatch an agent", "spawn an agent", "run a subagent", "invoke a subagent", "specialized subagent", "debug agent", "write agent"]},
    "CROSS_REPO":         {"weight": 3, "keywords": ["cross-repo", "different repo", "--dir", "another repository", "remote opencode", "different repository", "target repo", "other codebase", "separate repository", "remote opencode server", "--attach"]},
    "TEMPLATES":          {"weight": 3, "keywords": ["template", "prompt", "how to ask", "opencode prompt", "minimax", "MiniMax-M3", "tidd-ec", "prompt framework", "prompt template", "how do i phrase this", "copy-paste template", "prompt quality", "prompt craft", "costar framework", "example prompt"]},
    "PATTERNS":           {"weight": 3, "keywords": ["pattern", "workflow", "orchestrate", "session continue", "resume session", "integration pattern", "dispatch pattern", "continue the session", "resume a session", "session continuation"]},
    # WHY: DESIGN is an intent signal only — a deliberate cross-skill handoff to sk-design-md-generator,
    # not a same-skill resource bundle. It intentionally has NO RESOURCE_MAP entry: this skill
    # hands design work off rather than owning design reference docs. The durable sk-design-md-generator
    # loading contract lives in the always-fires Design Standards Loading rule and the dispatch
    # manifest (see ALWAYS rules 13-14); RESOURCE_MAP stays limited to same-skill markdown paths.
    "DESIGN":             {"weight": 4, "keywords": ["sk-design-md-generator", "extract design system", "generate design.md", "style reference", "design tokens", "css extraction", "tokens.json"]},
}

RESOURCE_MAP = {
    "EXTERNAL_DISPATCH":  ["references/cli-reference.md", "references/integration-patterns.md"],
    "PARALLEL_DETACHED":  ["references/integration-patterns.md", "assets/prompt-templates.md"],
    "CROSS_AI_HANDBACK":  ["references/integration-patterns.md", "references/opencode-tools.md"],
    "AGENT_DISPATCH":     ["references/agent-delegation.md", "assets/prompt-templates.md"],
    "CROSS_REPO":         ["references/cli-reference.md", "references/opencode-tools.md"],
    "TEMPLATES":          ["assets/prompt-templates.md", "references/cli-reference.md"],
    "PATTERNS":           ["references/integration-patterns.md", "references/cli-reference.md"],
}

LOADING_LEVELS = {
    "ALWAYS": ["references/cli-reference.md", "assets/prompt-quality-card.md"],
    "ON_DEMAND_KEYWORDS": ["full reference", "all templates", "deep dive", "complete guide", "opencode agent", "opencode prompt", "share url", "ablation", "worker farm", "self-invocation", "memory handback", "minimax", "MiniMax-M3", "tidd-ec"],
    "ON_DEMAND": ["references/opencode-tools.md", "assets/prompt-templates.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is the user asking about OpenCode CLI specifically?",
    "Does the task need the project's full plugin / skill / MCP runtime?",
    "Is a parallel detached session what they want?",
    "Is a non-Anthropic CLI handing back to OpenCode for a spec-kit workflow?",
]

Call sequence (using shared helpers from shared-smart-router.md):

1. discover_markdown_resources() — recursively enumerate current .md files under existing references/ and assets/ folders at routing time.
2. _guard_in_skill() + load_if_available() — sandbox paths to this skill, reject non-markdown loads, skip missing files, and suppress duplicates.
3. score_intents(task) and select_intents(scores, ambiguity_delta=1.0) — preserve provider-specific weighted intent scoring and top-2 ambiguity handling.
4. ALWAYS-load LOADING_LEVELS["ALWAYS"], then return UNKNOWN_FALLBACK with UNKNOWN_FALLBACK_CHECKLIST when max score is 0.
5. CONDITIONAL-load existing RESOURCE_MAP[intent] entries via load_if_available(), ON_DEMAND-load keyword matches, and return a notice when no intent-specific knowledge base is available beyond always-load resources.

The route_opencode_resources(task) function body lives in [shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md) — substitute ` = opencode`.

---

3. HOW IT WORKS

Prerequisites

# Verify installation (cli-opencode v1.0.0 is pinned to opencode v1.3.17)
opencode --version | grep -q '^1\.' || echo "Not installed or version drift. See references/cli-reference.md §9."

# Self-invocation guard
env | grep -q '^OPENCODE_' && echo "ERROR: Already inside OpenCode session"

# Authentication — providers configured via opencode providers (alias auth)
opencode providers

Authentication options: opencode providers login (and opencode auth login for subscription plans). Full per-provider login shapes and the configured-provider list: references/cli-reference.md §4.

Provider Auth Pre-Flight (Smart Fallback)

MANDATORY before any first dispatch in a session. The default provider may not be logged in — silently failing with provider/model not found or 401 Unauthorized mid-dispatch wastes a round-trip. Run the pre-flight once per session, cache the result, and re-run only on an auth failure.

The one-shot pre-flight bash, the per-provider decision trees, the user-facing prompt templates for missing providers, and the error-recovery contract live in [references/cli-reference.md](./references/cli-reference.md) §4 — do not duplicate them here. Never substitute a model the user didn't approve; ASK when the default is unavailable.

Default Invocation (Skill Default)

Default model + variant + format + dir: opencode-go/deepseek-v4-flash · --variant max · --format json · --dir (pinned to avoid CWD ambiguity). The Go gateway fronts the flash model at its max thinking tier — subsidized 2x-usage reasoning for routine dispatches (the direct DeepSeek API provider was retired).

Use opencode run --model opencode-go/deepseek-v4-flash --variant max --format json --dir "".

> The --agent flag (read this): Do NOT pass --agent on a top-level opencode run — current opencode treats named agents like general as subagents and rejects them at the top level, so --agent general fails outright. The default agent runs when --agent is omitted, which is correct for almost every dispatch. To target a specific agent profile, describe the role in the prompt body instead (e.g. open with "Act as a code-review agent: …"); only pass --agent after confirming acceptance via opencode run --help on the installed version.

Honor explicit user model, port, and handback phrasing verbatim; otherwise use the default invocation above.

Core Invocation Pattern

Core flags: --model, --agent, --variant, --format json, --dir, continuation/session/fork flags, --share and --port for detached sessions, --file, --thinking, --pure, and log flags.

> Non-interactive invocation stdin: always append **Always pin the model with -m **: a run that inherits an out-of-quota default provider retries the 429 forever and prints nothing, which looks exactly like a deadlock or a snapshot-lock hang. This is the single most common cause of a "hung" opencode run` — including command-driven deep-loop runs, where

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

Install and usage instructions live in the source repository linked above.