agentleFS
coreplanelabscoreplanelabs/switchboard/AGENTS.md

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.

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
  1. Very specific:

    Read this first. Details: README.md, docs at <https://switchboard.space> and the behavioral specs.

    line 5
  2. Very specific:

    The spec follows the code, never the reverse: Do not rename a test to satisfy a spec row.

    line 112
  3. Distinctive:

    One coherent change per PR, rewritten before review: No fix-up trails; names and types tell the truth.

    line 114

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

  1. 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.
  2. A failing test, then the code. Unit tests are the default proof. The loop is npx vitest run on the test files you touched, by name, once before the push — never --changed, never a directory: on a moving base --changed is most of the suite. CI runs the full suite and typecheck when the change needs them. Local human session: npm test before pushing.
  3. npm run fix, then the checks the change needs. fix regenerates 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 --check on the changed files, tsc --noEmit -p the touched tsconfig under NODE_OPTIONS=--max-old-space-size=6144, npm run hygiene:check, npm run specs:check) and uses judgement beyond that. Local human session: npm run verify before requesting review — it runs every CI gate locally, and a unit test holds the workflow to those scripts.
  4. 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.
  5. Use Switchboard for PR review unless the user instructs otherwise. Request agent:review through 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.
  6. 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

  1. The core never imports a platform SDK. Slack lives in src/channels/slack.ts; the core sees ChannelIO and IncomingMessage. Platform-specific? Extend a seam.
  2. 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.
  3. Authorization is one table, asked once per request, against the resolved actor and agent. Every command and every agent run passes authorize over the policy rows in src/core/authz/; adapters resolve identity, never authority; no registry command starts an agent run — that is dispatch()'s job alone.
  4. 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.
  5. Tools never touch the host. They call ctx.executor; LocalExecutor is the only place local process or file access is allowed; the bot never shells out to gh — GitHub is the REST API on the App credential.
  6. 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.
  7. 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 -->
CommandWhat it doesWhen
npm run buildCompiles the bot to dist/.check:dist and the Docker image run it; rarely by hand.
npm run startRuns the compiled bot from dist/.Production entry (the container's CMD).
npm run devRuns the bot from source with tsx.Local development against a real Slack app.
npm run typecheckTypeScript 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 testThe whole vitest suite from one entry, after deploy:gen.Local sessions before pushing; CI runs it for relevant changes.
npm run cliRuns operator commands and sends asks through the dispatcher.Smoke tests, deploys, config and run history.
npm run resident:archiveCaptures a retained resident and checks its offline restore.Reviewed disposable rehearsal; verify the binding and builds.
npm run resident:retirePreviews or retires one native scope.When deploy is blocked.
npm run emoji:syncDownloads custom Slack emoji.Manual; emoji:read.
npm run verifyRuns all repository and workspace CI checks.Local human checks; CI selects affected checks.
npm run verify:rootRuns the bot package's CI gates.Bot changes; agents use affected checks.
npm run check:consistencyThe 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:gateAccepts successful CI legs or planned skips.CI fan-out gates.
npm run ci:planSelects checks and builds from the full diff; uncertainty runs all.CI; locally with -- --base <ref>.
npm run fixRegenerates every generated artifact and repairs lint and formatting.Before committing; whenever check:consistency reports drift.
npm run deploy:genRenders 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:checkThe rendered wrangler.jsonc files match deploy:gen.When one looks hand-edited; change the template.
npm run check:lockfileNative 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-pairEach 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-titleJudges one PR title as the changelog line: grammar, type, scope, !.-- "feat(scope): …" before opening a PR; CI's title check.
npm run pr-title:genWrites the title gate's types and scopes from the release config and the code map.Part of fix.
npm run pr-title:checkThe committed title vocabulary equals its two sources.Part of check:consistency.
npm run check:project-factsChecks project names, URLs, contact and package metadata against project.json.After project or community file changes; part of check:consistency.
npm run check:registry-driftEvery example-config model ref still resolves against the pinned pi registry.After a pi bump; part of check:consistency.
npm run agents:genWrites the Commands table in AGENTS.md from package.json and this file.After adding or changing a script; part of fix.
npm run clock:genRegenerates both clock allowlists: wall-clock reads (empty) and duration literals outside src/core/budgets.ts.Part of fix.
npm run clock:checkNo 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:checkAGENTS.md is under its size budget, its Commands table is current, and every root script is described here.Part of check:consistency.
npm run lintESLint over the whole tree.npm run fix repairs what it can.
npm run lint:fixESLint with autofix.Part of fix.
npm run formatPrettier over the whole tree (not Markdown).Part of fix.
npm run format:checkPrettier in check mode.Part of verify:root.
npm run check:distBuilds the bot, rejects test files in dist/, and checks required runtime files.Local checks and the CI image build.
npm run check:siteChecks dashboard links against the built site.Docs changes; part of verify.
npm run check:imageBuilds every Worker's image.After touching a Dockerfile; needs Docker. One CI leg per image.
npm run skills:syncVendors the skills listed in skills/manifest.yaml.After changing the manifest; part of fix.
npm run skills:checkThe vendored skills match the manifest byte for byte.Part of check:consistency.
npm run licenses:checkEvery production dependency's license is on the allowlist.After adding a dependency.
npm run check:deps-driftInstalled node_modules match the lockfile: drift fails by name.Part of check:consistency.
npm run docs:genWrites 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:checkThe generated doc regions equal what the code would generate.Part of check:consistency.
npm run specs:checkChecks spec proofs, headers and decision boundaries.After test/spec edits; see spec coverage.
npm run specs:coverageMaps changed paths to specs and lists gaps.Before review: -- --changed origin/main...HEAD; -- --require fails on gaps.
npm run decisions:checkChecks decision and plan status, succession and amendment rules.Part of check:consistency; supersede or amend failed records.
npm run hygiene:checkThe 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:genRecords 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:checkNo 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:genRecords the remaining internal words; refuses growth unless -- --force.Part of fix.
npm run user-message:checkNo user-facing statement delegates recovery.Part of check:consistency; the baseline only shrinks.
npm run docs:changedReports changed docs inputs.One-commit diagnostics; CI uses ci:plan.
npm run deploy:targetsReports Workers selected by the diff.CI summary and release PR comment.
npm run docs:devServes the docs site locally with live reload.Writing docs; -- --port <n> picks the port.
npm run docs:buildBuilds the docs site to docs/.vitepress/dist.Rarely by hand; verify -w docs and the docs Worker's deploy run it.
npm run web:previewServes the dashboard bundle over fixtures for a visual check.After a web/ change.
npm run screenshots:genRenders changed dashboard captures in both themes and records input hashes.Paused; enable websiteMaintenance in project.json.
npm run screenshots:checkEach surface's inputs still hash to what its screenshots were rendered from — no browser.Skips while website maintenance is paused.
npm run loadLoad harness for infrastructure and route checks.Model capacity receipts.
npm run smoke:ingressChecks three deployment capability families; --check makes no network request.Configured disposable scope; release acceptance.
npm run staging:deployDeploys isolated staging; --recreate plans explicit recreation.Staging CI and explicit operator setup.
npm run installation:resetResets data; keeps settings.Preview, then approved apply.
npm run staging:resetTests two staging resets.Manual staging CI.
npm run staging:validateChecks PR eligibility before staging.Staging CI and queued-head recheck.
npm run check:native-scopeTests the native gate and kill.Docker; see the containment plan.
npm run staging:bootstrap-heldInstalls Resident support and keeps maintenance held.Manual staging CI; separate readiness artifact.
npm run staging:recoverRecovers 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:check enforces this.
  • Never hand-edit a generated file or region. Generated regions, the vendored skills, the reference tables and each Worker's wrangler.jsonc come from npm 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 under docs/plans/), never edited — superseded, and decisions:check holds 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.yaml documents every knob of the gitignored config/config.yaml.
  • Run only what the Commands table names. Need more? Add and describe a script; agents:check refuses 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.