Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(plugin): Claude Code plugin + root marketplace, refreshed to current surface (#356)
Raghav Chamadiya413e82905e2d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonnew file mode 100644index 000000000..9185f3fd2--- /dev/null+++ b/.claude-plugin/marketplace.json@@ -0,0 +1,31 @@+{+ "name": "repowise",+ "owner": {+ "name": "Repowise",+ "email": "[email protected]",+ "url": "https://repowise.dev"+ },+ "metadata": {+ "description": "The codebase intelligence layer for AI coding agents — graph, git, docs, decisions, and a defect-validated code-health score, exposed to Claude through nine task-shaped MCP tools.",+ "homepage": "https://repowise.dev"+ },+ "plugins": [+ {+ "name": "repowise",+ "source": "./plugins/claude-code",+ "description": "Codebase intelligence for Claude Code. Indexes your repo into five layers (Graph, Git, Docs, Decisions, Code Health) and gives Claude deep understanding of architecture, ownership, hotspots, decisions, and defect risk — fewer greps, fewer file reads, lower cost per query.",+ "version": "0.16.0",+ "category": "productivity",+ "keywords": [+ "codebase",+ "code-intelligence",+ "documentation",+ "architecture",+ "code-health",+ "mcp",+ "graph",+ "git-intelligence"+ ]+ }+ ]+}diff --git a/README.md b/README.mdindex 4aec5667a..4608fb59b 100644--- a/README.md+++ b/README.md@@ -252,14 +252,23 @@ repowise init . # scans for git repos, indexes each, runs cross-repo analysrepowise serve # workspace dashboard + per-repo pages```-`repowise init` automatically registers the MCP server, installs-PreToolUse/PostToolUse hooks in `~/.claude/settings.json`, generates `.mcp.json`-at the project root, and offers a post-commit hook that keeps everything in sync.-If the Codex CLI is installed and logged in, interactive runs also offer to write-project-local `.codex/config.toml`, `.codex/hooks.json`, and a managed `AGENTS.md`;+`repowise init` automatically registers the MCP server, installs a PostToolUse+hook in `~/.claude/settings.json`, generates `.mcp.json` at the project root, and+offers a post-commit hook that keeps everything in sync. If the Codex CLI is+installed and logged in, interactive runs also offer to write project-local+`.codex/config.toml`, `.codex/hooks.json`, and a managed `AGENTS.md`;non-interactive runs require `--codex`. Skip Codex setup with `--no-codex`; force orskip `AGENTS.md` with `--agents` / `--no-agents`.+**Claude Code plugin.** Prefer a one-command setup? Install the plugin from the+marketplace — it registers the MCP server and hook and adds `/repowise:*` slash+commands (`init`, `health`, `risk`, `dead-code`, `decision`, …):++```text+/plugin marketplace add repowise-dev/repowise+/plugin install repowise@repowise+```+To add the MCP server to another editor manually:```jsondiff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex d7f0535c6..a080855ca 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -93,7 +93,13 @@ If Node.js 20+ is installed, the web UI starts automatically. Otherwise, use Docrepowise mcp --transport stdio```-> **Automatic for Claude Code:** `repowise init` already registers the MCP server and installs PostToolUse hooks in `~/.claude/settings.json`. Broad or zero-result `Grep`/`Glob` searches can receive graph context, and git operations can notify the agent when the wiki is stale.+> **Automatic for Claude Code:** `repowise init` already registers the MCP server and installs a PostToolUse hook in `~/.claude/settings.json`. Broad or zero-result `Grep`/`Glob` searches can receive graph context, and git operations can notify the agent when the wiki is stale.++> **Claude Code plugin (one-command):** install from the marketplace to get the MCP server, the hook, and `/repowise:*` slash commands together:+> ```text+> /plugin marketplace add repowise-dev/repowise+> /plugin install repowise@repowise+> ```> **Automatic for Codex:** run `repowise init --codex` to write project-local `.codex/config.toml`, `.codex/hooks.json`, and managed `AGENTS.md`. See [Codex Integration](CODEX.md).diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd.py b/packages/cli/src/repowise/cli/commands/augment_cmd.pyindex a36f3f63e..7b07e6897 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd.py@@ -114,7 +114,16 @@ def _run_augment(*, client: str | None = None) -> None:def _emit_response(event: str, context: str) -> None:- """Write the hook JSON response to stdout."""+ """Write the hook JSON response to stdout.++ Suppressed when an identical emission was just produced (see+ :func:`_claim_emission`) so two concurrently-registered repowise hooks —+ one bundled in the Claude Code plugin, one written to+ ``~/.claude/settings.json`` by ``repowise init`` — can't echo the same+ enrichment block twice on a single tool event.+ """+ if not _claim_emission(event, context):+ returnresponse = {"hookSpecificOutput": {"hookEventName": event,@@ -125,6 +134,54 @@ def _emit_response(event: str, context: str) -> None:sys.stdout.flush()+# Window within which an identical (event, context) emission is treated as a+# duplicate. Generous enough to cover two hook processes racing on the same+# tool event, short enough that a genuinely repeated search later still speaks.+_EMIT_DEDUP_TTL_SECONDS = 8.0+++def _claim_emission(event: str, context: str) -> bool:+ """Return True if this caller may emit ``context`` for ``event`` now.++ Both repowise PostToolUse hooks fire on the same tool call and compute the+ same enrichment. A temp lock file keyed on the emission content lets+ exactly one win: the first caller creates it atomically and emits; a second+ caller within the TTL sees a fresh marker and stays silent. Fail-open — any+ error returns True so a dedup glitch can never swallow a real emission.+ """+ import hashlib+ import os+ import tempfile+ import time++ try:+ key = hashlib.sha1(f"{event}\x00{context}".encode()).hexdigest()[:16]+ marker = Path(tempfile.gettempdir()) / f".repowise-augment-{key}"+ now = time.time()+ try:+ # O_EXCL: only the first concurrent caller creates the file.+ fd = os.open(str(marker), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)+ try:+ os.write(fd, str(now).encode())+ finally:+ os.close(fd)+ return True+ except FileExistsError:+ # Someone emitted recently — defer unless the marker is stale, in+ # which case take it over (handles a real repeat search later, and+ # a crashed prior run that left the marker behind).+ try:+ if now - marker.stat().st_mtime <= _EMIT_DEDUP_TTL_SECONDS:+ return False+ except OSError:+ return True+ with contextlib.suppress(OSError):+ marker.write_text(str(now), encoding="utf-8")+ return True+ except Exception:+ return True++# ---------------------------------------------------------------------------# Codex SessionStart/UserPromptSubmit — lightweight MCP guidance# ---------------------------------------------------------------------------diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex 2a1966016..b3cc1a947 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -1,4 +1,4 @@-"""repowise MCP Server — 8 tools for AI coding assistants.+"""repowise MCP Server — 9 tools for AI coding assistants.Exposes the full repowise wiki as queryable tools via the MCP protocol.Supports both stdio transport (Claude Code, Cursor, Cline) and SSE transportdiff --git a/plugins/claude-code/.claude-plugin/marketplace.json b/plugins/claude-code/.claude-plugin/marketplace.jsondeleted file mode 100644index a7439ab10..000000000--- a/plugins/claude-code/.claude-plugin/marketplace.json+++ /dev/null@@ -1,21 +0,0 @@-{- "name": "repowise",- "owner": {- "name": "Repowise",- "email": "[email protected]"- },- "metadata": {- "description": "Codebase intelligence layer — graph, git, docs, and architectural decisions for AI coding agents.",- "version": "0.1.0"- },- "plugins": [- {- "name": "repowise",- "source": ".",- "description": "Codebase intelligence for Claude Code. Understand architecture, ownership, hotspots, and decisions.",- "version": "0.1.0",- "category": "productivity",- "tags": ["codebase", "documentation", "architecture", "mcp", "graph", "git-intelligence"]- }- ]-}diff --git a/plugins/claude-code/.claude-plugin/plugin.json b/plugins/claude-code/.claude-plugin/plugin.jsonindex 28ac17e98..980e90fed 100644--- a/plugins/claude-code/.claude-plugin/plugin.json+++ b/plugins/claude-code/.claude-plugin/plugin.json@@ -1,13 +1,23 @@{"name": "repowise",- "description": "Codebase intelligence for Claude Code. Indexes your codebase into four layers (Graph, Git, Docs, Decisions) and gives Claude deep understanding of architecture, ownership, hotspots, and why code is built the way it is.",- "version": "0.1.0",+ "description": "Codebase intelligence for Claude Code. Indexes your codebase into five layers (Graph, Git, Docs, Decisions, Code Health) and exposes them through nine task-shaped MCP tools — so Claude understands architecture, ownership, hotspots, why code is built the way it is, and where the defect risk lives.",+ "version": "0.16.0","author": {"name": "Repowise",- "email": "[email protected]"+ "email": "[email protected]",+ "url": "https://repowise.dev"},"homepage": "https://repowise.dev",- "repository": "https://github.com/repowise/repowise",+ "repository": "https://github.com/repowise-dev/repowise","license": "AGPL-3.0",- "keywords": ["codebase", "documentation", "architecture", "mcp", "intelligence", "graph", "git"]+ "keywords": [+ "codebase",+ "code-intelligence",+ "documentation",+ "architecture",+ "code-health",+ "mcp",+ "graph",+ "git"+ ]}diff --git a/plugins/claude-code/.mcp.json b/plugins/claude-code/.mcp.jsonindex ded3c4932..74368b17a 100644--- a/plugins/claude-code/.mcp.json+++ b/plugins/claude-code/.mcp.json@@ -2,8 +2,7 @@"mcpServers": {"repowise": {"command": "repowise",- "args": ["mcp"],- "env": {}+ "args": ["mcp"]}}}diff --git a/plugins/claude-code/CHANGELOG.md b/plugins/claude-code/CHANGELOG.mdnew file mode 100644index 000000000..fcb627a82--- /dev/null+++ b/plugins/claude-code/CHANGELOG.md@@ -0,0 +1,34 @@+# Changelog++All notable changes to the Repowise Claude Code plugin are documented here.++## 0.16.0++First release distributed through the marketplace at the repo root+(`/plugin marketplace add repowise-dev/repowise`).++### Added+- Marketplace manifest at the repo root pointing at `plugins/claude-code`.+- Bundled `PostToolUse` hook (`repowise-augment`) so proactive context+ enrichment works as soon as the plugin is installed.+- Commands: `/repowise:health`, `/repowise:risk`, `/repowise:dead-code`,+ `/repowise:decision`, `/repowise:doctor`.+- Skills: `code-health` and `change-review` (PR / branch / working-tree review+ combining the whole-change `repowise risk` score with `get_risk`'s per-file+ `directive` block).++### Changed+- Corrected the MCP tool surface to the **9 exposed tools**: `get_overview`,+ `get_answer`, `get_context`, `get_symbol`, `search_codebase`, `get_risk`,+ `get_why`, `get_dead_code`, `get_health`.+- Refreshed `codebase-exploration` to route across all 9 tools with explicit+ trust signals, and tightened `pre-modification`, `architectural-decisions`,+ and `dead-code-cleanup`.+- Documented the fifth layer (Code Health) throughout commands and docs;+ `init` now notes code health is built in index-only mode.++### Removed+- References to `get_dependency_path` and `get_architecture_diagram` (present in+ the server but not exposed as MCP tools).+- The standalone-repo distribution model and the install-time estimate from the+ setup-mode docs.diff --git a/plugins/claude-code/DEVELOPER.md b/plugins/claude-code/DEVELOPER.mdindex e2cd66e7c..284251051 100644--- a/plugins/claude-code/DEVELOPER.md+++ b/plugins/claude-code/DEVELOPER.md@@ -2,266 +2,153 @@Internal reference for maintaining, updating, and releasing the plugin.-## Repository Layout+## Layout-The plugin lives in two places:+The plugin and its marketplace both live in the main `repowise` repo — there is+no separate standalone plugin repo:-1. **Monorepo**: `plugins/claude-code/` inside the main `repowise` repo-2. **Standalone**: `repowise-dev/repowise-plugin` on GitHub (what users install from)+- **Marketplace manifest:** `.claude-plugin/marketplace.json` at the **repo root**.+ It lists the plugin and points at it via `source: "./plugins/claude-code"`.+- **Plugin:** `plugins/claude-code/`.-Changes should be made in the monorepo first, tested locally, then synced to the standalone repo for release.+This means one install command for users (`/plugin marketplace add+repowise-dev/repowise`) and a single source of truth — nothing to sync.-## File Structure+## File structure```-repowise-plugin/ # Standalone repo root+repowise/ # main repo root├── .claude-plugin/-│ ├── plugin.json # Plugin identity (name, version, author)-│ └── marketplace.json # Marketplace manifest (enables /plugin install)-├── .mcp.json # Auto-registers repowise MCP server-├── commands/ # User-invoked slash commands-│ ├── init.md # /repowise:init — full setup wizard-│ ├── status.md # /repowise:status — health check-│ ├── update.md # /repowise:update — incremental sync-│ ├── search.md # /repowise:search — wiki search-│ └── reindex.md # /repowise:reindex — rebuild embeddings-├── skills/ # Model-invoked skills (Claude auto-activates)-│ ├── codebase-exploration/-│ │ └── SKILL.md # Teaches Claude to use get_overview, search_codebase-│ ├── pre-modification/-│ │ └── SKILL.md # Teaches Claude to check get_risk before edits-│ ├── architectural-decisions/-│ │ └── SKILL.md # Teaches Claude to query get_why-│ └── dead-code-cleanup/-│ └── SKILL.md # Teaches Claude to use get_dead_code-├── .gitignore-├── CHANGELOG.md-├── LICENSE # AGPL-3.0 (same as main repo)-└── README.md # User-facing docs+│ └── marketplace.json # marketplace manifest → source: ./plugins/claude-code+└── plugins/claude-code/ # the plugin+ ├── .claude-plugin/+ │ └── plugin.json # plugin identity (name, version, author)+ ├── .mcp.json # auto-registers the repowise MCP server (9 tools)+ ├── hooks/+ │ └── hooks.json # PostToolUse → repowise-augment (proactive context)+ ├── commands/ # user-invoked slash commands (/repowise:<name>)+ │ ├── init.md status.md update.md search.md reindex.md+ │ └── health.md risk.md dead-code.md decision.md doctor.md+ ├── skills/ # model-invoked skills (Claude auto-activates)+ │ ├── codebase-exploration/SKILL.md+ │ ├── pre-modification/SKILL.md+ │ ├── change-review/SKILL.md+ │ ├── code-health/SKILL.md+ │ ├── architectural-decisions/SKILL.md+ │ └── dead-code-cleanup/SKILL.md+ ├── CHANGELOG.md+ ├── DEVELOPER.md # this file+ └── README.md # user-facing docs```+The repo-root `LICENSE` (AGPL-3.0) covers the plugin; no separate copy needed.+### What each file does-**`.claude-plugin/plugin.json`** — The only required file. Defines plugin name (used as slash command namespace `repowise:`), version, and metadata. Claude Code reads this to register the plugin.+**`.claude-plugin/marketplace.json` (repo root)** — Makes the repo a+self-hosted marketplace. `plugins[].source: "./plugins/claude-code"` points at+the plugin directory. Users `/plugin marketplace add repowise-dev/repowise`,+then `/plugin install repowise@repowise`.++**`plugins/claude-code/.claude-plugin/plugin.json`** — The plugin's required+manifest. Defines the name (the `repowise:` slash-command namespace), version,+and metadata. Do **not** put a `marketplace.json` next to it — the marketplace+lives at the repo root.-**`.claude-plugin/marketplace.json`** — Makes the repo a self-hosted marketplace. The `plugins[].source: "."` tells Claude Code the plugin root is the repo root itself. Without this file, users can't `/plugin install` from this repo.+**`.mcp.json`** — When the plugin is enabled, Claude Code auto-starts+`repowise mcp` as an MCP server, giving Claude the **9 tools** (`get_overview`,+`get_answer`, `get_context`, `get_symbol`, `search_codebase`, `get_risk`,+`get_why`, `get_dead_code`, `get_health`). Uses the `mcpServers` wrapper key.+The `repowise` binary must be on PATH (`/repowise:init` installs it).-**`.mcp.json`** — When the plugin is enabled, Claude Code auto-starts `repowise mcp` as an MCP server. This is what gives Claude access to the 10 tools. Uses `mcpServers` wrapper key. The `repowise` binary must be on PATH (the init command handles installation).+**`hooks/hooks.json`** — Registers a `PostToolUse` hook+(`Bash|Grep|Glob` → `repowise-augment`) so context enrichment works as soon as+the plugin is installed. This mirrors the hook `repowise init` writes to+`~/.claude/settings.json`; both firing is safe — see "Hook de-duplication".-**`commands/*.md`** — Markdown files that become `/repowise:<filename>` slash commands. Frontmatter defines `description`, `allowed-tools`, etc. The `$ARGUMENTS` placeholder captures user input after the command name.+**`commands/*.md`** — Become `/repowise:<filename>`. Frontmatter sets+`description` + `allowed-tools`; `$ARGUMENTS` captures user input.-**`skills/*/SKILL.md`** — Model-invoked skills. Claude reads the `description` in frontmatter to decide when to activate them. Not shown in the `/` menu (`user-invocable: false`). Keep under 80 lines — bloated skills get ignored.+**`skills/*/SKILL.md`** — Model-invoked. The `description` frontmatter is the+activation trigger — front-load the trigger words. Keep prescriptive and short.-## How Commands vs Skills Work+## Commands vs skills| | Commands | Skills ||---|---|---|-| **Trigger** | User types `/repowise:init` | Claude decides based on context |+| **Trigger** | User types `/repowise:init` | Claude decides from context || **Location** | `commands/<name>.md` | `skills/<name>/SKILL.md` || **Namespace** | `/repowise:<filename>` | `repowise:<dirname>` |-| **Frontmatter** | `allowed-tools`, `description` | `name`, `description`, `user-invocable` |-| **Content** | Step-by-step instructions for Claude to follow | Behavioral guidance for when/how to use tools |--## Local Development--### Testing the plugin--From the monorepo root:--```bash-claude --plugin-dir ./plugins/claude-code-```--Then test:-- `/repowise:init` — walks through setup-- `/repowise:status` — shows sync state-- Ask "how does the auth module work?" — should trigger codebase-exploration skill-- Start editing a file — should trigger pre-modification skill--After making changes, run `/reload-plugins` inside Claude Code to pick them up without restarting.--### Testing with multiple plugins--```bash-claude --plugin-dir ./plugins/claude-code --plugin-dir ./other-plugin-```--## Syncing to the Standalone Repo--The standalone repo is a flat copy of `plugins/claude-code/` plus standalone-only files (LICENSE, CHANGELOG.md, .gitignore).--### First-time setup (already done)+| **Content** | Step-by-step instructions to follow | Behavioral guidance for when/how to use tools |-```bash-# Clone the standalone repo somewhere-git clone https://github.com/repowise-dev/repowise-plugin.git /tmp/repowise-plugin-```--### Syncing changes--```bash-# From the monorepo-PLUGIN_SRC="plugins/claude-code"-STANDALONE="/tmp/repowise-plugin"--# Copy plugin files (overwrite)-cp -r $PLUGIN_SRC/.claude-plugin $STANDALONE/-cp $PLUGIN_SRC/.mcp.json $STANDALONE/-cp -r $PLUGIN_SRC/commands $STANDALONE/-cp -r $PLUGIN_SRC/skills $STANDALONE/-cp $PLUGIN_SRC/README.md $STANDALONE/--# Review, commit, push-cd $STANDALONE-git diff-git add -A-git commit -m "Sync from monorepo: <describe changes>"-git push origin main-```--## Releasing a New Version+## Hook de-duplication-### 1. Bump the version+The plugin bundles the same `repowise-augment` `PostToolUse` hook that+`repowise init` writes to `~/.claude/settings.json`. A user with both installed+would otherwise get duplicate enrichment on a single tool event. `repowise-augment`+guards against this: `_emit_response` claims a short-lived, content-keyed lock+(`_claim_emission` in `packages/cli/src/repowise/cli/commands/augment_cmd.py`)+so exactly one of the two firings emits. The guard is fail-open — if anything+goes wrong it emits rather than risk swallowing a real message.-Update version in both files:-- `.claude-plugin/plugin.json` → `"version": "0.2.0"`-- `.claude-plugin/marketplace.json` → `"version": "0.2.0"` (in both `metadata` and `plugins[0]`)+If you change the bundled hook's command or matcher, keep it in step with the+installer in+`packages/cli/src/repowise/cli/editor_integrations/claude_config.py`.-Version in `plugin.json` wins if they conflict, but keep them in sync.--### 2. Update CHANGELOG.md--Add a new section at the top:--```markdown-## 0.2.0 (YYYY-MM-DD)--### Added-- New skill for X--### Changed-- Updated init command to support Y--### Fixed-- Fixed Z in search command-```--### 3. Commit and tag+## Local development```bash-git add -A-git commit -m "Release v0.2.0 — <summary>"-git tag v0.2.0-git push origin main-git push origin v0.2.0-```--### 4. Create GitHub release--```bash-gh release create v0.2.0 --title "v0.2.0 — <title>" --notes-file CHANGELOG_EXCERPT.md-```--Or create it from the web at https://github.com/repowise-dev/repowise-plugin/releases/new.--### 5. Users get the update--Users run:-```-/plugin update repowise@repowise-```--This pulls the latest from the marketplace repo. The version bump in `plugin.json` drives cache invalidation — without bumping the version, users may get a stale cached copy.--## Adding New Components--### Adding a new command--1. Create `commands/<name>.md` with frontmatter:- ```yaml- ---- description: One-line description of what it does- allowed-tools: Bash, Read- ---- ```-2. Write the step-by-step instructions Claude should follow.-3. It automatically becomes `/repowise:<name>`.--### Adding a new skill--1. Create `skills/<name>/SKILL.md` with frontmatter:- ```yaml- ---- name: <name>- description: >- When to activate this skill. Be specific — Claude uses this text to decide- whether to load the skill. Front-load keywords users would say.- user-invocable: false- ---- ```-2. Write prescriptive instructions (not explanations). Keep under 80 lines.-3. The description is critical — it's the activation trigger.--### Adding supporting files to a skill--Skills can include extra files in their directory:-```-skills/my-skill/-├── SKILL.md # Required — main instructions-├── reference.md # Loaded on demand-└── scripts/- └── helper.sh # Claude can execute this-```--Reference them from SKILL.md so Claude knows they exist.--### Adding a hook--Create `hooks/hooks.json` at the plugin root:-```json-{- "hooks": {- "PostToolUse": [- {- "matcher": "Write|Edit",- "hooks": [{ "type": "command", "command": "echo 'file modified'" }]- }- ]- }-}-```--### Adding an agent--Create `agents/<name>.md` at the plugin root:-```yaml-----name: agent-name-description: What this agent does-model: sonnet------System prompt for the agent...+claude --plugin-dir ./plugins/claude-code```-## Key Gotchas--1. **Version bumps are required for updates.** Without bumping `plugin.json` version, `/plugin update` may serve a cached copy.--2. **Keep skills concise.** Claude ignores bloated skill files. Under 80 lines, prescriptive not verbose.--3. **Skill descriptions are truncated at 250 chars.** Front-load the key use case and trigger words.--4. **`.mcp.json` needs the `mcpServers` wrapper key.** Not just the server name at the top level.--5. **Don't put files inside `.claude-plugin/`.** Only `plugin.json` and `marketplace.json` go there. Everything else (`commands/`, `skills/`, `hooks/`) must be at the plugin root.--6. **`$ARGUMENTS` in commands.** If you use `$ARGUMENTS` in the markdown, it gets replaced with whatever the user typed after the slash command. If you don't use it, the args are appended as `ARGUMENTS: <value>`.--7. **The repowise CLI flags.** Always check the actual CLI (`repowise <cmd> --help`) before writing commands. Key flags that are easy to get wrong:- - `--index-only` (not `--no-llm`)- - `--concurrency` (not `--concurrent`)- - `--commit-limit` (not `--git-depth`)- - `--embedder` (not `--embedding-provider`)--8. **Graceful degradation.** Skills must handle the case where MCP tools fail (repowise not installed or repo not indexed). Always include fallback guidance pointing to `/repowise:init`.+Then exercise it:+- `/repowise:init` — setup wizard+- `/repowise:status`, `/repowise:health`, `/repowise:risk main..HEAD`+- Ask "how does the auth module work?" → should trigger `codebase-exploration`+- "review this PR" / a diff → should trigger `change-review`+- Start editing a shared file → should trigger `pre-modification`++After edits, run `/reload-plugins` inside Claude Code to pick them up.++## Releasing a new version++The plugin version tracks the repowise release it ships alongside (e.g. `0.16.0`).++1. **Bump the version** in two places, kept identical:+ - `plugins/claude-code/.claude-plugin/plugin.json` → `"version"`+ - `.claude-plugin/marketplace.json` (repo root) → `plugins[0].version`+ Bumping the version is what invalidates the `/plugin update` cache — without+ it, users may get a stale cached copy.+2. **Update `CHANGELOG.md`** with an entry for the new version.+3. **Commit** with the rest of the release. Users update via+ `/plugin update repowise@repowise`.++## Adding components++- **Command:** create `commands/<name>.md` with `description` + `allowed-tools`+ frontmatter. It becomes `/repowise:<name>`. Verify any CLI flags against the+ real CLI first (see gotchas).+- **Skill:** create `skills/<name>/SKILL.md` with `name` + `description` ++ `user-invocable: false`. The description is the activation trigger.++## Key gotchas++1. **Bump the version on every release** or `/plugin update` may serve a cached copy.+2. **Keep skills short and prescriptive.** Bloated skills get ignored; the+ description is truncated (~250 chars) — front-load trigger words.+3. **`.mcp.json` needs the `mcpServers` wrapper key.**+4. **Only `plugin.json` goes in `plugins/claude-code/.claude-plugin/`.** Everything+ else (`commands/`, `skills/`, `hooks/`) sits at the plugin root. The+ **marketplace** manifest lives at the **repo** root, not the plugin's.+5. **There are 9 exposed MCP tools.** `get_dependency_path` and+ `get_architecture_diagram` exist in the server but are **not** exposed — never+ reference them in commands/skills.+6. **Verify CLI flags against the source.** Easy ones to get wrong:+ `--index-only` (not `--no-llm`), `--concurrency` (not `--concurrent`),+ `--commit-limit` (not `--git-depth`), `--embedder` (not `--embedding-provider`).+ `dead-code` has no `--group-by` (that's a `get_dead_code` MCP param only).+7. **`repowise risk` scores a whole change** (commit or `base..head`), not a+ file, and is **CLI/REST only** — it is *not* an MCP tool. The MCP `get_risk`+ is per-file blast radius + the PR `directive` block.+8. **Graceful degradation.** Skills/commands must handle repowise-not-installed+ and repo-not-indexed, pointing back to `/repowise:init`.diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.mdindex f3852c03a..84e44824a 100644--- a/plugins/claude-code/README.md+++ b/plugins/claude-code/README.md@@ -1,90 +1,130 @@# Repowise Plugin for Claude Code-Gives Claude Code deep understanding of your codebase — architecture, ownership, hotspots, dependencies, and architectural decisions.+Gives Claude Code deep understanding of your codebase — architecture, ownership,+hotspots, dependencies, architectural decisions, and a defect-validated+code-health score. Claude answers *"why does auth work this way?"* instead of+*"here's what `auth.ts` contains"* — with fewer greps, fewer file reads, and+lower cost per query.## Install-### From Marketplace+### From the marketplace```shell-/plugin marketplace add repowise-dev/repowise-plugin+/plugin marketplace add repowise-dev/repowise/plugin install repowise@repowise```-### Local Development+### Local development```shellclaude --plugin-dir ./plugins/claude-code```-## Quick Start+## Quick start-After installing the plugin, just run:+After installing the plugin, run:```/repowise:init```-Claude will walk you through everything: installing repowise, choosing a mode, configuring your LLM provider, and indexing your codebase.+Claude walks you through everything: installing repowise, choosing a mode,+configuring your LLM provider, and indexing your codebase. Once indexed, the+MCP tools and skills activate automatically.-## What You Get+## What you get-### Slash Commands+### Five intelligence layers++Graph (tree-sitter dependency graph, 15 languages) · Git (hotspots, ownership,+co-change, bus factor) · Docs (LLM-generated wiki + semantic search) · Decisions+(architectural rationale mined from eight sources) · Code Health (1–10+defect-validated score from deterministic biomarkers).++### Slash commands| Command | What it does ||---------|-------------|| `/repowise:init` | Interactive setup — installs repowise, asks your preferences, indexes your codebase || `/repowise:status` | Health check — sync state, page counts, provider info |-| `/repowise:update` | Incremental update — sync docs with recent code changes |-| `/repowise:search` | Search across the codebase wiki (fulltext, semantic, or symbol) |-| `/repowise:reindex` | Rebuild the vector store (re-embed, no LLM calls) |--### Automatic Skills--Claude automatically uses Repowise when relevant — no slash commands needed:--- **Codebase exploration** — uses `get_overview()` and `search_codebase()` before reading raw files-- **Pre-modification checks** — calls `get_risk()` before editing files to assess impact-- **Architectural decisions** — queries `get_why()` when encountering "why" questions-- **Dead code cleanup** — calls `get_dead_code()` during cleanup and refactoring tasks--### MCP Tools (8 total)--Registered automatically when the plugin is installed:--| Tool | Purpose |-|------|---------|-| `get_overview` | Architecture summary, module map, entry points |-| `get_context` | Docs + ownership + history + decisions for files/modules |-| `get_risk` | Hotspot score, dependents, co-change partners |-| `get_why` | Architectural decisions — search, path-based, or health dashboard |-| `search_codebase` | Semantic search over the full wiki |-| `get_dependency_path` | How two modules/files are connected |-| `get_dead_code` | Unused code findings sorted by confidence |-| `get_architecture_diagram` | Mermaid diagram for repo or module |--## Setup Modes--| Mode | What you get | Requirements | Time |-|------|-------------|-------------|------|-| **Full** | Graph + Git + Docs + Decisions + Search | LLM API key | ~25 min / 3k files |-| **Index-only** | Graph + Git + Dead Code | Nothing | < 60 seconds |-| **Local (Ollama)** | Full mode, fully offline | Ollama running | ~45 min / 3k files |--Run `/repowise:init` and Claude will guide you through choosing the right mode.+| `/repowise:update` | Incremental update — sync the index with recent code changes |+| `/repowise:search` | Search the codebase wiki (fulltext, semantic, or symbol) |+| `/repowise:reindex` | Rebuild the vector store (re-embed; no LLM calls) |+| `/repowise:health` | Code-health KPIs, lowest-scoring files, refactoring targets, trends |+| `/repowise:risk` | Defect-risk score for a change (commit or `base..head` range) |+| `/repowise:dead-code` | Unreachable files, unused exports, zombie packages by confidence |+| `/repowise:decision` | List, inspect, add, or confirm architectural decisions |+| `/repowise:doctor` | Diagnose (and optionally repair) the setup, keys, and index drift |++### Automatic skills++Claude uses these when relevant — no slash command needed:++- **Codebase exploration** — routes questions to `get_overview` / `get_answer` / `search_codebase` / `get_context` / `get_symbol` instead of raw file reads.+- **Pre-modification check** — calls `get_risk` (and `get_health` for refactors) before editing to assess blast radius.+- **Change review** — for a PR / branch / working-tree diff, combines `repowise risk` (whole-change score) with `get_risk`'s per-file `directive` block (will-break / missing co-changes / missing tests).+- **Code health** — answers quality / complexity / "what to refactor" via `get_health`.+- **Architectural decisions** — queries `get_why` for the *why* before architectural changes.+- **Dead-code cleanup** — uses `get_dead_code`, conservatively, during cleanup.++### MCP tools (9)++Registered automatically when the plugin is enabled:++| Tool | What it answers |+|------|-----------------|+| `get_overview` | Architecture summary, module map, entry points, git health |+| `get_answer` | Cited, synthesised answer to a code question + a calibrated confidence |+| `get_context` | Triage card (docs, signatures, hotspot bit, callers, decisions) for files/modules/symbols |+| `get_symbol` | Raw source of one symbol with exact line bounds |+| `search_codebase` | Semantic search over the wiki |+| `get_risk` | Per-file hotspot, dependents, co-changes, owners; PR `directive` block with `changed_files` |+| `get_why` | Architectural decisions — search, path-anchored, or health dashboard |+| `get_dead_code` | Unused/unreachable findings tiered by confidence |+| `get_health` | 1–10 code-health score and biomarker findings per file |++## Setup modes++| Mode | What you get | Requirements |+|------|-------------|-------------|+| **Index-only** | Graph + Git + Code Health + Dead Code | Nothing (no LLM) |+| **Full** | Index-only **plus** Docs, semantic search, and Decisions | LLM API key |+| **Local (Ollama)** | Full mode, fully offline | Ollama running |++Index-only builds with zero LLM calls; full mode adds the documentation layer on+top, which can continue in the background. Run `/repowise:init` and Claude helps+you choose.++## Proactive context (hooks)++The plugin registers a `PostToolUse` hook that runs `repowise-augment` after+`Bash` / `Grep` / `Glob`. It stays silent unless it has something asymmetric to+add — rescuing a zero-result grep with the closest indexed symbol, ranking a+flood of matches by graph centrality, or flagging a stale index after a commit.+No LLM, no network. (`repowise init` installs the same hook in+`~/.claude/settings.json`; running both is safe — duplicate enrichment is+de-duplicated.)## Requirements-- Python 3.10+-- Git (for git intelligence features)-- Claude Code 1.0.33++- Python 3.11++- Git (for the git-intelligence layer)+- The `repowise` CLI on PATH (`/repowise:init` installs it)## Troubleshooting-**MCP tools not connecting:** Run `/repowise:init` — the plugin auto-registers the MCP server, but the `repowise` binary needs to be installed and on PATH.+**MCP tools not connecting:** run `/repowise:init` — the plugin auto-registers the+MCP server, but the `repowise` binary must be installed and on PATH.++**`pip install` fails on Windows:** try `python -m pip install repowise`.++**Semantic search / `get_answer` returns nothing:** the repo may be in index-only+mode (no wiki). Re-run `/repowise:init` with an LLM provider, or `/repowise:reindex`+if pages exist but embeddings are missing.-**`pip install` fails on Windows:** Try `python -m pip install repowise` instead.+**Stale results after code changes:** run `/repowise:update`.-**Semantic search returns no results:** Your repo may be in index-only mode (no wiki pages). Run `/repowise:init` again with an LLM provider, or run `/repowise:reindex` if pages exist but embeddings are missing.+## License-**Stale documentation:** Run `/repowise:update` to sync with recent code changes.+AGPL-3.0, same as repowise. See the [repository](https://github.com/repowise-dev/repowise).diff --git a/plugins/claude-code/commands/dead-code.md b/plugins/claude-code/commands/dead-code.mdnew file mode 100644index 000000000..1e0fdb0c2--- /dev/null+++ b/plugins/claude-code/commands/dead-code.md@@ -0,0 +1,43 @@+---+description: Report unreachable files, unused exports, and zombie packages, tiered by confidence.+allowed-tools: Bash, Read+---++# Repowise Dead Code++Find dead code through graph reachability + git context. No LLM — works in+index-only mode. Findings are tiered by confidence; only `safe_to_delete` ones+should be proposed for removal.++## Steps++1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.+2. Run `repowise dead-code` (with any filters from `$ARGUMENTS`).+3. Present findings grouped by confidence. Mark which are `safe_to_delete`. For+ lower-confidence ones, frame them as "candidates to investigate," not deletions.++## Filters from `$ARGUMENTS`++- A path → `repowise dead-code <path>`+- "safe" → `--safe-only` (only safe_to_delete findings)+- "files" → `--kind unreachable_file`+- "exports" → `--kind unused_export`+- "packages" / "zombie" → `--kind zombie_package`+- "strict" → `--min-confidence 0.7` (default is 0.4)++Other flags: `--format json`, `--include-internals` (aggressive, private-symbol+scan; higher false-positive rate), `--include-zombie-packages` /+`--no-include-zombie-packages`, `--no-unreachable`, `--no-unused-exports`,+`--repo <alias>` / `--no-workspace`.++For per-directory or per-owner rollups, use the `get_dead_code` MCP tool with+`group_by="directory"` or `group_by="owner"` (these are tool params, not CLI flags).++## Before suggesting any deletion++- Confirm with the user; show the name, confidence, and why it looks dead.+- Recently-touched "dead" code is more likely a false positive — flag it.+- Dynamically-loaded patterns (plugins, handlers, adapters, framework routes)+ can look unused but aren't. Repowise filters the common cases; edge cases remain.+- Double-check blast radius with `get_risk(targets=[...])` before removing files+ or exported symbols.diff --git a/plugins/claude-code/commands/decision.md b/plugins/claude-code/commands/decision.mdnew file mode 100644index 000000000..9e819ca05--- /dev/null+++ b/plugins/claude-code/commands/decision.md@@ -0,0 +1,40 @@+---+description: Work with architectural decisions — list, inspect health, add, or confirm auto-proposed decisions.+allowed-tools: Bash, Read+---++# Repowise Decisions++Repowise captures architectural decisions (the *why* behind the code) from eight+sources and tracks them for staleness and conflicts. This command drives the+`repowise decision` group.++## Steps++1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.+2. Map `$ARGUMENTS` to a subcommand, run it, and present the result clearly.++## Subcommands++- **list** (default) — `repowise decision list`+ - "stale" → `--stale-only`; "proposed" → `--proposed`+ - "active" / "deprecated" / "superseded" → `--status <value>`+ - filter by origin → `--source <value>`+- **health** — `repowise decision health` — stale decisions, conflicts, and+ ungoverned hotspots (high-churn files with no recorded decision). Good first call.+- **show** — `repowise decision show <id>` — full record: rationale, evidence+ spans, status, and the supersession lineage.+- **add** — `repowise decision add` — guided interactive capture (~90s). Use when+ the user makes a decision during the session and wants it recorded.+- **confirm** — `repowise decision confirm` — review decisions auto-proposed from+ git history and accept or reject them.+- **deprecate / dismiss** — `repowise decision deprecate <id>` (optionally+ `--superseded-by <id>`) or `repowise decision dismiss <id>`.++## Notes++- For *querying* why code looks the way it does mid-task, prefer the `get_why`+ MCP tool (the `architectural-decisions` skill) — it returns lineage and an+ alignment score. This command is for *managing* the decision records themselves.+- `add` and `confirm` are interactive; tell the user when a step needs their input.+- If unsure of an exact subcommand or flag, run `repowise decision --help`.diff --git a/plugins/claude-code/commands/doctor.md b/plugins/claude-code/commands/doctor.mdnew file mode 100644index 000000000..c3029a317--- /dev/null+++ b/plugins/claude-code/commands/doctor.md@@ -0,0 +1,32 @@+---+description: Diagnose the Repowise setup — install, API keys, index/store drift — and optionally repair it.+allowed-tools: Bash, Read+---++# Repowise Doctor++Check that Repowise is healthy: the install, configured provider / API keys, and+whether the index and stores are consistent with the repo.++## Steps++1. Run `repowise doctor`.+2. Summarize what passed and what didn't. For each problem, give the concrete fix+ (set an env var, run `/repowise:update`, re-run `/repowise:init`, etc.).++## Flags from `$ARGUMENTS`++- "repair" / "fix" → `repowise doctor --repair` (attempts to fix detected+ mismatches). Tell the user what it changed.+- "workspace" → `repowise doctor --workspace` (check every repo in the workspace);+ `--no-workspace` to force single-repo.+- a path → `repowise doctor <path>`++## Common findings++- **repowise not installed / not on PATH** → suggest `pip install repowise` (or+ `python -m pip install repowise` on Windows), then `/repowise:init`.+- **No API key for the configured provider** → show the exact `export` for the+ provider in `.repowise/config.yaml`.+- **Index drift (HEAD ahead of last sync)** → run `/repowise:update`.+- **Missing embeddings / store drift** → `/repowise:reindex`.diff --git a/plugins/claude-code/commands/health.md b/plugins/claude-code/commands/health.mdnew file mode 100644index 000000000..2881308b4--- /dev/null+++ b/plugins/claude-code/commands/health.md@@ -0,0 +1,41 @@+---+description: Show Repowise code-health — KPIs, lowest-scoring files, refactoring targets, trends, or per-file biomarkers.+allowed-tools: Bash, Read+---++# Repowise Health++Report the code-health layer: a deterministic 1–10 score per file from biomarkers+(complexity, deep nesting, brain methods, cohesion, duplication, untested+hotspots, and more). No LLM — works even in index-only mode.++## Steps++1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.+2. Decide the mode from `$ARGUMENTS` (see below), run the command, and present a+ readable summary — score(s), the top biomarker findings, and what they mean.+ Don't dump the raw table verbatim.++## Modes++Default (no args) — dashboard KPIs + lowest-scoring files:+```+repowise health+```++Handle `$ARGUMENTS`:+- A file or directory path → `repowise health <path>` (or `--file <path>` for a single file)+- "refactoring" / "targets" → `repowise health --refactoring-targets` (ranked by impact/effort)+- "trend" / "trends" → `repowise health --trend` (last snapshots + declining / predicted-decline alerts)+- "module <name>" → `repowise health --module <name>`+- "safe" → `repowise health --safe-only`+- a coverage file (e.g. `cov.lcov`, `coverage.xml`) → `repowise health --coverage <file>` to light up untested-hotspot / coverage-gap biomarkers (LCOV, Cobertura, Clover)++Other flags: `--format json` for machine-readable output, `--repo <alias>` /+`--no-workspace` in workspace mode.++## Notes++- A file that is both low-health **and** a churn hotspot is the highest-priority+ cleanup — cross-reference with `/repowise:risk` or `get_risk`.+- If everything scores high, say so plainly rather than inventing concerns.diff --git a/plugins/claude-code/commands/init.md b/plugins/claude-code/commands/init.mdindex dca71f2a0..b98e0f3f4 100644--- a/plugins/claude-code/commands/init.md+++ b/plugins/claude-code/commands/init.md@@ -41,8 +41,8 @@ Ask the user ONE question:"How would you like to set up Repowise?-1. **Index-only mode** — no LLM needed. Builds the dependency graph, mines git history, detects dead code. Runs in under 60 seconds. You get graph intelligence, git ownership, hotspots, and dead code detection — but no generated documentation or semantic search.-2. **Full mode** — generates rich documentation using an LLM. Requires an API key (Anthropic, OpenAI, Google Gemini, or Ollama for local). Takes longer but gives you the best results — full wiki, semantic search, and RAG context.+1. **Index-only mode** — no LLM needed. Builds the dependency graph, mines git history, scores code health, and detects dead code. Fast. You get graph intelligence, git ownership, hotspots, the 1–10 code-health score, and dead-code detection — but no generated documentation or semantic search.+2. **Full mode** — everything in index-only **plus** an LLM-generated wiki, semantic search, and architectural-decision mining. Requires an API key (Anthropic, OpenAI, Google Gemini, or Ollama for local). The graph/git/health layers are ready in minutes; the documentation layer runs after and can continue in the background.3. **I'll configure it myself** — just show me the available flags."### If Index-only mode:diff --git a/plugins/claude-code/commands/risk.md b/plugins/claude-code/commands/risk.mdnew file mode 100644index 000000000..8558ab45e--- /dev/null+++ b/plugins/claude-code/commands/risk.md@@ -0,0 +1,36 @@+---+description: Score the defect risk of a change — a commit or a base..head range — as a single 0–10 with drivers.+allowed-tools: Bash, Read+---++# Repowise Risk++Score a *change* (not a file) for defect risk. Repowise reads the diff shape —+lines added/deleted, files, directories, subsystems, change entropy, and author+familiarity — and returns a 0–10 score with an attributable driver breakdown.+Pure git + learned constants: no LLM, no network. A natural pre-merge / PR gate.++## Steps++1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.+2. Resolve the target from `$ARGUMENTS`, run `repowise risk`, and present the+ score, level, and top drivers — calling out *why* it's risky (e.g. wide+ diffusion across subsystems, low author familiarity).++## Choosing the revspec++- No args → `repowise risk` (scores `HEAD`)+- A commit SHA → `repowise risk <sha>`+- A range / PR / branch → `repowise risk <base>..<head>` (e.g. `repowise risk main..HEAD`)++Useful flags:+- `--ext .py,.ts` — only count changes in those file types+- `--format json` — machine-readable score + features + drivers+- `--path <dir>` — point at a different git repo++## How this differs from the other risk views++- This command = the **whole change** as one number (defect-risk gate).+- For **per-file** blast radius (what breaks, missing co-changes, missing tests),+ use the `get_risk` MCP tool / the `change-review` skill.+- For **per-file health** scores, use `/repowise:health`.diff --git a/plugins/claude-code/hooks/hooks.json b/plugins/claude-code/hooks/hooks.jsonnew file mode 100644index 000000000..c55ac719f--- /dev/null+++ b/plugins/claude-code/hooks/hooks.json@@ -0,0 +1,17 @@+{+ "hooks": {+ "PostToolUse": [+ {+ "matcher": "Bash|Grep|Glob",+ "hooks": [+ {+ "type": "command",+ "command": "repowise-augment",+ "timeout": 10,+ "statusMessage": "Checking codebase context..."+ }+ ]+ }+ ]+ }+}diff --git a/plugins/claude-code/skills/architectural-decisions/SKILL.md b/plugins/claude-code/skills/architectural-decisions/SKILL.mdindex a90ebda1b..19b8d4028 100644--- a/plugins/claude-code/skills/architectural-decisions/SKILL.md+++ b/plugins/claude-code/skills/architectural-decisions/SKILL.md@@ -13,12 +13,24 @@ user-invocable: falseRepowise captures architectural decisions — the *why* behind how code is built.+`get_why` has four modes — pick by what you pass:++1. `get_why(query="why is auth using JWT?")` — keyword + semantic decision search.+2. `get_why(query="src/auth/service.py")` — decisions governing that file, plus+ its origin story and an alignment score (does the file still follow its own ADRs?).+3. `get_why(query="why was caching added?", targets=["src/auth/cache.py"])` —+ target-anchored search; decisions touching the targets get boosted.+4. `get_why()` — the decision-health dashboard.++Decisions are mined from eight sources (ADR files, CHANGELOG, PR/commit bodies,+inline markers, git archaeology, README/docs, code comments, and the doc pass)+and linked by `supersedes` / `refines` / `relates_to` / `conflicts_with` edges,+so a single answer can return a whole lineage chain. When no decision exists for+a path, `get_why` falls back to git archaeology so the call is never empty.+## When the user asks "why is X built this way?"-Call `get_why(query="X")` to search across all captured decisions. This searches:-- Inline decision markers in code (`# WHY:`, `# DECISION:`, `# TRADEOFF:`)-- Decisions extracted from git history (migrations, refactors)-- Decisions mined from documentation+Call `get_why(query="X")`.## When about to make an architectural change@@ -28,10 +40,14 @@ Call `get_why(query="X")` to search across all captured decisions. This searches## When called with no specific query-Call `get_why()` with no arguments to get the decision health dashboard:+Call `get_why()` with no arguments to get the decision-health dashboard:- Stale decisions that may no longer apply+- Proposed decisions awaiting confirmation- Ungoverned hotspots (high-churn files with no recorded decisions)+The same signals surface in the CLI via `repowise decision health`, and you can+review auto-proposed decisions with `repowise decision confirm`.+## When a file has decision markersIf you see `# WHY:`, `# DECISION:`, `# TRADEOFF:`, or `# ADR:` comments in code, call `get_context(targets=["that_file.py"])` to see the full decision record with context and affected modules.diff --git a/plugins/claude-code/skills/change-review/SKILL.md b/plugins/claude-code/skills/change-review/SKILL.mdnew file mode 100644index 000000000..1cd429dc9--- /dev/null+++ b/plugins/claude-code/skills/change-review/SKILL.md@@ -0,0 +1,87 @@+---+name: change-review+description: >+ Use when reviewing a set of changes before they merge — a PR, a branch diff, or the working-tree+ changes you just made — in a Repowise-indexed codebase (.repowise/ directory exists). Activates+ for "review this PR", "is this safe to merge", "what's the blast radius of these changes", "did I+ miss anything", or "what else should change with this".+user-invocable: false+---++# Change Review with Repowise++When a diff is on the table, Repowise turns "what files changed" into "what does+this change put at risk" — fusing git history (churn, ownership, co-change) with+graph topology (dependents, impact surface), test gaps, security signals, and the+architectural decisions that govern the touched code.++Two complementary risk signals — use both:++- **`repowise risk` (CLI)** scores the *whole change as one unit* (a commit or a+ `base..head` range) → a single 0–10 defect-risk score with drivers (lines+ added/deleted, files, directories, subsystems, change entropy, author+ familiarity). No LLM, no network. This is the pre-merge gate: "how risky is+ this change overall?"+- **`get_risk(changed_files=…)` (MCP)** works *per file* and returns the+ `directive` block — the specific things to check inside the diff.++## Score the whole change first++```+repowise risk <revspec> # HEAD, a commit SHA, or base..head (e.g. main..HEAD)+```++Read the score and its top drivers — a high score from large diffusion (many+dirs/subsystems) or low author familiarity tells you where to look hardest.+Add `--ext .py,.ts` to count only certain file types, `--format json` for a+machine-readable breakdown.++## Then drill into the directive block++Call `get_risk` in **PR mode** by passing the changed files:++```+get_risk(targets=<changed files>, changed_files=<same changed files>)+```++The response carries a `directive` block — read it first, it's three short lists:++- **`will_break`** — files/symbols that depend on what changed but are *not* in+ the diff. These are the likely breakages. Check each one.+- **`missing_cochanges`** — files that historically change together with the+ changed files but were left untouched. Often a forgotten update.+- **`missing_tests`** — changed code with a test gap. Flag for new/updated tests.++`pr_blast_radius` holds the fuller dossier behind those three lists.++## Then go deeper where it matters++1. **Why does this code exist?** For any non-trivial changed file, call+ `get_why(query="<file>")` — don't let a change silently contradict a recorded+ architectural decision. Surface `conflicts_with` / `supersedes` hits.+2. **Did the change make health worse?** `get_health(targets=<changed files>,+ include=["biomarkers"])` — call out new complexity, deep nesting, or+ duplication the diff introduced.+3. **Who should review?** `get_risk` ownership + co-change signals suggest the+ people with the most context on the touched code.++## Getting the diff++- A GitHub PR: `gh pr diff <number>` (or `gh pr view <number> --json files`).+- A branch: `git diff --name-only main...HEAD`.+- Working tree: `git status --porcelain`.+- CLI shortcut for a range: `repowise risk main..HEAD` scores a branch/PR range+ for defect risk directly.++## Write the review around evidence++Lead with a risk level and the `directive` findings, each tied to a concrete+file. Distinguish **"will break"** (a dependent outside the diff) from **"worth a+look"** (a co-change or health regression). Don't pad with findings the tools+didn't support.++## Error handling++If `get_risk` errors or returns nothing, the MCP server may be down or the repo+unindexed — say so and review from the raw diff, noting that Repowise context was+unavailable. Suggest `/repowise:init` if the repo isn't indexed.diff --git a/plugins/claude-code/skills/code-health/SKILL.md b/plugins/claude-code/skills/code-health/SKILL.mdnew file mode 100644index 000000000..9a2da367e--- /dev/null+++ b/plugins/claude-code/skills/code-health/SKILL.md@@ -0,0 +1,61 @@+---+name: code-health+description: >+ Use when the user asks about code health, code quality, complexity, technical debt, which files+ are risky or hard to maintain, what to refactor next, untested hotspots, or coverage gaps in a+ Repowise-indexed codebase (.repowise/ directory exists). Also use to get a before/after health+ read when planning or finishing a refactor.+user-invocable: false+---++# Code Health with Repowise++Repowise scores **every file 1–10** from deterministic biomarkers — McCabe+complexity, deep nesting, brain methods, class cohesion (LCOM4), god classes,+clone detection, untested hotspots, function-level churn, ownership dispersion,+and more. Zero LLM calls; pure local analysis. The weights are calibrated+against a real defect corpus, so a low score means *more likely to harbour bugs*,+not just *bigger*.++## Pick the mode by what you pass++- **Dashboard** — `get_health()` (no targets): repo-level KPIs plus the+ lowest-scoring files. Start here for "how healthy is this codebase?" or "what+ should we clean up?".+- **Targeted** — `get_health(targets=["src/x.py", "src/y.py"])`: per-file score+ and the specific biomarker findings driving it. Use before/after a refactor,+ or to explain *why* a file is flagged.++## Useful `include` flags++`get_health(targets=[...], include=[...])`:+- `"biomarkers"` — always return the findings list (what's wrong, where).+- `"refactoring"` — deterministic, ranked refactoring suggestions (by impact/effort).+- `"coverage"` — surface coverage data when it's been ingested.+- `"trend"` — recent health snapshots + declining / predicted-decline signal.++## How to use the results++1. For "what should I refactor?" → dashboard mode, then+ `get_health(targets=[worst files], include=["refactoring"])` and present the+ ranked suggestions, not just the scores.+2. For a specific file → report the score, the top 2–3 biomarker findings, and+ what each one means in plain language. Avoid dumping the raw payload.+3. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file+ that is both low-health *and* a churn hotspot deserves the most care.+4. Untested-hotspot / coverage questions → tell the user coverage biomarkers+ light up once they ingest a report: `repowise health --coverage cov.lcov`+ (LCOV / Cobertura / Clover).++## CLI equivalents++- `repowise health` — KPIs + lowest-scoring files+- `repowise health --refactoring-targets` — ranked by impact / effort+- `repowise health --trend` — snapshots + declining alerts+- `repowise health --coverage <file>` — ingest coverage, light up untested-hotspot++## Error handling++If `get_health` reports no repository, suggest `/repowise:init`. Code health is+computed even in index-only mode (no LLM needed), so it should be available+whenever the repo is indexed.diff --git a/plugins/claude-code/skills/codebase-exploration/SKILL.md b/plugins/claude-code/skills/codebase-exploration/SKILL.mdindex 055c7a260..5ddf4518b 100644--- a/plugins/claude-code/skills/codebase-exploration/SKILL.md+++ b/plugins/claude-code/skills/codebase-exploration/SKILL.md@@ -2,36 +2,55 @@name: codebase-explorationdescription: >Use when exploring, understanding, or answering questions about a codebase that has Repowise- indexed (indicated by a .repowise/ directory in the project root). Activates for questions like- "how does X work", "explain the architecture", "where is Y implemented", "what does this module do",- or any task requiring understanding of codebase structure before diving into source files.+ indexed (a .repowise/ directory in the project root). Activates for "how does X work",+ "explain the architecture", "where is Y implemented", "what does this module do", or any task+ that needs an understanding of structure before diving into source files.user-invocable: false---# Codebase Exploration with Repowise-This project has a Repowise intelligence layer. Before reading raw source files to understand the codebase, use Repowise MCP tools — they provide richer context including documentation, ownership, history, and architectural decisions.+This project has a Repowise intelligence layer. Before grepping and reading raw+source to understand the codebase, reach for the Repowise MCP tools — they+return documentation, ownership, history, decisions, and graph structure that+plain file reads don't, usually in one round-trip instead of many.-## When starting a new exploration task+## Which tool for which question-Call `get_overview()` first. This returns the architecture summary, module map, entry points, and tech stack. This single call replaces reading dozens of files to understand the project structure.+| You want… | Call |+|---|---|+| First orientation in an unfamiliar repo | `get_overview()` — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |+| A direct answer to "how/where/why does X work" | `get_answer(question="…")` — synthesised answer with citations + a `retrieval_quality` signal. Collapses the search → read → reason loop. |+| Candidate files for a fuzzy concept | `search_codebase(query="…")` — semantic wiki search. Each hit reports `search_method` (`embedding` vs `bm25` fallback). Use Grep for exact identifiers. |+| A triage card for specific files/symbols | `get_context(targets=[…])` — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. |+| The actual source of one symbol | `get_symbol("path/to/file.py::Name")` — exact bytes with line bounds. Cheaper than Read + offset math. Use a `symbol_id` from `get_context`. |-## When answering "how does X work" questions+## Recommended flow-1. Call `search_codebase(query="X")` to find the most relevant documented modules and files.-2. Call `get_context(targets=[...relevant files from search results...])` to get full documentation, ownership, freshness, and decisions for those targets. Batch all targets in one call.-3. Only read raw source files if the Repowise docs don't cover enough detail for the specific question.+1. New area you don't know → `get_overview()` once.+2. A specific question → `get_answer(question=…)` first.+ - High confidence → answer it, cite the paths.+ - `medium`/`low` confidence → follow `best_guesses[0].file` or+ `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.+3. More files around a concept → `search_codebase`, then `get_context` on the+ hits (batched), then `get_symbol` only for the bodies you actually need.-## When asked about connections between modules+Fall back to raw Read/Grep only when the indexed context doesn't cover the+specific detail the user asked about.-Call `get_dependency_path(source="module_a", target="module_b")` to understand how two parts of the codebase are connected through the dependency graph.+## Trust signals — verify when-## When you need a visual overview+- `_meta.stale_warning` is present (the index has diverged from HEAD), or+- `retrieval_quality` is `partial`/`weak`, or+- a result's `search_method` is `bm25`.-Call `get_architecture_diagram(scope="module", path="path/to/module")` for a Mermaid diagram of a specific subsystem, or `get_architecture_diagram()` for the full repo.+Otherwise the response is current — act on it.## Error handling-- If tools return "No repositories found. Run 'repowise init' first." — suggest the user run `/repowise:init`.-- If `search_codebase` returns empty results — the repo may be in analysis-only mode (no wiki pages). Note this and fall back to `get_context` with specific file paths, or suggest upgrading to full mode.-- If tools fail to connect entirely — the `repowise` binary may not be installed. Suggest `/repowise:init`.+- "No repositories found. Run 'repowise init' first." → suggest `/repowise:init`.+- `get_answer`/`search_codebase` come back empty → the repo may be in index-only+ mode (no wiki). Fall back to `get_context` with explicit paths, and note that+ full mode (`/repowise:init` with an LLM provider) unlocks docs + semantic search.+- Tools fail to connect at all → the `repowise` binary may not be installed;+ suggest `/repowise:init`.diff --git a/plugins/claude-code/skills/dead-code-cleanup/SKILL.md b/plugins/claude-code/skills/dead-code-cleanup/SKILL.mdindex feab4a04d..508bce6f1 100644--- a/plugins/claude-code/skills/dead-code-cleanup/SKILL.md+++ b/plugins/claude-code/skills/dead-code-cleanup/SKILL.md@@ -20,6 +20,8 @@ Call `get_dead_code()` to get findings sorted by confidence tier. Useful paramet- `kind="zombie_package"` — monorepo packages with no consumers- `directory="src/old/"` — limit to a specific directory- `tier="high"` — only high-confidence findings (>= 0.8)+- `min_confidence=0.7` — raise the floor (default is 0.5) for a release-ready cleanup+- `group_by="directory"` or `group_by="owner"` — roll up to see where the dead code concentrates and who owns the most of it## How to present findingsdiff --git a/plugins/claude-code/skills/pre-modification/SKILL.md b/plugins/claude-code/skills/pre-modification/SKILL.mdindex ad743e2a6..5526efb3f 100644--- a/plugins/claude-code/skills/pre-modification/SKILL.md+++ b/plugins/claude-code/skills/pre-modification/SKILL.md@@ -14,12 +14,15 @@ Before modifying files in a Repowise-indexed codebase, assess the impact.## Before editing a file-Call `get_risk(targets=["path/to/file.py"])` to understand:-- **Hotspot status** — is this a high-churn file? Extra care needed.-- **Dependents** — what other files/modules depend on this? How wide is the blast radius?-- **Co-change partners** — what files typically change together with this one? You may need to update them too.-- **Ownership** — who owns this code? Relevant for PR review routing.-- **Bus factor** — if only 1 person owns this, changes need extra review.+Call `get_risk(targets=["path/to/file.py"])`. Per file it returns+`hotspot_score`, `trend`, `risk_type`, `impact_surface` (top 3),+`dependents_count`, `co_change_partners`, `primary_owner`, `bus_factor`,+`test_gap`, and `security_signals`. Read it for:+- **Hotspot status** (`hotspot_score`, `trend`) — high-churn × complex? Extra care needed.+- **Dependents** (`dependents_count`, `impact_surface`) — how wide is the blast radius?+- **Co-change partners** — files that change together with this one (often without an import link); you may need to update them too.+- **Ownership / bus factor** — who owns it, and whether a single author maintains it.+- **Test gap & security signals** — flag untested or security-sensitive files before touching them.## When modifying multiple files@@ -37,6 +40,10 @@ If `get_risk` shows:Call `get_context(targets=["file.py"])` first to understand the full context: what uses this file, what decisions govern it, and why it's structured this way. This prevents accidentally violating architectural decisions.+For a heavy refactor, also call `get_health(targets=["file.py"])` — the+biomarker findings (complexity, deep nesting, low cohesion, duplication) tell+you *what* to improve while you're in there, and give you a before/after score.+## Error handlingIf `get_risk` returns a tool error, the MCP server may not be running. Proceed with the modification but note that risk assessment was unavailable.