---
name: harness-map
description: Generate an interactive, self-contained HTML dependency map of a repository's AI harness — skills, slash commands, agents, and MCP servers, with typed evidence-backed edges showing which skills hand off to which, what delegates to which agents, and what uses which MCP servers. Use when the user asks to map, visualize, diagram, or audit their agent harness, skills, subagents, or MCP setup. Works on any repo with .claude/, skills/, or .mcp.json surfaces. Output is a single offline HTML file.
---

# Harness Map

Generate `harness-map.html` for the current repository in four phases. Phases 1, 3, and 4
are exact script invocations — do not improvise them. Phase 2 is your judgment work.

Working directory for intermediate files: `harness-map-work/` in the target repo root
(git-ignore it or delete it afterwards; only `harness-map.html` is the deliverable).

## Phase 1 — Scan (deterministic)

    node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs --repo . --out harness-map-work

This discovers skills (both `<name>/SKILL.md` and flat `<name>.md` layouts), slash commands
(folded into same-named skills), agents, and `.mcp.json` servers, with git history and
contributors. It writes `harness-map-work/scan.json` containing `nodes` (facts) and
`readList` (every file you must read in Phase 2).

If it reports 0 nodes, stop and tell the user no harness surfaces were found.

## Phase 2 — Infer edges (your judgment)

Read `harness-map-work/scan.json`, then read EVERY file in `readList` — no sampling.
For repos with many files, dispatch parallel subagents over slices of `readList`; give each
subagent the node id list and the edge rules below, and merge their outputs.

Produce `harness-map-work/graph.json`: a copy of scan.json's `schemaVersion`, `meta`, and
`nodes`, minus `readList`, with your additions:

1. **`summary`** on every node — one sentence, ≤120 chars, stating what it does. Ground it
   in the file body, not the name.
2. **`cluster`** on nodes that form an obvious functional group (optional; omit when unsure).
3. **`edges`** — typed relationships per `references/edge-taxonomy.md`. For every edge:
   - You MUST be able to quote the line that justifies it; put that file's repo-relative
     path in `evidence`.
   - Look for: skill names after `/`, `Skill(...)` invocations, "run X", "use the X skill",
     agent names in delegation phrasing, `mcp__<server>__` tool prefixes, MCP server names.
   - Do NOT emit an edge because two things sound related. No evidence, no edge.
4. **`clusters`** array — leave `[]` unless the user asked for cluster grouping.

Schema contract: `references/schema.md`. Do not author `stats`, `edgeTypes`, or `positions`. `clusters` you declare are auto-reconciled by the build — any `cluster` value you set on a node is safe even if you don't list it in `clusters`.

## Phase 3 — Validate (deterministic, fail-closed)

    node ${CLAUDE_SKILL_DIR}/scripts/validate.mjs --graph harness-map-work/graph.json --repo .

On errors: fix `graph.json` and re-run. Loop until it prints `OK`. Never skip this.

## Phase 4 — Build (deterministic)

    node ${CLAUDE_SKILL_DIR}/scripts/build.mjs --graph harness-map-work/graph.json --out harness-map.html

## Report

Tell the user: node/edge counts by kind, the output path, and 2–3 notable findings from the
map (e.g. orphan skills with no edges, the most-depended-on agent, unused MCP servers).
Offer to open it: `open harness-map.html`.