@codyswann/lisa 2.121.1 → 2.123.0

package/plugins/lisa-openclaw-agy/skills/lisa-openclaw-setup/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: lisa-openclaw-setup
+description: Set up OpenClaw as the chat-surface runtime for this project's staff roles. Verifies the openclaw CLI, the ~/.openclaw/openclaw.json config, a secret provider, and the required gateway capabilities (sessions_spawn, native-reply session scoping, the NO_REPLY sentinel), then writes a lean `openclaw` section to .lisa.config.json. Prerequisite for lisa-openclaw-connect-staff and lisa-openclaw-connect-repo-topic. Use when a project wants its facilitator/specialist staff reachable from Telegram or Slack.
+---
+
+# lisa-openclaw-setup
+
+Verify the OpenClaw runtime prerequisites and record a minimal, placeholder-safe pointer in
+`.lisa.config.json` so the connect skills have what they need. **This skill writes only setup-level
+pointers** — never tokens, channel/topic/group ids, bot handles, or route tables. Those live in
+`~/.openclaw/openclaw.json` (OpenClaw's own machine-local source of truth) and are written by the
+connect skills, never committed.
+
+This SKILL.md is self-contained and runs identically under Claude Code and Codex. There is no
+command/argument layer in Codex, so do not rely on one.
+
+## What OpenClaw is (so the checks make sense)
+
+OpenClaw is a locally-hosted multi-agent gateway. A **CLI** (`openclaw`, usually at
+`~/.local/bin/openclaw`) manages a **config file** (`~/.openclaw/openclaw.json`) that defines agents,
+chat-channel bindings (Telegram groups/topics, Slack channels), and routing. A long-running
+**gateway** process delivers chat messages to agents and back. Agents reach other agents internally
+via `sessions_spawn` rather than by messaging each other on the chat platform.
+
+## Required inputs
+
+Gather (ask only for what is missing):
+
+- **platform** the project will default to: `telegram` or `slack`
+- **facilitator agent id** — the single human-facing "chief of staff" agent id (a staff role id; see
+  the soft dependency below)
+- **secret provider** — how OpenClaw stores bot/app tokens (e.g. the OS keychain, a named secret
+  manager, or `0600` local token files). Capture only its *type* and a *reference*, never a value.
+
+## Soft dependency on staff roles
+
+The facilitator and specialists are **staff roles**. A companion plugin (`lisa-wiki`) scaffolds a
+staff role's "brain" (a `wiki/staff/<id>.md` doc page plus a dual-runtime subagent at
+`.claude/agents/<id>.md` and `.codex/agents/<id>.toml`) from a `config.staff[]` entry. This plugin
+wires that role to a chat surface — the "body".
+
+If `config.staff[]` (in `.lisa.config.json`) has no entries yet, tell the user to define their staff
+first:
+
+- In Claude Code: run `/lisa:add-role <Role>` (e.g. `/lisa:add-role Chief of Staff`).
+- In Codex: invoke `$lisa-wiki:lisa-wiki-add-role` with the role.
+
+Only auto-delegate if that skill is actually available in the active runtime; otherwise just print the
+exact next step and stop.
+
+## Workflow
+
+### 1. Locate the OpenClaw CLI
+
+Resolve a usable `openclaw` binary, in order:
+
+1. `~/.local/bin/openclaw`
+2. `openclaw` on `PATH`
+3. a path the user supplies
+
+If none is found, stop and tell the user to install OpenClaw and re-run. Record the resolved path for
+the config's `configPath`/CLI discovery only if it is non-standard.
+
+### 2. Verify the config file
+
+Confirm `~/.openclaw/openclaw.json` exists and is valid JSON. Do **not** print token values found
+inside it. If it is missing, instruct the user to initialize OpenClaw (its own init flow creates the
+file) before continuing.
+
+### 3. Verify a secret provider
+
+Confirm a token-storage mechanism is configured. Acceptable: the OpenClaw-configured secret provider,
+an OS keychain entry, or `0600`-permissioned local token files outside the repo. Capture the provider
+*type* and a non-secret *reference* only.
+
+### 4. Probe required gateway capabilities
+
+The connect skills depend on three OpenClaw behaviors. Probe for them and **fail closed** (warn
+loudly, do not silently proceed) if any is missing:
+
+- **`sessions_spawn`** — internal agent-to-agent dispatch (how the facilitator consults specialists).
+- **Native-reply session scoping** — a top-level human request seeds a session keyed to its thread
+  root (Slack channel + root `thread_ts`; Telegram supergroup + forum topic + root `message_id`), and
+  replies in that thread continue the same session, so concurrent threads don't share short-term
+  context.
+- **`NO_REPLY` sentinel** — after an agent sends a message with the platform message tool, returning
+  exactly `NO_REPLY` as its assistant final prevents the gateway from posting a duplicate loose
+  message.
+
+Probe via the OpenClaw CLI/version and a non-mutating validate, e.g.:
+
+```sh
+openclaw --version
+openclaw config validate
+```
+
+If a capability cannot be confirmed, record it as an unmet prerequisite. The connect skills must
+refuse to create routes that would post duplicates or leak cross-thread context.
+
+### 5. Write the lean config section
+
+Update **only** the `openclaw` section of `.lisa.config.json`. Parse the existing JSON, preserve all
+other keys and formatting as much as practical, and write structurally (never string-splice). Shape:
+
+```json
+{
+  "openclaw": {
+    "defaultPlatform": "telegram",
+    "facilitatorAgentId": "<facilitator-agent-id>",
+    "secretProvider": {
+      "type": "<secret-provider-type>",
+      "ref": "<secret-provider-ref>"
+    },
+    "configPath": "~/.openclaw/openclaw.json"
+  }
+}
+```
+
+Rules for this section:
+
+- `defaultPlatform`: `"telegram"` or `"slack"`.
+- `facilitatorAgentId`: the default facilitator/chief id only — **not** per-surface routing.
+- `secretProvider`: a pointer only; never token material.
+- `configPath`: optional; default `~/.openclaw/openclaw.json`. Set only for non-standard installs.
+- **Reject** writing tokens, channel ids, topic ids, group ids, Slack thread roots, bot handles, or
+  repo paths here. If the user offers them, decline and explain they belong in
+  `~/.openclaw/openclaw.json`.
+
+### 6. Report
+
+Finish with: resolved CLI path, config-file status, secret-provider type/ref, each capability probe
+result (pass / warn / unknown), the `openclaw` section written, and the exact next command/skill
+(`lisa-openclaw-connect-staff` or `lisa-openclaw-connect-repo-topic`).
+
+## Related
+
+`lisa-openclaw-connect-staff`, `lisa-openclaw-connect-repo-topic`. Staff "brains" come from the
+`lisa-wiki` plugin's `add-role`.

package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "lisa-openclaw",
+  "version": "2.123.0",
+  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
+  "author": {
+    "name": "Cody Swann"
+  }
+}

package/plugins/lisa-openclaw-copilot/commands/connect-repo-topic.md

@@ -0,0 +1,7 @@
+---
+description: "Bind a Telegram forum topic to an OpenClaw dispatcher+worker pair that runs a coding CLI against a repo (single-repo or folder-scoped), so you can drive code work from chat. Requires /lisa:setup-openclaw first."
+argument-hint: "<admin|developer> <single-repo|folder-scoped> <topic name> <workspace path>"
+---
+
+Use the lisa-openclaw-connect-repo-topic skill to provision or update a Telegram repo-coding topic
+(dispatcher + worker pair) and wire it in OpenClaw. $ARGUMENTS

package/plugins/lisa-openclaw-copilot/commands/connect-staff-slack.md

@@ -0,0 +1,7 @@
+---
+description: "Connect staff roles to Slack via OpenClaw using a facilitator/specialist hub-and-spoke model — register the app, create/reuse the facilitator channel, wire routes, validate, and run an end-to-end route test. Requires /lisa:setup-openclaw first."
+argument-hint: "<facilitator role + specialists, e.g. Chief of Staff with Legal, Finance, Sales>"
+---
+
+Use the lisa-openclaw-connect-staff skill with platform `slack`. Connect the named facilitator and
+specialists to a Slack facilitator channel via OpenClaw. $ARGUMENTS

package/plugins/lisa-openclaw-copilot/commands/connect-staff-telegram.md

@@ -0,0 +1,7 @@
+---
+description: "Connect staff roles to Telegram via OpenClaw using a facilitator/specialist hub-and-spoke model — register bots, create/reuse the facilitator topic, wire routes, validate, and run an end-to-end route test. Requires /lisa:setup-openclaw first."
+argument-hint: "<facilitator role + specialists, e.g. Chief of Staff with Legal, Finance, Sales>"
+---
+
+Use the lisa-openclaw-connect-staff skill with platform `telegram`. Connect the named facilitator and
+specialists to a Telegram facilitator topic via OpenClaw. $ARGUMENTS

package/plugins/lisa-openclaw-copilot/commands/setup-openclaw.md

@@ -0,0 +1,7 @@
+---
+description: "Set up OpenClaw as the chat-surface runtime for this project's staff. Verifies the openclaw CLI, ~/.openclaw/openclaw.json, a secret provider, and required gateway capabilities, then writes a lean `openclaw` section to .lisa.config.json. Run before connect-staff / connect-repo-topic."
+argument-hint: "[telegram|slack]"
+---
+
+Use the lisa-openclaw-setup skill to verify OpenClaw prerequisites and write the lean `openclaw`
+section to .lisa.config.json. If a platform is given, use it as the defaultPlatform. $ARGUMENTS

package/plugins/lisa-openclaw-copilot/skills/lisa-openclaw-connect-repo-topic/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: lisa-openclaw-connect-repo-topic
+description: Bind a Telegram forum topic to an OpenClaw dispatcher+worker agent pair that runs a coding CLI against a repo, so you can drive code work from chat. Supports single-repo topics and folder-scoped topics (multiple repos with repo-confirmation). Creates/validates the agent pair, ensures the bot is a group admin, captures real group/topic ids, wires the route in ~/.openclaw/openclaw.json, validates the gateway, and runs a no-change self-test. Requires lisa-openclaw-setup first.
+---
+
+# lisa-openclaw-connect-repo-topic
+
+Turn a Telegram forum topic into a repeatable OpenClaw entrypoint for code work. A **dispatcher**
+agent receives the request and delegates; a **worker** agent runs the local coding CLI in a safe
+target directory and relays the result.
+
+This SKILL.md is complete and runnable under both Claude Code and Codex (no command/`$ARGUMENTS`
+layer in Codex). Keep real ids/handles/paths out of committed files — they go only in
+`~/.openclaw/openclaw.json`. For exact config shapes read
+[references/repo-topic-config.md](references/repo-topic-config.md).
+
+## Prerequisites
+
+- `lisa-openclaw-setup` has run and its capability probes passed.
+- A Telegram supergroup with forum topics, and a bot that is (or can be promoted to) a **group
+  admin** — bot presence alone is not enough for topic routing.
+
+## Boundaries (apply every time)
+
+- groups = the human trust boundary
+- topics = the project-routing boundary
+- native-reply roots = the short-term session boundary inside a topic
+- agents = the capability boundary
+- Do not mix admin-only repos with broader-collaboration repos in one group. If two repos need
+  different member lists, use separate groups, not topic-only separation.
+
+## Scope modes (pick exactly one per topic)
+
+- **`single-repo`** — the topic is pinned to one repo directory; the dispatcher never asks which repo.
+- **`folder-scoped`** — the topic is pinned to a parent folder containing multiple repos; the
+  dispatcher must confirm the inferred repo(s) unless the user named them explicitly.
+
+Do not mix both behaviors in one topic.
+
+## Required inputs
+
+- trust boundary: `admin` or `developer`
+- scope mode: `single-repo` or `folder-scoped`
+- access surface: Telegram group + topic (by name; ids captured during the run)
+- the bot handle to bind
+- workspace root on disk (repo dir for single-repo; parent folder for folder-scoped)
+- allowed Telegram user ids
+- completion policy:
+  - `admin` topics may request change + docs + commit + PR + merge
+  - `developer` topics default to change + docs + commit + PR only
+- for `folder-scoped`: a repo catalog (label, absolute path, a few matching keyword hints)
+
+## Workflow
+
+### 1. Resolve the contract
+
+Confirm the trust boundary, scope mode, workspace root, bot handle, and (for folder-scoped) the repo
+catalog. If a needed agent doesn't exist yet, create it in step 3.
+
+### 2. Provision / reuse the Telegram surface
+
+Reuse the trust-matched group and the exact topic if they already exist; otherwise create them (enable
+forum/topics mode first). Ensure the bot is in the group and **promoted to admin**. Telegram Bot API
+cannot list groups by name — discover ids from a logged-in Telegram client, an existing route in
+`~/.openclaw/openclaw.json`, or a received Bot API update. If browser/UI automation blocks on a human
+confirmation step, give the user only the blocked step, wait, then resume.
+
+### 3. Implement the dispatcher + worker pair
+
+Create or update two agents (exact tool-deny shapes in
+[references/repo-topic-config.md](references/repo-topic-config.md)):
+
+- **`<topic-slug>-dispatch`** — skill-aware entrypoint; tools restricted to delegation/session tools
+  (+ optional `read`); denies file writes, shell/exec, browser, gateway, automation; may delegate
+  only to `<topic-slug>-codex`.
+- **`<topic-slug>-codex`** — restricted worker; keeps `read` + `exec`; denies session spawning,
+  browser, gateway, and direct file-write tools; runs the local coding CLI for the actual work.
+
+### 4. Repo-selection behavior
+
+- `single-repo`: treat the repo as decided; pass the fixed repo path to the worker; never ask.
+- `folder-scoped`: infer candidates from the catalog. If the user named repo(s) explicitly, skip
+  confirmation; otherwise ask before spawning:
+  - one likely repo: `This looks like <repo>. Is that correct?`
+  - multiple: `This may belong to <repo-1> or <repo-2>. Is that correct, or which repo(s)?`
+  On confirmation of multiple repos, spawn one worker run per repo (or ask the user to split a
+  too-coupled change). Never skip confirmation in folder-scoped mode unless selection was explicit.
+
+### 5. Worker safety contract
+
+Every worker task receives an explicit repo path and:
+
+1. inspects `git status --short --branch` in the selected repo
+2. if the primary checkout is dirty or already on a feature branch, creates a temporary worktree from
+   `main` under `/tmp`
+3. trusts local tool config in a fresh worktree if required (e.g. `mise trust <target_dir>`)
+4. runs the coding CLI in the foreground in the target directory
+5. cleans up the temporary worktree after success when safe
+
+The worker prepares the safe target and launches the CLI; it does not edit files directly.
+
+### 6. Bind the topic
+
+Route the topic to the dispatcher: set
+`channels.telegram.groups.<group-id>.topics.<topic-id>.agentId = <topic-slug>-dispatch`, keep
+`requireMention = true` and allowlist policy, and add `allowFrom` only when membership must be
+narrower than the group. The topic `systemPrompt` must state the scope mode, treat each native-reply
+root as an independent request context, confirm repo selection only in folder-scoped mode, spawn the
+worker with an explicit repo path, and return the worker result to the topic. Back up
+`~/.openclaw/openclaw.json` before editing and preserve unrelated routes.
+
+### 7. Validate + self-test
+
+```sh
+openclaw config validate
+openclaw gateway restart
+openclaw gateway status
+openclaw channels status --probe
+```
+
+Then from the target topic: mention the bot and ask for an exact-token reply with **no** file
+changes, commits, PRs, or merges, e.g. `<bot-handle> reply with exactly TELEGRAM-ROUTE-OK`. Confirm
+the visible reply, that the dispatcher spawned the worker, and that the worker ran in the intended
+repo. For folder-scoped topics, also send a request that implies but doesn't name a repo and confirm
+the dispatcher asks for confirmation before proceeding. Do **not** treat `openclaw agent --agent
+<id> ...` as proof a topic route works — use the visible topic reply.
+
+## Output standard
+
+Finish with: group id + topic id used; scope mode; workspace root and repo path or catalog;
+dispatcher + worker agent ids; whether the bot is confirmed group admin; validation results; whether
+the self-test passed; and any remaining manual follow-up or trust caveat.
+
+## Related
+
+`lisa-openclaw-setup` (run first), `lisa-openclaw-connect-staff` (facilitator/specialist staff on
+Telegram or Slack).

package/plugins/lisa-openclaw-copilot/skills/lisa-openclaw-connect-repo-topic/references/repo-topic-config.md

@@ -0,0 +1,109 @@
+# Repo-coding topic config shapes
+
+Placeholder-only. Real ids/paths/handles go only into `~/.openclaw/openclaw.json` (machine-local,
+never committed). Back up that file before editing; change only the intended keys.
+
+## Trust model
+
+- `admin` group: highly trusted people; machine-config/infra repos allowed; topics may request merge
+  after PR.
+- `developer` group: broader collaborators; topics stop at change + docs + commit + PR unless
+  explicitly raised.
+
+If two repos need different member lists, use different groups even if both are `developer`.
+
+## Folder-scoped repo catalog
+
+```yaml
+repos:
+  - name: repo-1
+    path: /absolute/path/to/repo-1
+    hints: [billing, invoices]
+  - name: repo-2
+    path: /absolute/path/to/repo-2
+    hints: [login, mobile-app]
+```
+
+## Naming
+
+- topic slug: derived from the topic purpose or workspace name
+- dispatcher agent id: `<topic-slug>-dispatch`
+- worker agent id: `<topic-slug>-codex`
+
+## Dispatcher agent
+
+```json5
+{
+  "id": "<topic-slug>-dispatch",
+  "workspace": "/absolute/path/to/repo-or-parent",
+  "skills": ["acp-router"],
+  "subagents": { "allowAgents": ["<topic-slug>-codex"] },
+  "tools": {
+    "profile": "coding",
+    "deny": [
+      "group:ui", "group:automation", "group:nodes",
+      "bash", "exec", "process", "browser", "canvas", "cron",
+      "gateway", "write", "edit", "apply_patch"
+    ]
+  },
+  "elevated": { "enabled": false }
+}
+```
+
+## Worker agent
+
+```json5
+{
+  "id": "<topic-slug>-codex",
+  "workspace": "/absolute/path/to/repo-or-parent",
+  "tools": {
+    "profile": "coding",
+    "deny": [
+      "group:ui", "group:automation", "group:nodes", "group:sessions",
+      "subagents", "process", "browser", "canvas", "cron",
+      "gateway", "write", "edit", "apply_patch"
+    ]
+  },
+  "elevated": { "enabled": false }
+}
+```
+
+## Topic route
+
+```json5
+{
+  "channels": {
+    "telegram": {
+      "groups": {
+        "<group-id>": {
+          "groupPolicy": "allowlist",
+          "requireMention": true,
+          "allowFrom": ["<telegram-user-id>"],
+          "topics": {
+            "<topic-id>": {
+              "agentId": "<topic-slug>-dispatch",
+              "requireMention": true,
+              "systemPrompt": "Use the topic's configured scope mode. For single-repo, pass the fixed repo path to <topic-slug>-codex. For folder-scoped, confirm the inferred repo or repo set unless the user already named it explicitly, then pass the explicit repo path(s) to <topic-slug>-codex. Treat each native reply root as an independent request context."
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Worker launcher form
+
+```sh
+PATH="$HOME/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin" \
+  "$HOME/bin/<coding-cli>" exec -C <target_dir> "<prompt>"
+```
+
+## Id rules
+
+- Telegram Bot API `chat_id` for a supergroup is the full signed id (usually starts `-100`); the short
+  positive number is not a valid substitute.
+- Topic id is the Telegram `message_thread_id`.
+- Discover ids from a logged-in Telegram client, an existing route in `~/.openclaw/openclaw.json`, or a
+  received Bot API update — the Bot API cannot list groups by name.

package/plugins/lisa-openclaw-copilot/skills/lisa-openclaw-connect-staff/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: lisa-openclaw-connect-staff
+description: Connect staff roles to a human chat surface (Telegram or Slack) via OpenClaw using a facilitator/specialist hub-and-spoke model. Registers bots/apps, creates or reuses the human-facing surface, wires routes in ~/.openclaw/openclaw.json, writes facilitator/specialist agent prompts, validates the gateway, resets stale sessions, and runs an end-to-end route test. Use when you want a "chief of staff" facilitator and its specialists reachable from chat. Requires lisa-openclaw-setup first.
+---
+
+# lisa-openclaw-connect-staff
+
+Wire existing staff roles into a working hub-and-spoke chat deployment on **Telegram** or **Slack**
+through OpenClaw. Humans talk only to the **facilitator** (the "chief of staff"); the facilitator
+consults **specialists** internally and synthesizes one answer back to the human.
+
+This SKILL.md is the complete, runnable definition for **both Claude Code and Codex**. Codex has no
+command or `$ARGUMENTS` layer, so every behavior — including platform selection — is specified here.
+Keep all real values (org names, ids, handles, tokens, paths) out of any committed file; they belong
+only in `~/.openclaw/openclaw.json` (machine-local, never committed).
+
+## Prerequisites
+
+1. `lisa-openclaw-setup` has run (an `openclaw` section exists in `.lisa.config.json`, and the
+   required gateway capabilities — `sessions_spawn`, native-reply session scoping, `NO_REPLY` — are
+   confirmed). If a capability is unmet, **fail closed**: do not create routes that would post
+   duplicates or bleed cross-thread context.
+2. The staff roles to connect exist in `config.staff[]` and each has a dual-runtime subagent
+   (`.claude/agents/<id>.md` + `.codex/agents/<id>.toml`). If a role or its subagent is missing:
+   - Claude Code: run `/lisa:add-role <Role>` first.
+   - Codex: invoke `$lisa-wiki:lisa-wiki-add-role` first.
+   Only auto-delegate if that skill is available in the active runtime; otherwise print the exact
+   next step and stop. **Never infer agent ids from display names** — always use `config.staff[].id`.
+
+## Platform selection (identical in both runtimes)
+
+Resolve the platform with this precedence:
+
+1. An explicit platform in the user's request (the Claude commands pre-state `telegram` or `slack`).
+2. `openclaw.defaultPlatform` from `.lisa.config.json`.
+3. If still unknown, ask exactly one question: `Connect staff via telegram or slack?`
+
+## Hub-and-spoke contract (both platforms)
+
+- Humans speak only to the facilitator; specialists never take direct human work.
+- The facilitator consults specialists via internal OpenClaw `sessions_spawn` with **explicit**
+  `agentId`s — never by messaging another bot on the chat platform (bot-to-bot delivery is
+  unreliable; treat any visible specialist "workroom" as an audit copy, not proof of delivery).
+- Each visible human request thread is its own short-term session boundary.
+- The facilitator acknowledges after starting consultation, waits/yields for specialist results,
+  evaluates them (asking follow-ups when weak/incomplete/conflicting), synthesizes one answer, and
+  replies in the original thread / native reply.
+- After any explicit message-tool send, the agent returns exactly `NO_REPLY` as its assistant final
+  so the gateway does not post a duplicate loose message.
+- Do not instruct agents to add bracketed self-labels like `[Facilitator]`; the platform shows
+  identity.
+
+## Required inputs
+
+- platform (resolved above)
+- facilitator: staff id, display name, title, human-facing surface name
+- specialists: list of staff ids + roles to attach to this facilitator
+- surface visibility: Slack channel `private` (default) or `public`; for Telegram, whether any
+  specialist audit topics are wanted (default: none)
+- visible bot/app identities (display names, usernames/handles) if separate avatars are needed
+- communication rules (who may talk to whom)
+
+For exact route shapes and the facilitator/specialist prompt text, read
+[references/platform-routing.md](references/platform-routing.md) and
+[references/prompts.md](references/prompts.md).
+
+## Workflow
+
+### 1. Inspect existing state
+
+Read only what you need; never print token contents:
+
+- `~/.openclaw/openclaw.json` (existing agents, channels, groups, topics, routes)
+- `config.staff[]` and the staff subagent files
+- existing chat surfaces, apps, and bot accounts (reuse before creating)
+
+### 2. Plan the platform shape
+
+**Telegram:** create or reuse one organization supergroup with forum topics enabled; create one
+human-facing facilitator topic; create one bot per visible identity only when separate names/avatars
+are needed; specialist audit topics only if explicitly requested. The Bot API `chat_id` for a
+supergroup is the **signed** id (usually starting `-100`); the topic id is the
+`message_thread_id`.
+
+**Slack:** use Socket Mode for a workstation-hosted gateway unless told otherwise; create or reuse one
+human-facing facilitator channel (default `<organization-slug>-chief-of-staff`, private/invite-only
+unless public is requested); bind routes by stable channel **id**, not channel name; optional
+specialist workrooms are audit-only.
+
+Telegram bot-to-bot and bot-originated-topic messages can fail to wake other bots — this is exactly
+why internal `sessions_spawn` is the default route.
+
+### 3. Register apps / bots and store tokens
+
+- Telegram: create bots with the agreed names/usernames; add visible bots to the supergroup, promote
+  as needed, and disable privacy mode when topic messages must reach them.
+- Slack: create or reuse the org app; grant only required scopes; save `xoxb`/`xapp` tokens.
+- Store every token via the configured secret provider (or `0600` local files outside the repo).
+  **Never** print/paste tokens into chat, logs, docs, or any committed file. After saving, verify the
+  token via an OpenClaw probe or platform API check without exposing it.
+- If creation is rate-limited (e.g. BotFather) or needs a human confirmation step, wire what
+  completed, record what is pending plus the retry time, and ask only for the specific approval/code
+  needed.
+
+### 4. Create or update agent files
+
+For the facilitator and each specialist, ensure the OpenClaw agent exists and its prompt encodes the
+hub-and-spoke contract. Use the prompt templates in [references/prompts.md](references/prompts.md).
+The facilitator prompt must require: consult ≥1 specialist before substantive answers; treat the
+current thread/native-reply root as the session boundary; route via `sessions_spawn` with explicit
+`agentId`s; acknowledge → yield/wait → evaluate → synthesize → reply in the original thread; return
+`NO_REPLY` after any message-tool send; isolate/clear/archive consulted specialist context after the
+investigation. Specialist prompts must require: accept work only via internal dispatch; return
+concise structured results; never post to human-facing surfaces.
+
+### 5. Wire OpenClaw routing
+
+Edit `~/.openclaw/openclaw.json` carefully (see [references/platform-routing.md](references/platform-routing.md)
+for exact shapes). **Back up the file first.** Parse JSON, change only the intended keys, and preserve
+all unrelated agents, channels, routes, and tokens:
+
+- add/update each agent in `agents.list`
+- give the facilitator `subagents.allowAgents` = the specialist ids; set
+  `subagents.requireAgentId = true` when supported
+- bind the human-facing surface (Telegram topic / Slack channel) to the facilitator
+- bind optional audit surfaces as visibility-only
+- for Slack, set `channels.slack.replyToModeByChatType.channel = "all"` so acknowledgements and final
+  answers are real thread replies
+- disable any default-bot fallback that would answer instead of the facilitator
+
+Show the exact route keys you will change before writing.
+
+### 6. Validate
+
+Run, waiting for the gateway to warm up before declaring success:
+
+```sh
+openclaw config validate
+openclaw gateway restart
+openclaw channels status --probe --timeout 90000
+```
+
+### 7. Reset stale sessions (when changing an existing route's behavior)
+
+Archive (don't delete) affected session files under `~/.openclaw/session-archive/`, remove active
+session pointers for the changed routes, restart the gateway, and re-probe. Old session history can
+preserve stale routing instructions after a prompt/config change.
+
+### 8. End-to-end route test
+
+Do not call the work complete until the live loop passes. Acceptance criteria:
+
+1. A human post reaches the facilitator surface.
+2. The facilitator acknowledges as a thread reply / native reply to the original message.
+3. A second post in the same channel/topic but a different visible thread gets a **distinct** session
+   context (no cross-thread bleed).
+4. The facilitator starts internal `sessions_spawn` consultation with ≥1 explicit specialist id.
+5. A specialist returns an internal result.
+6. The facilitator evaluates and asks a follow-up if needed.
+7. The facilitator synthesizes and replies in the original thread / native reply.
+8. No duplicate loose message appears after the message-tool send (the `NO_REPLY` rule held).
+
+If the test fails, inspect gateway logs and sessions before changing config; check the bot's admin
+rights (Telegram) / app channel membership and scopes (Slack), and mention-gating, first.
+
+## Output standard
+
+Finish with: platform and human-facing surface; surfaces created/reused; apps/bots registered and any
+pending; token storage location (no values); facilitator + specialist agents created/updated;
+validation results; end-to-end test result; and any remaining manual or cooldown follow-up.
+
+## Related
+
+`lisa-openclaw-setup` (run first), `lisa-openclaw-connect-repo-topic` (Telegram repo-coding topics).
+Staff "brains" come from the `lisa-wiki` plugin's `add-role`.