switchboard
AGENTS.md5 starsChanged 2 months agoApache-2.0View on GitHub
Switchboard is an agent gateway: Slack, the CLI, HTTP or MCP sends a message; a dispatcher routes it to an agent, whose provider-backed run uses tools through an executor it never touches directly. Slack is one channel, not the architecture. Read this first. Details: README.md, docs at <https://switchboard.space> and the behavioral specs.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- address-review-findingsSkill
- code-review-and-qualitySkill
- doubt-driven-developmentSkill
- incremental-implementationSkill
- performance-optimizationSkill
- pr-descriptionSkill
- re-review-deltaSkill
- security-and-hardeningSkill
- spec-driven-developmentSkill
- test-driven-developmentSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 5
Read this first. Details: README.md, docs at <https://switchboard.space> and the behavioral specs.
- Very specific: line 112
The spec follows the code, never the reverse: Do not rename a test to satisfy a spec row.
- Distinctive: line 114
One coherent change per PR, rewritten before review: No fix-up trails; names and types tell the truth.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Switchboard — the operating contract
Switchboard is an agent gateway: Slack, the CLI, HTTP or MCP sends a message; a dispatcher routes it to an agent, whose provider-backed run uses tools through an executor it never touches directly. Slack is one channel, not the architecture.
Read this first. Details: README.md, docs at https://switchboard.space and the behavioral specs.
How a change is made
- The spec says what should be true. Each behavior has a row under
docs/reference/specs/: a criterion and proof (file::describe::it, a live procedure, or[gap]). Change the row with the code in the same PR. Stale specs are bugs. The review agent reads touched specs (specs:coverage) and reports contradictions as findings. - A failing test, then the code. Unit tests are the default proof. The loop is
npx vitest runon the test files you touched, by name, once before the push — never--changed, never a directory: on a moving base--changedis most of the suite. CI runs the full suite and typecheck when the change needs them. Local human session:npm testbefore pushing. npm run fix, then the checks the change needs.fixregenerates every generated artifact and repairs lint and formatting. CI selects checks and builds from the push's inputs, so a pipeline agent validates its own change at the changed-set scope (npx prettier --checkon the changed files,tsc --noEmit -pthe touched tsconfig underNODE_OPTIONS=--max-old-space-size=6144,npm run hygiene:check,npm run specs:check) and uses judgement beyond that. Local human session:npm run verifybefore requesting review — it runs every CI gate locally, and a unit test holds the workflow to those scripts.- A PR written for the reader. The title is the changelog line, 72 characters at most:
type(scope): what a reader can now do or expect, scope from the code map's Areas,!plus a migration note when it breaks (the rule); a required check refuses the rest. Body: the fixed-size map of pr-description.md; decisions and receipts fold below. Docs for changed behavior change in the same PR. - Use Switchboard for PR review unless the user instructs otherwise. Request
agent:reviewthrough native MCP. Watch and address findings, rewrite commits, and re-request at each new head until it has LGTM and no outstanding findings.LGTM:auto-approves where enabled; a person merges. - Squash-merge, release, deploy. The title is the commit. release-please accumulates a release PR; merging it tags the version and CI deploys only the Workers whose inputs changed.
Invariants
- The core never imports a platform SDK. Slack lives in
src/channels/slack.ts; the core seesChannelIOandIncomingMessage. Platform-specific? Extend a seam. - Every boundary is an interface with at least two implementations — channel, provider, executor, agent (as data), store. A new capability is a new implementation behind the seam, never a special case in the core.
- Authorization is one table, asked once per request, against the resolved actor and agent. Every command and every agent run passes
authorizeover the policy rows insrc/core/authz/; adapters resolve identity, never authority; no registry command starts an agent run — that isdispatch()'s job alone. - IDs are platform-namespaced (
slack:C…,slack:U…,slack:C…:<ts>). Config scopes, grants, and memory key on them; a new adapter brings its own prefix. - Tools never touch the host. They call
ctx.executor;LocalExecutoris the only place local process or file access is allowed; the bot never shells out togh— GitHub is the REST API on the App credential. - State survives restarts. Conversation context rebuilds from channel history; workspaces re-clone; anything durable lives in a store behind a seam. No in-memory state a restart loses silently.
- Model refs are
<provider>/<model>strings resolved through the config layers (directive > thread > user > channel > defaults), and effort rides the same layers. Never hardcode a model or an effort in an agent or the core.
Where things are
The user's nouns: the Vocabulary. Module by module: the Code map. The behavior each area must keep: its spec under docs/reference/specs/. The why behind it: the decision records. When they disagree with the code, one is wrong; the checks (specs:check, decisions:check, docs:check) say which.
Commands
Deterministic, non-interactive commands. Credentials are named when required. CI uses these commands.
<!-- generated:commands · npm run agents:gen — generated from package.json + project.json, do not edit by hand -->| Command | What it does | When |
npm run build | Compiles the bot to dist/. | check:dist and the Docker image run it; rarely by hand. |
npm run start | Runs the compiled bot from dist/. | Production entry (the container's CMD). |
npm run dev | Runs the bot from source with tsx. | Local development against a real Slack app. |
npm run typecheck | TypeScript over the bot and its scripts, no emit. | After type-level changes; verify:root runs it. A pipeline agent scopes it to the touched tsconfig. |
npm run test | The whole vitest suite from one entry, after deploy:gen. | Local sessions before pushing; CI runs it for relevant changes. |
npm run cli | Runs operator commands and sends asks through the dispatcher. | Smoke tests, deploys, config and run history. |
npm run resident:archive | Captures a retained resident and checks its offline restore. | Reviewed disposable rehearsal; verify the binding and builds. |
npm run resident:retire | Previews or retires one native scope. | When deploy is blocked. |
npm run emoji:sync | Downloads custom Slack emoji. | Manual; emoji:read. |
npm run verify | Runs all repository and workspace CI checks. | Local human checks; CI selects affected checks. |
npm run verify:root | Runs the bot package's CI gates. | Bot changes; agents use affected checks. |
npm run check:consistency | The sub-second checks that generated and declared things equal the code, this table included. | After touching a generated or declared artifact; one CI leg. |
npm run ci:gate | Accepts successful CI legs or planned skips. | CI fan-out gates. |
npm run ci:plan | Selects checks and builds from the full diff; uncertainty runs all. | CI; locally with -- --base <ref>. |
npm run fix | Regenerates every generated artifact and repairs lint and formatting. | Before committing; whenever check:consistency reports drift. |
npm run deploy:gen | Renders each Worker's gitignored wrangler.jsonc from its template and the profile in force. | test, each Worker's verify and deploy all run it; by hand before wrangler dev. |
npm run deploy:check | The rendered wrangler.jsonc files match deploy:gen. | When one looks hand-edited; change the template. |
npm run check:lockfile | Native packages carry Linux x64 and macOS arm64 variants; records mirror their package.json. | After a manifest edit or npm install; failures name the fix. |
npm run check:sandbox-pair | Each Worker on the cloudflare/sandbox image pins @cloudflare/sandbox to exactly its Dockerfile tag. | After bumping either half of a pair. |
npm run check:pr-title | Judges one PR title as the changelog line: grammar, type, scope, !. | -- "feat(scope): …" before opening a PR; CI's title check. |
npm run pr-title:gen | Writes the title gate's types and scopes from the release config and the code map. | Part of fix. |
npm run pr-title:check | The committed title vocabulary equals its two sources. | Part of check:consistency. |
npm run check:project-facts | Checks project names, URLs, contact and package metadata against project.json. | After project or community file changes; part of check:consistency. |
npm run check:registry-drift | Every example-config model ref still resolves against the pinned pi registry. | After a pi bump; part of check:consistency. |
npm run agents:gen | Writes the Commands table in AGENTS.md from package.json and this file. | After adding or changing a script; part of fix. |
npm run clock:gen | Regenerates both clock allowlists: wall-clock reads (empty) and duration literals outside src/core/budgets.ts. | Part of fix. |
npm run clock:check | No production file reads the wall clock directly or gained a duration literal outside src/core/budgets.ts; both allowlists match the tree. | Part of check:consistency. |
npm run agents:check | AGENTS.md is under its size budget, its Commands table is current, and every root script is described here. | Part of check:consistency. |
npm run lint | ESLint over the whole tree. | npm run fix repairs what it can. |
npm run lint:fix | ESLint with autofix. | Part of fix. |
npm run format | Prettier over the whole tree (not Markdown). | Part of fix. |
npm run format:check | Prettier in check mode. | Part of verify:root. |
npm run check:dist | Builds the bot, rejects test files in dist/, and checks required runtime files. | Local checks and the CI image build. |
npm run check:site | Checks dashboard links against the built site. | Docs changes; part of verify. |
npm run check:image | Builds every Worker's image. | After touching a Dockerfile; needs Docker. One CI leg per image. |
npm run skills:sync | Vendors the skills listed in skills/manifest.yaml. | After changing the manifest; part of fix. |
npm run skills:check | The vendored skills match the manifest byte for byte. | Part of check:consistency. |
npm run licenses:check | Every production dependency's license is on the allowlist. | After adding a dependency. |
npm run check:deps-drift | Installed node_modules match the lockfile: drift fails by name. | Part of check:consistency. |
npm run docs:gen | Writes the generated regions of the reference docs from the command registry. | After changing a command, flag, route, or config key; part of fix. |
npm run docs:check | The generated doc regions equal what the code would generate. | Part of check:consistency. |
npm run specs:check | Checks spec proofs, headers and decision boundaries. | After test/spec edits; see spec coverage. |
npm run specs:coverage | Maps changed paths to specs and lists gaps. | Before review: -- --changed origin/main...HEAD; -- --require fails on gaps. |
npm run decisions:check | Checks decision and plan status, succession and amendment rules. | Part of check:consistency; supersede or amend failed records. |
npm run hygiene:check | The public tree's imprint (company, people, trackers, plan ids, ids, dates) equals the recorded list, which only shrinks. | Part of check:consistency. New hit: rewrite the line or allow it by name. |
npm run hygiene:gen | Records the tree's remaining imprint after a scrub; refuses growth unless -- --force. | Part of fix; new imprint fails it like hygiene:check. |
npm run vocabulary:check | No internal word prints on a user surface; the baseline only shrinks. | Part of check:consistency; a hit is rewritten in the user's nouns. |
npm run vocabulary:gen | Records the remaining internal words; refuses growth unless -- --force. | Part of fix. |
npm run user-message:check | No user-facing statement delegates recovery. | Part of check:consistency; the baseline only shrinks. |
npm run docs:changed | Reports changed docs inputs. | One-commit diagnostics; CI uses ci:plan. |
npm run deploy:targets | Reports Workers selected by the diff. | CI summary and release PR comment. |
npm run docs:dev | Serves the docs site locally with live reload. | Writing docs; -- --port <n> picks the port. |
npm run docs:build | Builds the docs site to docs/.vitepress/dist. | Rarely by hand; verify -w docs and the docs Worker's deploy run it. |
npm run web:preview | Serves the dashboard bundle over fixtures for a visual check. | After a web/ change. |
npm run screenshots:gen | Renders changed dashboard captures in both themes and records input hashes. | Paused; enable websiteMaintenance in project.json. |
npm run screenshots:check | Each surface's inputs still hash to what its screenshots were rendered from — no browser. | Skips while website maintenance is paused. |
npm run load | Load harness for infrastructure and route checks. | Model capacity receipts. |
npm run smoke:ingress | Checks three deployment capability families; --check makes no network request. | Configured disposable scope; release acceptance. |
npm run staging:deploy | Deploys isolated staging; --recreate plans explicit recreation. | Staging CI and explicit operator setup. |
npm run installation:reset | Resets data; keeps settings. | Preview, then approved apply. |
npm run staging:reset | Tests two staging resets. | Manual staging CI. |
npm run staging:validate | Checks PR eligibility before staging. | Staging CI and queued-head recheck. |
npm run check:native-scope | Tests the native gate and kill. | Docker; see the containment plan. |
npm run staging:bootstrap-held | Installs Resident support and keeps maintenance held. | Manual staging CI; separate readiness artifact. |
npm run staging:recover | Recovers a held reset. | CI preview; approved continuation. |
<!-- /generated:commands -->Each workspace has its own verify (-w web|docs|deploy/<worker>|packages/switchboard); the root one runs them all.
Rules for agents
- Comments are for the stranger. Explain why. Keep private trackers, people and incidents in changelogs or decision records;
hygiene:checkenforces this. - Never hand-edit a generated file or region. Generated regions, the vendored skills, the reference tables and each Worker's
wrangler.jsonccome fromnpm run fix; change the source and regenerate. - The spec follows the code, never the reverse. Do not rename a test to satisfy a spec row; fix the row. A proof reference is exact or wildcarded (
title…), never a truncation. - Tidy first. Structural change (rename, move, extract) and behavioral change are separate commits, each readable on its own.
- One coherent change per PR, rewritten before review. No fix-up trails; names and types tell the truth; a comment that stopped being true during review is removed.
- Decisions are written down. Non-obvious choices go in the PR's Decisions section; one that shapes the architecture becomes a record under
docs/decisions/(a plan underdocs/plans/), never edited — superseded, anddecisions:checkholds that line. - Tests move with code. A moved module takes its tests and spec rows with it, same commit.
- Credentials are never in the tree and never on the bot host when a sandbox executes tools; a missing one fails fast by name.
config/config.example.yamldocuments every knob of the gitignoredconfig/config.yaml. - Run only what the Commands table names. Need more? Add and describe a script;
agents:checkrefuses an undescribed one.
Using Switchboard
Develop and test locally. Only PR review requires Switchboard. Use native MCP when using Switchboard unless the user instructs otherwise; if unavailable, report the blocker. See MCP ingress and operating guidance.
Working locally
Setup, the three test passes and the PR expectations: CONTRIBUTING.md. Production, sizing and deliberate gaps: Operate production, Capacity and sizing, Known limits. One rule for every local run: bash runs model-generated commands inside the executor's boundary, so write-capable credentials stay out of the model's reach.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

