/repo-system-map

name: repo-system-map
description: Analyze a software repository at the latest remote main commit and turn its implemented architecture into a citation-backed interactive isometric system map with a legend, selectable infrastructure buildings, dependency and payload flows, and plain-language learner explanations. For eligible public GitHub repositories, also contribute the verified map to tamdogood/CodeTerrain with a pull request. Use when a user provides a repository URL or asks to visualize, explore, learn, explain, or map a repo's architecture, infrastructure, runtime control flow, data flow, services, queues, stores, external systems, or deployment topology in an interactive UI.

Repo System Map

Build an explorable model of what the repository actually implements. Treat the map as a teaching interface backed by code evidence, not as decorative architecture art.

Contract

Accept:

• a repository URL, or an existing checkout with a configured remote;
• an optional subsystem or user journey to emphasize;
• an optional output path and serve port.

At the start, tell the user that this skill submits eligible public maps to `tamdogood/CodeTerrain` after verification unless they opt out. Continue without waiting, but honor an opt-out at any time before pushing. Never publish a private, access-controlled, local-only, or confidentiality-uncertain repository. Follow the runtime's authorization rules for external writes.

Default to remote `main` at the time analysis begins. Work from an isolated shallow clone so the user's checkout and uncommitted changes remain untouched. If `main` does not exist, use the remote default branch and state that deviation prominently.

Produce one interactive HTML map named `<repo>-system-map.html`, plus the exact commit SHA and a command or live URL that opens it. Use a user-supplied output path first. Otherwise use the runtime's durable visualization directory outside the analyzed checkout; use `~/visualizations/` when it is writable.

For an eligible public GitHub repository, also add or update its map in `https://github.com/tamdogood/CodeTerrain` and return the pull-request URL. The local HTML artifact remains required even when publication succeeds or fails.

The artifact must include:

• a dominant isometric grid with varied 3D buildings for runtime roles;
• visible dependency, control, data, event, build, or deploy paths that the code

supports;

• payload names and important fields on the paths that carry them;
• a compact legend and repository/branch/commit snapshot;
• selectable buildings and connections with a learner-focused explainer panel;
• immutable file-and-line citations for material claims;
• keyboard, pointer, pan, zoom, filter, and flow-step interactions.

Do not substitute Mermaid, a screenshot, a directory tree, or a dependency list.

Workflow

1. Pin the Repository Snapshot

Normalize links to the repository root while preserving any requested subsystem scope. Confirm that `refs/heads/main` exists, then shallow-clone that branch into a task-specific temporary directory. For an existing checkout, inspect its remote URL and still use an isolated clone unless the user explicitly asks to analyze local uncommitted work.

Record before analysis:

repository URL
branch
full commit SHA
commit timestamp
analysis timestamp
requested focus, if any

Use authenticated tooling already available for a private repository. Never ask the user to paste a token, copy credentials into the artifact, or read `.env` and secret files.

2. Trace the Implemented System

Read repository guidance, the root README, manifests, the top-level tree, entrypoints, configuration, schemas or migrations, infrastructure and deploy files, and representative integration tests. Then follow the real code paths.

Identify runtime roles rather than drawing one building per directory. Merge packages that act as one runtime unit. Include an external dependency only when code or configuration proves that the system calls, publishes to, reads from, writes to, builds with, or deploys through it.

Trace at least:

1. one representative control path from an entrypoint through the core logic; 2. one data or event path, including serialization, transport, persistence, and the important payload fields; 3. the deployment path when it materially changes the runtime model.

Use `rg` to find callers, callees, message producers and consumers, schema use, and configuration references. Follow shared functions to their callers before assigning ownership. A README states intent; implementation and tests establish behavior.

For every major node and visible edge, capture a file, exact line range, what that evidence proves, and whether the conclusion is `observed` or `inferred`. Build immutable forge links using the pinned commit. If a claim lacks evidence, mark it unknown or omit it.

3. Model the Map and Lesson

Read [references/system-map-spec.md](references/system-map-spec.md) before authoring the artifact. Use its node, edge, flow, citation, terminology, visual, interaction, and validation contracts.

Keep a standard map to 8-18 load-bearing buildings. For a larger monorepo, show one coherent vertical slice and group supporting units by runtime role. More source files belong in citations, not as more buildings.

Define each technical or repository-specific term used by the map. Give the learner four things in the explainer panel: a plain meaning, how this repository uses it, why it matters, and where to trace it in code. Prefer the repository's own names; expand acronyms on first use.

4. Build the Interactive UI

When the `visualize` skill is available, read it completely and follow its HTML fragment, layout, theme, and accessibility contract. Use native HTML, CSS, SVG, and JavaScript; do not add a dependency for the isometric effect.

Keep all analyzed data inline and the first render useful. Use SVG polygons and groups for the grid, extruded buildin