mappamind

Mappamind

Use this skill when a user wants Mappamind enabled for a repo/workspace, asks for the initial architecture map, wants an impact card for an AI coding agent session, asks to inspect what the agent changed, or explicitly invokes Mappamind.

Workflow

1. Check Mappamind status for the current git repo or parent workspace:

mappamind status "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" --json

2. If the command is missing, tell the user to install the CLI:

npm i -g mappamind-cli

3. If status reports baseline.state as missing or stale, ask the user before running the expensive initial map. After approval, run:

mappamind setup "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" --host claude --yes

If setup prints studio: file://..., include that URL in the response under Mappamind Studio.

Baselines are local to the repo/workspace path, not to each git branch. A branch checkout can make the stored baseline stale; shifts still compare the session-start snapshot to the session-end tree.

4. Before making code edits in a session, run:

mappamind snapshot "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

5. After meaningful code changes and before the final response, run:

mappamind shift "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

6. If the command prints card: file://..., include that URL in the final response under Mappamind card.

7. If the command folds the card, report the folded reason instead of inventing an impact.

8. If browser opening fails, still relay the file:// URL. The Studio is one self-contained app at .mappamind/index.html with four tabs (Studio, Shifts, Capabilities, Contracts) — no server, no scripts. A non-cosmetic shift card is written at .mappamind/shift/latest.html and archived per session at .mappamind/shift/<timestamp>.html; the Shifts tab links to every archived card.

Notes

• Platform-specific packages can bundle lifecycle hooks; users may need to review or trust those hooks in their agent.
• If status.hooks.warnings mentions duplicate Codex project hooks, tell the user to run mappamind hooks --remove --agent codex in the target root.
• Opening can be suppressed with MAPPAMIND_OPEN=0.
• Mappamind depends on the mappamind CLI being available on PATH.