@codyswann/lisa 2.29.0 → 2.31.0

package/.agents/plugins/marketplace.json

@@ -87,6 +87,30 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Coding"
+    },
+    {
+      "name": "lisa-wiki",
+      "source": {
+        "source": "local",
+        "path": "./plugins/lisa-wiki"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "lisa-openclaw",
+      "source": {
+        "source": "local",
+        "path": "./plugins/lisa-openclaw"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }

package/.claude-plugin/marketplace.json

@@ -55,6 +55,12 @@
       "source": "./plugins/lisa-wiki",
       "description": "LLM Wiki — git-native markdown knowledge base: ingest, query, lint, onboard (Claude + Codex)",
       "category": "productivity"
+    },
+    {
+      "name": "lisa-openclaw",
+      "source": "./plugins/lisa-openclaw",
+      "description": "Connect staff to Telegram or Slack via OpenClaw — facilitator/specialist routing and repo-coding topics (Claude + Codex)",
+      "category": "productivity"
     }
   ]
 }

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/skills/github-build-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-build-intake
-description: "GitHub counterpart to lisa:jira-build-intake. Scans a GitHub repository for issues carrying the configured `ready` build label, claims each by relabeling to the configured `claimed` label, runs the implementation/build flow via lisa:github-agent, and relabels to the configured `done` label on completion. The `ready` label is the human-flipped signal that an issue is truly ready for development — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
+description: "GitHub counterpart to lisa:jira-build-intake. Scans a GitHub repository for issues carrying the configured `ready` build label, claims each leaf work unit by relabeling to the configured `claimed` label, runs the implementation/build flow via lisa:github-agent, and relabels to the configured `done` label on completion. Enforces the claim-time arm of the `leaf-only-lifecycle` rule: a parent/container with open child work (or a childless Epic/Story/Spike) that still carries a stale build-ready label is skipped or safe-blocked with a lifecycle-repair comment, never claimed. The `ready` label is the human-flipped signal that an issue is truly ready for development — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
 allowed-tools: ["Skill", "Bash"]
 ---
 
@@ -135,7 +135,54 @@ If none of the configured role labels exist on the repo → label convention not
 
 ### Phase 3 — Process each ready issue (serial)
 
-#### 3a. Claim
+#### 3a. Leaf-only claim gate (skip / safe-block containers)
+
+Build intake claims **only independently implementable leaf work units**. This enforces the claim-time arm of the vendor-neutral `leaf-only-lifecycle` rule: a parent/container that still carries a stale build-ready role (e.g. `status:ready` applied before this rule existed, or hand-applied to an Epic/Story) is **never claimed** — intake skips it or safe-blocks it with a clear lifecycle-repair message. It is the claim-time complement to the write-time labeling in `lisa:github-write-issue` and the validate-time S15 gate in `lisa:github-validate-issue`; all three cite the same rule so the classification never drifts. **Never silently implement a container.**
+
+Run this gate **before** the claim relabel, for every candidate issue. Do NOT relabel, comment "Claimed", or invoke `lisa:github-agent` for an issue that fails the gate.
+
+**Resolve container vs. leaf — structural first, then nominal.** Per `leaf-only-lifecycle` the classification is structural: an issue is a **container** if it has **open** child work, whatever its declared type; otherwise the **type label** decides. Resolve child work using the same hierarchy `lisa:github-read-issue` uses — native sub-issues first, then body parentage (task-list checkboxes referencing other issues, `Blocked by #<n>` / `Parent: #<n>` references):
+
+```bash
+# Native sub-issues via GraphQL (same query lisa:github-read-issue uses).
+SUBS=$(gh api graphql -f query='
+query($org:String!,$repo:String!,$number:Int!){
+  repository(owner:$org,name:$repo){
+    issue(number:$number){
+      subIssues(first: 100) {
+        nodes { number state }
+      }
+    }
+  }
+}' -F org=<org> -F repo=<repo> -F number=<number> 2>/dev/null)
+
+# Count children still OPEN — a parent whose children are all closed is no longer
+# holding open work and rolls up via lisa:github-read-issue's rollup, not here.
+OPEN_CHILDREN=$(echo "$SUBS" | jq -r '[.data.repository.issue.subIssues.nodes[]? | select(.state == "OPEN")] | length' 2>/dev/null)
+OPEN_CHILDREN=${OPEN_CHILDREN:-0}
+```
+
+If the GraphQL `subIssues` field is unavailable (older GHES), fall back to parsing the body for child references exactly as `lisa:github-read-issue` does, and treat the issue as a container if any referenced child issue is open. Note "GraphQL sub-issues unavailable" so the operator knows parentage was text-derived.
+
+Classify and act (first match wins). `type:` is read from the issue's labels (`type:Epic`, `type:Story`, `type:Spike`, `type:Bug`, `type:Task`, `type:Sub-task`, `type:Improvement`):
+
+| Condition | Class | Action |
+|---|---|---|
+| `OPEN_CHILDREN > 0` (open child work, any type) | **Container** | **Skip / safe-block — do NOT claim** |
+| no open children AND `type ∈ {Epic, Story, Spike}` | **Childless container-type** | **Skip / safe-block — do NOT claim** |
+| no open children AND `type ∈ {Bug, Task, Sub-task, Improvement}` (or no `type:` label) | **Leaf work unit** | **Proceed to 3b claim** |
+
+The childless-parent exception is narrow: childlessness enables a claim **only** for types that are leaf work units to begin with. A childless Epic/Story/Spike is an incomplete decomposition, not an implementable unit — it is never claimed.
+
+**Safe-block (default action for a flagged container).** Leave the build-ready role in place (don't silently strip it — that hides the lifecycle error), post a single lifecycle-repair comment, and record the issue under "Skipped (container)" in the summary. Do NOT relabel to `$CLAIMED`. Keep the comment idempotent — skip posting if an identical `[claude-build-intake]` lifecycle-repair comment already exists on the issue, so a re-entrant cycle doesn't spam it.
+
+```bash
+gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Not claimed: this issue carries the build-ready role ($READY) but is a container with open child work (or a childless Epic/Story/Spike), which violates the leaf-only-lifecycle rule. Build-ready is leaf-only — an agent claims and implements leaves, never a container. Repair: move $READY off this parent onto its leaf children (or, for a childless Epic/Story/Spike, decompose it into leaf children or reclassify it to a leaf type). A parent's lifecycle state rolls up from its children and is never set to ready directly."
+```
+
+This gate never blocks a legitimate flat Task/Bug: those have no open children and a leaf `type:`, so they fall straight through to the claim in 3b.
+
+#### 3b. Claim
 
 ```bash
 gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
@@ -146,7 +193,7 @@ This is the idempotency lock — a re-entrant cycle's `--label $READY` filter wi
 
 If the relabel fails (permission, race), log under "Errors" in the cycle summary and skip this issue. **Do not invoke the build flow on an issue you didn't successfully claim.**
 
-#### 3b. Run the build flow
+#### 3c. Run the build flow
 
 Invoke `lisa:github-agent` (the per-issue lifecycle agent) with the issue ref. `lisa:github-agent` owns:
 - Reading the full issue graph (`lisa:github-read-issue`)
@@ -163,7 +210,7 @@ Wait for `lisa:github-agent` to return. Capture its outcome:
 - **Blocked by ticket-triage ambiguities** — `lisa:github-agent` posts findings and stops. The issue stays in `$CLAIMED`. Surface to human; do not auto-relabel. Record under "Errors".
 - **Errored** — exception, missing config, etc. Leave the issue in `$CLAIMED` for human investigation. Record under "Errors".
 
-#### 3c. Transition to $DONE (only on Success)
+#### 3d. Transition to $DONE (only on Success)
 
 If `lisa:github-agent` returned Success:
 
@@ -176,7 +223,7 @@ gh issue comment <number> --repo <org>/<repo> --body "[claude-build-intake] Buil
 
 For any non-Success outcome, do NOT transition. The issue sits in `$CLAIMED` (or wherever `lisa:github-agent` left it) — humans take it from there.
 
-#### 3d. Continue
+#### 3e. Continue
 
 Move to the next ready issue. One issue failing does not stop others.
 
@@ -192,6 +239,8 @@ Cycle completed: <ISO timestamp>
 Issues processed: <n>
 - $DONE (build complete, PR ready): <n>
   - <org>/<repo>#<number> <title> → PR <URL>
+- Skipped (container — leaf-only-lifecycle): <n>
+  - <org>/<repo>#<number> <title> — build-ready on a parent with open child work; lifecycle-repair comment posted
 - Blocked (pre-flight verify failed): <n>
   - <org>/<repo>#<number> <title> — see issue comments
 - Held (triage found ambiguities): <n>
@@ -204,6 +253,7 @@ Total PRs opened: <n>
 
 ## Idempotency & safety
 
+- **Leaf-only claim gate runs first**: Phase 3a classifies each candidate before any claim; a container with open child work (or a childless Epic/Story/Spike) is skipped/safe-blocked, never claimed. The safe-block comment is idempotent — a re-entrant cycle does not re-post it.
 - **Claim-first ordering**: `$CLAIMED` set BEFORE `lisa:github-agent` invocation — no double-pickup.
 - **No writes outside the lifecycle**: this skill only relabels `$READY → $CLAIMED` and `$CLAIMED → $DONE`. Every other label change is owned by `lisa:github-agent`.
 - **Failure isolation**: per-issue exceptions caught and recorded; the cycle continues.
@@ -227,6 +277,7 @@ If the repo has not adopted the `status:*` label namespace, this skill cannot ru
 
 ## Rules
 
+- **Claim leaves only.** Per the `leaf-only-lifecycle` rule, never claim a container — an issue with open child work, or a childless Epic/Story/Spike — even if it carries the build-ready role. Skip or safe-block it (Phase 3a); never silently implement a container.
 - Never relabel an issue the cycle didn't claim. The `$CLAIMED` label is the signature of cycle ownership.
 - Never bypass `lisa:github-agent` to do build work directly. `lisa:github-agent` owns the per-issue lifecycle.
 - Never auto-transition past `$DONE`. Downstream labels (terminal `status:done`, etc.) are owned by QA / PM / merge automation.

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -0,0 +1,8 @@
+{
+  "name": "lisa-openclaw",
+  "version": "2.31.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/.codex-plugin/plugin.json

@@ -0,0 +1,32 @@
+{
+  "name": "lisa-openclaw",
+  "version": "2.31.0",
+  "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "keywords": [
+    "openclaw",
+    "telegram",
+    "slack",
+    "agents",
+    "chat-ops"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Lisa OpenClaw",
+    "shortDescription": "Staff on Telegram/Slack via OpenClaw",
+    "longDescription": "Wire staff roles to human chat surfaces through OpenClaw: set up the gateway prerequisites, connect a facilitator (chief of staff) and its specialists on Telegram or Slack with hub-and-spoke routing, and bind Telegram forum topics to dispatcher+worker pairs for repo-coding work. Distributed for both Claude Code and Codex.",
+    "developerName": "Cody Swann",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Set up OpenClaw for this project",
+      "Connect my chief of staff to Telegram",
+      "Connect staff to Slack via OpenClaw"
+    ]
+  }
+}

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