@codyswann/lisa 2.127.1 → 2.128.0

package/plugins/src/base/skills/parity-safety-net-rules/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: parity-safety-net-rules
+description: "View, set, and verify the custom guard rules enforced by Lisa's safety-net PreToolUse Bash hook (parity-safety-net.sh). The consolidated cross-agent equivalent of the upstream safety-net plugin's set-custom-rules + verify-custom-rules skills — manages a project-local list of extended-regex patterns that block destructive shell commands, on Codex, agy, Copilot, Cursor, and Claude."
+allowed-tools: ["Read", "Edit", "Write", "Bash"]
+synced-from: safety-net@cc-marketplace@0.9.0
+---
+
+# Parity Safety-Net Rules
+
+Manage the **custom guard rules** that Lisa's safety-net hook enforces on every
+Bash command. The hook (`hooks/parity-safety-net.sh`, registered as a
+`PreToolUse` matcher on `Bash`) ships with built-in guards against catastrophic
+commands; this skill lets a project **view**, **set**, and **verify** *additional*
+project-specific rules on top of those built-ins.
+
+> **Lisa-native reimplementation.** This consolidates the upstream
+> `safety-net@cc-marketplace` plugin's two rule-management skills
+> (`set-custom-rules` + `verify-custom-rules`) into one. It is reimplemented from
+> scratch against Lisa conventions — it does **not** port or invoke upstream
+> plugin code.
+>
+> **Drift tracking.** Pinned to `safety-net@cc-marketplace@0.9.0`.
+> `scripts/plugin-parity-drift.mjs` compares this pin against the upstream
+> version in the plugin cache and flags staleness. **Do not port or copy upstream
+> plugin code.**
+
+## How the rules work
+
+- The hook always enforces its **built-in guards** (see below). These cannot be
+  disabled from the rules file — they are the floor.
+- **Custom rules** live in a project-local file, one **POSIX extended regular
+  expression (ERE)** per line. Blank lines and lines beginning with `#` are
+  ignored. Matching is case-insensitive (`grep -Ei`).
+- If *any* built-in guard or custom rule matches the proposed command, the hook
+  exits non-zero and the Bash call is **blocked**, with the reason shown to the
+  agent.
+
+### Rules file location
+
+Resolved in this order:
+
+1. `$SAFETY_NET_RULES_FILE` (explicit override), else
+2. `${CLAUDE_PROJECT_DIR:-$PWD}/.claude/safety-net-rules.txt`
+
+```bash
+RULES_FILE="${SAFETY_NET_RULES_FILE:-${CLAUDE_PROJECT_DIR:-$PWD}/.claude/safety-net-rules.txt}"
+```
+
+### Built-in guards (always on)
+
+1. `rm -rf` of a filesystem root, `$HOME`/`~`, or a top-level wildcard.
+2. Force-pushing a protected branch (`main`/`master`/`production`/`release`).
+   `--force-with-lease` is intentionally allowed.
+3. `git reset --hard` while the working tree is **dirty** (would discard work).
+4. Destructive SQL — `DROP DATABASE/SCHEMA/TABLE`, `TRUNCATE TABLE`.
+
+## View the current rules
+
+```bash
+RULES_FILE="${SAFETY_NET_RULES_FILE:-${CLAUDE_PROJECT_DIR:-$PWD}/.claude/safety-net-rules.txt}"
+if [ -f "$RULES_FILE" ]; then
+  echo "Custom safety-net rules ($RULES_FILE):"
+  grep -vE '^[[:space:]]*(#|$)' "$RULES_FILE" || echo "(no active rules)"
+else
+  echo "No custom rules file yet ($RULES_FILE). Only built-in guards are active."
+fi
+```
+
+`Read` the file to show comments and structure as well.
+
+## Set (add or edit) a rule
+
+A rule is an ERE matched against the full command string. Keep rules **specific**
+to avoid blocking legitimate work — anchor on the dangerous verb and its target.
+
+1. Ensure the file exists, then **append** a commented rule (use `Edit`/`Write`,
+   or append from the shell):
+
+   ```bash
+   RULES_FILE="${SAFETY_NET_RULES_FILE:-${CLAUDE_PROJECT_DIR:-$PWD}/.claude/safety-net-rules.txt}"
+   mkdir -p "$(dirname "$RULES_FILE")"
+   {
+     echo "# Block deleting a Kubernetes namespace"
+     echo 'kubectl[[:space:]]+delete[[:space:]]+namespace'
+   } >> "$RULES_FILE"
+   ```
+
+2. **Always verify** the new rule (next section) before considering it set —
+   confirm it blocks what it should and allows what it shouldn't.
+
+Editing/removing: open the file with `Edit` and change or delete the line.
+Removing a rule never affects the built-in guards.
+
+## Verify the rules
+
+Two checks — both should pass before you trust a rule.
+
+### 1. The ERE is valid
+
+An invalid regex would make the hook error on every command. Validate it:
+
+```bash
+printf '%s' "$RULE" | grep -Eq -- "$RULE" 2>/dev/null && echo "valid ERE" \
+  || echo "INVALID ERE — fix before saving"
+```
+
+### 2. The rule behaves as intended
+
+Drive the **actual hook** with a fake `PreToolUse` payload and assert the exit
+code (non-zero = blocked, 0 = allowed). Build the JSON with `jq` so the test
+command line itself never contains the dangerous literal:
+
+```bash
+HOOK="${CLAUDE_PLUGIN_ROOT}/hooks/parity-safety-net.sh"
+
+check() { # check <expect: block|allow> <command>
+  jq -nc --arg c "$2" '{tool_name:"Bash",tool_input:{command:$c}}' \
+    | bash "$HOOK" >/dev/null 2>&1
+  local code=$?
+  local got=allow; [ "$code" -ne 0 ] && got=block
+  printf '%-5s want=%-5s got=%-5s  %s\n' \
+    "$([ "$got" = "$1" ] && echo OK || echo FAIL)" "$1" "$got" "$2"
+}
+
+# Should block (matches the new rule):
+check block "kubectl delete namespace prod"
+# Should allow (must not over-match):
+check allow "kubectl get pods"
+```
+
+Report a table of cases with want/got/verdict. If any case disagrees, tighten the
+ERE and re-verify.
+
+## Rules
+
+- **Built-in guards are the floor** — custom rules only *add* blocks; they cannot
+  weaken the built-ins.
+- **Prefer specific over broad** — a rule that blocks too much trains users to
+  bypass the safety net. Anchor on verb + target.
+- **Verify every rule against the real hook** before saving — never ship an
+  unverified or syntactically invalid ERE.
+- **Never weaken the net to unblock yourself.** If a built-in guard fires on a
+  command that is genuinely safe, run it manually outside the agent after the
+  user confirms — do not edit the hook to remove the guard.

package/plugins/src/base/skills/parity-sentry-sdk-setup/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: parity-sentry-sdk-setup
+description: "Install and configure the Sentry SDK for a project — detect the framework/runtime, add the correct @sentry/<framework> package, initialize the client, wire the DSN through env, enable error + performance monitoring, and set up source map upload for readable stack traces. One consolidated skill covering react, nextjs, node, nestjs, express, python, django, react-native, and more. Lisa-native reimplementation of Sentry's SDK-setup suite. Use when adding Sentry to a project or fixing an existing Sentry install."
+allowed-tools: ["Read", "Edit", "Write", "Bash"]
+synced-from: sentry@claude-plugins-official@1.0.0
+---
+
+# Sentry SDK Setup
+
+Detect a project's framework and runtime, then install and configure the correct
+Sentry SDK with sensible, production-ready defaults: client initialization, DSN
+via environment variable, error capture, performance/tracing, and source map
+upload so stack traces are readable.
+
+## Consolidation note
+
+The upstream `sentry@claude-plugins-official` plugin ships **~30 separate
+per-SDK setup skills** (one per framework/runtime). This **single** Lisa-native
+skill consolidates all of them: instead of one thin skill per SDK, it detects the
+framework and applies the matching case below. The behavior is reimplemented from
+scratch against Lisa conventions — it is **not** a translation of the upstream
+skills. Pinned to `sentry@claude-plugins-official@1.0.0` via `synced-from` so the
+parity drift detector tracks it as one unit.
+
+## Step 1 — Detect framework & runtime
+
+Inspect the project before choosing an SDK. Read `package.json`
+(dependencies/scripts), config files, and lockfiles:
+
+- `next` dependency or `next.config.*` → **Next.js**
+- `@nestjs/core` → **NestJS**
+- `react-native` / `expo` → **React Native / Expo**
+- `react` + a bundler (vite/webpack) without Next → **React (browser)**
+- `express` / `fastify` / `koa` and a Node entrypoint → **Node server**
+- `vue` / `@angular/core` / `svelte` → that browser framework
+- `pyproject.toml` / `requirements.txt`; `django`/`flask`/`fastapi` →
+  **Python** (and which web framework)
+- A plain Node library/CLI → **Node**
+
+If the runtime is genuinely ambiguous, ask which app to instrument rather than
+guessing. Respect the project's package manager (bun/npm/pnpm/yarn — match the
+lockfile) and module system (ESM vs CJS).
+
+## Step 2 — Install the package
+
+Use the project's package manager. Examples (swap `bun add` for your manager):
+
+| Framework | Package |
+| --- | --- |
+| React (browser) | `@sentry/react` |
+| Next.js | `@sentry/nextjs` |
+| Node / Express / Fastify | `@sentry/node` (+ `@sentry/profiling-node` for profiling) |
+| NestJS | `@sentry/nestjs` (+ `@sentry/node`) |
+| React Native / Expo | `@sentry/react-native` |
+| Vue | `@sentry/vue` |
+| Angular | `@sentry/angular` |
+| Svelte / SvelteKit | `@sentry/svelte` / `@sentry/sveltekit` |
+| Python (generic) | `sentry-sdk` |
+| Django | `sentry-sdk[django]` |
+| Flask | `sentry-sdk[flask]` |
+| FastAPI | `sentry-sdk[fastapi]` |
+
+For Next.js, prefer the official wizard when available — it scaffolds the config
+files and source-map upload for you:
+
+```bash
+npx @sentry/wizard@latest -i nextjs
+```
+
+## Step 3 — Initialize the client
+
+Initialize **as early as possible** in the app's lifecycle, before other code
+runs. Always read the DSN from the environment (see Step 4) — never hard-code it.
+
+**React (browser)** — `src/instrument.ts`, imported first in the entrypoint:
+
+```ts
+import * as Sentry from "@sentry/react";
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  environment: import.meta.env.MODE,
+  integrations: [Sentry.browserTracingIntegration()],
+  tracesSampleRate: 0.1, // tune per traffic; 1.0 in dev
+});
+```
+
+**Node / Express** — `instrument.ts`, required at the very top of the entrypoint
+(`import "./instrument";` must be the first import):
+
+```ts
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  tracesSampleRate: 0.1,
+});
+```
+
+Then, after routes are defined: `Sentry.setupExpressErrorHandler(app);`
+
+**NestJS** — import `./instrument` first in `main.ts`, then add Sentry's module:
+
+```ts
+// main.ts — FIRST line
+import "./instrument";
+// ...
+// app.module.ts
+import { SentryModule } from "@sentry/nestjs/setup";
+@Module({ imports: [SentryModule.forRoot()] })
+export class AppModule {}
+```
+
+**Next.js** — config lives in `sentry.client.config.ts`,
+`sentry.server.config.ts`, `sentry.edge.config.ts`, and `next.config.js` is
+wrapped with `withSentryConfig`. The wizard (Step 2) writes these; verify the DSN
+is read from `process.env.NEXT_PUBLIC_SENTRY_DSN` / `process.env.SENTRY_DSN`.
+
+**React Native / Expo** — wrap the root component:
+
+```ts
+import * as Sentry from "@sentry/react-native";
+Sentry.init({
+  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
+  tracesSampleRate: 0.2,
+});
+export default Sentry.wrap(App);
+```
+
+**Python (Django/Flask/FastAPI/generic)** — initialize at startup
+(`settings.py`, app factory, or main module):
+
+```python
+import os
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn=os.environ["SENTRY_DSN"],
+    environment=os.environ.get("ENVIRONMENT", "production"),
+    traces_sample_rate=0.1,
+    send_default_pii=False,
+)
+```
+
+Framework-specific integrations (e.g. `DjangoIntegration`, `FastApiIntegration`)
+are auto-enabled by the matching extra installed in Step 2.
+
+## Step 4 — DSN via environment
+
+- Store the DSN in an environment variable, never in committed source.
+- Add it to `.env.example` (with a placeholder) so the requirement is documented,
+  but keep the real value in `.env`/secrets and confirm `.env` is gitignored.
+- Use the framework's public-env convention for client-side code:
+  `NEXT_PUBLIC_SENTRY_DSN` (Next.js), `VITE_SENTRY_DSN` (Vite),
+  `EXPO_PUBLIC_SENTRY_DSN` (Expo). Server-only code uses `SENTRY_DSN`.
+- For source-map upload (Step 6) the build also needs `SENTRY_AUTH_TOKEN`,
+  `SENTRY_ORG`, and `SENTRY_PROJECT` — these are **build/CI** secrets, not
+  shipped to the client.
+
+## Step 5 — Error + performance monitoring
+
+- **Errors**: unhandled exceptions/rejections are captured automatically once
+  `init` runs; add the framework error handler where required (Express:
+  `setupExpressErrorHandler`; React: an error boundary via
+  `Sentry.ErrorBoundary`; NestJS: `SentryModule`). Use
+  `Sentry.captureException(err)` for caught-but-notable errors.
+- **Performance/tracing**: set a `tracesSampleRate` (start ~0.1 in production,
+  `1.0` in dev) and enable the framework tracing integration (browser tracing,
+  HTTP/DB auto-instrumentation on the server). Optionally add profiling on Node
+  via `@sentry/profiling-node` and `profilesSampleRate`.
+- Set `environment` and (ideally) `release` so issues are grouped per deploy.
+
+## Step 6 — Source maps (readable stack traces)
+
+Minified/transpiled traces are useless without source maps. Configure upload at
+build time:
+
+- **Next.js**: handled by `withSentryConfig` in `next.config.js` (the wizard sets
+  it up); ensure `SENTRY_AUTH_TOKEN`/`SENTRY_ORG`/`SENTRY_PROJECT` exist in CI.
+- **Vite/Webpack/Rollup/esbuild**: add the Sentry bundler plugin
+  (`@sentry/vite-plugin`, `@sentry/webpack-plugin`, etc.) with `sourcemaps`
+  upload enabled and the same auth env vars.
+- **Node**: build with source maps emitted and upload via
+  `sentry-cli sourcemaps upload` (or the bundler plugin) in the release step.
+- **React Native**: source maps upload through the Sentry Metro/Gradle/Xcode
+  integration added by the SDK's setup.
+- Tie uploads to a **release** identifier (commit SHA or version) and inject the
+  same release into `Sentry.init({ release })` so traces map to the right build.
+
+## Step 7 — Verify
+
+- Build/typecheck to confirm the SDK wiring compiles:
+  `bun run build` / `bun run typecheck` (or the project's equivalents).
+- Trigger a deliberate test error in a non-production environment and confirm it
+  appears in Sentry with a **readable** (source-mapped) stack trace.
+- Confirm a transaction/trace shows up to validate performance monitoring.
+- Remove the test error afterward.
+
+## Rules
+
+- **Do not port or copy upstream plugin code** — reimplement from scratch.
+- Never hard-code or commit a DSN or `SENTRY_AUTH_TOKEN`; route everything
+  through env/secrets and update `.env.example`.
+- Match the project's package manager and module system; do not introduce a new
+  one to install Sentry.
+- Initialize Sentry before any other application code runs.
+- Tune sample rates for the environment — do not ship `tracesSampleRate: 1.0` to
+  high-traffic production by default.
+- Verify with a real captured event and a source-mapped trace before declaring
+  setup complete.

package/plugins/src/base/skills/parity-sentry-seer/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: parity-sentry-seer
+description: "AI debugging — given an error message, stack trace, or failing test, analyze the signal, form ranked hypotheses, locate the root cause in the codebase with file:line evidence, and propose a minimal fix. Lisa-native reimplementation of Sentry's seer workflow, available across all agent runtimes. Use when handed an exception, crash, regression, or red test and asked to find and fix the cause."
+allowed-tools: ["Read", "Grep", "Glob", "Bash", "Edit"]
+synced-from: sentry@claude-plugins-official@1.0.0
+---
+
+# Seer — AI Root-Cause Debugging
+
+Take a failure signal (exception, stack trace, failing test, log excerpt, or a
+Sentry issue) and drive it to a proven root cause and a proposed fix. This is the
+Lisa-native reimplementation of the upstream `sentry@claude-plugins-official`
+plugin's `seer` command, rebuilt from scratch so the AI-debugging workflow is
+available to the Codex, agy, and Copilot runtimes (Cursor loads upstream
+natively).
+
+> The Sentry MCP itself (for pulling live issue data) is re-pointed per agent
+> separately by the parity subsystem — this skill works **with or without** it.
+> When the MCP is connected, use it to fetch issue details, breadcrumbs, and
+> event context; when it is not, work from the error text the user pastes in.
+
+## Drift tracking
+
+Pinned to `sentry@claude-plugins-official@1.0.0` via `synced-from`. SDK install
+& configuration is a separate concern owned by `parity-sentry-sdk-setup`.
+
+## Inputs this handles
+
+- A raw stack trace or exception message.
+- A failing test (name + assertion output, or the command to reproduce it).
+- A log excerpt or error ID from CloudWatch / project logging.
+- A Sentry issue URL or ID (resolve via the Sentry MCP when available).
+
+If the signal is too thin to act on (no message, no location, not reproducible),
+ask for the one missing thing — the exact error text, the failing command, or a
+repro step — before guessing.
+
+## Workflow
+
+### 1. Capture & normalize the signal
+
+- Read the full error: type, message, and the **complete** stack trace.
+- Identify the **deepest frame that belongs to this codebase** (ignore
+  node_modules / stdlib frames) — that file:line is your primary anchor.
+- Note the runtime, environment, and any IDs (request id, user id, release).
+- If a Sentry issue is referenced and the MCP is connected, fetch the event,
+  breadcrumbs, tags, and first/last-seen + frequency.
+
+### 2. Reproduce (or pin down why you cannot)
+
+- For a failing test, run it in isolation and read the actual vs. expected:
+  ```bash
+  bun run test -- <test-file-or-pattern>
+  ```
+- For a runtime error, find the smallest command/route/input that triggers it.
+- A reliably reproduced failure is the strongest evidence; if it is flaky or
+  environment-only, say so explicitly and treat hypotheses as provisional.
+
+### 3. Form ranked hypotheses
+
+List 2–4 candidate causes, **most likely first**, each with the reasoning that
+makes it plausible and a concrete way to confirm or refute it. Common classes:
+
+- Null/undefined or unexpected shape reaching the failing frame.
+- Off-by-one / boundary / empty-collection edge case.
+- Async race, unawaited promise, or ordering assumption.
+- Contract drift — a caller and callee disagree after a recent change.
+- Bad input validation / unhandled external response.
+- Config/env divergence (works locally, fails in the target environment).
+
+### 4. Locate the root cause with evidence
+
+Walk the code to confirm or kill each hypothesis, highest-ranked first:
+
+- `Grep`/`Glob` for the failing symbol, message string, and the function in the
+  anchor frame; read the surrounding code, not just the one line.
+- Trace the data **backward** from the failure point to where the bad value
+  originates — the crash site is usually a symptom, not the cause.
+- Use `git log`/`git blame` on the anchor file to find a correlated recent change:
+  ```bash
+  git log -n 5 --oneline -- <path/to/anchor/file>
+  git blame -L <line>,<line> -- <path/to/anchor/file>
+  ```
+- When a value is uncertain, add a **temporary** strategic log/assert to confirm
+  the actual value, run, observe, then remove it. State the observed value as
+  evidence. (For deeper investigations, the `debug-specialist` agent owns
+  log-placement and CloudWatch tracing.)
+
+Stop when one hypothesis is **proven** — you can point to the exact line where
+the wrong value/behavior originates and explain the mechanism.
+
+### 5. Propose the fix
+
+- Describe the **minimal** change that addresses the root cause, not the symptom.
+- Prefer fixing where the bad value originates over masking it at the crash site.
+- Note any other call sites affected by the same root cause.
+- Recommend a regression test that would have caught it (a failing test that the
+  fix turns green) — pair with `reproduce-bug` / `tdd-implementation` to land it
+  TDD-style, and `codify-verification` to lock it in.
+- Do not silently broaden scope; if you spot adjacent issues, list them
+  separately as follow-ups.
+
+## Output
+
+Report in this shape:
+
+```
+## Signal
+<error type/message + anchor frame file:line + repro status>
+
+## Root cause
+<the proven cause, in plain English, with the mechanism>
+
+## Evidence
+- <file:line> — <what it shows>
+- <observed value / test output / blame commit> — <why it confirms the cause>
+
+## Proposed fix
+<minimal change, where, and why it addresses the cause not the symptom>
+
+## Regression test
+<the test that should be added to prevent recurrence>
+
+## Follow-ups (if any)
+<adjacent issues found but out of scope>
+```
+
+## Rules
+
+- **Do not port or copy upstream plugin code.** This is a native reimplementation.
+- Prove the cause before proposing a fix — no speculative "try changing this".
+- Cite concrete `file:line` evidence for every claim.
+- Remove any temporary debug logging you add before finishing.
+- Fix the root cause, not the symptom; flag, don't smuggle in, scope creep.
+- Never weaken a test to make it pass, and never use `--no-verify`.

package/plugins/src/base/skills/parity-skill-creator/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: parity-skill-creator
+description: "Author a new Lisa skill end-to-end — scaffold the SKILL.md frontmatter (name/description/allowed-tools), write the pass-through command, follow hyphen naming, place files under plugins/src/base, and rebuild plugins. Lisa-native reimplementation of the upstream skill-creator plugin. NO drift pin: upstream publishes no semver, so it is not drift-trackable."
+allowed-tools: ["Read", "Edit", "Write", "Bash"]
+---
+
+# Skill Creator
+
+Author a new, working Lisa skill (and its pass-through command) from a one-line
+description. This is the Lisa-native equivalent of the upstream
+`skill-creator@claude-plugins-official` plugin, reimplemented from scratch
+against Lisa's conventions so the same capability is available to the Codex,
+agy, and Copilot runtimes (Cursor reads `.claude-plugin/` natively).
+
+## Not drift-trackable
+
+This skill intentionally carries **no `synced-from` pin**. The upstream
+`skill-creator` plugin publishes **no semver** (its cache version resolves to
+`unknown`), so a `@unknown` pin would be unparseable and meaningless to
+`scripts/plugin-parity-drift.mjs`. **Drift is tracked manually** — re-review the
+upstream plugin by hand whenever the curated plugin set is refreshed. Do **not**
+add a `synced-from` line to skills generated by this skill unless they
+reimplement a semver-versioned upstream plugin.
+
+## When to use
+
+- A reusable workflow, checklist, or piece of domain knowledge keeps recurring
+  and deserves a named, invokable skill.
+- You are reimplementing an upstream third-party plugin command/skill for
+  cross-agent parity (see `analyze-plugin` / `implement-plugin-parity`).
+- The user asks to "create a skill", "add a command", or "scaffold a skill".
+
+If the knowledge is narrow or one-off, prefer a rule in `.claude/rules/` instead
+— skills are for broad, repeatable capabilities. When unsure whether content
+warrants a skill, run it past the `skill-evaluator` agent first.
+
+## Where skills live
+
+Lisa skills are **build output** for downstream projects. The source of truth is
+`plugins/src/`, never the generated `plugins/lisa*` artifacts:
+
+| Source directory | Builds artifact | Use for |
+| --- | --- | --- |
+| `plugins/src/base/` | `plugins/lisa` | Skills that ship to **every** stack |
+| `plugins/src/<stack>/` | `plugins/lisa-<stack>` | Stack-specific (typescript, expo, nestjs, cdk, harper-fabric, rails) |
+
+Lisa-repo-only skills (parity tooling, wiki ingestion, `lisa-*` meta-skills) live
+at the **root** `.claude/skills/` and `.claude/commands/`, NOT under
+`plugins/src` — they are not relevant to downstream projects. Decide placement
+first:
+
+- Ships to downstream projects → `plugins/src/base/skills/<name>/SKILL.md`
+- Only meaningful inside the Lisa monorepo → `.claude/skills/<name>/SKILL.md`
+
+## Naming
+
+- Use **hyphen-separated** names: `git-commit`, `tracker-write`,
+  `parity-sentry-seer`. No spaces, no camelCase, no underscores.
+- The directory name, the frontmatter `name`, and the command filename must all
+  match exactly.
+- Commands map to colon-separated UI names via directory nesting:
+  `commands/git/commit.md` → `/lisa:git:commit`; a flat
+  `commands/plan.md` → `/lisa:plan`.
+
+## SKILL.md frontmatter
+
+Skills support **only** these frontmatter keys (they do **not** support
+`argument-hint` or `$ARGUMENTS` substitution — those belong on the command):
+
+```yaml
+---
+name: my-skill                       # required — matches the directory name
+description: "One or two sentences."  # required — when to use + what it does
+allowed-tools: ["Read", "Edit", "Write", "Bash"]  # optional — least privilege
+synced-from: <plugin>@<marketplace>@<version>      # ONLY for semver upstream reimplementations
+---
+```
+
+- **`name`** — the hyphen identifier, byte-identical to the directory.
+- **`description`** — write it so the model knows *when* to reach for the skill,
+  not just what it does. Lead with the trigger. This is the single most
+  important field for discoverability.
+- **`allowed-tools`** — grant the minimum set. A read-only review skill needs no
+  `Write`/`Edit`. Omit the key entirely to inherit the caller's tools.
+- **`synced-from`** — add **only** when the skill reimplements an upstream plugin
+  that publishes a real semver. Grammar: `name@marketplace@version`
+  (e.g. `sentry@claude-plugins-official@1.0.0`). Omit for upstreams with no
+  semver (note that in the body instead, as this skill does).
+
+## The command pass-through pattern
+
+Every skill should have a thin command that is the user-facing entry point.
+Commands support `description`, `argument-hint`, and `$ARGUMENTS`; they delegate
+straight to the skill:
+
+```markdown
+---
+description: "Same human-facing summary as the skill, phrased for the picker."
+argument-hint: "<what the user should type after the command>"
+---
+
+Use the /lisa:my-skill skill to <do the thing>. $ARGUMENTS
+```
+
+The command carries the `argument-hint` and forwards `$ARGUMENTS`; the SKILL.md
+carries the actual logic. Keep the two descriptions consistent.
+
+## Scaffolding walkthrough
+
+1. **Decide placement** — downstream (`plugins/src/base`) vs. Lisa-only
+   (`.claude`). For base, both a skill and a command directory entry are needed.
+2. **Pick the name** — hyphenated, unique. Check it does not collide:
+   `ls plugins/src/base/skills/` and `ls plugins/src/base/commands/`.
+3. **Create the skill** at
+   `plugins/src/base/skills/<name>/SKILL.md` with the frontmatter above and a
+   body that follows house style — see `plugins/src/base/skills/quality-review/SKILL.md`
+   for the canonical shape (title, "When to use", numbered checklist/steps,
+   explicit "Rules"/"Output" sections). Write real, actionable guidance, not
+   TODOs.
+4. **Create the command** at `plugins/src/base/commands/<name>.md` (or a nested
+   `commands/<namespace>/<name>.md` for a colon-namespaced command) using the
+   pass-through template.
+5. **Rebuild the artifacts** so the generated plugins match source:
+   ```bash
+   bun run build:plugins
+   ```
+   Then commit **both** `plugins/src/...` and the regenerated `plugins/lisa*`.
+   The `🧩 Plugins Sync` CI check (and `bun run check:plugins` locally) fails if
+   artifacts drift from source — never hand-edit `plugins/lisa*`.
+6. **Verify discoverability** — confirm the skill appears in the skill list and
+   the command resolves to `/lisa:<name>`.
+
+## Body house style
+
+- Open with an `#` H1 title in Title Case.
+- Add a `## When to use` section that names the triggers.
+- Use numbered steps for procedures, checklists for review-style skills.
+- End with an explicit `## Rules` (hard constraints) and/or `## Output` section.
+- Write in plain, imperative English. Prefer concrete examples over abstraction.
+- Reference sibling skills by their hyphen name (e.g. "delegate to `git-commit`").
+
+## Rules
+
+- Never edit `plugins/lisa*` directly — edit `plugins/src/` and rebuild.
+- Skill frontmatter must not contain `argument-hint` or `$ARGUMENTS`.
+- The directory name, `name` field, and command filename must match exactly.
+- Add `synced-from` **only** for semver-versioned upstream reimplementations.
+- Do not include `/coding-philosophy` in task `skills` metadata — it auto-loads.
+- One skill, one responsibility. If a skill grows two jobs, split it.

package/scripts/plugin-parity-drift.mjs

@@ -496,10 +496,18 @@ export function parseArgs(argv) {
     cacheRoot ??
     process.env.CLAUDE_PLUGIN_CACHE ??
     path.join(os.homedir(), ".claude", "plugins", "cache");
+  // Default roots: both the root-level Lisa skills AND the distributed base
+  // plugin skills (plugins/src/base/skills), where the real cross-agent parity
+  // reimplementations carrying `synced-from` pins now live. The generated
+  // plugins/lisa*/skills artifacts are deliberately NOT included — they are
+  // copies of plugins/src/base and would double-count every pin.
   const resolvedSkills =
     skillsRoots.length > 0
       ? skillsRoots
-      : [path.join(REPO_ROOT, ".claude", "skills")];
+      : [
+          path.join(REPO_ROOT, ".claude", "skills"),
+          path.join(REPO_ROOT, "plugins", "src", "base", "skills"),
+        ];
   return {
     cacheRoot: path.resolve(resolvedCache),
     json,