Repo System Map

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 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 buildings, paths, arrows, and payload markers. Let the map dominate. Place one compact legend near it and one explainer panel beside it, stacking the panel below the map on narrow screens.

Required interactions:

• select a building or connection to update the explainer and citations;
• hover or focus a building to emphasize its immediate incoming and outgoing paths without hiding its label;
• toggle relationship kinds from the legend;
• choose a named end-to-end flow and step forward or backward through it;
• drag to pan, use wheel or labeled controls to zoom, and reset the view;
• expose every pointer action through native keyboard-accessible controls;
• stop nonessential motion under prefers-reduced-motion.

Escape every repository-derived string. Insert labels with textContent, encode URLs, safely serialize inline data, and never place source text or secrets in the page. The artifact must not fetch data at runtime.

5. Render and Verify

Keep the editable fragment as the source when using the bundled visualization renderer. Locate the installed renderer instead of hard-coding its version:

REPO_MAP_RENDERER="$(find "${CODEX_HOME:-$HOME/.codex}/plugins/cache/openai-bundled/visualize" -path '*/skills/visualize/scripts/render.py' -print -quit)"
python3 "$REPO_MAP_RENDERER" /absolute/path/<repo>-system-map.html --serve --port 8765

If the user supplies a known renderer path, use it directly. If the renderer is unavailable, write a standalone HTML document and serve its directory with Python's standard http.server; do not remove interaction or return a static fallback.

Open the result and verify it at approximately 1024, 736, and 360 pixels wide. Exercise selection, legend filters, every flow step, pan, zoom, reset, citation display, keyboard use, and reduced motion. Check the console for errors and confirm that labels and the explainer never clip or overlap.

Before handoff, compare the pinned SHA with remote main again. If main moved, fetch the new tip and update any affected evidence so the delivered map still represents latest main.