---
name: hv-map
description: Maintain the project map of subsystems under .hv/map/. Modes — first-run (scaffold), after-work (update touched subsystems), consolidate (merge stale/duplicate entries). Auto-invoked post-cycle by /hv-work, /hv-debug, /hv-go; run manually for first-run and consolidation.
user-invocable: true
---

# /hv-map — project map orchestrator

Subsystems are AI-curated narratives describing one coherent area of the project. The system has three layers (see spec `docs/superpowers/specs/2026-05-09-context-scaling-map-design.md`):

1. **Map artifacts** — `.hv/MAP.md` + `.hv/map/<name>.md` detail files with frontmatter (`subsystem`, `summary`, `touched`, `created`, `related-topics`, `related-items`).
2. **Always-on index** — `## Project Map` managed block in CLAUDE.md, regenerated by `bin/hv-map-index`.
3. **Hygiene** — staleness flags via `hv-staleness`, soft-cap warnings, manual consolidation.

## Modes

`/hv-map` and `/hv-docs` share the three-mode skeleton (scaffold / after-work / audit) and intentionally diverge on artifact root, gate strength, and authoring tier — see `references/three-mode-skill-shape.md`.

### Mode: first-run

Run when `.hv/map/` is empty.

1. Inspect: directory structure (`ls -d */`), top-level commands (`bin/hv-*` and skill folders `hv-*/`), KNOWLEDGE topics (`hv-knowledge-query` over each topic name listed in `## Project Knowledge` of CLAUDE.md), recent commits (`git log --oneline -50`).
2. Propose 3–10 candidate subsystems with one-line summaries. Show them to the user; do not write yet.
3. On confirmation, create `.hv/map/<name>.md` for each, with frontmatter (`subsystem`, `summary`, `created` = today, `touched` = today) and the five body sections (Purpose, Entry points, Key files / dirs, Conventions specific here, Notes / gotchas) — populated from what was inspected. Leave any unknown section as a single placeholder line so future cycles fill it in.
4. Run `bin/hv-map-index` to regenerate the CLAUDE.md block.
5. Commit: `chore: scaffold project map (.hv/map/, ## Project Map block)`.

### Mode: after-work

Auto-invoked at the end of `/hv-work`, `/hv-debug`, `/hv-go` when the cycle's plan touched files belonging to one or more subsystems.

1. Determine touched subsystems. Match changed files (from the cycle's commits) against each subsystem's `Key files / dirs` and `Entry points`. If no existing subsystem fits and the project is under the soft cap (default 20 subsystems), ask the user whether to propose a new subsystem; default to "yes" with an inferred name.
2. For each touched subsystem: bump `touched:` to today; refresh `summary:` if the cycle's intent changed it; add new entry points where helpful; do not rewrite untouched sections.
3. Run `bin/hv-map-index`.
4. Stage the `.hv/map/<name>.md` updates as part of the cycle's final commit (do not create a separate commit — ride along with the work).

### Mode: consolidate

Run on demand when the user asks ("consolidate the map", "clean up subsystems", or after a soft-cap warning).

1. Read `bin/hv-map-stats` to find: stale entries (via `bin/hv-staleness map --days 90`), near-duplicates (any two summaries with cosine-similarity-by-shared-words ≥ 0.6 — fall back to substring overlap if too coarse), entries with `broken_refs ≥ 3`.
2. Propose, in order: merges (two subsystems → one, with a chosen target name), archives (rename to `.hv/map/_archive/<name>-YYYY-MM-DD.md`), and entry-point fixes.
3. Show the proposed changes; never auto-apply. On confirmation, perform them, run `bin/hv-map-index`, and commit: `chore: consolidate project map (<short reason>)`.
4. Apply the same review to KNOWLEDGE topics and TODO items: print suggestions ("topic X has 1 bullet from 8 months ago — fold into Y?", "TODO Z idle 90+ days — archive?"). Suggest only; do not edit those files in this skill.

## Soft caps

Default thresholds (override in `.hv/config.json`):

```json
{
  "map": {
    "softcap_subsystems": 20,
    "stale_days": 90
  }
}
```

The soft-cap nudge runs via `.hv/bin/hv-map-cap-check`, invoked from /hv-debug, /hv-go, /hv-work. It emits a one-line warning to stderr when `bin/hv-map-stats` reports subsystem count at or above `softcap_subsystems`. Never blocks.

## Failure modes

- Missing/corrupted detail file: helpers skip silently with stderr warning. Re-create or fix manually; the file lives in `.hv/map/`.
- Frontmatter `touched:` missing: hygiene falls back to git mtime.
- New subsystem proposal during `after-work` declined by user: cycle commits without the map update; the area stays uncovered until next time.

## References

- [`references/three-mode-skill-shape.md`](../references/three-mode-skill-shape.md) — Three-mode skill shape (first-run / after-work / restructure) used by `/hv-docs` and `/hv-map`.