@codyswann/lisa 2.189.6 → 2.189.8

package/plugins/lisa/skills/lisa-cross-pollinate/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: lisa-cross-pollinate
+description: "Detect a host project's locally-authored coding-agent definitions (skills, subagents, rules, commands, hooks, MCP) and make each available in the formats of the OTHER agents the project supports, as declared in .lisa.config.json. Any-to-any, provenance-tracked, idempotent, never clobbers hand-edited output."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
+argument-hint: "[path] [--dry-run] [--write]"
+---
+
+# Cross-Pollinate: $ARGUMENTS
+
+A host project that installs Lisa may hand-author a definition for **one** coding
+agent — a `.claude/skills/foo`, a `.cursor/rules/bar.mdc`, an MCP server only
+Claude sees. `/lisa:cross-pollinate` detects those locally-authored definitions
+and regenerates each in the formats of the **other** agents the project supports,
+so the whole fleet stays in parity with what a developer wrote for any single one.
+
+## The model
+
+```
+any agent's format  ->  Claude-format IR  ->  every OTHER configured agent
+```
+
+Claude format is the canonical intermediate representation (IR) because every
+Lisa generator already sources from it. So translation is always: **normalize
+the detected definition up to Claude-format IR, then fan that IR out** to each
+target agent using the documented mappings below. Never translate format A → B
+directly — that multiplies error and loses fidelity on every hop.
+
+The agents a project supports come from `.lisa.config.json` `harness`
+(`claude` | `codex` | `cursor` | `agy` | `copilot` | `opencode` | `both` | `fleet`;
+`all` is an alias for `fleet`). Only emit to agents that harness includes.
+
+## Provenance is authoritative — the lockfile, not file paths
+
+`.lisa/cross-pollination.lock.json` (committed) is the source of truth for what
+this skill generated. Location heuristics **cannot** work: a generated Cursor
+rule sits in the same `.cursor/rules/` directory as a hand-authored one. The
+lockfile is the only reliable way to enforce the four invariants:
+
+1. **No loops** — a path recorded as a `target` is NEVER treated as a source on
+   the next run. Without this, today's output becomes tomorrow's input and
+   translations ping-pong forever.
+2. **Garbage collection** — when a source is deleted/renamed, its now-orphaned
+   targets are removed.
+3. **Never clobber edits (Chesterton's fence)** — if a target's on-disk hash
+   differs from the recorded `generatedHash`, a human edited it. Stop and report;
+   do not overwrite. They may have intentionally diverged, or want to adopt the
+   edit as a new source.
+4. **Idempotent** — unchanged source + intact targets => no-op. (This is why it
+   is safe to also run during `lisa apply`.)
+
+Lockfile shape:
+
+```json
+{
+  "version": 1,
+  "entries": {
+    "skill:security-review": {
+      "source":  { "agent": "claude", "path": ".claude/skills/security-review", "hash": "…" },
+      "targets": [ { "agent": "codex", "path": ".claude/skills/security-review/agents/openai.yaml", "generatedHash": "…" } ]
+    }
+  }
+}
+```
+
+The `logicalId` is `<kind>:<name>` — stable across formats. It links a source to
+its targets and detects **collisions**: the same `logicalId` authored
+independently in two agents (neither generated). On a collision, NEVER
+auto-translate over either side — report it and let the human pick the source of
+truth.
+
+## How to run
+
+The deterministic core (scan, provenance, loop/GC/drift/conflict detection, and
+the skill + MCP emitters) is a bundled engine. **Always run it first** — it does
+the safe, mechanical work and tells you exactly what is left for you to translate
+by hand.
+
+```bash
+# dry-run (default): report only, writes nothing
+node "${CLAUDE_PLUGIN_ROOT}/scripts/cross-pollinate.mjs" "$PROJECT_ROOT" --json
+# apply the deterministic emits + update the lockfile
+node "${CLAUDE_PLUGIN_ROOT}/scripts/cross-pollinate.mjs" "$PROJECT_ROOT" --write
+```
+
+In the Lisa source repo itself the path is
+`node plugins/lisa/scripts/cross-pollinate.mjs` (built) or
+`node plugins/src/base/scripts/cross-pollinate.mjs` (source).
+
+The JSON report has four lists you act on:
+
+- `emits` — already handled by `--write` (skills, MCP). Verify, don't redo.
+- `conflicts` — STOP. Report each to the user; do not translate.
+- `orphans` — GC'd by `--write`. Confirm the removals look right.
+- `pending` — **your job.** Definitions whose target format the engine does not
+  emit deterministically. Translate each per the mappings below, then record
+  provenance (see "Recording provenance").
+
+## Per-agent format mappings (for `pending` translation)
+
+Normalize the source to Claude-format IR first, then emit per target:
+
+### Rules
+- **Claude ↔ Cursor**: handled deterministically by the engine. Claude reads
+  `.claude/rules/<name>.md`; Cursor reads `.cursor/rules/<name>.mdc` with YAML
+  frontmatter (`description` from the first H1, `alwaysApply: true`) and intra-rule
+  link extensions rewritten. You do not translate these — verify the engine's
+  emits.
+- **Codex / OpenCode / agy** (`pending`): project rules are delivered via
+  `AGENTS.md`, not a per-rule file. MERGE the rule content into `AGENTS.md` under a
+  stable marked section rather than writing a separate file (so re-runs replace,
+  not append). agy never gets a duplicate rule file (rules-once).
+- **Copilot** (`pending`): `.github/copilot-instructions.md` (inline). Merge into a
+  marked section, don't scatter.
+
+### Subagents
+- **Claude / agy / Cursor / OpenCode**: `agents/<name>.md` (or `.claude/agents/`).
+- **Copilot**: `agents/<name>.agent.md` (note the `.agent.md` suffix).
+- **Codex**: does not consume agent files. Report as **dropped — unsupported**,
+  do not invent a target.
+
+### Commands
+- **Claude / Cursor / Copilot**: markdown command files (`.claude/commands/…`).
+- **Codex / agy**: auto-derive commands from skills; no separate command file.
+  Report as **dropped — derived-from-skill**.
+
+### Hooks (lossy — drop-and-report, never fake support)
+- Event-name casing differs per agent (`PreToolUse`→`preToolUse`/`beforeSubmitPrompt`,
+  `UserPromptSubmit`→`userPromptSubmitted`, `Stop`→`agentStop`/`stop`, …).
+- **agy** lacks `SessionStart`/`SubagentStart` — only `PreToolUse` (e.g.
+  block-no-verify) is portable. Everything else: dropped — unsupported.
+- **Codex** plugin hooks do not fire in `codex exec` — install into
+  `~/.codex/hooks.json`, not a bundled file.
+- **Copilot** rejects the entire hooks config if a `SubagentStart`/empty-matcher
+  entry is present — drop that event wholesale.
+- For every hook you cannot faithfully translate to a target, REPORT it with the
+  reason. Do not silently omit (no silent caps).
+
+### MCP (handled by the engine for Claude↔Cursor; report others)
+- **Claude**: `.mcp.json`. **Cursor**: `.cursor/mcp.json` (same JSON shape).
+- **Copilot**: inline `mcpServers` object in the plugin manifest (bundled
+  `.mcp.json` is ignored). **Codex**: TOML / `.codex-plugin` pointer.
+  **agy/OpenCode**: user-global installer / `.opencode`. The engine reports these
+  as pending; translate per the target's documented shape or report dropped.
+
+## Recording provenance for hand-translated `pending` items
+
+After you write a target by hand, it MUST be recorded in
+`.lisa/cross-pollination.lock.json` or the next run will treat it as a source
+(loop) or fail to GC it. Re-run the engine after staging your translated files —
+on its next pass it adopts and hashes any target already referenced — OR add the
+entry yourself following the lockfile shape above (compute `generatedHash` as the
+sha256 of the written file/dir). Prefer the engine; only hand-edit the lock if
+the engine cannot infer the mapping.
+
+## Output
+
+Report, concisely:
+- harness + resolved target agents
+- counts: detected sources, written, skipped-drift, GC'd
+- every conflict (with the agents involved)
+- every pending item you translated, and every hook/agent/command you **dropped**
+  with its reason
+- confirm `.lisa/cross-pollination.lock.json` was updated and the working tree
+  otherwise contains only intended changes
+
+## Rules
+
+- Treat the lockfile as authoritative; never infer "mine vs theirs" from paths.
+- Never overwrite a drifted (hand-edited) target — report it.
+- Never auto-resolve a collision — report it.
+- Only emit to agents the project's `harness` includes.
+- Drop-and-report any translation a target genuinely cannot support; never fake
+  a location you are unsure of.
+- This skill is additive — it does not delete a human's source definitions, only
+  its own orphaned generated targets.

package/plugins/lisa/skills/lisa-cross-pollinate/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Cross Pollinate"
+short_description: "Detect a host project's locally-authored coding-agent definitions (skills, subagents, rules, commands, hooks, MCP) and make each available…"
+default_prompt:
+  - "Use $lisa-cross-pollinate: Detect a host project's locally-authored coding-agent definitions (skills, subagents, rules, commands, hooks, MCP) and make each available…."

package/plugins/lisa/skills/lisa-debrief/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lisa-debrief
+description: "Run the Debrief flow over a shipped initiative. Input: a PRD URL (Notion / Confluence / Linear / GitHub Issue / file), a JIRA epic key, or a GitHub epic issue URL. Output: a triage-ready learnings document covering every work item in the initiative — edge cases, gotchas, process friction, tooling gaps, convention drift — each with structured evidence and a human-disposition field. Persistence is deferred to lisa-debrief-apply."
+allowed-tools: ["Skill", "ToolSearch", "TeamCreate", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Debrief: $ARGUMENTS
+
+Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their PRs, and produce a triage-ready learnings document for human review.
+
+## Orchestration: agent team
+
+If you are NOT already operating inside an agent team (no prior successful team-creation or subagent-delegation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude: use `TeamCreate`. If `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
+
+Until the team is established, the first Codex teammate has been spawned, or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+| Input shape | Resolution |
+|-------------|------------|
+| Notion / Confluence / Linear / GitHub Issue PRD URL | Fetch the PRD; read its `## Tickets` (or equivalent) back-link section written by the Plan flow |
+| File path to a PRD markdown | Read the file; parse its `## Tickets` section |
+| JIRA epic key (e.g. `SE-1234`) or epic URL | Fetch the epic; list its child issues (Stories, Tasks, Bugs) |
+| GitHub epic issue URL or `<org>/<repo>#<n>` | Fetch the epic issue; list its sub-issues / linked items |
+
+If the PRD has no `## Tickets` section AND the input is not an epic, stop and report — the Plan flow's PRD back-link step (`lisa-prd-backlink`) was likely skipped. Suggest re-running Plan to populate the section, or pass the epic key directly.
+
+## Gate
+
+Run before mining begins:
+
+1. **All work items terminal.** Every linked work item must be in a terminal state (Done / Closed / Cancelled equivalent for the tracker). If any item is still open, stop and list the unfinished items — Debrief is post-shipping by definition.
+2. **PR coverage.** Every Done item that was implementable (Story / Task / Bug; not Spike) must have at least one merged PR linked. Items missing a PR are recorded as **anomalies** to surface in the report rather than silently excluded — a Done item with no PR is itself a learning ("how did this ship?").
+3. **Headless safety.** In headless / `-p` / scheduled mode, do not block on missing input — fail fast with a clear error listing what was needed.
+
+## Flow
+
+Execute the **Debrief** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gate, mining, synthesis, output, hand-off). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+The flow's mining step runs `tracker-mining-specialist` and `pr-mining-specialist` in parallel as separate tasks within the team. Both must complete before `learnings-synthesizer` runs. Express this with `blockedBy` so the synthesizer task is automatically gated on the two mining tasks.
+
+## Exhaustiveness expectation
+
+Debrief is deliberately exhaustive — the human, not the agent, decides what is worth keeping. Specialists should err toward surfacing more candidates, not fewer. A candidate that the synthesizer rates low confidence is still a row in the triage doc; only outright duplicates are dropped.
+
+## Output
+
+A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or wherever the project's debrief output directory is configured) containing:
+
+1. **Header** — initiative name, source PRD/epic link, work-item count, PR count, generation date, gate results.
+2. **Anomalies** — work items missing PRs, items with abnormal status-transition timing, PRs with no review comments at all (signal-of-absence is a learning), etc.
+3. **Candidate learnings** — one row per candidate, grouped by category (Edge case / Recurring gotcha / Process friction / Tooling gap / Convention drift). Each row has:
+   - `Summary` — one sentence
+   - `Category`
+   - `Evidence` — links to the source ticket comment / PR comment / commit / test file (multiple allowed)
+   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "PROJECT_RULES.md", "memory: project_*.md", "new tooling-gap ticket")
+   - `Disposition` — empty checkbox-style field the human will fill: `[ ] Accept` / `[ ] Reject` / `[ ] Defer` plus a free-text reason
+4. **Source map** — appendix listing every work item and PR walked, so the human can verify completeness.
+
+Before returning, write the Debrief run's direct usage onto the triage document through
+`lisa-usage-accounting` so the markdown artifact carries its own `## Lisa Usage` section separate
+from delivery-time usage. If runtime usage is unavailable, record a debrief entry with
+`source: unavailable` and nullable token/cost fields instead of skipping the row.
+
+The skill's terminal output is the path to the triage document and a one-line summary of counts per category. Persistence does not happen here — that is `lisa-debrief-apply`'s job.
+
+## Hand-off
+
+After producing the triage document, print:
+
+```text
+Triage document written to: <path>
+Counts: <n> edge cases, <n> gotchas, <n> friction, <n> tooling gaps, <n> convention drift; <n> anomalies
+Next: human triage. When done, run `/lisa:debrief:apply <path>` to persist accepted learnings.
+```
+
+Then stop. Debrief never persists learnings on its own.

package/plugins/lisa/skills/lisa-debrief/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Debrief"
+short_description: "Run the Debrief flow over a shipped initiative"
+default_prompt:
+  - "Use $lisa-debrief: Run the Debrief flow over a shipped initiative."

package/plugins/lisa/skills/lisa-debrief-apply/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: lisa-debrief-apply
+description: "Apply human-marked dispositions from a Debrief triage document. Reads the triage doc produced by lisa-debrief, parses each row's disposition (Accept / Reject / Defer), and routes Accepted items to their persistence destination. Deterministic and idempotent — safe to re-run if dispositions are added incrementally."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# Debrief Apply: $ARGUMENTS
+
+Read the triage document at `$ARGUMENTS` and persist every Accepted candidate learning to its destination.
+
+This skill is intentionally **single-agent** — there is no team. Routing is deterministic given the disposition column. Spawning sub-agents would only add latency.
+
+## Input
+
+A path or URL to a Debrief triage document produced by `lisa-debrief`. The document is expected to follow the structure that skill produces — a header, an anomalies section, candidate-learning rows grouped by category, and a source-map appendix.
+
+## Pre-flight
+
+1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
+2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), project-rules file (default: `.claude/rules/PROJECT_RULES.md`), memory directory (per the auto-memory system path), tracker for new tickets.
+
+## Routing rules
+
+For every row marked **Accept**:
+
+| Category | Destination | Action |
+|----------|-------------|--------|
+| Edge case | Edge Case Brainstorm checklist in `intent-routing.md` | Append the new pattern + question to the matching group (Navigation, Data, Failure, Input, Auth, or a new group if none fit). Use the row's `Summary` and `Evidence` link as a citation comment. |
+| Recurring gotcha | Memory file (`project_*.md`) | Write a new memory entry with `type: project`, structured as: rule, **Why:**, **How to apply:**. Add an index line to `MEMORY.md`. |
+| Process friction | Project rules file | Append a one-line guideline to `PROJECT_RULES.md` under an appropriate heading (or create one). |
+| Tooling gap | Configured tracker | Create a new ticket via `lisa-tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc. Label appropriately (`type:tooling`, `lifecycle-improvement`, etc.). |
+| Convention drift | `CLAUDE.md` (project) or `PROJECT_RULES.md` | Append the convention as a one-paragraph note under the relevant section. If no relevant section exists, create one. |
+
+For every row marked **Reject** or **Defer**: no action. Defer is a no-op for `apply` but worth surfacing in the run summary — the human may want to revisit at the next debrief.
+
+## Idempotency
+
+`apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint — before writing, check whether the destination already cites that fingerprint. If it does, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.
+
+## Updating the triage doc
+
+After each Accepted row is persisted, replace its `[ ] Accept` checkbox with `[x] Applied — <one-line summary of what was written>`. This makes the triage doc itself the audit log of what was acted on. If a write fails (e.g., tracker is unreachable), mark the row `[!] Apply failed — <reason>` and continue with the rest. Never abort the whole run because one row failed.
+
+## Output
+
+A run summary printed to the user:
+
+```text
+Applied <n> learnings:
+  <n> edge cases → intent-routing.md
+  <n> gotchas → memory
+  <n> friction → PROJECT_RULES.md
+  <n> tooling gaps → <tracker> (<key1>, <key2>, ...)
+  <n> convention drift → CLAUDE.md
+Skipped:
+  <n> rejected, <n> deferred, <n> already-applied
+Failed:
+  <n> (see <path> for details)
+Triage doc updated in place: <path>
+```
+
+If anything is written to a tracker, suggest the human commit the local file changes (memory, rules, intent-routing) when ready — `apply` does not commit.

package/plugins/lisa/skills/lisa-debrief-apply/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Debrief Apply"
+short_description: "Apply human-marked dispositions from a Debrief triage document"
+default_prompt:
+  - "Use $lisa-debrief-apply: Apply human-marked dispositions from a Debrief triage document."