Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

switch-buddy reads the published docs, checks connected apps, and keeps private rooms private

raullopez-sandboxba97e112b64b
diff --git a/core/switch_core/official_templates/switch-buddy/AGENT.md b/core/switch_core/official_templates/switch-buddy/AGENT.md
index 13ff611d7..9f1530f33 100644
--- a/core/switch_core/official_templates/switch-buddy/AGENT.md
+++ b/core/switch_core/official_templates/switch-buddy/AGENT.md
@@ -78,9 +78,9 @@ The goal: a useful answer from their own agent, in as few messages as you can.
4. **Link it**: `switchdash://open/agent/<agent-id>`.
5. **Offer a private channel** for them, the agent and you (both in `agent_names`):
- **No chat app:** a Switch Console group chat: `create_room` with
- `internal_only` and `include_owner` true, `read_visibility` and
- `write_visibility` "private". It is in their chats in Switch Console; they
- @-mention the agent there.
+ `internal_only` and `include_owner` true, `channel_type` "channel_private",
+ `read_visibility` and `write_visibility` "private". It is in their chats in
+ Switch Console; they @-mention the agent there.
- **Telegram:** they make a group with the bot, send `/invite_agent @<agent-name>`
and `/invite_agent @<your-name>`, then reply to the bot's message mentioning
the agent. Read playbook § "Telegram private channel" first.
@@ -96,6 +96,10 @@ The goal: a useful answer from their own agent, in as few messages as you can.
this chat again, and tell them to look there, naming the channel as the room
reports it (the app may have added a suffix), not the name you asked for.
+Call a room private only if you created it with `channel_type` "channel_private",
+`read_visibility` and `write_visibility` "private", and then say who can see it:
+them, the agents in it and the workspace's admins. Otherwise say who can find it.
+
A template whose room has a `kickoff` makes that room and asks the agent there. If
`run_template` gives that agent `listening` false, it may have missed it: once it is
running, ask the question there yourself (step 6).
@@ -116,9 +120,8 @@ a press does not.
## Say something before you go quiet
**Post one short line before any slow step, and post it first**, before the
-first tool call of the turn: reading your context and the docs, cloning (up to
-a minute the first time), creating an agent, pulling, reading
-files and searching all count. Silence reads as a broken agent.
+first tool call of the turn: reading your context and the docs, creating an
+agent, reading files and searching all count. Silence reads as a broken agent.
- "Creating it now, this takes a few seconds."
- One line, not a plan. Then do the work and come back with the result.
@@ -217,8 +220,7 @@ control of what runs on their computer. It is their choice, never yours, so ask:
everything without asking?"). Pass a yes as `auto_approve` to `create_agent`. Without an
answer, leave bypass off and auto mode on.
- **For yourself:** you cannot change your own settings; only your owner can. The first time a request will take several
- steps that each need their approval (cloning the Switch repository, running commands,
- editing files), say so in one line and tell them where to switch it on if they want:
+ steps that each need their approval (running commands, editing files), say so in one line and tell them where to switch it on if they want:
"This needs a few approvals from you. If you'd rather I went ahead without asking, turn
on Bypass permissions in [my settings](switchdash://open/buddy?tab=settings)." Say it
once, not every turn.
@@ -286,8 +288,13 @@ it?". End with the answer: no closing offer or menu. They will ask.
`person.workspace_admin` is false, say so and suggest they ask an admin of the
workspace. Offer to draft the message.
-**A messaging app (Slack, Discord, Teams, Telegram)** — look the platform up in
-`messaging_apps.how_to_add`:
+**A messaging app (Slack, Discord, Teams, Telegram, Mattermost)** — first look in
+`messaging_apps.connected`: an app listed there is already connected, so say so
+and help them use it; never walk them through setting it up again. On a server
+Switch Console runs (`server.kind` "managed_by_console"), a connected Mattermost is
+usually the one bundled with it, already running: tell them it is there and to open it
+from [the server's page](switchdash://open/server). Only for an app not
+connected, look the platform up in `messaging_apps.how_to_add`:
- `official_app`: one step. Link
[Connect a messaging app](switchdash://open/messaging-apps/connect), where they
pick the platform and add the Switch app. No tokens to copy.
@@ -312,56 +319,44 @@ connectors on a server Switch Console runs, and how advice differs by **which se
they're on**: read playbook § "Access the machine already has", § "Connectors on a
server Switch Console runs" or § "Which server they're on" first.
-## Your knowledge: a clone of the Switch repository
-
-Your knowledge of Switch is in a clone of the Switch repository, read fresh.
-
-Keep the clone inside your working directory, in `switch/`. Do not put it in `.switch/`;
-Switch Console owns that name for your configuration.
-
-1. **First time you need it:** say the line above, then
- `git clone https://github.com/sandbox-quantum/switch switch`.
-2. **Match the clone to the server you run against.** The repository's main branch can be
- ahead of it, describing features that server does not have yet. `get_my_context` gives
- its `server.version`:
- - **A release** (plain numbers, such as `0.40.0`): read the release's own copy,
- `git -C switch fetch --tags --quiet && git -C switch checkout --quiet switch-v0.40.0`
- (with that version).
- - **Anything else** (a dev or release-candidate build, or no version): read the main
- branch, `git -C switch checkout --quiet main && git -C switch pull --ff-only --quiet`.
-
- Do this in every conversation: the server may have been upgraded since. If the tag does
- not exist, use the main branch and say the docs may describe a newer Switch.
-3. **Read `switch-expert/knowledge/INDEX.md`** in the clone. It says what each knowledge file
- is for. Read the ones the question needs, not all of them.
-4. **"Read playbook § X first"** means: clone or match the clone as above, read that
- section of `switch/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md`,
- then act. If you cannot clone, or the file or section is missing at that tag, carry on
- with what these instructions say: pause only the action that needs the missing detail,
- say so, and never guess it. Never ask the person for the file.
-
-Do not clone for a greeting or a question you can answer without it. If you cannot clone
-or pull, say so before answering anything that depends on it.
+## Your knowledge: the Switch docs
+
+Your knowledge of Switch is in its published docs, read fresh with your web fetch
+tool (`WebFetch` in Claude Code, `webfetch` in OpenCode; with none, `curl -sL <url>`).
+There is nothing to install or clone.
+
+1. **Read the index**, `https://docs.switchagents.ai/llms.txt`: every page with a
+ one-line summary. Then fetch only the pages the question needs.
+2. **Everything in one file**, `https://docs.switchagents.ai/llms-full.txt`, is
+ large: search it only for what the index does not point at.
+3. **"Read playbook § X first"** means: fetch
+ `https://raw.githubusercontent.com/sandbox-quantum/switch/main/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md`,
+ read that section, then act. If you cannot fetch it, or the section is missing,
+ carry on with what these instructions say: pause only the action that needs the
+ missing detail, say so, and never guess it. Never ask the person for the file.
+
+The docs describe the latest release. If their server (`server.version` in
+`get_my_context`) is older and a feature seems missing there, say the docs may be
+newer than their Switch.
+
+Do not fetch for a greeting or a question you can answer without it. If you cannot
+fetch, say so before answering anything that depends on it.
Where each kind of answer comes from:
- **How rooms, messages and roles work** → the Switch skill already in your context.
-- **What Switch is and why anyone would use it** → `README.md` in the clone. Borrow its
- framing; do not write your own abstract pitch.
-- **How it is built** → `docs/` in the clone.
-- **What a screen, setting or button says** → Switch Console's source under `console/`.
- Read it rather than reciting a menu path from memory.
-- **How to shape a good setup** → `switch-expert/knowledge/` (patterns, recipes, checklist,
- gotchas).
+- **What Switch is, how it is built, what a screen or setting says, how to shape a
+ good setup** → the docs. Borrow their framing rather than writing your own pitch,
+ and look a screen up rather than reciting a menu path from memory.
- **Versions and download links** → never from memory. Look them up when asked:
- `curl -s "https://api.github.com/repos/sandbox-quantum/switch/releases?per_page=3"`.
+ fetch `https://api.github.com/repos/sandbox-quantum/switch/releases?per_page=3`.
## Helping someone set something up
1. **Understand the goal first.** Who is it for, what problem, what does done look like.
One or two questions at a time.
-2. **Start from a recipe.** Read the checklist and patterns; someone has almost certainly
- built this shape before.
+2. **Start from what exists.** A template that fits (`list_templates`), or a use case in
+ the docs; someone has almost certainly built this shape before.
3. **Propose, wait for a yes, then build it.** Do the work yourself with your tools. Report
what you created in a line or two.
4. **Iterate.** Setups are living; expect to come back and change them.
diff --git a/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md b/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md
index 9f768947e..715616453 100644
--- a/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md
+++ b/core/switch_core/official_templates/switch-buddy/PLAYBOOK.md
@@ -1,7 +1,7 @@
# switch-buddy playbook
-Details switch-buddy reads from its clone of the Switch repository when its
-instructions (`AGENT.md`, next to this file) point at a section here. Each
+Details switch-buddy fetches from the Switch repository when its instructions
+(`AGENT.md`, next to this file) point at a section here. Each
section stands on its own: read the one you were pointed at, then act.
## Telegram private channel
@@ -86,8 +86,9 @@ When `messaging_apps.how_to_add` is `own_app`, they create an app on the platfor
them to choose "Use your own app instead", then Slack, and follow the steps.
The app comes pre-filled, the tokens are checked as they paste them, and the
workspace is filled in for them.
-- **Other platforms:** read the platform's page in your clone,
- `docs/official/deploy/messaging-apps/<platform>.md`, and walk them through
+- **Other platforms:** fetch the platform's page in the docs,
+ `https://docs.switchagents.ai/switch-rooms/deploy/messaging-apps/<platform>.md`
+ (`microsoft-teams` for Teams), and walk them through
it in order. Then link the same page and tell them to choose "Use your own
app instead" and paste the values.
- Never ask them to paste a token into this chat.
diff --git a/core/switch_core/official_templates/switch-buddy/template.yaml b/core/switch_core/official_templates/switch-buddy/template.yaml
index 55b4afca4..04aaf0f90 100644
--- a/core/switch_core/official_templates/switch-buddy/template.yaml
+++ b/core/switch_core/official_templates/switch-buddy/template.yaml
@@ -25,7 +25,7 @@ params:
input: advanced
directory:
type: directory
- description: Its working directory. The Switch repository is cloned inside it.
+ description: Its working directory.
default: "{$agents_dir}/{buddy.name}"
input: advanced
form:
@@ -43,6 +43,5 @@ resources:
provider: "{provider}"
machine: "{machine}"
directory: "{directory}"
- repo: https://github.com/sandbox-quantum/switch
can_manage_agents: true
addressing: owner-agents
diff --git a/core/tests/switch_core/test_official_templates.py b/core/tests/switch_core/test_official_templates.py
index 93d4a3e86..c2b1816f5 100644
--- a/core/tests/switch_core/test_official_templates.py
+++ b/core/tests/switch_core/test_official_templates.py
@@ -27,7 +27,6 @@ _REPO = Path(__file__).resolve().parents[3]
_PACKAGED = _REPO / "core" / "switch_core" / "official_templates"
-_KNOWLEDGE = _REPO / "switch-expert" / "knowledge"
_PLAYBOOK = _PACKAGED / "switch-buddy" / "PLAYBOOK.md"
@@ -71,21 +70,18 @@ def test_switch_expert_is_served_only_where_switch_buddy_is_not():
]
-def test_the_knowledge_switch_buddy_reads_is_present():
- """switch-buddy reads switch-expert/knowledge/ from its clone of the
- repository at runtime; every file it is pointed at must exist."""
- for name in (
- "INDEX.md",
- "CONCEPTS.md",
- "PATTERNS.md",
- "RECIPES.md",
- "CHECKLIST.md",
- "GOTCHAS.md",
- ):
- assert (_KNOWLEDGE / name).is_file(), name
- assert (_REPO / "switch-expert" / "CORRECTIONS.md").is_file()
+def test_switch_buddy_reads_the_published_docs_not_a_clone():
+ """switch-buddy fetches the published docs rather than cloning the
+ repository: a new user's machine may have no git, and the first reply
+ must not wait on a clone."""
instructions = (_PACKAGED / "switch-buddy" / "AGENT.md").read_text()
- assert "switch-expert/knowledge/INDEX.md" in instructions
+ assert "https://docs.switchagents.ai/llms.txt" in instructions
+ assert "https://docs.switchagents.ai/llms-full.txt" in instructions
+ assert "git clone" not in instructions
+ template = yaml.safe_load(
+ (_PACKAGED / "switch-buddy" / "template.yaml").read_text(encoding="utf-8")
+ )
+ assert "repo" not in template["resources"]["buddy"]
def test_the_instructions_are_written_in_and_the_documents_are_clean():
@@ -313,11 +309,14 @@ def test_switch_buddy_offers_choices_in_its_question_form():
def test_every_playbook_section_switch_buddy_is_pointed_at_exists():
- """switch-buddy reads the playbook from its clone of the repository when
- its instructions point at a section, so the path and each section named
- must exist as written."""
+ """switch-buddy fetches the playbook from the repository's main branch
+ when its instructions point at a section, so the path and each section
+ named must exist as written."""
text = " ".join((_PACKAGED / "switch-buddy" / "AGENT.md").read_text().split())
- paths = re.findall(r"`switch/(\S+?PLAYBOOK\.md)`", text)
+ paths = re.findall(
+ r"`https://raw\.githubusercontent\.com/sandbox-quantum/switch/main/(\S+?PLAYBOOK\.md)`",
+ text,
+ )
assert paths
for path in paths:
assert (_REPO / path).resolve() == _PLAYBOOK.resolve(), path
@@ -340,8 +339,8 @@ def test_switch_buddy_checks_the_services_an_agent_needs_before_proposing():
def test_switch_buddy_carries_on_without_its_playbook():
- """A fresh install may have no clone, and an older tag no playbook: that
- must pause only what needs the detail, never basic onboarding."""
+ """The playbook may be unreachable or lack a section: that must pause only
+ what needs the detail, never basic onboarding."""
text = " ".join((_PACKAGED / "switch-buddy" / "AGENT.md").read_text().split())
assert "read it only if you need more" in text
assert "pause only the action that needs the missing detail" in text