@codyswann/lisa 2.38.0 → 2.39.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/skills/lisa-wiki-add-ingest/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-add-ingest"
-short_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."
+display_name: "Lisa Wiki Add Ingest"
+short_description: "Scaffold a project-specific \"front-door\" ingest skill that does something unique (classify a source, fetch from a special system, stamp…"
 default_prompt:
-  - "Use $lisa-wiki-add-ingest"
+  - "Use $lisa-wiki-add-ingest: Scaffold a project-specific \"front-door\" ingest skill that does something unique (classify a source, fetch from a special system, stamp…."

package/plugins/lisa-wiki/skills/lisa-wiki-add-role/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-add-role"
-short_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."
+display_name: "Lisa Wiki Add Role"
+short_description: "Scaffold a domain-expert \"digital staff\" role over the wiki — a dual-runtime subagent (Claude + Codex) plus a staff doc page — from a…"
 default_prompt:
-  - "Use $lisa-wiki-add-role"
+  - "Use $lisa-wiki-add-role: Scaffold a domain-expert \"digital staff\" role over the wiki — a dual-runtime subagent (Claude + Codex) plus a staff doc page — from a…."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-confluence/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-confluence"
-short_description: "Produce sanitized Confluence source notes for lisa-wiki ingest via the Atlassian MCP. Use only when lisa-wiki-ingest routes to the confluence connector. Read-only; tenant-guarded."
+display_name: "Lisa Wiki Connector Confluence"
+short_description: "Produce sanitized Confluence source notes for lisa-wiki ingest via the Atlassian MCP"
 default_prompt:
-  - "Use $lisa-wiki-connector-confluence"
+  - "Use $lisa-wiki-connector-confluence: Produce sanitized Confluence source notes for lisa-wiki ingest via the Atlassian MCP."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-docs/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-docs"
-short_description: "Ingest a local document (PDF, DOCX, Markdown, text) into a sanitized source note for lisa-wiki ingest. Use only when lisa-wiki-ingest routes to the docs connector (a file-path input). Uses available local converters; no heavy bundled dependency."
+display_name: "Lisa Wiki Connector Docs"
+short_description: "Ingest a local document (PDF, DOCX, Markdown, text) into a sanitized source note for lisa-wiki ingest"
 default_prompt:
-  - "Use $lisa-wiki-connector-docs"
+  - "Use $lisa-wiki-connector-docs: Ingest a local document (PDF, DOCX, Markdown, text) into a sanitized source note for lisa-wiki ingest."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-git/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-git"
-short_description: "Produce sanitized git/PR-history source notes for lisa-wiki ingest. Use only when lisa-wiki-ingest routes to the git connector (self repo or a registered project). Read-only — never checks out, fetches, or mutates the target repo."
+display_name: "Lisa Wiki Connector Git"
+short_description: "Produce sanitized git/PR-history source notes for lisa-wiki ingest"
 default_prompt:
-  - "Use $lisa-wiki-connector-git"
+  - "Use $lisa-wiki-connector-git: Produce sanitized git/PR-history source notes for lisa-wiki ingest."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-jira/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-jira"
-short_description: "Produce sanitized JIRA source notes for lisa-wiki ingest via the Atlassian MCP. Use only when lisa-wiki-ingest routes to the jira connector. Read-only; tenant-guarded."
+display_name: "Lisa Wiki Connector Jira"
+short_description: "Produce sanitized JIRA source notes for lisa-wiki ingest via the Atlassian MCP"
 default_prompt:
-  - "Use $lisa-wiki-connector-jira"
+  - "Use $lisa-wiki-connector-jira: Produce sanitized JIRA source notes for lisa-wiki ingest via the Atlassian MCP."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-memory/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-memory"
-short_description: "Ingest the agent's PROJECT-SCOPED memory into a sanitized source note. Use only when lisa-wiki-ingest routes to the memory connector. NEVER ingests global or unrelated memory — global Codex memory and the Chronicle store are refused."
+display_name: "Lisa Wiki Connector Memory"
+short_description: "Ingest the agent's PROJECT-SCOPED memory into a sanitized source note"
 default_prompt:
-  - "Use $lisa-wiki-connector-memory"
+  - "Use $lisa-wiki-connector-memory: Ingest the agent's PROJECT-SCOPED memory into a sanitized source note."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-notion/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-notion"
-short_description: "Produce sanitized Notion source notes for lisa-wiki ingest via the Notion MCP. Use only when lisa-wiki-ingest routes to the notion connector. Read-only; teamspace-guarded."
+display_name: "Lisa Wiki Connector Notion"
+short_description: "Produce sanitized Notion source notes for lisa-wiki ingest via the Notion MCP"
 default_prompt:
-  - "Use $lisa-wiki-connector-notion"
+  - "Use $lisa-wiki-connector-notion: Produce sanitized Notion source notes for lisa-wiki ingest via the Notion MCP."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-roles/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-roles"
-short_description: "Ingest the wiki's own digital-staff roster (config.staff[] + wiki/staff/*) into a sanitized source note. Use only when lisa-wiki-ingest routes to the roles connector. Does not run any subagent."
+display_name: "Lisa Wiki Connector Roles"
+short_description: "Ingest the wiki's own digital-staff roster (config.staff[] + wiki/staff/*) into a sanitized source note"
 default_prompt:
-  - "Use $lisa-wiki-connector-roles"
+  - "Use $lisa-wiki-connector-roles: Ingest the wiki's own digital-staff roster (config.staff[] + wiki/staff/*) into a sanitized source note."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-slack/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-slack"
-short_description: "Ingest a Slack channel into sanitized source notes via a user token. Use only when lisa-wiki-ingest routes to the slack connector AND the run carries explicit external-write intent (Slack OAuth opens a browser and stores a token file). Centralized stdlib-Python scripts; secrets are redacted."
+display_name: "Lisa Wiki Connector Slack"
+short_description: "Ingest a Slack channel into sanitized source notes via a user token"
 default_prompt:
-  - "Use $lisa-wiki-connector-slack"
+  - "Use $lisa-wiki-connector-slack: Ingest a Slack channel into sanitized source notes via a user token."

package/plugins/lisa-wiki/skills/lisa-wiki-connector-web/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-connector-web"
-short_description: "Ingest a public URL into a sanitized source note for lisa-wiki ingest (via WebFetch). Use only when lisa-wiki-ingest routes to the web connector (a URL input). Read-only."
+display_name: "Lisa Wiki Connector Web"
+short_description: "Ingest a public URL into a sanitized source note for lisa-wiki ingest (via WebFetch)"
 default_prompt:
-  - "Use $lisa-wiki-connector-web"
+  - "Use $lisa-wiki-connector-web: Ingest a public URL into a sanitized source note for lisa-wiki ingest (via WebFetch)."

package/plugins/lisa-wiki/skills/lisa-wiki-doctor/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-doctor"
-short_description: "Verify that a wiki is correctly set up and (after migration) fully functional. Runs the deterministic checks plus functional smoke tests, writes a doctor report, and returns an overall verdict. Use as the final gate of /migrate, after /setup, or anytime to confirm wiki health. A repo is not \"migrated\" until its doctor verdict is READY."
+display_name: "Lisa Wiki Doctor"
+short_description: "Verify that a wiki is correctly set up and (after migration) fully functional"
 default_prompt:
-  - "Use $lisa-wiki-doctor"
+  - "Use $lisa-wiki-doctor: Verify that a wiki is correctly set up and (after migration) fully functional."

package/plugins/lisa-wiki/skills/lisa-wiki-ingest/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-ingest"
-short_description: "Ingest source material into the LLM Wiki. With an argument (URL, file path, or prompt) it ingests that one source; with no argument it runs a full ingest across every enabled non-external-write source. Routes to the right connector, then runs the ordered pipeline (source note → synthesis → index → log → verify → state → commit/PR). Use whenever new knowledge should enter the wiki."
+display_name: "Lisa Wiki Ingest"
+short_description: "Ingest source material into the LLM Wiki"
 default_prompt:
-  - "Use $lisa-wiki-ingest"
+  - "Use $lisa-wiki-ingest: Ingest source material into the LLM Wiki."

package/plugins/lisa-wiki/skills/lisa-wiki-lint/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-lint"
-short_description: "Health-check the LLM Wiki. Reports orphan pages, contradictions, stale claims, broken internal links, missing index/log coverage, structure-manifest violations, and secret/tenant leaks. Use periodically or before hardening a wiki. Read-only — it reports findings, it does not fix them."
+display_name: "Lisa Wiki Lint"
+short_description: "Health-check the LLM Wiki"
 default_prompt:
-  - "Use $lisa-wiki-lint"
+  - "Use $lisa-wiki-lint: Health-check the LLM Wiki."

package/plugins/lisa-wiki/skills/lisa-wiki-migrate/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-migrate"
-short_description: "Migrate an existing, hand-rolled wiki implementation onto the lisa-wiki kernel — phased and compatibility-first, with a strict no-loss guarantee. Use when adopting lisa-wiki in a repo that already has its own wiki/, ingest skills, docs, or roles. Renaming things into the canonical shape is fine; losing functionality or data is not. Ends by running /doctor."
+display_name: "Lisa Wiki Migrate"
+short_description: "Migrate an existing, hand-rolled wiki implementation onto the lisa-wiki kernel — phased and compatibility-first, with a strict no-loss…"
 default_prompt:
-  - "Use $lisa-wiki-migrate"
+  - "Use $lisa-wiki-migrate: Migrate an existing, hand-rolled wiki implementation onto the lisa-wiki kernel — phased and compatibility-first, with a strict no-loss…."

package/plugins/lisa-wiki/skills/lisa-wiki-onboard-me/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-onboard-me"
-short_description: "Onboard a user to the project via its LLM Wiki. Interviews the user about themselves in relation to the project, captures that to project-scoped memory only, then gives a guided tour of what the project is and sample questions they can ask. Use when someone is new to the project or asks to be onboarded. Read-mostly — it does not open PRs or write PII into the wiki."
+display_name: "Lisa Wiki Onboard Me"
+short_description: "Onboard a user to the project via its LLM Wiki"
 default_prompt:
-  - "Use $lisa-wiki-onboard-me"
+  - "Use $lisa-wiki-onboard-me: Onboard a user to the project via its LLM Wiki."

package/plugins/lisa-wiki/skills/lisa-wiki-query/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-query"
-short_description: "Answer a question from the LLM Wiki with citations. Reads the index, drills into relevant pages, and synthesizes a cited answer. Read-only by default; only files new synthesis back into the wiki when the user explicitly asks. Use when someone asks a question the wiki should be able to answer, or wants to explore what the wiki knows."
+display_name: "Lisa Wiki Query"
+short_description: "Answer a question from the LLM Wiki with citations"
 default_prompt:
-  - "Use $lisa-wiki-query"
+  - "Use $lisa-wiki-query: Answer a question from the LLM Wiki with citations."

package/plugins/lisa-wiki/skills/lisa-wiki-setup/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-setup"
-short_description: "Scaffold, repair, verify, or upgrade a project's LLM Wiki from its config. Use when setting up the wiki in a new repo, fixing a broken/incomplete structure, or upgrading to a newer kernel version. Asks the wiki's purpose and README mode, renders the contract snapshot, scaffolds the canonical folders, and seeds the staff roster. Idempotent and non-destructive."
+display_name: "Lisa Wiki Setup"
+short_description: "Scaffold, repair, verify, or upgrade a project's LLM Wiki from its config"
 default_prompt:
-  - "Use $lisa-wiki-setup"
+  - "Use $lisa-wiki-setup: Scaffold, repair, verify, or upgrade a project's LLM Wiki from its config."

package/plugins/lisa-wiki/skills/lisa-wiki-usage/agents/openai.yaml

@@ -1,4 +1,4 @@
-display_name: "lisa-wiki-usage"
-short_description: "Explain how to browse, query, and contribute to this project's LLM Wiki. Use when a user asks how the wiki works, where knowledge lives, how to find something, or how to add to it — the read/navigation path, not an ingestion or write workflow."
+display_name: "Lisa Wiki Usage"
+short_description: "Explain how to browse, query, and contribute to this project's LLM Wiki"
 default_prompt:
-  - "Use $lisa-wiki-usage"
+  - "Use $lisa-wiki-usage: Explain how to browse, query, and contribute to this project's LLM Wiki."

package/scripts/generate-codex-plugin-artifacts.mjs

@@ -123,30 +123,167 @@ export function serializeInterfaceToYaml(iface) {
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Acronyms that should stay fully upper-cased when a skill name is humanized.
+ *
+ * Skill names are kebab/snake tokens (e.g. `exploratory-qa`); naive title-casing
+ * would yield "Qa". Tokens listed here (compared case-insensitively) are emitted
+ * upper-case instead so `exploratory-qa` -> "Exploratory QA". The set is small and
+ * deliberately conservative — only well-known initialisms that appear in Lisa
+ * skill names — so humanization stays a pure, predictable function of the input.
+ */
+const ACRONYMS = new Set([
+  "qa",
+  "ci",
+  "cd",
+  "pr",
+  "prd",
+  "ui",
+  "ux",
+  "api",
+  "cli",
+  "sdk",
+  "tdd",
+  "mcp",
+  "aws",
+  "cdk",
+  "zap",
+  "owasp",
+  "sql",
+  "url",
+  "id",
+  "io",
+  "llm",
+]);
+
+/**
+ * Humanize a kebab/snake/space-delimited token into a Title-Cased display name.
+ *
+ * Splits on `-`, `_`, and runs of whitespace, then title-cases each word —
+ * except tokens in {@link ACRONYMS}, which are upper-cased. This is the rule the
+ * PRD (#521) specifies for `display_name`: `exploratory-qa` -> "Exploratory QA".
+ * Pure: same input always yields the same output.
+ *
+ * @param {string} raw The raw skill/frontmatter name token.
+ * @returns {string} The humanized, title-cased display name.
+ */
+function humanizeName(raw) {
+  return raw
+    .split(/[-_\s]+/)
+    .filter(word => word.length > 0)
+    .map(word =>
+      ACRONYMS.has(word.toLowerCase())
+        ? word.toUpperCase()
+        : word.charAt(0).toUpperCase() + word.slice(1)
+    )
+    .join(" ");
+}
+
+/**
+ * Boilerplate openings that several Lisa skill descriptions share (e.g. "This
+ * skill should be used when ..."). They add no signal to a short UI summary, so
+ * the leading phrase is stripped before the first-sentence summary is taken.
+ * Matched case-insensitively at the very start of the description only.
+ */
+const DESCRIPTION_PREFIXES = [
+  /^this skill should be used (when|to|for|whenever|any time|anytime|while)\s+/i,
+  /^this skill should be used\s+/i,
+  /^use this skill (when|to|for|whenever|any time|anytime|while)\s+/i,
+  /^use when\s+/i,
+];
+
+/** Upper bound on the derived `short_description` length (characters). */
+const SHORT_DESCRIPTION_MAX = 140;
+
+/**
+ * Derive a concise `short_description` from a skill's full frontmatter
+ * `description`.
+ *
+ * DERIVATION RULE (Epic Open Question — "use best judgement based on the context
+ * of the project", per the PRD #521 author): a Lisa skill description leads with
+ * a one-line summary and then enumerates trigger conditions across several
+ * sentences. The concise summary is therefore the first sentence:
+ *
+ *  1. Strip a leading "This skill should be used when/to/for ..." boilerplate
+ *     prefix (see {@link DESCRIPTION_PREFIXES}) so the summary carries signal.
+ *  2. Take the text up to the first sentence terminator (`. `, `! `, `? `).
+ *  3. Trim a trailing period and clamp to {@link SHORT_DESCRIPTION_MAX} chars
+ *     (word-boundary truncation with an ellipsis) so it stays a *short*
+ *     description.
+ *
+ * For `exploratory-qa` this yields "Playwright-backed exploratory QA workflow
+ * for web apps", matching the PRD's hand-written example shape.
+ *
+ * @param {string} description The full (trimmed) frontmatter description.
+ * @returns {string} A concise one-line summary (may be empty if input is empty).
+ */
+function summarizeDescription(description) {
+  if (description === "") {
+    return "";
+  }
+  const deboilerplated = DESCRIPTION_PREFIXES.reduce(
+    (text, prefix) => text.replace(prefix, ""),
+    description
+  ).trim();
+  // First sentence: stop at the first `.`, `!`, or `?` that is followed by
+  // whitespace or end-of-string (so "e2e" / "U.S." mid-sentence don't split).
+  const sentenceMatch = /^(.*?[.!?])(?:\s|$)/.exec(deboilerplated);
+  const firstSentence = (
+    sentenceMatch ? sentenceMatch[1] : deboilerplated
+  ).replace(/[.\s]+$/, "");
+  if (firstSentence.length <= SHORT_DESCRIPTION_MAX) {
+    return firstSentence;
+  }
+  const clamped = firstSentence.slice(0, SHORT_DESCRIPTION_MAX);
+  const lastSpace = clamped.lastIndexOf(" ");
+  const truncated = lastSpace > 0 ? clamped.slice(0, lastSpace) : clamped;
+  return `${truncated.replace(/[,;:.\s]+$/, "")}…`;
+}
+
 /**
  * Derive a Codex `interface` object from a skill's SKILL.md frontmatter.
  *
- * NOTE ON DERIVATION RULES: this is the minimal/placeholder derivation that the
- * walk-and-emit shell (issue #547) needs to produce a valid `interface` block.
- * The richer humanization/summarization rules — title-casing `display_name`,
- * trimming `short_description`, and the `$<name>` starter prompt — are issue
- * #548's responsibility and will refine these defaults. Until then we fall back
- * to the raw frontmatter values (and the skill directory name when frontmatter
- * is missing) so every skill still emits a well-formed file.
+ * DERIVATION RULES (issue #548; the Epic Open Question asked the author for the
+ * `short_description`/`default_prompt` rule and the guidance was "use best
+ * judgement based on the context of the project"):
+ *
+ *  - `display_name`  — {@link humanizeName} of `frontmatter.name`: title-cased,
+ *    with known acronyms upper-cased (`exploratory-qa` -> "Exploratory QA").
+ *  - `short_description` — {@link summarizeDescription} of `frontmatter.description`:
+ *    the boilerplate-stripped first sentence, clamped to a short length.
+ *  - `default_prompt` — a single short starter prompt that references the skill
+ *    token `$<name>` (the canonical kebab name, not the humanized one, because
+ *    Codex invokes skills by their `$<name>` token). When a summary is available
+ *    the prompt reads "Use $<name>: <summary>." — a colon join is used rather
+ *    than "Use $<name> to <summary>" because a derived summary may be a noun
+ *    phrase ("Playwright-backed exploratory QA workflow") rather than a verb
+ *    clause, and "... to <noun phrase>" reads awkwardly. The colon form is
+ *    grammatical for either shape. When there is no description it falls back to
+ *    a bare "Use $<name>". The `$<name>` token is always present — the
+ *    acceptance criterion.
+ *
+ * Falls back to the skill directory name (and an empty description) when the
+ * frontmatter is missing, so every skill still emits a well-formed file. Pure:
+ * no I/O, deterministic output for deterministic input.
  *
  * @param {{ name?: string, description?: string } | null} frontmatter Parsed
  *   SKILL.md frontmatter (or `null` when the file has no frontmatter block).
  * @param {string} skillName The skill directory name, used as a fallback.
  * @returns {{ display_name: string, short_description: string, default_prompt: string[] }}
- *   The normalized interface object the serializer consumes. Pure.
+ *   The normalized interface object the serializer consumes.
  */
 export function deriveSkillInterface(frontmatter, skillName) {
   const name = frontmatter?.name?.trim() || skillName;
   const description = frontmatter?.description?.trim() || "";
+  const shortDescription = summarizeDescription(description);
+  const starter =
+    shortDescription === ""
+      ? `Use $${name}`
+      : `Use $${name}: ${shortDescription}.`;
   return {
-    display_name: name,
-    short_description: description,
-    default_prompt: [`Use $${name}`],
+    display_name: humanizeName(name),
+    short_description: shortDescription,
+    default_prompt: [starter],
   };
 }
 
@@ -155,9 +292,9 @@ export function deriveSkillInterface(frontmatter, skillName) {
  * `skills/<name>/agents/openai.yaml` (issue #547).
  *
  * For each skill directory containing a SKILL.md, the frontmatter is parsed
- * (#545), an interface object is derived (#548 refines the rules), and the
- * deterministic serializer (#546) writes `agents/openai.yaml`, creating the
- * `agents/` directory when missing. Behavior boundaries:
+ * (#545), an interface object is derived via {@link deriveSkillInterface} (#548),
+ * and the deterministic serializer (#546) writes `agents/openai.yaml`, creating
+ * the `agents/` directory when missing. Behavior boundaries:
  *
  *  - No-op when the plugin has no `skills/` directory.
  *  - Never clobber a hand-authored `agents/openai.yaml` that already exists in