sightmap plugin

Slash commands, skills, and curator subagents for keeping a .sightmap/ view inventory in sync with your codebase. Wraps @sightmap/mcp.

Ships per-harness manifests at the repo root so the same source tree installs into Claude Code, Codex, Cursor, and opencode.

Install (Claude Code)

From inside Claude Code:

/plugin marketplace add sightmap/plugin
/plugin install sightmap@sightmap

The first command registers this repo's .claude-plugin/marketplace.json; the second installs the sightmap plugin from it.

Install (other harnesses)

| Harness | Manifest | Status | |-----------|--------------------------------|-------------| | Claude Code | .claude-plugin/plugin.json | Supported | | Codex | .codex-plugin/plugin.json | Manifest in place; harness wiring in progress | | Cursor | .cursor-plugin/plugin.json | Manifest in place; harness wiring in progress | | opencode | .opencode/plugin.json | Manifest in place; harness wiring in progress |

Surface

Slash commands

• /sightmap:init — first-time scaffolding
• /sightmap:bootstrap — seed .sightmap/ from an existing codebase
• /sightmap:audit — six-dimension audit of the current inventory
• /sightmap:explain — narrate what a view does
• /sightmap:fix — apply patches (confirm-first; --apply to auto-apply)
• /sightmap:reflect — end-of-turn nudge to fold the agent's just-completed source edits back into .sightmap/ (description/memory only)

Skills

audit/, bootstrap/, explain/, fix/, init/, reflect/ under skills/.

Subagents

• sightmap-auditor — read-only; runs the six-dimension audit
• sightmap-assistant — write-capable curator with full authority over every view field (structural + semantic). Adds, updates, and deletes views via the mcp__sightmap__* curation tools, and proposes audit-driven fix patches.

Hooks (Claude Code)

| Role | Script | When | |--------------|---------------------------------|-----------------------------------------------| | SessionStart | bin/session-start.sh | Once per session, unconditional | | PreToolUse | bin/pre-tool-use-advisory.sh | Before Write/Edit on .sightmap/** | | PostToolUse | bin/post-tool-use-validate.sh | After Write/Edit/MultiEdit on .sightmap/** | | Stop | bin/stop-summary.sh | End of turn; nudges /sightmap:reflect when the agent touched component sources |

All four are advisory — they print to stderr/stdout but never block the user's edits.

MCP compatibility

This plugin invokes tools provided by @sightmap/mcp. The compatibleMcpVersion field in each per-harness plugin.json declares the MCP semver range this version expects (currently ^0.8.0). The hooks shell out to npx --no-install sightmap by default; override with SIGHTMAP_BIN to pin a binary path.

Development

git clone --recurse-submodules https://github.com/sightmap/plugin.git
cd plugin
pnpm test   # or: bats test/*.bats test/unit/ test/integration/

Tests require bats-core (brew install bats-core on macOS, apt-get install bats jq on Debian/Ubuntu) and jq. bats-support and bats-assert ship as git submodules under test/helpers/.

The hook scripts and tests honour SIGHTMAP_BIN for pinning the sightmap CLI — defaults to npx --no-install sightmap.