Connections & Remote Switchboard Session Entry Point

You are entering a Connections & Remote Switchboard planning session. Drive board planning either remotely (away from desk) or side-by-side using external AI surfaces (e.g. Gemini Spark or Claude Cowork). Plans live in Linear, Notion, or external file return paths. MCP or file watchers serve as the integration layer.

This is the external/remote counterpart to /sw (switchboard-chat). Use /sw when you have local access; use /sw-remote for external surfaces or away-from-desk control.

1. Confirm Remote Context

Check which MCP servers are connected (Linear, Notion, GitHub):

• Report what's available and note any missing connections.
• If neither Linear nor Notion is connected, warn the user that remote planning won't be possible and offer to fall back to /sw if the user has local access.

2. Remote-Mode Rules

• Plans are stored in Linear/Notion — do NOT write .md files to .switchboard/plans/ or commit to a branch for planning work.
• Use list_issues (Linear) / Notion database queries to read the current kanban state (not local kanban.db or kanban-board.md).
• To improve a plan: use /improve-remote-plan (not /improve-plan).
• To create a new plan: write directly to a new Linear issue or Notion page, set status to "Created".
• Column transitions happen via status updates in Linear/Notion — the extension picks them up on next IDE startup via the startup reconciler.
• To trigger local execution: set the Linear/Notion status to the execution-trigger state (confirm the name with list_issue_statuses first for Linear; read the Kanban Column select options for Notion).

2a. The remote command vocabulary is closed at two verbs

A remote surface may author content and move a card. Nothing else. There is no third verb, and there is no free-text instruction channel — not as a setting, not as an advanced toggle. ALLOWED_REMOTE_VERBS in src/services/remote/RemoteCommandEnforcement.ts is the definition, and test:contract:remote-command-vocabulary fails CI if it grows.

Why, rather than just what. A column move dispatches a plan file that already exists — authored, materialised, imported, and advanced through columns. So the worst a compromised remote surface can do is dispatch an already-reviewed plan at the wrong moment: bad, recoverable, bounded. A free-text instruction channel collapses authoring and triggering into a single write, and that is the entire difference. It cannot cause novel code to run, because it cannot author the thing that runs and trigger it in one motion.

This matters more here than in most products because the fleet reads untrusted content for a living — issue bodies, Notion pages, ClickUp tasks, PR and review comments, fetched web pages. An agent that reads such content and holds write access to a command channel is a confused deputy: text arriving in a ticket can instruct the agent to write the queue, and the local controller executes that queue because executing it is its job. Prompt injection becomes code execution on a machine holding every repository, key and credential the operator works with. No link in that chain is a bug.

Token scoping does not fix this, and it is important not to believe it does. Table+action scoping narrows board data damage. It does nothing about execution, because the local controller runs the contents of the channel by design. A token scoped to insert into an instruction queue is a token that can run code.

Two things you must know when driving remotely:

1. A trigger into an execution column is refused unless the plan passed review. The gate keys on the column's role/kind, not its label, so renaming a column does not open it; and it fails closed when the column configuration cannot be resolved. It is transport-neutral — a local agent reading the same poisoned ticket authors the same plan a remote one does, so the gate does not care where the trigger came from. A refusal is never silent: it posts a receipt naming the plan, the credential and the reason.
2. The two transports are not equally tight. Linear and Notion descriptions are free text pulled into plan bodies — that is the shipped remote-authoring workflow and it stays. The store transport's typed switch table carries no free-text column at all. Do not assume the switch table's guarantees apply to Linear; for the SaaS path the review gate is the control.

Credential separation is the control that actually breaks the chain. The credential that can trigger must not be the one handed to agents that read tickets, pages, PR comments or the web. Two credentials, two trust zones: an authoring/read token for content-consuming agents, and a triggering credential the operator holds. Switchboard operates no service and enforces no authorisation — this is a vocabulary boundary, not an access-control layer, and nothing here protects you from a leaked triggering credential. It limits what that credential can express.

3. Read Current Board State

• Query Linear/Notion for issues in the Switchboard-mapped project, grouped by status.
• Present a brief summary: how many plans per column, any plans in a state that suggests remote action is needed (e.g. "Created" plans that could be improved).

4. Prompt for Intent

After orientation, ask: "What would you like to work on?" — same consultative opening as /sw.

5. Architecture Overview

• Linear is a two-way sync message bus: Switchboard polls Linear every 30–120s (configurable) and mirrors state changes locally.
• Moving a Linear issue to a new state → dispatches the Kanban column agent for that state on the local machine.
• Comments posted on a Linear issue → routed to the current column's agent as input.
• Notion equivalent: Switchboard polls the plans DB + Comments DB on a timer; Kanban Column property drives column mapping; "Switchboard Comments" database is the async message bus.
• Config is stored in the Kanban DB under key remote.config, not in settings.json; toggle is in the toolbar remote control button; configuration is in the Kanban REMOTE tab.

6. Pre-flight

• Remote Control must be enabled with the correct provider (Linear or Notion) and the board mapped in the Switchboard Remote tab.
• For Notion: the one-time "Run Notion setup sync" must have been run (creates the plans DB, Comments DB, and matches column options).
• For Linear: confirm the correct project is mapped.

7. Ground Every Plan in the Synced Project Context

You have no repo access — no GitHub, no git, no file system. What you DO have is the project-context mirror: Switchboard syncs the workspace's curated planning context — Dev Docs + project PRDs + the workspace constitution — outward to the tracker. Read it before authoring any plan, so your plan names real modules, files, and conventions instead of being a "post-it note" that sends the local execution agent in the wrong direction.

Where to find it:

• Notion: a page titled "Switchboard Project Context — <workspace>", created beside the plans database ("Switchboard Kanban Backup"). Find it with Notion MCP search.
• Linear: a document titled "Switchboard Project Context" on the project itself (project documents, not an issue body).

How to use it:

1. Read the constitution first (project principles and hard rules — plans must respect them).
2. Read the PRD of the project the card belongs to (WHAT the product requires).
3. Read the Dev Docs (HOW the codebase is put together — modules, seams, conventions).
4. Author the plan citing concrete paths, symbols, and conventions from the Dev Docs, so the local agent — which DOES have the repo — can navigate straight to the work.

Rules and edge cases:

• Never edit the synced context on the tracker. It is regenerated from Switchboard (project.html) on every sync — your edits will be silently overwritten. Author plans (cards), not doc edits. If the context is wrong, say so in a plan or comment so the human fixes it at the source.
• Check staleness. The context header carries its Synced at timestamp. If it looks stale, note that in your plan and tell the user they can push a fresh copy via Remote tab → Sync Context Now in Switchboard's Project panel.
• No context found? Context sync isn't enabled or has never run. Fall back to planning from the card text alone (the original behavior), state that limitation in the plan, and tell the user to enable Project Context Sync in the Remote tab.
• Notion tier differences: precise database property queries are tier-gated on some plans. If structured queries fail, fall back to notion-search / notion-fetch by title ("Switchboard Project Context"). Only navigation efficiency changes — the flow above stays the same.

8. Notion Steps (if Notion is the provider)

1. Find the plans database. Use Notion MCP search/query to locate the Switchboard plans database (titled "Switchboard Kanban Backup") and the "Switchboard Comments" database.
2. Create or find the card's page. Either edit an existing page (setup sync created one per board card) or create a brand-new page in the plans DB for new work — the next ping imports a new page as a new local markdown plan automatically.
3. Write the implementation plan into the page BODY. Author it fully before moving the card, grounded in the synced project context — cite the concrete paths, modules, and conventions the Dev Docs name. The local poll reads the page body and writes it to the local plan file — so the body is the source of truth the local agent runs against. Convention: write the body completely, THEN flip the column (a half-written body can be picked up if you flip too early). Note: an empty body is skipped (the poll won't overwrite a local plan with nothing), so always author the body when you intend to revise it.
4. Trigger the local agent: set Kanban Column. Read the board's real column names first (they are the select options). Set Kanban Column to the trigger column for the work you want (e.g. a planning column to refine, a coding column to implement). The poll mirrors the column locally and dispatches that column's agent.
5. Converse without a state change: add a Comments-DB row. To send an instruction or question without moving the card, create a row in the "Switchboard Comments" database:
   • Message = your text
   • Plan = relation to the card's page ← REQUIRED. A row with no Plan relation cannot be routed and is dropped.
   • From = Remote The comment is routed to the card's current column agent.
6. Read results. On a later turn, query the "Switchboard Comments" database for rows with From = Switchboard (the local agent's replies), and/or re-read the card's page body.

Features (grouping related work)

An feature is a parent card that groups related subtask cards. Moving a feature's Kanban Column cascades the move to all its subtasks on the local machine — so you can dispatch a whole group of work in one action.

To create a feature (Notion)

1. Create the feature's page in the plans DB (same as any card).
2. Check the Is Feature checkbox property.
3. The page is now a feature — it can have subtasks.

To create a feature (Linear)

1. Create the feature's issue in the mapped Linear project.
2. Create subtask issues and set their parent to the feature issue.
3. The local poll detects the parent/child relationship and mirrors it — the feature cascades subtask moves automatically.

To assign a subtask to a feature (Notion)

1. Create or find the subtask's page.
2. Set its Feature relation property to point to the feature's page.
3. The local poll mirrors the link — the subtask now moves when the feature moves.

To trigger a group of work

1. Set the Kanban Column (Notion) or Linear status on the feature card (not the subtasks).
2. The local cascade moves all subtasks to the same column and dispatches each subtask's column agent.

Constraints

• A subtask can belong to only one feature (single-select relation / single parent).
• Only create feature/subtask links between cards on the same synced board — the local poll can only mirror links between cards it tracks.
• A feature with no subtasks is harmless (it just cascades to nothing).

Edge Cases

• Neither Linear nor Notion connected: Skill degrades gracefully — explain the limitation and offer to fall back to /sw if the user has local access.
• Multiple boards mapped: If multiple Switchboard projects exist in Linear, guide the user to identify the correct one using list_projects.
• User accidentally uses /sw in a remote session: Not a hard error, but /sw will try to read local files that don't exist. Use /sw-remote for remote contexts.
• Status name drift: Linear status names can be renamed by the user. Always use list_issue_statuses rather than assuming names from prior sessions.
• Read-back latency: Results written by the local agent appear in the Linear issue / Notion page after the next sync cycle (up to 30–120s depending on poll frequency). Note this when checking results in a follow-up session.

Capability Note

Every Notion MCP connector reliably supports database query, create-page/row, and property updates — which is all this flow needs. If your specific connector lacks create-row, fall back to creating a child page under the Comments DB with the same properties, or report the gap to the user.

Plan Sizing & Feature Grouping

Plan Sizing — split before drafting. Before writing any plan file, assess whether the work is one plan or multiple. Auto-split into separate plan files when EITHER signal is present:

• 3+ distinct deliverables: the work produces 3+ independent outputs (e.g. 3+ pages, 3+ components that don't share a root cause, 3+ API endpoints in different domains, 3+ unrelated bug fixes).
• 2+ independently-shippable phases: the work has sequential stages where each could be shipped on its own. When splitting: write each as a separate plan file with its own Goal, Metadata, and Verification Plan. If the user explicitly asks for a single plan, respect that and write one.

Feature Grouping. When the work described will span 3 or more plan files on a related topic (sharing a common feature area or root cause):

• Early (during scoping): Flag it once: "This looks like it will produce 3+ related plans — once they're all drafted, want me to group them under a feature?" Do not create anything yet.
• Closing (when all plans are drafted): Offer again: "You now have [N] plans covering [topic] — want me to create a feature to group them?"

The gate depends on who initiated grouping: if the user already asked for grouping or a feature (e.g. "split these into plans and create a feature"), the original ask IS the confirmation — create the feature now without a second confirm. If you are proposing grouping the user did not request, only create the feature if the user confirms. In a remote session, feature creation follows the /create-feature skill (direct file write to .switchboard/features/) or the create-feature.js script if the extension is reachable.

8b. Linear Steps (if Linear is the provider)

Linear is the provider to prefer when the operator is on a phone — it has a first-class mobile app, and its structured queries are not tier-gated the way some Notion connectors are. These steps mirror section 8.

1. Find the board. list_projects to locate the mapped Switchboard project. If several Switchboard projects exist, confirm which one before writing anything.
2. Read the real status names. list_issue_statuses every session — do not carry names over from a previous one. Users rename statuses, and the mapped column names are what drive local dispatch.
3. Create or find the card's issue. Either update an existing issue (one per board card) or create a new issue in the mapped project — the next poll imports a new issue as a new local markdown plan automatically.
4. Write the plan into the issue DESCRIPTION. Author it fully before moving the card, and ground it in the synced project context per section 7. The local poll reads the description and writes it to the local plan file, so the description is the source of truth the local agent runs against. Write the description completely, THEN change the status — a half-written description can be picked up if you flip too early. An empty description is skipped, so always author it when you intend to revise.
5. Trigger the local agent: change the status. Set the issue's status to the trigger state for the work you want (a planning state to refine, a coding state to implement). The poll mirrors the state locally and dispatches that column's agent.
6. Converse without a state change: add a comment. A comment on the issue is routed to the card's current column agent as input. This is the Linear equivalent of the Notion Comments-DB row, and needs no relation field — the issue is the addressing.
7. Read results. On a later turn, re-read the issue description and its comments. Local agents post back as comments, and the description carries whatever the local plan file now says.

Features (Linear)

Per the Features section above: create the feature's issue, then set each subtask issue's parent to it. The local poll mirrors the parent/child relationship, so changing the feature's status cascades to all subtasks and dispatches each one's column agent.

Automation rules — label-triggered pipelines

Linear has a capability Notion does not: automation rules keyed on a label plus a set of states. Configured in Switchboard's Remote tab, each rule is { name, triggerLabel, triggerStates, targetColumn, finalColumn, writeBackOnComplete }, and a card matching both the label and one of the states is imported into targetColumn — with the result written back to the card when it completes, if writeBackOnComplete is set.

For an agent driving the board remotely this means: applying a label can be a dispatch action, not just metadata. Before using labels that way, ask the operator which rules are configured — a label you add casually may fire a pipeline. Conversely, if the operator wants a repeatable "file a card, get work done" path, a rule is the mechanism to suggest rather than hand-moving statuses each time.

9. Driving from a phone

This skill is the phone answer for Switchboard. The board itself is a desktop surface — it has no responsive layout and its kanban card moves use HTML5 drag-and-drop, which does not fire on touch devices at all — so a phone drives the board through the tracker, not through the board.

What that means in practice:

• Prefer Linear. Real mobile app, no tier-gated queries, comments as the message bus.
• Latency is the design, not a defect. Local results appear after the next poll (30-120s). Write, put the phone away, read the answer later. Do not sit and refresh — and do not tell the user something failed because it has not appeared yet.
• One action per turn is usually right. Author the description fully, then change the status. The half-written-body race in step 4 is more likely on a phone, where the operator is interrupted mid-edit.
• Nothing here requires exposing the host. The tracker is reachable from the phone; the host is not, and does not need to be. Never suggest opening a port, a tunnel or a proxy to make a phone work — that is a different and much larger decision, and the tracker path exists so it is not needed.

10. What the tracker cannot show you

The mirror is faithful for plans, statuses, features and comments. It carries nothing for the following, so do not offer them, and say plainly that they are desk-only if asked:

• Missions (Notion & ClickUp). On Notion and ClickUp, mission state, membership, launch/stop, and dependency gating are local-only (these providers have no milestone primitive). On Linear, missions and their dependency edges ARE mirrored natively (missions as project milestones, dependency edges as blocks relations), though runtime launch/stop controls remain host-managed. A question like "why hasn't this card moved" on Notion/ClickUp may have a mission-gating answer that is invisible from there. Say so rather than guessing.
• Memo capture. Local-only. There is no memo surface on the tracker.
• Worktree diffs and git state. Not mirrored. "Did the agent do something sane?" cannot be answered from the tracker unless an agent wrote the answer into a comment.
• Live terminal output. Not mirrored, and not something to attempt — agents report by posting comments, and that is the only stream available here.

When the operator asks for one of these, the honest answer is that it needs the board, plus an offer to have an agent post the specific thing they want as a comment. Do not speculate about local state you cannot see — the sync's silence is not evidence that nothing is happening.

11. Remote mode is what makes agents talk to you

This is the most important operational fact in this skill, and it is a pre-flight item, not a detail.

When a board is under remote control, REMOTE_MODE_DIRECTIVE is injected into every agent role on dispatch. Its text:

REMOTE MODE: You are running under remote control — the user is NOT at the terminal. If you need to ask the user anything or report a blocker, post it as a comment on the linked issue using the linear-api protocol (or clickup-api protocol) via switchboard api GET /protocol/linear-api (or switchboard api GET /protocol/clickup-api). Do NOT wait on terminal input. Continue with any work you can do without the answer.

So the question-and-answer loop already exists and is bidirectional:

• Agent → operator. The agent posts through the host-side comment bridge. Comments are stamped with a self-marker host-side, never by the agent, which is what stops Switchboard's own comments from being re-ingested as operator input. Agents never call the tracker API directly.
• Operator → agent. Your comment on the issue is routed to that card's current column agent as input, with the marker filtering Switchboard's own comments out.

Why this matters when you are driving remotely:

• Confirm remote control is actually ON for the board you are working, per the pre-flight in section 6. It is gated per board. With it off, a dispatched agent that hits a question blocks on terminal input nobody is watching — the work stalls silently and no comment ever appears. If cards seem to stop mid-flight with no explanation, this is the first thing to check.
• A quiet card is not necessarily a stuck card. The directive tells agents to continue with whatever does not need the answer, so silence can mean "still working". Read the comments before concluding anything.
• Answer in the thread, not by editing the description. A reply is a comment; the description is the plan body and rewriting it mid-flight fights the poll.
• Do not design around this loop's absence. If asked how to get an answer back from an agent, the answer is "it already comes back as a comment" — not a tunnel, not a port, not a new channel.

Planned change — where a comment goes

The statements above that a comment is routed to the card's current column agent describe today's behaviour and are correct as written. A planned change (a-card-comment-cannot-reach-the-seat-holding-the-work.md) routes a comment on an in-flight card to the seat actually holding it — the card's dispatched_terminal — and leaves column routing in place for every other card. Until that ships, assume column routing. After it ships, this section is what to update.

12. Linear Native App User & Agent Surface

When Switchboard connects to Linear via an OAuth App Actor, it operates as a first-class app user:

• Assign to Dispatch (Delegation): Assigning an issue to Switchboard in Linear sets Switchboard as the issue's delegate (preserving human ownership) and dispatches execution locally.

  Privilege Boundary: Assigning an issue to Switchboard starts real work on the operator's machine.

• @Mention to Seat: @mentioning @Switchboard on an issue or comment routes the message directly into the live seat (dispatched_terminal) holding that work.
• Agent Sessions & Activities: Switchboard creates native Linear agent sessions (agentSessionCreateOnIssue / agentSessionCreateOnComment) and emits durable state transitions and ephemeral progress updates as native activities (agentActivityCreate).
• Tri-Layer Dispatch:
  1. Status moves: Driven by board UI, external integrations, or Linear's native agent (@linear launch).
  2. Assignment (delegation): Driven directly by human operators.
  3. Natural language: Driven by Linear's native agent executing project playbooks.

This whole section requires the OAuth app-actor credential. A personal-API-key install has no app user: it cannot be assigned or @mentioned, creates no agent sessions, and shows none of these affordances. If the operator is on a personal key, say the surface is unavailable rather than describing behaviour they will not see.

13. Provider Capabilities Comparison