/orchestrate

name: orchestrate
description: Coordinate several coding agents in parallel through Paradev (formerly Superset), each in its own workspace, with follow-ups, progress reads, dependency tracking, and structured results. Use when the user asks to delegate, parallelize, fan out, or split up coding work across agents, workspaces, or hosts, hand work between agents, or monitor workers, including "spin up agents for each of these", "run these in parallel", "what are my workers doing". Not for ordinary single-agent workspace, task, or automation management.
argument-hint: the work to split up and coordinate
allowed-tools: Bash(superset:*) Bash(paradev:*)

Paradev Orchestration

`paradev` is an alias for the `superset` CLI: every `superset` command here also runs as `paradev`.

Coordinate terminal agents with Paradev's workspace, agent, and terminal commands. Treat this as a coordinator-driven protocol: Paradev 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 schema 2>/dev/null | jq -re '.commands[] | select(.path==["terminals"]) | .commands[].path[1]' || superset terminals --help` and require `list`, `read`, `send`, and `close`. The `--help` fallback covers a CLI older than 1.34.0 (no `schema`) and a machine without `jq`. 3. If those commands are absent, run `superset update` and recheck. Do not invent or substitute unsupported orchestration commands. `hosts add`, `terminals send --keys`, `terminals wait`, `terminals attach`, `panes`, and `notifications show` are newer than CLI 1.37.0; when one is still missing after an update, skip it and fall back to `terminals read` and `send`. 4. 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" --local` explicitly to agent and terminal commands; they never default `--workspace`. Without `--local` or `--host`, `agents create/read/wait`, terminal, and workspace commands target the cloud when the account has cloud workspaces; `agents list` needs one of them. 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. To run workers on a machine that is not a host yet but that the user can SSH into, `superset hosts add <ssh-target>` installs the CLI there, signs it in, and keeps it running as a user service. It changes that machine, so get the user's go-ahead first and pass `--yes` only after they agree. It needs `ssh <ssh-target>` to already work from here, and on the remote: macOS or glibc Linux (x64 or arm64, not Alpine or Windows), `curl`, and on Linux a valid `/etc/machine-id` and systemd user services. Without `gh` signed in there, private repos will not clone on that host. Running it again on the same target repairs a broken setup, and `superset hosts remove <ssh-target>` undoes it. 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 | Paradev 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. Paradev 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 Paradev 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