Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Repowise Claude Code Plugin — Developer Guide
Internal reference for maintaining, updating, and releasing the plugin.
Layout
The plugin and its marketplace both live in the main repowise repo — there is
no separate standalone plugin repo:
- Marketplace manifest:
.claude-plugin/marketplace.jsonat the repo root. It lists the plugin and points at it viasource: "./plugins/claude-code". - Plugin:
plugins/claude-code/.
This means one install command for users (/plugin marketplace add repowise-dev/repowise) and a single source of truth — nothing to sync.
File structure
repowise/ # main repo root
├── .claude-plugin/
│ └── 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 (10 flagship + list_repos)
├── 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/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.
.mcp.json — When the plugin is enabled, Claude Code auto-starts
repowise mcp as an MCP server, giving Claude the ten flagship tools
(get_overview, get_answer, get_context, get_symbol, search_codebase,
get_risk, get_change_risk, get_why, get_dead_code, get_health) plus
list_repos by default. Uses the mcpServers wrapper key.
The repowise binary must be on PATH (/repowise:init installs it).
hooks/hooks.json — Registers SessionStart
(startup|resume|clear → repowise-augment) and PostToolUse
(Grep|Glob|Read|Edit|Write|mcp__.*[Rr]epowise.*__.* →
repowise-augment) so context enrichment works as soon as the plugin is
installed. This mirrors the hooks repowise init writes to
~/.claude/settings.json; both firing is safe — see "Hook de-duplication".
commands/*.md — Become /repowise:<filename>. Frontmatter sets
description + allowed-tools; $ARGUMENTS captures user input.
skills/*/SKILL.md — Model-invoked. The description frontmatter is the
activation trigger — front-load the trigger words. Keep prescriptive and short.
Commands vs skills
| Commands | Skills | |
|---|---|---|
| Trigger | User types /repowise:init |
Claude decides from context |
| Location | commands/<name>.md |
skills/<name>/SKILL.md |
| Namespace | /repowise:<filename> |
repowise:<dirname> |
| Content | Step-by-step instructions to follow | Behavioral guidance for when/how to use tools |
Hook de-duplication
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/command.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.
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.
A user who runs repowise init --no-editor-setup (or sets
REPOWISE_SKIP_EDITOR_SETUP=1) gets no hooks from the installer at all. The
plugin's bundled copy still fires, which is the point: the plugin is how you get
the enrichment without letting init write to your global settings.
Local development
claude --plugin-dir ./plugins/claude-code
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).
- Bump the version in two places, kept identical:
plugins/claude-code/.claude-plugin/plugin.json→"version".claude-plugin/marketplace.json(repo root) →plugins[0].versionBumping the version is what invalidates the/plugin updatecache — without it, users may get a stale cached copy.
- Update
CHANGELOG.mdwith an entry for the new version. - Commit with the rest of the release. Users update via
/plugin update repowise@repowise.
Adding components
- Command: create
commands/<name>.mdwithdescription+allowed-toolsfrontmatter. It becomes/repowise:<name>. Verify any CLI flags against the real CLI first (see gotchas). - Skill: create
skills/<name>/SKILL.mdwithname+description+user-invocable: false. The description is the activation trigger.
Key gotchas
- Bump the version on every release or
/plugin updatemay serve a cached copy. - Keep skills short and prescriptive. Bloated skills get ignored; the description is truncated (~250 chars) — front-load trigger words.
.mcp.jsonneeds themcpServerswrapper key.- Only
plugin.jsongoes inplugins/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. - Default single-repo surface is 11 tools (the ten flagship tools plus
list_repos). Workspace mode addsget_architectureandget_blast_radiusautomatically (13). Opt-in tools such asget_conformancestay off unless configured — seedocs/agent/MCP_TOOLS.md. Never reference unexposed tools in commands/skills. - Verify CLI flags against the source. Easy ones to get wrong:
--prose/--no-proseis the wiki-spend switch (--index-onlyand--docs llm|deterministicare deprecated aliases; do not write them into new agent-facing commands).--concurrency(not--concurrent),--commit-limit(not--git-depth),--embedder(not--embedding-provider).dead-codehas no--group-by(that's aget_dead_codeMCP param only). repowise risk/ MCPget_change_riskscore a whole change (commit orbase..head), not a file. MCPget_riskis per-file blast radius + the PRdirectiveblock.- Graceful degradation. Skills/commands must handle repowise-not-installed
and repo-not-indexed, pointing back to
/repowise:init.