Opencode commander

OpenCode Commander

Act as the coordinator. Decompose the requested outcome, dispatch bounded tasks to real OpenCode agents, monitor structured results, resolve contradictions, and produce one coherent deliverable.

Do not dispatch merely because this skill was loaded. Dispatch only when the user explicitly asks for parallel OpenCode work or approves a proposed dispatch.

Resolve the skill directory

Resolve <skill-dir> to the directory containing this SKILL.md. Run bundled scripts with paths relative to that directory. Never assume a user name, home directory, or installation location.

Workflow

1. Check the local runtime without invoking a model:

python3 <skill-dir>/scripts/commander.py doctor

2. Define the final artifact and split the task into 3-5 non-overlapping workers. Read dispatch-method.md when the split is not obvious.

3. Create a task document from tasks.example.json. Use only agent names reported by opencode agent list. Never dispatch TBD.

4. Validate and inspect the execution plan:

python3 <skill-dir>/scripts/commander.py validate /path/to/tasks.json
python3 <skill-dir>/scripts/commander.py dispatch /path/to/tasks.json --dry-run

5. Dispatch headlessly. This is the default and most reliable mode:

python3 <skill-dir>/scripts/commander.py dispatch /path/to/tasks.json --max-workers 4

The command prints the run directory. OpenCode workers run concurrently through opencode run --format json; the script never enables --auto.

6. While another terminal is dispatching, inspect or cancel the run:

python3 <skill-dir>/scripts/commander.py status /path/to/run
python3 <skill-dir>/scripts/commander.py cancel /path/to/run

7. Collect results and synthesize them:

python3 <skill-dir>/scripts/commander.py collect /path/to/run

Separate agreed facts, useful disagreements, weak evidence, the coordinator's judgment, and the recommended next action. Do not average worker opinions.

iTerm split panes

Use iTerm panes only when the user asks for visual split-pane monitoring. The headless coordinator remains the source of truth; each pane streams one worker's structured output.

python3 <skill-dir>/scripts/iterm_dispatch.py /path/to/tasks.json

The optional adapter requires macOS and iTerm. Its default auto backend uses the Python API when the process already has iTerm authentication and the API server is available; otherwise it uses iTerm's native AppleScript split commands without prompting or interpolating task content into script source. If both backends are unavailable, continue headlessly.

Safety rules

• Default every task to read-only. This is a prompt contract; use a restricted OpenCode agent when operating-system-level enforcement is required.
• Use worktree for implementation tasks. Each worker receives an isolated git worktree and branch; the host coordinator reviews and integrates changes.
• Allow shared-write only with the command-line --allow-shared-writes flag after confirming that workers cannot edit overlapping files.
• Never add OpenCode's --auto flag, type credentials, expose tokens in prompts, or dispatch purchases, trades, deployments, publishing, or destructive commands without exact user approval.
• Treat raw run logs as sensitive. The coordinator stores them with user-only permissions and redacts common secret patterns from collected summaries.
• Stop and report authentication failures. Do not automate login or token entry.

Recovery

• Unknown agent: choose a real listed agent or leave the task undispatched.
• Failed dependency: keep dependent tasks skipped; fix or rerun the failed prerequisite.
• Timeout: narrow the task, increase its explicit timeout, or route it to another agent.
• Contradiction: dispatch a focused adjudication task or verify directly from primary sources.
• Concurrent code conflict: keep worktree branches separate and let the host coordinator integrate.

Read task-format.md for the complete task and result contract.