switchboard-orchestration

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 an orchestration worktree, or an external orchestrator (Cursor / Zed / Claude Code / Antigravity) driving the whole 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.

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 skill. Never consult that skill for invocation; never consult this skill for behavior conventions.

---

1. Bootstrap

# The port is written to a file at extension startup.
PORT=$(cat .switchboard/api-server-port.txt)
BASE="http://127.0.0.1:$PORT"

# Confirm Switchboard is up before anything else.
curl -s "$BASE/health"     # -> { status: 'ok', port, roots: [...] }

If .switchboard/api-server-port.txt is missing or /health fails, Switchboard is not running — tell the user to open the workspace in VS Code with the Switchboard extension active. 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), pass Authorization: Bearer <token>; if none is set, any localhost request is accepted.

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 DB/extension not ready, 500 handler error.

---

2. Read endpoints (GET)

curl -s "$BASE/kanban/board"
curl -s "$BASE/kanban/plans?column=PLAN%20REVIEWED"
curl -s "$BASE/kanban/plan?planId=a1b2c3d4"      # includes .data.content (the .md file)
curl -s "$BASE/kanban/features"
curl -s "$BASE/worktree/list"

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

---

3. Plan lifecycle (POST / PUT / DELETE)

# Create — returns { success:true, planId, planFile, slug }
curl -s -X POST "$BASE/kanban/plans" -H "Content-Type: application/json" -d '{
  "title": "Add rate limiting to the API",
  "complexity": "5",
  "tags": "backend, api",
  "body": "Add token-bucket rate limiting to the public endpoints."
}'

curl -s -X PUT "$BASE/kanban/plans/project" -H "Content-Type: application/json" \
  -d '{"planId":"a1b2c3d4","project":"Platform"}'

curl -s -X DELETE "$BASE/kanban/plans?planId=a1b2c3d4"                    # DB row only
curl -s -X DELETE "$BASE/kanban/plans?planId=a1b2c3d4&deleteFile=true"    # also remove the file

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 | LEAD CODED | CODER CODED | INTERN CODED
#                    | CODE REVIEWED | ACCEPTANCE TESTED | COMPLETED   (see GET /kanban/columns)
curl -s -X POST "$BASE/kanban/move" -H "Content-Type: application/json" \
  -d '{"planId":"a1b2c3d4","targetColumn":"CODE REVIEWED"}'

curl -s -X POST "$BASE/kanban/feature" -H "Content-Type: application/json" \
  -d '{"name":"Auth Refactor","planIds":["id1","id2"],"description":"Group the auth work."}'

---

4a. Oversight pass (POST/GET) — attended column-oversight engine

The in-extension attended oversight pass (switchboard.md §6/§6a/§7) — the supervising manager starts it, polls status in short turns, and produces the digest; the extension runs the two-lane state machine on the GlobalPlanWatcherService plan-file-mtime completion signal (the activity-light OFF-switch). Requires the running extension; absent in headless/test harnesses (503).

Queue semantics (resolved once at start, in code AND prose):

• queue.planIds → explicit list IS the queue, in given order, feature subtasks included (only feature container rows are rejected). §6a.
• queue.sourceColumn → column sweep, oldest first, excluding feature rows AND feature subtasks (subtasks carry their own kanban_column). §6.

Two overlapping lanes (engine-encoded, not prose-enforced):

• Coding lane WIP-1, review-gated by default for explicit lists (reviewGate defaults true when planIds is supplied, false for column sweeps). cardStage = coding → review. targetColumn omitted/"auto" ⇒ complexity auto-routing.
• Planner lane overlaps the coding lane with a ≥cooldownMs (default 120000) cooldown measured from the previous planner dispatch's completion signal.

Halt / resume / singleton:

• Halt-on-failure: any dispatch failure or stuck-timeout halts the WHOLE pass — never re-dispatch, never skip silently, never move a card backward. state: "halted" + haltReason.
• The extension is the sole writer of .switchboard/oversight-state.md (rewritten per state change) and oversight-log.md (append-only). Agents read them for the resume offer and digest; never write them. The state file is deleted only after the final pass-summary log line; on halt it is kept.
• On extension reactivation the engine resumes an in-flight pass from oversight-state.md without re-dispatching the in-flight card.
• Never arms /orchestration/start (separate unattended mode).

# Start an explicit-list pass (the list IS the queue, feature subtasks included)
curl -s -X POST "$BASE/oversight/start" -H "Content-Type: application/json" -d '{
  "workspaceRoot": "/repo",
  "queue": { "planIds": ["a1b2c3d4", "e5f6g7h8"] },
  "stage": "coding"
}'

# Start a column sweep (excludes feature rows and feature subtasks)
curl -s -X POST "$BASE/oversight/start" -H "Content-Type: application/json" -d '{
  "workspaceRoot": "/repo",
  "queue": { "sourceColumn": "CREATED" }
}'

# Poll in short turns
curl -s "$BASE/oversight/status?workspaceRoot=/repo"

# Cancel
curl -s -X POST "$BASE/oversight/stop" -H "Content-Type: application/json" -d '{"workspaceRoot": "/repo"}'

---

5. Comms (POST)

POST /orchestrator/request — fleet agent → orchestrator

File a question / warning / research request / blocker. The extension writes it to .switchboard/orchestrator/inbox/; the orchestrator drains it on its next wake.

curl -s -X POST "$BASE/orchestrator/request" -H "Content-Type: application/json" -d '{
  "stage": "coder",
  "type": "blocked",
  "from": "coder-worktree-3",
  "planId": "a1b2c3d4",
  "feature": "Auth Refactor",
  "worktreePath": "/repo/.worktrees/auth-refactor-3",
  "body": "The mock DB does not implement the new transaction interface. Update the mock or skip the integration tests?"
}'

• Required: stage (planner|coder|reviewer), type (question|warning|research|blocked), body.
• Optional: from, planId, feature, worktreePath.
• Do not use this for routine progress — the orchestrator reads git/board state directly.

Other comms

• 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 do not have a chat channel to the orchestrator; you use HTTP.

PORT=$(cat .switchboard/api-server-port.txt); BASE="http://127.0.0.1:$PORT"

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

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

# 3. Hit a blocker or ambiguity? File a request — then continue or stop per its severity.
curl -s -X POST "$BASE/orchestrator/request" -H "Content-Type: application/json" -d "{
  \"stage\":\"coder\",\"type\":\"question\",\"planId\":\"$PLAN_ID\",
  \"from\":\"$(basename "$PWD")\",\"worktreePath\":\"$PWD\",
  \"body\":\"Should the cache be per-tenant or global?\"}"

# 4. Check whether the orchestrator answered (it replies in the session log / a reply file).
curl -s "$BASE/orchestrator/session-log" | jq -r '.data' | tail -40

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

---

8. Workflow B — external orchestrator driving the board

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

PORT=$(cat .switchboard/api-server-port.txt); BASE="http://127.0.0.1:$PORT"

# 1. Read the whole board on each wake.
curl -s "$BASE/kanban/board" | jq '.data'

# 2. Group loose plans into features (the external equivalent of group-into-features).
curl -s -X POST "$BASE/kanban/feature" -H "Content-Type: application/json" \
  -d '{"name":"Checkout v2","planIds":["id1","id2","id3"]}'

# 3. For each feature, read its subtasks + fan out (or dispatch to your own agents).
curl -s "$BASE/kanban/plans?featureId=$FEATURE_ID" | jq '.data'
curl -s -X POST "$BASE/kanban/orchestration/dispatch" -H "Content-Type: application/json" \
  -d "{\"featurePlanId\":\"$FEATURE_ID\",\"workspaceRoot\":\"$PWD\"}"

# 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.
curl -s "$BASE/worktree/list" | jq -r '.data[] | [.path, .base_branch] | @tsv' |
while IFS=
#x27;\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.
curl -s -X POST "$BASE/kanban/move" -H "Content-Type: application/json" \
  -d "{\"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.
curl -s -X POST "$BASE/worktree/cleanup" -H "Content-Type: application/json" \
  -d "{\"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.

---

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 — DB/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 (the orchestrator reads these each wake):

• Inbox: write .switchboard/orchestrator/inbox/req-<UTC>-<stage>-<rand>.md — YAML frontmatter (from, stage, type, planId, feature, worktreePath, created) + body below ---.
• Session log: .switchboard/orchestrator/session-log.md — append-only; read it to see the orchestrator's decisions.
• Progress: .switchboard/orchestrator/progress.json — the orchestrator's per-plan stall state.

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 orchestrator persona is switchboard-orchestrator.