# 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

Until the plugin is published to a marketplace, install via a path entry in `~/.claude/settings.json`:

```json
{
  "plugins": {
    "isurus-hg": {
      "path": "/absolute/path/to/isurus-claude-plugin"
    }
  }
}
```

Then restart Claude Code. The skills become available; 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+.

## 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`.

## Development

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

```sh
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](LICENSE).