feat: ship Claude Code plugin in-tree

.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "raysense-marketplace",
+  "version": "0.1.0",
+  "description": "Raysense — architectural X-ray for your codebase, exposed to AI coding agents through MCP",
+  "owner": {
+    "name": "Anton Kundenko",
+    "email": "anton.kundenko@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "raysense",
+      "description": "Phase-scoped skills (bootstrap / impact / verify / audit) over the raysense MCP server. Surfaces structural health, blast radius, dependency cycles, and persisted memory to coding agents.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Anton Kundenko",
+        "email": "anton.kundenko@gmail.com"
+      },
+      "source": "./claude-plugin",
+      "category": "development"
+    }
+  ]
+}

claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "raysense",
+  "version": "0.1.0",
+  "description": "Architectural telemetry for AI coding agents. Phase-scoped skills over the raysense MCP server: scan + baseline at session start, blast-radius before edits, regression diff after, on-demand architecture audits.",
+  "author": {
+    "name": "Anton Kundenko",
+    "email": "anton.kundenko@gmail.com"
+  },
+  "homepage": "https://github.com/RayforceDB/raysense",
+  "repository": "https://github.com/RayforceDB/raysense",
+  "license": "MIT",
+  "keywords": [
+    "architecture",
+    "code-quality",
+    "mcp",
+    "agent-loop",
+    "structural-health",
+    "coupling",
+    "cycles",
+    "blast-radius",
+    "memory",
+    "raysense"
+  ]
+}

claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "raysense": {
+      "command": "raysense",
+      "args": ["--mcp"]
+    }
+  }
+}

claude-plugin/skills/raysense-audit/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: raysense-audit
+description: Use when the user explicitly asks for a structural audit, architecture review, dead-code report, test-gap analysis, or evolution hotspot scan. Heavier and noisier than the other raysense skills — only run on demand, not as part of the routine edit loop.
+---
+
+# Raysense Audit
+
+This skill is for deliberate "look at the whole codebase" requests.
+It calls multiple raysense MCP tools and produces a multi-section
+report. Do not run it as part of routine edits — it is loud by design
+and will pollute the working context.
+
+All tools take a `path` argument; pass the current repo root.
+
+## Steps
+
+1. **Architecture** — call `raysense_architecture`. Reports root
+   causes, cycles by SCC, layer levels, and unstable modules. Lead
+   the report with the worst root cause.
+2. **DSM** — call `raysense_dsm` for the module dependency matrix and
+   level assignments. Useful for showing the user the *shape* of the
+   project, not just the metrics.
+3. **Evolution** — call `raysense_evolution`. Surfaces bus factor,
+   change-coupling pairs (files that change together), and temporal
+   hotspots (commits × max complexity).
+4. **Test gaps** — call `raysense_test_gaps`. Files without nearby
+   tests, ranked by risk.
+5. **Optional dashboard** — call `raysense_visualize` if the user
+   asked for something they can browse. Writes a self-contained HTML
+   file the user can open.
+
+## Report structure
+
+When summarising back to the user, lead with the *one* finding that
+matters most — usually the worst architectural root cause or the
+highest-risk untested file. Long lists overwhelm; a single
+prioritized headline plus a short table of next-three-things tends to
+land better.
+
+## When to skip
+
+- The user asked a narrow question. Use `raysense-impact` or a
+  single targeted MCP call instead.
+- The repo is tiny (under ~50 files). The audit will produce mostly
+  noise — just call `raysense_health` and read out the grade.

claude-plugin/skills/raysense-bootstrap/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: raysense-bootstrap
+description: Use at the start of any coding session in a repository to scan the structure, save a baseline, and materialize splayed-table memory for fast follow-up queries. Establishes the "before" reference point that raysense-verify diffs against later.
+---
+
+# Raysense Bootstrap
+
+Run this once per session, before any non-trivial edits. It produces a
+persisted baseline plus live splayed-table memory that the other
+raysense skills (`raysense-impact`, `raysense-verify`,
+`raysense-audit`) read against.
+
+All tools take a `path` argument. Always pass the current working
+directory as an absolute path so per-project state stays inside the
+repo (`<repo>/.raysense/`).
+
+## Steps
+
+1. **Health overview** — call `raysense_health` with `path: <cwd>`.
+   Note the overall grade and the worst dimension.
+2. **Save the baseline** — call `raysense_baseline_save` with
+   `path: <cwd>`. This writes `<cwd>/.raysense/baseline/manifest.json`
+   plus splayed tables under `<cwd>/.raysense/baseline/tables/`.
+3. **Confirm memory is live** — call `raysense_memory_summary` with
+   `path: <cwd>`. Report the row/column counts so the user can see the
+   memory is materialized.
+4. **Surface the top 3 hotspots** — call `raysense_hotspots` and
+   `raysense_rules`. List the three highest-traffic files and any
+   already-failing rules. These are the spots most likely to bite
+   during the session.
+
+## What to keep in working memory
+
+After bootstrap, the agent should remember (briefly):
+
+- The overall health grade and the lowest-scoring dimension.
+- The three hottest files (high coupling × high churn).
+- Whether any rules are currently failing (so a later regression isn't
+  mistaken for pre-existing breakage).
+
+## When to skip
+
+- Session is read-only (the user just asked a question — no edits
+  planned). Skip bootstrap; reach for `raysense-audit` instead if
+  structural context is needed.
+- A baseline already exists from a recent session and no commits have
+  landed since (`git log -1 --since='1 hour ago'` shows nothing).
+  Re-using the previous baseline is fine; just call `raysense_health`
+  for a fresh grade and skip the rest.

claude-plugin/skills/raysense-impact/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: raysense-impact
+description: Use before refactoring, deleting, moving, or substantially modifying a file to compute its blast radius, coupling profile, and cycle exposure. Lets the agent edit with awareness of downstream effects rather than discovering them after the fact.
+---
+
+# Raysense Impact
+
+Call this *before* a non-trivial edit (deletion, rename, signature
+change, extraction, file move). It tells the agent what depends on the
+target and what the target depends on, so the edit plan can account
+for the blast radius up front.
+
+All tools take a `path` argument (absolute, current repo root) plus
+the target file path relative to that root.
+
+## Steps
+
+1. **Blast radius** — call `raysense_blast_radius` with `path: <cwd>`
+   and `file: <target>`. Returns the set of files reachable downstream
+   under the active edge filter. A blast radius >20 files is a strong
+   signal to break the change into smaller commits.
+2. **Coupling profile** — call `raysense_coupling`. Look up the
+   target's module in the response: afferent (incoming) and efferent
+   (outgoing) counts, plus main-sequence distance. High-afferent
+   modules are stable foundations — breaking changes there cascade
+   widely.
+3. **Cycle exposure** — call `raysense_cycles`. If the target appears
+   in any reported cycle, call
+   `raysense_break_cycle_recommendations` for ranked candidate edges
+   to remove. The recommended edge is often *not* the obvious one.
+4. **Optional simulation** — when the planned change is mechanical
+   (file removal, edge removal), call `raysense_what_if` to preview
+   the health delta without touching the working tree.
+
+## What to keep in working memory
+
+- Number of files in the blast radius — quote it back to the user
+  before starting an edit that exceeds 20.
+- Whether the target is on any cycle — informs whether the edit is
+  likely to introduce or break a cycle.
+- The `instability` score — a value near 1.0 means the file is
+  expected to depend on stable foundations, not be one.
+
+## When to skip
+
+- Local-only edit inside one file with no signature changes (typo
+  fix, comment, internal rename). No downstream effect, no need.
+- Brand-new file. Nothing depends on it yet.

claude-plugin/skills/raysense-verify/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: raysense-verify
+description: Use after completing a logical chunk of edits to rescan the project and detect new rule violations or health regressions against the session baseline. Catches structural regressions before they reach review.
+---
+
+# Raysense Verify
+
+Call this after a meaningful chunk of edits — typically before
+suggesting the user run tests or commit. It rescans the project and
+diffs the result against the baseline that `raysense-bootstrap`
+established.
+
+All tools take a `path` argument; pass the current repo root as an
+absolute path.
+
+## Steps
+
+1. **Rescan** — call `raysense_rescan` with `path: <cwd>`. Forces a
+   fresh walk; uses cached config and plugin state.
+2. **Rule status** — call `raysense_check_rules`. Pass/fail per rule.
+   A rule that was passing at bootstrap and is failing now is a
+   regression to flag explicitly.
+3. **Baseline diff** — call `raysense_baseline_diff` with
+   `path: <cwd>`. Health-dimension deltas vs the saved baseline.
+   Anything that dropped a grade letter (B → C, etc.) is worth
+   surfacing.
+4. **Remediations on regression** — if step 2 or 3 reports
+   regressions, call `raysense_remediations` for suggested fixes.
+   Surface the regression *and* the suggestion to the user before
+   continuing.
+
+## What to surface to the user
+
+Be concise. The user does not want a wall of metrics. A good verify
+report is:
+
+- "Rules: all pass" *or* "Rules: 1 new failure (`max_blast_radius`,
+  was 18 / threshold 25 / now 27)."
+- "Baseline diff: modularity B → C-, redundancy stable, others
+  unchanged." Only the dimensions that moved.
+
+## When to skip
+
+- Edits were limited to comments, docs, or config that does not
+  affect imports.
+- The session bootstrapped less than a minute ago and the working
+  tree shows trivial changes (`git diff --stat` is one or two lines).