isurus-hg (Grok plugin)

Mercurial fluency and Isurus forge skills for Grok / Grok Build — with a PreToolUse hook that blocks accidental git commands inside .hg repositories.

Leafscale teams use Isurus (a privacy-first multi-VCS forge: Git, Mercurial, Fossil) for product and customer work. This plugin teaches the agent to:

1. Operate Mercurial correctly (bookmarks, phases, amend-on-draft, PR push).
2. Use the Isurus forge as a platform (multi-VCS PRs, issues, API scopes).
3. Author and debug Isurus CI (.isurus-ci.yml).
4. Follow Isurus product house rules when working in the forge codebase itself.

A Claude Code sibling lives in ../isurus-claude-plugin. That plugin is incomplete (v0.1.x scaffolding and early skills only; plan acceptance / dogfooding / forge-layer skills / MCP were never finished). Treat it as historical reference, not the source of truth. This Grok package is the active, fuller skill surface (GROK_PLUGIN_ROOT, camelCase hook JSON, run_terminal_command matcher, forge + CI skills).

Skills

Slash commands match skill names, e.g. /mercurial-basics, /isurus-forge.

Hook

hooks/block-git-in-hg.sh runs on every run_terminal_command / Bash tool call:

1. Command does not start with git → allow.
2. Bare git repo (HEAD + refs/ + objects/) → allow (import fixtures).
3. Closest VCS is .git/ → allow.
4. Closest VCS is .hg/ → deny with an hg equivalent suggestion.
5. No VCS context → allow.

Supports both Grok (toolInput.command) and Claude (tool_input.command) stdin envelopes. Emits {"decision":"deny","reason":"..."} on stdout and exit code 2.

Requires jq on PATH (fails open with a warning if missing).

Install

Option A — local path (recommended while developing)

grok plugin install /home/ctusa/repos/isurus-project/isurus-grok-plugin --trust
grok plugin enable isurus-hg

Or copy/link into the auto-trusted user plugins dir:

ln -sfn /home/ctusa/repos/isurus-project/isurus-grok-plugin ~/.grok/plugins/isurus-hg

Then enable in ~/.grok/config.toml:

[plugins]
enabled = ["isurus-hg"]

Option B — local marketplace

Parent marketplace index (example at repo root):

{
  "name": "leafscale-local",
  "owner": { "name": "Leafscale" },
  "plugins": [
    {
      "name": "isurus-hg",
      "description": "Mercurial + Isurus forge skills for Grok",
      "source": { "type": "local", "path": "./isurus-grok-plugin" }
    }
  ]
}

grok plugin marketplace add /path/to/isurus-project
grok plugin install isurus-hg --trust

Option C — config path

[plugins]
paths = ["/home/ctusa/repos/isurus-project/isurus-grok-plugin"]
enabled = ["isurus-hg"]

Reload plugins in the TUI (Ctrl+L → Plugins → r) or start a new session. Confirm with:

grok plugin details isurus-hg
grok inspect

Requirements

• Grok Build with plugins enabled
• Mercurial 6.0+ (7.x recommended) for the workflows the skills describe
• jq + Bash 4+ for the hook
• make check on the Isurus product needs PostgreSQL isurus-test (see isurus-conventions)

Development

cd isurus-grok-plugin

./scripts/check-skills.sh    # frontmatter + length
./hooks/test/run.sh          # hook unit tests
grok plugin validate .       # manifest / layout

# Manual scenarios
cat tests/MANUAL.md

Design notes: docs/superpowers/specs/2026-08-02-isurus-grok-plugin.md

Relationship to isurus-claude-plugin

isurus-claude-plugin is incomplete. Do not assume parity or copy from it as authoritative. Gaps on the Claude side include unfinished plan acceptance work, limited dogfooding, no forge/CI platform skills, and deferred phase-2 items (forge MCP, evolve/topics, evals, etc.).

If Claude support is needed later, port from this Grok plugin outward — not the other way around.

License

MIT — see LICENSE.