@codyswann/lisa 2.24.0 → 2.25.1

package/plugins/src/wiki/scripts/slack_oauth_user.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Run a local Slack OAuth flow for a user token.
+
+This helper intentionally requests user scopes, not bot scopes. It stores the
+OAuth response in an ignored local file by default; do not commit that file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import stat
+import sys
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+
+DEFAULT_SCOPES = ",".join(
+    [
+        "channels:read",
+        "channels:history",
+        "groups:read",
+        "groups:history",
+        "users:read",
+        "files:read",
+    ]
+)
+
+
+class OAuthHandler(BaseHTTPRequestHandler):
+    server: "OAuthServer"
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        return
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        params = urllib.parse.parse_qs(parsed.query)
+        state = params.get("state", [""])[0]
+        code = params.get("code", [""])[0]
+        error = params.get("error", [""])[0]
+
+        if error:
+            self.server.error = error
+            self._respond(400, f"Slack OAuth failed: {error}")
+            return
+
+        if state != self.server.expected_state:
+            self.server.error = "state_mismatch"
+            self._respond(400, "Slack OAuth failed: state mismatch.")
+            return
+
+        if not code:
+            self.server.error = "missing_code"
+            self._respond(400, "Slack OAuth failed: missing code.")
+            return
+
+        self.server.code = code
+        self._respond(200, "Slack OAuth complete. You can return to the terminal.")
+
+    def _respond(self, status: int, body: str) -> None:
+        data = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+class OAuthServer(HTTPServer):
+    expected_state: str
+    code: str | None
+    error: str | None
+
+
+def exchange_code(
+    *,
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str,
+) -> dict:
+    body = urllib.parse.urlencode(
+        {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+        }
+    ).encode("utf-8")
+    basic = base64.b64encode(f"{client_id}:{client_secret}".encode("utf-8")).decode("ascii")
+    request = urllib.request.Request(
+        "https://slack.com/api/oauth.v2.access",
+        data=body,
+        headers={
+            "Authorization": f"Basic {basic}",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    if not payload.get("ok"):
+        raise RuntimeError(f"Slack token exchange failed: {payload}")
+    return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--client-id", default=os.environ.get("SLACK_CLIENT_ID"))
+    parser.add_argument("--client-secret", default=os.environ.get("SLACK_CLIENT_SECRET"))
+    parser.add_argument("--redirect-uri", default="http://localhost:8765/slack/oauth/callback")
+    parser.add_argument("--scopes", default=os.environ.get("SLACK_USER_SCOPES", DEFAULT_SCOPES))
+    parser.add_argument("--output", default=".secrets/slack-user-token.json")
+    parser.add_argument("--no-open", action="store_true", help="Print the URL without opening a browser.")
+    args = parser.parse_args()
+
+    if not args.client_id or not args.client_secret:
+        parser.error("Provide --client-id/--client-secret or SLACK_CLIENT_ID/SLACK_CLIENT_SECRET.")
+
+    redirect = urllib.parse.urlparse(args.redirect_uri)
+    if redirect.hostname not in {"localhost", "127.0.0.1"}:
+        parser.error("This helper only starts a localhost callback server.")
+
+    state = secrets.token_urlsafe(32)
+    query = urllib.parse.urlencode(
+        {
+            "client_id": args.client_id,
+            "user_scope": args.scopes,
+            "redirect_uri": args.redirect_uri,
+            "state": state,
+        }
+    )
+    authorize_url = f"https://slack.com/oauth/v2/authorize?{query}"
+
+    server = OAuthServer((redirect.hostname or "localhost", redirect.port or 80), OAuthHandler)
+    server.expected_state = state
+    server.code = None
+    server.error = None
+
+    print("Open this URL to authorize Slack user-token access:")
+    print(authorize_url)
+    if not args.no_open:
+        webbrowser.open(authorize_url)
+
+    while server.code is None and server.error is None:
+        server.handle_request()
+
+    if server.error:
+        print(f"OAuth failed: {server.error}", file=sys.stderr)
+        return 1
+
+    payload = exchange_code(
+        client_id=args.client_id,
+        client_secret=args.client_secret,
+        code=server.code or "",
+        redirect_uri=args.redirect_uri,
+    )
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    output.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+    team = payload.get("team") or {}
+    print(f"Saved Slack OAuth response to {output}")
+    print(f"Team: {team.get('name') or team.get('id') or 'unknown'}")
+    print("Use it with: python3 scripts/ingest_slack_channel.py --token-file " + str(output) + " --channel '#channel-name'")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/src/wiki/scripts/validate-config.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * validate-config.mjs — dependency-free validator for wiki/lisa-wiki.config.json.
+ *
+ * Enforces the constraints described in schema/lisa-wiki-config.schema.json without
+ * requiring a JSON-Schema runtime, so it is portable to any downstream repo that
+ * installs the lisa-wiki plugin (no ajv / node_modules assumptions).
+ *
+ * Usage: node validate-config.mjs [path-to-config]
+ *   default path: wiki/lisa-wiki.config.json (relative to cwd)
+ * Exit code 0 = valid, 1 = invalid or unreadable.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const MODES = ["embedded", "wrapper", "standalone", "subdir"];
+const SIDE_EFFECTS = ["read-only-ingest", "repo-write", "external-write"];
+const RETENTION = [
+  "raw-ok",
+  "sanitized-note-only",
+  "metadata-only",
+  "external-pointer-only",
+];
+const SENSITIVITY = ["public", "internal", "confidential", "restricted"];
+const SOURCE_LAYOUT = ["by-system", "by-category"];
+const README_MODE = ["rich", "stub", "preserve"];
+
+const configPath = path.resolve(
+  process.argv[2] ?? "wiki/lisa-wiki.config.json"
+);
+const errors = [];
+const err = msg => errors.push(msg);
+
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every(x => typeof x === "string");
+}
+function checkEnum(value, allowed, label) {
+  if (value !== undefined && !allowed.includes(value)) {
+    err(`${label}: "${String(value)}" is not one of ${allowed.join(" | ")}`);
+  }
+}
+function checkType(value, type, label) {
+  if (value !== undefined && typeof value !== type) {
+    err(
+      `${label}: expected ${type}, got ${Array.isArray(value) ? "array" : typeof value}`
+    );
+  }
+}
+
+if (!fs.existsSync(configPath)) {
+  console.error(`✗ config not found: ${configPath}`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+} catch (e) {
+  console.error(`✗ config is not valid JSON: ${e.message}`);
+  process.exit(1);
+}
+
+if (!isObject(config)) {
+  console.error("✗ config must be a JSON object");
+  process.exit(1);
+}
+
+// Required
+for (const key of ["schemaVersion", "org", "mode", "wikiRoot", "categories"]) {
+  if (config[key] === undefined) err(`missing required field: ${key}`);
+}
+checkType(config.schemaVersion, "string", "schemaVersion");
+checkType(config.org, "string", "org");
+checkType(config.displayName, "string", "displayName");
+checkType(config.purpose, "string", "purpose");
+checkEnum(config.mode, MODES, "mode");
+checkType(config.wikiRoot, "string", "wikiRoot");
+if (
+  typeof config.wikiRoot === "string" &&
+  (path.isAbsolute(config.wikiRoot) ||
+    config.wikiRoot.split(/[\\/]/).includes(".."))
+) {
+  err(
+    'wikiRoot: must be a relative path inside the repo (no absolute paths, no ".." traversal)'
+  );
+}
+checkType(config.frontmatter, "boolean", "frontmatter");
+if (
+  config.categories !== undefined &&
+  !(isStringArray(config.categories) && config.categories.length > 0)
+) {
+  err("categories: must be a non-empty array of strings");
+}
+checkEnum(config.sourceRetention, RETENTION, "sourceRetention");
+checkType(config.contaminationTerms, "object", "contaminationTerms");
+if (
+  config.contaminationTerms !== undefined &&
+  !isStringArray(config.contaminationTerms)
+) {
+  err("contaminationTerms: must be an array of strings");
+}
+
+if (config.sources !== undefined) {
+  if (!isObject(config.sources)) err("sources: must be an object");
+  else checkEnum(config.sources.layout, SOURCE_LAYOUT, "sources.layout");
+}
+if (config.git !== undefined) {
+  if (!isObject(config.git)) err("git: must be an object");
+  else {
+    checkType(config.git.prPerIngestion, "boolean", "git.prPerIngestion");
+    checkType(config.git.autoMerge, "boolean", "git.autoMerge");
+    checkType(config.git.targetBranch, "string", "git.targetBranch");
+    checkType(config.git.branchPrefix, "string", "git.branchPrefix");
+  }
+}
+if (config.readme !== undefined) {
+  if (!isObject(config.readme)) err("readme: must be an object");
+  else checkEnum(config.readme.mode, README_MODE, "readme.mode");
+}
+if (config.sensitivity !== undefined) {
+  if (!isObject(config.sensitivity)) err("sensitivity: must be an object");
+  else {
+    checkType(config.sensitivity.enabled, "boolean", "sensitivity.enabled");
+    checkEnum(config.sensitivity.default, SENSITIVITY, "sensitivity.default");
+  }
+}
+if (config.documentation !== undefined) {
+  if (!isObject(config.documentation)) err("documentation: must be an object");
+  else {
+    checkType(config.documentation.absorb, "boolean", "documentation.absorb");
+    if (
+      config.documentation.keepInPlace !== undefined &&
+      !isStringArray(config.documentation.keepInPlace)
+    ) {
+      err("documentation.keepInPlace: must be an array of strings");
+    }
+  }
+}
+if (config.onboarding !== undefined) {
+  if (!isObject(config.onboarding)) err("onboarding: must be an object");
+  else
+    checkType(
+      config.onboarding.allowAudienceNote,
+      "boolean",
+      "onboarding.allowAudienceNote"
+    );
+}
+
+if (config.connectors !== undefined) {
+  if (!isObject(config.connectors))
+    err("connectors: must be an object (name -> connector config)");
+  else {
+    for (const [name, c] of Object.entries(config.connectors)) {
+      if (!isObject(c)) {
+        err(`connectors.${name}: must be an object`);
+        continue;
+      }
+      checkType(c.enabled, "boolean", `connectors.${name}.enabled`);
+      if (c.sideEffects === undefined) {
+        err(
+          `connectors.${name}: missing required field "sideEffects" (every connector must declare its side-effect class so full ingest can skip external-write)`
+        );
+      } else {
+        checkEnum(
+          c.sideEffects,
+          SIDE_EFFECTS,
+          `connectors.${name}.sideEffects`
+        );
+      }
+    }
+  }
+}
+
+if (config.customConnectors !== undefined) {
+  if (!Array.isArray(config.customConnectors))
+    err("customConnectors: must be an array");
+  else {
+    config.customConnectors.forEach((c, i) => {
+      if (!isObject(c)) {
+        err(`customConnectors[${i}]: must be an object`);
+        return;
+      }
+      for (const k of ["name", "skill", "sourceSystem", "sideEffects"]) {
+        if (c[k] === undefined)
+          err(`customConnectors[${i}]: missing required field "${k}"`);
+      }
+      checkEnum(
+        c.sideEffects,
+        SIDE_EFFECTS,
+        `customConnectors[${i}].sideEffects`
+      );
+    });
+  }
+}
+
+if (config.staff !== undefined) {
+  if (!Array.isArray(config.staff)) err("staff: must be an array");
+  else {
+    config.staff.forEach((s, i) => {
+      if (!isObject(s)) {
+        err(`staff[${i}]: must be an object`);
+        return;
+      }
+      for (const k of ["id", "role"]) {
+        if (s[k] === undefined)
+          err(`staff[${i}]: missing required field "${k}"`);
+      }
+      checkEnum(s.sensitivity, SENSITIVITY, `staff[${i}].sensitivity`);
+      if (s.owns !== undefined) {
+        if (!isObject(s.owns)) err(`staff[${i}].owns: must be an object`);
+        else {
+          for (const ok of ["categories", "connectors", "skills"]) {
+            if (s.owns[ok] !== undefined && !isStringArray(s.owns[ok])) {
+              err(`staff[${i}].owns.${ok}: must be an array of strings`);
+            }
+          }
+        }
+      }
+    });
+  }
+}
+
+if (errors.length > 0) {
+  console.error(`✗ ${path.relative(process.cwd(), configPath)} is invalid:`);
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}
+
+console.log(`✓ ${path.relative(process.cwd(), configPath)} is valid.`);

package/plugins/src/wiki/scripts/verify-migration.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * verify-migration.mjs — the deterministic half of /doctor. Dependency-free.
+ *
+ * Composes validate-config + lint-wiki into a grouped report and writes
+ * <wikiRoot>/state/migration/doctor-report.json with an overall verdict. Groups D
+ * (runtime surfaces) and E (functional smoke) are SKIPPED here — the lisa-wiki-doctor
+ * SKILL performs those and merges its results.
+ *
+ * Usage: node verify-migration.mjs [--wiki <root>] [--config <path>] [--migration]
+ * Exit 0 = READY or READY_WITH_WARNINGS, 1 = NOT_READY.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./_wiki-lib.mjs";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const opt = n => {
+  const i = argv.indexOf(n);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const migration = argv.includes("--migration");
+const configPath = opt("--config");
+const { config } = loadConfig(configPath);
+const wikiRoot = path.resolve(opt("--wiki") ?? config?.wikiRoot ?? "wiki");
+
+const groups = { A: [], B: [], C: [], D: [], E: [], F: [], G: [] };
+const add = (g, id, status, message) => groups[g].push({ id, status, message });
+
+function runNode(script, args) {
+  const res = spawnSync("node", [path.join(scriptDir, script), ...args], {
+    encoding: "utf8",
+  });
+  return {
+    status: res.status ?? 1,
+    stdout: res.stdout ?? "",
+    stderr: (res.stderr ?? "") + (res.error ? `\n${res.error.message}` : ""),
+  };
+}
+
+// --- A. structure & config ------------------------------------------------
+const vc = runNode("validate-config.mjs", [
+  configPath ?? path.join(wikiRoot, "lisa-wiki.config.json"),
+]);
+add(
+  "A",
+  "config-valid",
+  vc.status === 0 ? "PASS" : "FAIL",
+  vc.status === 0
+    ? "config validates"
+    : `config invalid: ${(vc.stderr || vc.stdout).trim().split("\n").slice(0, 6).join("; ")}`
+);
+add(
+  "A",
+  "schema-version",
+  config?.schemaVersion ? "PASS" : "FAIL",
+  config?.schemaVersion
+    ? `schemaVersion ${config.schemaVersion}`
+    : "schemaVersion missing"
+);
+add(
+  "A",
+  "readme-mode",
+  config?.readme?.mode ? "PASS" : "WARN",
+  config?.readme?.mode
+    ? `readme.mode ${config.readme.mode}`
+    : "readme.mode not recorded (asked by /setup)"
+);
+add(
+  "A",
+  "purpose",
+  config?.purpose ? "PASS" : "WARN",
+  config?.purpose
+    ? "purpose set"
+    : "purpose not set (asked by /setup; feeds onboarding + contract)"
+);
+
+// --- A/B. lint (structure -> A, everything else -> B) ---------------------
+const lint = runNode("lint-wiki.mjs", [
+  "--wiki",
+  wikiRoot,
+  ...(configPath ? ["--config", configPath] : []),
+  "--json",
+]);
+let lintReport;
+try {
+  lintReport = JSON.parse(lint.stdout);
+} catch {
+  add(
+    "B",
+    "lint-run",
+    "FAIL",
+    `lint-wiki did not produce JSON: ${(lint.stderr || lint.stdout).trim().slice(0, 200)}`
+  );
+}
+if (lintReport) {
+  const structureItems = lintReport.items.filter(i => i.group === "structure");
+  const otherItems = lintReport.items.filter(i => i.group !== "structure");
+  if (structureItems.length === 0)
+    add("A", "structure", "PASS", "structure conforms to the manifest");
+  for (const i of structureItems)
+    add(
+      "A",
+      `structure:${i.group}`,
+      i.status,
+      `${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+  if (otherItems.length === 0)
+    add("B", "integrity", "PASS", "no integrity/safety findings");
+  for (const i of otherItems)
+    add(
+      "B",
+      `${i.group}`,
+      i.status,
+      `${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+}
+
+// --- C/D/E/F/G: deterministic-light + delegated to the doctor skill --------
+add(
+  "C",
+  "no-loss",
+  "SKIP",
+  "no-loss/parity needs the migration manifest from /migrate; dangling-link check is covered in B"
+);
+add(
+  "D",
+  "runtime",
+  "SKIP",
+  "runtime surfaces (commands/skills/subagents/MCP) verified by the lisa-wiki-doctor skill"
+);
+add(
+  "E",
+  "smoke",
+  "SKIP",
+  "functional smoke tests (ingest/query/lint/onboard) performed by the lisa-wiki-doctor skill"
+);
+add(
+  "F",
+  "mode",
+  config?.mode ? "PASS" : "FAIL",
+  config?.mode ? `mode: ${config.mode}; wikiRoot resolves` : "mode not set"
+);
+add(
+  "G",
+  "git-ci-dist",
+  "SKIP",
+  "git/CI/distribution checks performed by the lisa-wiki-doctor skill and CI"
+);
+
+// --- verdict --------------------------------------------------------------
+const all = Object.values(groups).flat();
+const isBlockingWarn = (item, group) =>
+  migration && (group === "A" || group === "B") && item.status === "WARN";
+let verdict = "READY";
+if (all.some(i => i.status === "FAIL")) verdict = "NOT_READY";
+else if (
+  Object.entries(groups).some(([g, items]) =>
+    items.some(i => isBlockingWarn(i, g))
+  )
+)
+  verdict = "NOT_READY";
+else if (all.some(i => i.status === "WARN")) verdict = "READY_WITH_WARNINGS";
+
+const reportObj = {
+  tool: "verify-migration",
+  deterministic: true,
+  wikiRoot: path.relative(process.cwd(), wikiRoot) || ".",
+  mode: config?.mode ?? null,
+  migration,
+  generatedAt: new Date().toISOString(),
+  verdict,
+  subset: "deterministic",
+  note: "Deterministic subset only. Groups C (no-loss/parity), D (runtime surfaces), E (functional smoke), and G (git/CI/distribution) are completed by the lisa-wiki-doctor skill, which merges its results into this report.",
+  groups,
+};
+
+const outPath = path.join(wikiRoot, "state", "migration", "doctor-report.json");
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, `${JSON.stringify(reportObj, null, 2)}\n`);
+
+const counts = all.reduce(
+  (acc, i) => ((acc[i.status] = (acc[i.status] ?? 0) + 1), acc),
+  {}
+);
+console.log(
+  `verdict: ${verdict}  (${["PASS", "WARN", "FAIL", "SKIP"].map(s => `${counts[s] ?? 0} ${s}`).join(", ")})`
+);
+console.log(`report → ${path.relative(process.cwd(), outPath)}`);
+console.log(
+  "  (deterministic subset — C/D/E/G completed by the /doctor skill)"
+);
+for (const i of all.filter(i => i.status === "FAIL" || i.status === "WARN")) {
+  console.log(`  ${i.status === "FAIL" ? "✗" : "⚠"} [${i.id}] ${i.message}`);
+}
+process.exit(verdict === "NOT_READY" ? 1 : 0);

package/plugins/src/wiki/skills/lisa-wiki-add-ingest/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: lisa-wiki-add-ingest
+description: Scaffold a project-specific "front-door" ingest skill that does something unique (classify a source, fetch from a special system, stamp domain frontmatter) and then chains into /ingest. Use when a project needs a bespoke ingestion path that the core connectors do not cover — instead of forking the kernel. The generated skill enriches and delegates; the kernel still owns synthesis, index, log, verify, state, and PR.
+---
+
+# lisa-wiki-add-ingest
+
+Generate a thin, project-local front-door ingest skill so a project can extend ingestion **without
+forking** the kernel. The front-door does only the unique part, then hands enriched parameters to
+`/ingest`.
+
+## Workflow
+1. **Interview** the project: a short name; what the source is; which `wiki/sources/<sourceSystem>/`
+   bucket and page type/frontmatter it should produce; whether it merely *enriches/classifies* an
+   input or also *fetches* from an external system; and its **side-effect class**
+   (`read-only-ingest` | `repo-write` | `external-write`).
+2. **Generate** the front-door skill on both runtimes —
+   `.claude/skills/lisa-wiki-local-<name>/SKILL.md` and `.agents/skills/lisa-wiki-local-<name>/SKILL.md`.
+   Its body does the unique step, then **delegates to the `lisa-wiki-ingest` skill** (Claude facade
+   `/ingest`) passing the bucket/type/metadata. If it fetches, it writes only a sanitized source note
+   (+ run metadata) and lets the kernel do synthesis/index/log/verify/state/PR.
+3. **Register** it in `wiki/lisa-wiki.config.json` under `customConnectors`
+   (`{ name, skill, sourceSystem, stateFile, sideEffects }`). `/ingest` dispatches **only** to
+   registered names — no auto-discovery.
+
+## Rules (the front-door contract)
+- A generated front-door writes **only** its source note + run metadata. It must not write synthesis
+  pages, `index.md`, `log.md`, or final state — the kernel does those, in order, after it returns.
+- `external-write` front-doors require config opt-in **and** explicit per-run intent, and their PRs
+  never auto-merge.
+- Side effects outside the declared class are a hard failure (enforced by the touched-file guard).
+
+## Related
+`lisa-wiki-ingest` (what it chains into), `lisa-wiki-add-role`, `lisa-wiki-doctor`.

package/plugins/src/wiki/skills/lisa-wiki-add-role/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lisa-wiki-add-role
+description: Scaffold a domain-expert "digital staff" role over the wiki — a dual-runtime subagent (Claude + Codex) plus a staff doc page — from a config.staff[] entry. Use when a project wants a role-scoped expert (e.g. Legal, Finance, Sales) whose knowledge is a slice of the wiki. The plugin only SETS UP the subagent; whether it is ever invoked, scheduled, or routed is out of scope.
+---
+
+# lisa-wiki-add-role
+
+Turn a role definition into two generated artifacts: a documentation page in the wiki and a runnable,
+brain-pointed subagent on both runtimes. **Running the subagent (invocation, scheduling, Telegram /
+agent-team routing, private notebooks) is out of scope** — this skill only creates it.
+
+## Workflow
+1. **Resolve the role** from a `config.staff[]` entry (or interview to add one): `id`, `role`,
+   `expertise`, `owns` (categories / connectors / skills), `sensitivity`.
+2. **Doc page:** generate `wiki/staff/<id>.md` describing the role, its owned domain, and who it
+   reports to. This page is wiki content and is itself ingestible (the `roles` connector).
+3. **Subagents (dual-runtime), rendered from the role-agent templates:**
+   - Claude: `.claude/agents/<id>.md`.
+   - Codex: `.codex/agents/<id>.toml` (keys `name`, `description`, `developer_instructions`; optional
+     `model`, `model_reasoning_effort`, `sandbox_mode`).
+4. **Brain-pointed, not baked:** the subagent's instructions say *"your domain is `wiki/<owned>/`;
+   `/query` it first, contribute via `/ingest`; stay in your lane."* It points at the live wiki so it
+   never goes stale. Only its one-line `description` is synthesized from the wiki at generation time.
+
+## Rules
+- v1 instructs lane-keeping but does not *enforce* per-role write isolation (deferred).
+- Setup seeds the starter roster by delegating here per `config.staff[]` entry.
+
+## Related
+`lisa-wiki-setup` (seeds the roster), `lisa-wiki-add-ingest`, `lisa-wiki-onboard-me`.