/orchestrate

name: orchestrate
description: Coordinate multiple terminal coding agents through the Superset CLI by creating isolated workspaces, launching workers, sending follow-ups, reading terminal output, tracking dependencies, and collecting structured results. Use when asked to delegate or parallelize coding work, coordinate agents across workspaces or hosts, hand work between agents, monitor worker progress, or run a multi-agent workflow with Superset. Do not use for ordinary single-agent workspace, task, or automation management.

Superset Orchestration

Coordinate terminal agents with Superset's workspace, agent, and terminal commands. Treat this as a coordinator-driven protocol: Superset provides session transport, while the coordinator owns task dependencies and completion state.

Establish the control surface

1. Run `superset auth whoami --json`. 2. Run `superset terminals --help` and require `list`, `read`, `send`, and `close`. 3. If those commands are absent, run `superset update` and recheck. Do not invent or substitute unsupported orchestration commands. 4. When developing inside the Superset monorepo, use `bun run --cwd packages/cli dev --` in place of `superset` to exercise the source CLI against the API configured in the root `.env`. To reuse production CLI authentication while testing unreleased source commands, run them from `packages/cli` with `SUPERSET_API_URL=https://api.superset.sh bunx cli-framework dev`. 5. Resolve the workspace, host, and terminal-capable agent before dispatching:

superset hosts list --json
superset agents list --local --json
superset workspaces list --local --json

When coordinating from inside the target workspace, pass `--workspace "$SUPERSET_WORKSPACE_ID"` explicitly to agent and terminal commands. Only `workspaces get` defaults its workspace ID from that environment variable. Pass `--host <id>` consistently for a remote host. If the target host is offline, use `hosts wake <id>` and confirm it is online before dispatching. Do not use `--agent superset`: it creates a chat session, and terminal read/send cannot control it.

Plan the work

Create a compact coordinator table with these fields:

| Field | Purpose | | --- | --- | | Task | Stable short identifier | | Dependencies | Tasks that must complete first | | Workspace | Superset workspace ID | | Host | Host ID, or local | | Terminal | `sessionId` returned by `agents create` | | Status | `pending`, `ready`, `running`, `completed`, `blocked`, or `failed` | | Result | Summary, files, checks, and follow-up work |

Keep this state in the coordinator's working context. Superset organization tasks are issue-tracker records, not orchestration DAG nodes; do not create or mutate them unless the user asks.

Prefer independent tasks and shallow dependency chains. For parallel editing, give workers separate workspaces/branches. Sharing one workspace is appropriate for read-only analysis or deliberately complementary work with non-overlapping files.

Define the worker protocol

Give every worker a bounded prompt containing:

• task ID and objective;
• workspace scope and files it may change;
• acceptance criteria and verification commands;
• dependencies or prior findings it needs;
• a warning not to broaden scope or overwrite unrelated changes;
• the completion envelope below.

Require the worker's final response to end with one of these envelopes:

SUPERSET_WORKER_DONE
task: <task-id>
summary: <one-line outcome>
files: <comma-separated paths or none>
checks: <commands and outcomes>
handoff: <next-step context or none>

SUPERSET_WORKER_BLOCKED
task: <task-id>
reason: <specific blocker>
needs: <decision, access, or dependency required>

These markers are a prompt convention visible in terminal snapshots, not durable Superset events. Treat malformed or missing envelopes as unstructured output and inspect the full snapshot.

Dispatch workers

Launch a terminal agent once and retain its session ID:

superset agents create \
  --workspace <workspace-id> \
  --host <host-id> \
  --agent <preset-or-config-id> \
  --effort <supported-level> \
  --attachment <optional-path> \
  --prompt "<worker prompt>" \
  --json

Omit `--effort` or `--attachment` when they are not needed. The result is `{ "kind", "sessionId", "label" }`. Require `kind` to be `terminal`; store `sessionId` as the terminal ID. Launch all ready, independent tasks before monitoring them.

Use `superset workspaces create` first when a worker needs an isolated branch. Do not create parallel editing workers in the same worktree unless their file ownership is explicitly disjoint.

Monitor and communicate

Reacquire live terminal IDs after losing coordinator context or restarting the host service:

superset terminals list \
  --workspace <workspace-id> \
  --host <host-id> \
  --json

Terminal discovery does not identify semantic recipients or agent completion state. Preserve the coordinator table's task-to-terminal mapping whenever possible.

Read recent output without mutating the session:

superset terminals read \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --max-lines 240 \
  --json

The JSON result includes `text`. Inspect it for the completion or blocked envelope and confirm that the surrounding output supports the claimed result. `terminals list` reports live sessions, not whether an agent is working or idle; do not infer completion from presence, absence, `attached`, or terminal title alone.

Send clarification, dependency results, review feedback, or a handoff into the existing session:

superset terminals send \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --text "<follow-up>" \
  --json

Poll at a measured cadence and read all running workers in each pass. Prefer several short monitoring passes over one long blocking shell loop so progress and user updates remain vis