Superconductor CLI
Use live sc instructions and capability output as authoritative. Keep SC syntax and lifecycle policy here; role skills should reference this skill rather than reproduce commands.
Boundaries
- Use SC only for the requested orchestration or app-managed outcome.
- Require explicit human intent for worktree/branch creation or deletion, target-branch changes, force termination, destructive cleanup, closing/rearranging existing sessions, and unrelated review-thread mutations.
- Never create a worktree merely for delegation or launch replacement agents for follow-ups.
- Prefer stable labels or stable target IDs and
--active keep. - Dispatch and idle state are not completion; always wait, read, and verify.
Live Preflight
Before the first mutation, run the matching guide:
| Area | Command |
|---|---|
| Agents, teams, delegation | sc instructions orchestration |
| Tabs, panes, views | sc instructions layout |
| Worktrees or branches | sc instructions worktree |
| In-app review threads | sc instructions review |
For orchestration, inspect current capabilities and targets:
bashcommand -v sc sc layout capabilities --output json sc layout views --worktree "$PWD" --output json sc agents list --worktree "$PWD" --output json sc chat providers --json
Verify the launch shape, provider, UI mode, model, reasoning level, and structured-read support before specifying them. If unavailable, report the exact limitation instead of silently substituting another mechanism.
Read references/orchestration.md before launching or controlling sessions. Read references/worktrees-and-reviews.md before requested worktree or review-thread operations.
Individual Pi Worker
Delegated Pi sessions default to terminal mode. Long prompts should use a temporary JSONL launch input built with jq; it is command input, not durable workflow state, and must be removed after launch.
bashsc layout run tabs \ --provider pi --ui terminal \ --label worker-TODO-001 \ --prompt 'Complete prompt with task and absolute handover paths.' \ --worktree "$PWD" --active keep --output json
Capture the returned label/stable target. Then collect that same target:
bashsc agent wait --to label:worker-TODO-001 --idle --timeout-ms 120000 \ --worktree "$PWD" --output json sc agent read --to label:worker-TODO-001 --last 40 \ --worktree "$PWD" --output json
Check reads for target/provider errors, incomplete output, and the evidence required by the prompt. Verify source-writing results independently with Git and tests. Run shared-checkout source writers sequentially.
Use sc agent send for clarification in the existing session. If a turn must be redirected, interrupt then send. Do not infer success from launch, queue admission, or idle state.
Independent Teams
Use sc team run only for genuinely independent fan-out whose roles do not require per-role UI or model overrides:
bashsc team run \ --label correctness --provider pi --prompt 'Independent read-only review prompt.' \ --label regressions --provider pi --prompt 'Independent read-only review prompt.' \ --worktree "$PWD" --output json
sc team run currently has no per-role --ui, --model, or --reasoning flags. When an ensemble requires distinct Pi models or Pi Chat UI, launch individually labeled sessions with sc layout run tabs, wait/read their stable targets, and fan their reports into the designated lead session. Do not claim those sessions are an SC team run or instruct them to call sc team report.
Every team prompt must include its task, absolute handover paths, read/write limits, and this completion contract:
bashsc team report --run RUN_ID --role ROLE --status done \ --summary 'Concise evidence-based report.' --worktree "$PWD" --output json
Use --result-file only when a detailed report exceeds the summary limit; do not use it for the session-file workflow. In a synchronous workflow, capture the returned stable role targets, wait for them, then collect the durable reports with sc team status. Once every role is Reported, use those report summaries directly; call sc agent read only for a missing, failed, or malformed report.
Do not pass --notify self when the coordinator waits synchronously. That option inserts the team synthesis into the creator's editor as a follow-up prompt and may require the user to submit it. Use it only for an explicitly asynchronous workflow, end the coordinator turn after launch, and explain that behavior to the user. Never combine it with manual wait/status collection. Team launch provides parallelism, not sequencing.
Session-File Handover
For /plan, /todos, /execute, and /review:
- A coordinator session file is required:
PI_SESSION_FILEin Pi, or$HOME/.claude/projects/<project slug>/$CLAUDE_CODE_SESSION_ID.jsonlin Claude Code (slug = the project directory path with/and.mapped to-). - Durable handover files are exactly
${SESSION_FILE%.jsonl}.plan.md,${SESSION_FILE%.jsonl}.todos.md, and${SESSION_FILE%.jsonl}.review.md. /reviewmay use the session JSONL and Git state without plan or todos files; include either handover when it exists.- The coordinator alone writes these files.
- Delegated prompts receive the resolved absolute paths and read them directly.
- Do not create sidecar directories, repository run stores, membership records, coordination-state mirrors, or custom JSONL state.
Managed Terminal Title
In a managed Pi terminal:
bashsc tab title "$TITLE" --to "id:terminal:$SUPERCONDUCTOR_TERMINAL_ID" --json
Verify response.new_title. Do not omit the stable target.
Cleanup
Do not stop agents, close tabs/views, delete groups, or remove other managed state unless the human requested cleanup. Inspect exact targets and current help before any such operation.
