diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..7c40e24 --- /dev/null +++ b/.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" + } + ] +} diff --git a/claude-plugin/.claude-plugin/plugin.json b/claude-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..261091c --- /dev/null +++ b/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" + ] +} diff --git a/claude-plugin/.mcp.json b/claude-plugin/.mcp.json new file mode 100644 index 0000000..277bffd --- /dev/null +++ b/claude-plugin/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "raysense": { + "command": "raysense", + "args": ["--mcp"] + } + } +} diff --git a/claude-plugin/skills/raysense-audit/SKILL.md b/claude-plugin/skills/raysense-audit/SKILL.md new file mode 100644 index 0000000..a67a270 --- /dev/null +++ b/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. diff --git a/claude-plugin/skills/raysense-bootstrap/SKILL.md b/claude-plugin/skills/raysense-bootstrap/SKILL.md new file mode 100644 index 0000000..e18c7e6 --- /dev/null +++ b/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 (`/.raysense/`). + +## Steps + +1. **Health overview** — call `raysense_health` with `path: `. + Note the overall grade and the worst dimension. +2. **Save the baseline** — call `raysense_baseline_save` with + `path: `. This writes `/.raysense/baseline/manifest.json` + plus splayed tables under `/.raysense/baseline/tables/`. +3. **Confirm memory is live** — call `raysense_memory_summary` with + `path: `. 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. diff --git a/claude-plugin/skills/raysense-impact/SKILL.md b/claude-plugin/skills/raysense-impact/SKILL.md new file mode 100644 index 0000000..af0fc7a --- /dev/null +++ b/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: ` + and `file: `. 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. diff --git a/claude-plugin/skills/raysense-verify/SKILL.md b/claude-plugin/skills/raysense-verify/SKILL.md new file mode 100644 index 0000000..d071030 --- /dev/null +++ b/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: `. 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: `. 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).