isurus-hg

A Claude Code plugin that teaches Claude to work fluently in Mercurial 7.x, with an Isurus-conventions overlay for the Isurus forge codebase, and a PreToolUse hook that prevents accidental git commands inside .hg repositories.

Built because Claude's general competence is uneven on Mercurial — bookmarks, named branches, phases, and Isurus's house conventions are easy to get wrong without explicit guidance — and because "never use git" is more reliable as a hook than as a memorized instruction.

What it includes

Skills (auto-loaded by Claude when relevant):

• mercurial-basics — status, diff, log, add, commit, message format, phase awareness.
• mercurial-bookmarks-and-prs — bookmark workflow as the unit of feature work and PRs.
• mercurial-sync-and-merge — pull, update, multiple heads, merge, conflict resolution.
• mercurial-history-rewriting — amend, uncommit, the draft-vs-public phase rule, recovery patterns.
• mercurial-finishing-a-branch — pre-PR checklist + push flow (the hg counterpart to superpowers' finishing-a-development-branch).
• isurus-conventions — overlay skill that activates in the Isurus repo; supplies project-specific values (URLs, branches, make targets) that the generic skills' procedures plug into.

Hook:

• block-git-in-hg.sh — fires on every Bash tool call. If the command starts with git and the working directory is inside an .hg repository (and not inside a closer .git repo or a bare git repo), the call is blocked with a message suggesting the hg equivalent.

Install

Two supported mechanisms, depending on whether you want the plugin loaded for one session or persistently across sessions.

Option 1 — --plugin-dir flag (session-only, recommended for development and testing)

Launch Claude Code with the plugin directory as an argument:

claude --plugin-dir /absolute/path/to/isurus-claude-plugin

The plugin is loaded for that session only. Repeat the flag to load multiple plugins. Takes precedence over installed marketplace plugins, which is what you want while iterating on the plugin itself.

Option 2 — local marketplace (persistent across sessions)

If you want the plugin to load every time Claude Code starts, register it through a local marketplace.

1. Create a marketplace.json in any parent directory of the plugin. For this repo's recommended layout, place it at <parent>/.claude-plugin/marketplace.json:

   {
     "name": "local-isurus",
     "owner": { "name": "Your Name" },
     "plugins": [
       {
         "name": "isurus-hg",
         "source": "./isurus-claude-plugin",
         "description": "Mercurial fluency for Claude Code, with an Isurus-conventions overlay."
       }
     ]
   }
   

   source is relative to the marketplace.json's directory.

2. Register the marketplace and install the plugin from inside Claude Code:

   /plugin marketplace add /absolute/path/to/parent
   /plugin install isurus-hg@local-isurus
   

The skills become available and the hook is registered automatically via hooks/hooks.json.

Requirements:

• Mercurial 7.x (the skills assume modern command behavior).
• jq on PATH (the hook uses it to parse tool-call JSON; if missing, the hook fails open with a warning).
• Bash 4+.

Note for v0.1.0 users: earlier README revisions described an undocumented "plugins": { ... } block in ~/.claude/settings.json. That block is not a supported Claude Code feature and is silently ignored. Use one of the two mechanisms above instead.

Hook behavior

The hook intercepts Bash tool calls. Decision tree:

1. Command doesn't start with git → allow.
2. Working directory is a bare git repository (contains HEAD, refs/, objects/ at top level) → allow.
3. Closest VCS ancestor is .git/ → allow.
4. Closest VCS ancestor is .hg/ → block with exit code 2 and a stderr message suggesting the hg equivalent.
5. No VCS context → allow (e.g., git --version outside any repo).

Documented limitation: only the leading token of the command is inspected, so cd /tmp && git init from inside an .hg repo is allowed (intended escape valve). Override the hook by commenting out the entry in hooks/hooks.json.

Layered defense — the hook is a backstop, not the primary mechanism

git-in-hg avoidance happens at two layers:

• Skills (primary): the mercurial-* skills teach Claude to recognize .hg/ and reach for hg commands directly. When the skills load, the model usually never attempts git in the first place.
• Hook (backstop): if a git command is invoked anyway, the hook intercepts and blocks it. The 7 unit tests under hooks/test/ validate the block path in isolation.

In practice this means the hook may rarely fire in a session where the plugin loaded cleanly — that's expected, not a defect. To verify the hook actively works in a live session, see the adversarial sub-test in tests/MANUAL.md Scenario 5.

Development

This plugin is developed in Mercurial (eating its own dogfood). To work on it:

hg clone <repo-url>
cd isurus-claude-plugin

# Validate skills
./scripts/check-skills.sh

# Run hook tests
./hooks/test/run.sh

# Walk manual scenarios after meaningful changes
cat tests/MANUAL.md

Design spec: docs/superpowers/specs/2026-05-01-isurus-hg-plugin-design.md
Implementation plan: docs/superpowers/plans/2026-05-02-isurus-hg-plugin.md

License

MIT — see LICENSE.