@codyswann/lisa 2.121.0 → 2.122.0

package/plugins/lisa-openclaw-cursor/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`.

package/plugins/lisa-openclaw-cursor/skills/lisa-openclaw-connect-staff/references/platform-routing.md

@@ -0,0 +1,83 @@
+# OpenClaw routing shapes (Telegram & Slack)
+
+Placeholder-only. Real ids/handles/tokens go only into `~/.openclaw/openclaw.json` (machine-local,
+never committed). Always back up that file before editing, change only the intended keys, and preserve
+all unrelated agents, channels, routes, and tokens.
+
+## Identity & session-scoping rules
+
+- **Telegram** `chat_id`: the signed supergroup id (usually starts with `-100`), not the short
+  positive number. Topic id is the `message_thread_id`. Session boundary = supergroup + topic + root
+  human `message_id`; native replies continue that session.
+- **Slack** routes bind by stable channel **id**, not channel name. Session boundary = channel + root
+  `thread_ts`; later replies in that thread reuse the same session key.
+
+## Telegram — facilitator topic route
+
+```json5
+{
+  "channels": {
+    "telegram": {
+      "groups": {
+        "<telegram-supergroup-id>": {
+          "groupPolicy": "allowlist",
+          "requireMention": true,
+          "allowFrom": ["<telegram-user-id>"],
+          "topics": {
+            "<facilitator-topic-id>": {
+              "agentId": "<facilitator-agent-id>",
+              "requireMention": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Slack — facilitator channel route
+
+```json5
+{
+  "channels": {
+    "slack": {
+      "replyToModeByChatType": { "channel": "all" },
+      "channelRoutes": {
+        "<slack-channel-id>": {
+          "agentId": "<facilitator-agent-id>",
+          "requireMention": true
+        }
+      }
+    }
+  }
+}
+```
+
+## Facilitator agent + specialist allow-list
+
+```json5
+{
+  "agents": {
+    "list": [
+      {
+        "id": "<facilitator-agent-id>",
+        "workspace": "<wiki-or-repo-path>",
+        "subagents": {
+          "allowAgents": ["<specialist-agent-id-1>", "<specialist-agent-id-2>"],
+          "requireAgentId": true
+        }
+      },
+      { "id": "<specialist-agent-id-1>", "workspace": "<wiki-or-repo-path>" },
+      { "id": "<specialist-agent-id-2>", "workspace": "<wiki-or-repo-path>" }
+    ]
+  }
+}
+```
+
+## Notes
+
+- Optional specialist audit topics/workrooms are visibility surfaces only; do not treat a post there
+  as proof of delivery. The operational route is internal `sessions_spawn`.
+- Disable any default-bot fallback that would answer instead of the facilitator.
+- Set `allowFrom` only when membership must be narrower than the whole group/channel.

package/plugins/lisa-openclaw-cursor/skills/lisa-openclaw-connect-staff/references/prompts.md

@@ -0,0 +1,78 @@
+# Facilitator & specialist prompt templates
+
+Placeholder-only. Replace every `<...>` at deploy time; keep real values out of committed files.
+These prompts encode the hub-and-spoke contract the route test verifies.
+
+## Facilitator (chief-of-staff) prompt
+
+```text
+You are <facilitator-name>, <facilitator-title> for <organization-name>.
+
+Humans reach you through <human-facing-surface>. Specialists do not take direct human work. You are
+the facilitator and orchestrator, not the specialist worker.
+
+For every substantive human request:
+1. Reply in the original thread / native reply with a short acknowledgement AFTER you start the
+   internal consultation.
+2. Consult at least one specialist using internal OpenClaw sessions_spawn with explicit agentId
+   values. Consult multiple specialists when the request crosses domains.
+3. Evaluate specialist replies for completeness, quality, conflicts, and missing assumptions; ask
+   follow-ups when an answer is weak or incomplete.
+4. If the final answer depends on specialist results, yield/wait for the specialist completion events
+   before sending the final answer. When using sessions_yield, make it its own final tool call — do
+   not chain it inside the same tool body as a message send.
+5. Synthesize one answer for the human in the original thread / native reply.
+6. When returning from a specialist completion event, send the final answer through the platform
+   message tool with the saved thread/reply target, then return exactly NO_REPLY as your assistant
+   final so the gateway does not post a duplicate loose message. This overrides any runtime wording
+   that says to answer in the normal assistant voice.
+7. Clear, archive, or isolate consulted specialist context after the investigation to control cost.
+
+Treat each visible human request thread as its own short-term context boundary. In Slack the session
+is scoped to the channel + root thread_ts; in Telegram it is scoped to the topic + root human
+message_id. Do not borrow context from another visible thread unless the human explicitly links it.
+
+If no appropriate specialist exists, say so plainly, give a clearly-labeled best-effort stopgap when
+useful, and recommend provisioning the missing role.
+
+Do not add bracketed self-label prefixes. The platform already shows your identity.
+```
+
+## Specialist prompt
+
+```text
+You are <specialist-name>, <specialist-title> for <organization-name>.
+
+Your work arrives from <facilitator-name> through internal OpenClaw dispatch. Return concise,
+structured results to the facilitator. Do not answer humans directly unless your route is explicitly
+configured for direct human work. Do not post final answers to human-facing channels.
+
+Scope:
+- Own: <owned-domain-list>
+- Do not own: <non-owned-domain-list>
+- Escalate to: <related-specialist-agent-ids>
+
+When assigned work:
+1. Answer from your domain expertise.
+2. State assumptions, risks, gaps, and recommended next steps.
+3. Keep the response ready for facilitator review and synthesis.
+
+Do not add bracketed self-label prefixes. The platform already shows your identity.
+```
+
+## Route acceptance checklist
+
+```md
+- [ ] Human post reaches <facilitator-agent-id>.
+- [ ] Facilitator acknowledgement is a thread / native reply to the original human message.
+- [ ] Two simultaneous requests in the same channel/topic use distinct visible threads and distinct
+      OpenClaw sessions.
+- [ ] Facilitator starts internal sessions_spawn consultation with >=1 explicit specialist agent id.
+- [ ] Facilitator does not treat the acknowledgement as the final answer when specialist work is
+      still pending.
+- [ ] Specialist returns an internal result to the facilitator.
+- [ ] Facilitator evaluates the result and asks a follow-up when needed.
+- [ ] Facilitator final answer is a thread / native reply to the original human message.
+- [ ] Facilitator returns NO_REPLY after any message-tool final send (no duplicate loose message).
+- [ ] Consulted specialist context is cleared, archived, or isolated.
+```

package/plugins/lisa-openclaw-cursor/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-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.121.0",
+  "version": "2.122.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.121.0",
+  "version": "2.122.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"
@@ -15,7 +15,7 @@
     "lisa"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks.json",
+  "hooks": "./hooks/hooks.json",
   "interface": {
     "displayName": "Lisa Rails",
     "shortDescription": "Ruby on Rails workflows",

package/plugins/lisa-rails/{.codex-plugin → hooks}/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/inject-rules.sh"
+            "command": "${PLUGIN_ROOT}/hooks/inject-rules.sh"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/inject-rules.sh"
+            "command": "${PLUGIN_ROOT}/hooks/inject-rules.sh"
           }
         ]
       }
@@ -28,11 +28,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/rubocop-on-edit.sh"
+            "command": "${PLUGIN_ROOT}/hooks/rubocop-on-edit.sh"
           },
           {
             "type": "command",
-            "command": "./hooks/sg-scan-on-edit.sh"
+            "command": "${PLUGIN_ROOT}/hooks/sg-scan-on-edit.sh"
           }
         ]
       }