Skill: Switchboard Orchestration HTTP Surface

This is the complete HTTP contract for driving Switchboard from outside the VS Code webview — whether you are a fleet coding/review agent working inside a Mission Control worktree, an external Mission Control (Cursor / Zed / Claude Code / Antigravity) driving the whole board, or a team member (a discoverable-skill agent) reading the local board.

Switchboard's LocalApiServer runs inside the VS Code extension and is the sole writer of kanban.db. You never touch the DB directly — you call these endpoints. The board is the source of truth; the UI is just one view of it.

Endpoint inventory. The hand-written list below is a subset for the calls agents most often make. The authoritative, generated inventory is GET /catalog — it lists every verb, endpoint, and prefix the server actually serves (drift-checked in CI via catalog:check), so it can never lag behind the server the way a hand-maintained list can. When you need a call this document does not cover, hit GET /catalog first; the payload contract for any call below still lives here, since the catalog carries only {path, method, prefix} and not request shapes.

Behavior vs. invocation. This skill is the invocation authority (endpoints, verbs, payload fields). For behavior contracts — how the system behaves (cards move on coding start, completion = plan-file mtime advance, plan files are write-once-at-the-end, subtask column exclusion) — consult the switchboard-contracts protocol (switchboard api GET /protocol/switchboard-contracts). Never consult that skill for invocation; never consult this skill for behavior conventions.

1. Bootstrap

Verify Switchboard is up before anything else:

switchboard api GET /health     # -> { status: 'ok', port, roots: [...] }

If switchboard api fails with server not running, Switchboard is not running — tell the user to open the workspace in VS Code with the Switchboard extension active (or run the standalone host). Do not fall back to editing kanban.db directly.

Auth. All endpoints sit behind the localhost boundary. If a token is set in VS Code (Switchboard: Api Token), the CLI handles auth automatically.

Multi-root. /health returns roots. DB-backed endpoints accept an optional ?workspaceRoot=<root> (GET) or "workspaceRoot" body field (POST/PUT/DELETE); omit it to use the primary workspace.

Response envelope.

• Read endpoints return { "success": true, "data": <payload> }.
• Mutation endpoints return { "success": true, ...fields } (no data wrapper).
• Errors return { "error": "<message>" } with an HTTP status: 400 bad input, 401 unauthorized, 404 not found, 409 conflict, 503 store/extension not ready, 500 handler error.
• A 503 from a read endpoint also carries code and tier: { "error": "...", "code": "STORE_UNAVAILABLE", "tier": "board" | "archive" }.

Three read outcomes — branch on all three. A board read has exactly three answers, and two of them used to be the same value:

STORE_UNAVAILABLE is not an empty board. An orchestrator that reads it as one makes confident decisions about a board it cannot see — it will dispatch nothing, report a fleet as idle, or mark work missing. On STORE_UNAVAILABLE: retry once after a few seconds; if it repeats, stop and report, naming the tier that failed. Never poll it in a loop, and never fold it into "no cards found".

2. Read endpoints (GET)

switchboard api GET /kanban/board
switchboard api GET "/kanban/plans?column=PLAN%20REVIEWED"
switchboard api GET "/kanban/plan?planId=a1b2c3d4"      # includes .data.content (the .md file)
switchboard api GET /kanban/features
switchboard api GET /worktree/list

⚠ planId is NOT a valid query filter on GET /kanban/plans. The handler (_handleGetPlans, LocalApiServer.ts:6483) reads only column and featureId from the query string — a planId param is silently ignored and the full workspace array is returned. An agent consuming res.data[0] then inspects whichever card happens to be first in the DB (often from a different column), generating false reports. For a single plan, use GET /kanban/plan?planId=<id> (returns one plan plus its file content at .data.content). Client-side filtering (res.data.find(p => p.planId === id)) works but fetches the whole board — prefer the dedicated endpoint.

Column filter requires the storage column id, not the board label. GET /kanban/plans?column=Planned returns an empty array — the stored id is PLAN REVIEWED, URL-encoded as PLAN%20REVIEWED. See the column-translation table in query-kanban/SKILL.md or call GET /kanban/columns for the live {id, label} mapping.

Record lookups span the archive; collection reads stay windowed. The board keeps a window of recent work; completed cards that age past it move to a separate archive store. The two kinds of read treat that boundary differently, on purpose:

• GET /kanban/plan?planId= spans both stores and labels the result with .data.source ('board' or 'archive'). A card is returned exactly once even while the archive sweep is moving it. So a 404 here is a real absence in both stores — never "it got old". The storage window is a fact about where a card is kept, not a fact about the card.
• GET /kanban/board, GET /kanban/plans and GET /kanban/features are windowed and deliberately exclude dormant cards — that is the human board's view, and spanning them would flood it. To ask about a specific old card, use the record lookup.

.data.source is where the record was found; a GET does not promote a dormant card back to the board.

Plan records include: planId, sessionId, topic, planFile, kanbanColumn, status, complexity, tags, project, isFeature, featureId, worktreeId, worktreeStatus, dispatchedAt (null = not currently working), recommendedRole.

recommendedRole (lead | coder | intern) is the seat the board would route this plan to — resolved through the operator's kanban.routingMapConfig and the pair-mode intern bypass, the same rule POST /kanban/dispatch uses for "auto". Dispatch a subtask to a seat of that role on your team; if your team has no such seat, dispatch to a coder and say why. Absent when the plan's complexity is unknown — treat absence as coder. Do not re-derive it by reading the plan file's Recommendation: line: nothing in the system parses that line, and a remapped board or an active pair mode would make it wrong.

3. Plan lifecycle (POST / PUT / DELETE)

# Create — returns { success:true, planId, planFile, slug }
switchboard api POST /kanban/plans '{
  "title": "Add rate limiting to the API",
  "complexity": "5",
  "tags": "backend, api",
  "body": "Add token-bucket rate limiting to the public endpoints."
}'

switchboard api PUT /kanban/plans/project '{"planId":"a1b2c3d4","project":"Platform"}'

switchboard api PUT /kanban/plans/priority '{"planId":"a1b2c3d4","starred":true}'

switchboard api DELETE "/kanban/plans?planId=a1b2c3d4"                    # DB row only
switchboard api DELETE "/kanban/plans?planId=a1b2c3d4&deleteFile=true"    # also remove the file

workspaceRoot validation: POST /kanban/plans and POST /kanban/plans/import require workspaceRoot (if provided) to match a known registered workspace root as reported by GET /health → roots. Any unregistered root (or a differently-cased / symlinked spelling that does not match) is refused with 400.

delete_plan gotcha: without deleteFile=true, the .md file stays on disk and the plan re-appears on the next import_plans (or a webview reset). Use deleteFile=true for a permanent delete. create_plan refuses to overwrite an existing file (409) and rejects path-traversal slugs (400).

4. Board mutations (POST)

# Column vocabulary: CREATED | PLAN REVIEWED | STAGING | LEAD CODED | CODER CODED | INTERN CODED
#                    | CODE REVIEWED | COMPLETED   (see GET /kanban/columns)
switchboard api POST /kanban/move '{"planId":"a1b2c3d4","targetColumn":"CODE REVIEWED"}'

switchboard api POST /kanban/feature '{"name":"Auth Refactor","planIds":["id1","id2"],"description":"Group the auth work."}'

4a. Verb-rail traps (read before you call POST /<panel>/verb/<name>)

The generic verb rail (POST /<panel>/verb/<name>) routes webview messages through the same handler a UI click takes. Two traps hide on this surface, and they share one failure mode: the route answers {success:true} and nothing happens. An agent cannot detect the no-op from the response, so it reports success and moves on — the most expensive class of bug on this surface.

Trap 1 — read verbs return only {success:true}

Read verbs (get* / fetch* / load*) over the generic rail return only {success:true} — their data arrives on the WS hub, which an HTTP client cannot see. The call looks successful and returns nothing.

Use the dedicated GET endpoints instead: GET /kanban/board, GET /kanban/plans, GET /kanban/plan?planId=<id>. They return the data in the response body (wrapped in .data).

Trap 2 — exact webview field names

Raw verbs expect the exact webview message field names. The two that bite:

• triggerAction takes { sessionId, targetColumn } — not planId, not column.
• promptOnDrop takes { sessionIds, sourceColumn, targetColumn } — not planId, not column.

Wrong names (planId, column) make the arm silently no-op while the route layer still answers {success:true} — the call LOOKS successful and nothing happened.

Prefer the first-class endpoints (POST /kanban/dispatch, POST /kanban/move) — they validate, canonicalize columns, verify against the DB, and return honest errors. Use raw verbs only when no endpoint exists, and verify the effect afterwards (GET /kanban/plan?planId=<id> → check dispatchedAt and kanbanColumn).

4b. Prompt delivery (POST /terminals/verb/*) — attended coder driving

When you are a head agent driving a coder terminal (dispatch a subtask, get called back, review the diff, resend a fix) — not running an unattended column sweep — use the prompt-delivery verb pair. The behavioral rules are inlined in the enriched drive prefix built by _buildDrivePrefix in KanbanProvider.ts; the endpoints are:

(Note: POST /terminals/verb/ptyClearTerminal remains as a low-level host verb used internally, but POST /terminals/clear is the canonical agent-facing endpoint.)

ptySendPrompt delivery evidence & response fields

• success: true: Bytes were written to the pty and the submit CR was sent. It is not an echo, not a round trip, and not a claim that the CLI parsed anything.
• bytesWritten: UTF-8 byte length of text written to the terminal, including host-appended directive, seat, and standing-orders blocks. It is expected to exceed the length of your data field. A larger number is not evidence of corruption.
• promptSeq: That seat's delivery ordinal (post-increment promptCount). Re-reading promptCount on ptyListTerminals and seeing it advance past your promptSeq means a later send landed, not that yours did — your own evidence is the promptSeq on your own response.
• lastDataAt: The seat's output heartbeat from ptyListTerminals. It proves the CLI emitted something; it never proves the CLI received something.

Clear a coder the moment you stand it down, not on the way back in — the precondition is completion received and next work assigned elsewhere, and never clear your own terminal (see the inlined "Clear a terminal only when at rest" rule in the drive prefix).

Terminal Reset & Clear Protocol — why /clear via ptySendPrompt fails

Agents frequently try to clear a terminal by sending /clear through ptySendPrompt. This does not work, pollutes the prompt, and is rejected.

ptySendPrompt wraps data in bracketed-paste escape sequences (\x1b[200~ ... \x1b[201~). A CLI receiving bracketed-paste /clear treats it as literal text input, not a slash command. Inside the block it is absorbed as literal text and silently prefixes or pollutes the payload with appended orders. Sending bare slash commands like /clear via ptySendPrompt is rejected by the server with an error directing callers to POST /terminals/clear.

The canonical mechanism is POST /terminals/clear:

# Clear a single seat
switchboard api POST /terminals/clear '{"name":"<terminal friendlyName>","from":"<your terminal name>"}'

# Clear team terminals
switchboard api POST /terminals/clear '{"team":"<head terminal friendlyName or teamId>","from":"<your terminal name>"}'

Rules:

• from is required on all calls to prevent accidental caller context wipe.
• Clear a coder the moment you stand it down, not on the way back in. A clear issued at rest is what resets a coder you always send with clearBeforePrompt: false, and it lands long before the next dispatch instead of racing it.
• Never clear your own terminal.
• Never use ptyClearAllTerminals (it clears every active terminal, you included).

5. Comms (POST)

• POST /comment — { provider, id, body }: reply to a Linear/Notion/ClickUp remote-control card.
• POST /phone-a-friend — { planFile, originRole? }: notify a second-pass terminal at batch end.

6. Integration proxies (POST)

Passthrough to the tracker APIs using Switchboard's stored tokens (you never see the tokens):

• POST /api/clickup, POST /api/linear — raw API proxy.
• GET /resolve/<clickup|linear>/name/<name>, GET /metadata/<clickup|linear>, /task/*, POST /doc/clickup, POST /diagram/generate — see the clickup_api / linear_api skills.

7. Workflow A — fleet coding/review agent inside a worktree

You were dispatched into a worktree to code or review one plan. You report back to your head agent via ptySendPrompt (installed as a standing order on every team member). You do not have a chat channel to Mission Control; you use HTTP for board reads.

# 1. Find your plan (its planId is in your dispatch prompt) and read its full spec.
switchboard api GET "/kanban/plan?planId=$PLAN_ID" --json | jq -r '.result.data.content'

# 2. Do the work in this worktree. Commit as you go (Mission Control verifies via git, not chat).

# 3. Report back to your head agent when done (the standing order installed on dispatch).
#    The head agent or the extension's turn-end notifier will signal Mission Control.

You do not move your own card or merge — Mission Control does that after verifying your git state.

8. Workflow B — external Mission Control driving the board

You are an external agent acting as Mission Control. Mirror the in-VS-Code persona (switchboard-mission-control): coding + code-review only; planner-stage questions escalate to the human.

# 1. Read the whole board on each wake.
switchboard api GET /kanban/board --json | jq '.result.data'

# 2. Group loose plans into features (the external equivalent of group-into-features).
switchboard api POST /kanban/feature '{"name":"Checkout v2","planIds":["id1","id2","id3"]}'

# 3. For each feature, read its subtasks + message the team leads (or dispatch to your own agents).
switchboard api GET "/kanban/plans?featureId=$FEATURE_ID" --json | jq '.result.data'
switchboard api POST /terminals/verb/ptySendPrompt "{
  \"name\":\"<lead terminal friendlyName>\",
  \"data\":\"You are leading the <feature name> feature. Your PLAN REVIEWED subtasks are: <list>. Implement each, commit, and report back when done.\",
  \"origin\":\"<your own terminal friendlyName>\",
  \"clearBeforePrompt\":false,
  \"kind\":\"dispatch\",
  \"dispatch\":{\"planId\":\"<featurePlanId>\",\"role\":\"lead\"}}"

# 4. On each wake: VERIFY VIA GIT, not self-report. A subtask is "coded" only when its worktree
#    branch is ahead of base with committed work. Use the base_branch from GET /worktree/list.
switchboard api GET /worktree/list --json | jq -r '.result.data[] | [.path, .base_branch] | @tsv' |
while IFS=$'\t' read -r wt base; do
  echo "$wt: $(git -C "$wt" rev-list --count "${base:-main}"..HEAD 2>/dev/null) commits ahead"
done

# 5. Advance verified cards; escalate planner-stage questions to the human.
switchboard api POST /kanban/move "{\"planId\":\"$PLAN_ID\",\"targetColumn\":\"CODE REVIEWED\"}"

# 6. When all of a feature's subtasks are CODE REVIEWED, merge the feature's single shared
#    worktree branch into main (per-feature model: one worktree per feature, so one merge —
#    git -C <main checkout> merge <feature branch>), then clean up the worktree.
switchboard api POST /worktree/cleanup "{\"branch\":\"$BRANCH\"}"

9. The truth rule

Trust git and board state, never an agent's self-reported "done":

• Coded = worktree branch ahead of base with committed work (git -C <wt> rev-list --count <base>..HEAD > 0) and a clean tree (git -C <wt> status --porcelain).
• Reviewed = the review stage genuinely passed and the card sits in CODE REVIEWED.
• Read board state via these endpoints; read ground truth via your own git commands.

9a. Fleet Completion Detection Recipe

When an operator asks you to monitor a fleet until completion, three concrete signals define "done". Check them in order; the first non-null/stopping signal wins.

1. Database signal — completedAt. completed_at is non-null on the plan record (written by POST /kanban/task/complete via setCompletedAt). Read it via GET /kanban/plan?planId=<id> → .data.completedAt. NULL means the team is still working — do not report completion.
   • The completed_at write is idempotent — a repeat POST /kanban/task/complete for the same planId returns the existing timestamp without re-writing. When polling, a stable timestamp is not a new event; do not re-report.
   • outcome is optional — a post with no outcome still completes the card. The post itself is the completion signal; prose does not gate it.
2. Queue signal — POST /kanban/queue/next. Returns 200 { success: true, dispatched: null, reason: "queue empty" } when no eligible staged cards remain — report and stop. (The response is wrapped in the standard success envelope; an agent parsing for a bare { dispatched, reason } object will not find it under res.data and may misread the response.)
   • There is no in-flight refusal: a card your team still holds does not block the pop. A re-dispatched card resets its completed_at and owner stamp; if the work is already done the dispatched agent reads the plan and says so — that is the intended cheap path, not an error.
   • To leave a resume hint for the next dispatch, append a checkpoint event (switchboard verb checkpoint '{"planId":"<id>","text":"…"}'). The next dispatch surfaces it in the prompt as advisory resume context; it never gates dispatch.
3. Git signal — Switchboard-Plan trailer. A commit on the integration branch (main or the feature's shared worktree branch) carrying the git trailer Switchboard-Plan: <planId> (one line per planId in a batch dispatch), preceded by Switchboard-Stage: <stage>. The trailer block requires a blank line before it (git only parses trailers in the message's final paragraph). Verify with:

   git log --format='%(trailers:key=Switchboard-Plan,valueonly)'

All three are ground truth; an agent's self-reported "done" is not. Trust the database timestamp, the queue response, and the git trailer — never a chat claim.

10. Failure modes

• SWITCHBOARD_NOT_RUNNING — port file missing or /health fails → tell the user to start the extension. Never edit kanban.db directly.
• 404 — plan/feature/worktree not found (bad id).
• 400 — invalid input (bad column, empty body, path-traversal slug); the message names the problem.
• 409 — create_plan slug already exists.
• 503 with code: "STORE_UNAVAILABLE" — the board or archive store did not answer (tier says which). This is NOT an empty board and NOT a missing card. Retry once after a few seconds, then stop and report — do not loop on a store that is down, and do not act as though the board were empty.
• 503 without that code — extension not ready yet → retry after a short delay.

11. File-based fallback (no HTTP)

If the API server is down you can still communicate via the filesystem (Mission Control reads these):

• Session file: .switchboard/mission-control/session.md — the current session file (Rules + append-only Log); read it to see Mission Control's decisions. The legacy .switchboard/mission-control/session-log.md is still honoured as a fallback by GET /mission-control/session-log on installs that have one.
• Progress: .switchboard/mission-control/progress.json — Mission Control's per-plan stall state.

Reports channel — switchboard reports

A report is a host-recorded turn-end event stored in the plan_events table (event_type turn_end), not a file. The host writes a row on every turn-end (finished, blocked, stalled), joined to the card's current kanban column. This is not an HTTP surface — there is no GET /mission-control/reports endpoint. Read reports via the CLI:

switchboard reports [--kind blocked|finished] [--limit N] [--json]

• --kind blocked filters to blocked turn-ends (a seat went quiet or a feature stalled).
• --kind finished filters to finished turn-ends (a seat completed its turn).
• The output includes each card's current kanban column, so you can tell whether a formerly blocked card is still blocked.
• A row whose card was deleted or archived still appears, with [no card] — the record survives its card.
• Rows are pruned by the retention service; the accumulation that 1900+ files became cannot recur.
• Every row on this channel is host-written; the row carries no from field. Agent-authored reports are a separate path (team reports via GET /teams/<id>/reports), not this channel.
• The old file-based channel (.switchboard/mission-control/reports/) is retired. Existing files remain as archival evidence; no code reads or writes them.

Notes

• localhost only (127.0.0.1) — never a public interface.
• Reads wrap payloads in .data; mutations return { success, ...fields }.
• This surface is documented for external tools; the in-VS-Code Mission Control persona is switchboard-mission-control.

Remote & Mobile Network Addressing (Tailscale)

When the operator machine is reachable over Tailscale, the board and terminals are addressable at http://100.x.y.z:7777 (the Tailscale IP, port from the live server). SSH access to the host requires key-based authentication when password auth is hardened — the operator must have a registered SSH key, not a password.

Tailscale IS the network boundary. The API server must never be exposed on a public interface. Tailscale's encrypted mesh is the controlled boundary that replaces exposing a port to the open internet; it is not a hole in the localhost boundary, it is the boundary itself.