Skip to content
Skills Library
Programming · Learning & explanation

project-map

/project-map

[Orbit 3.1.1 Maps & diagrams] Interactive project map in one HTML: phases, steps in reading order, transitions, links to code. Use when: «карта проекта», «схема проекта», «как устроено», «интерактивная карта репозитория», «покажи как устроен проект»; project map, how the project works.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
22
Scripts
13
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 13 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/build.py, assets/project-data.starter.js, assets/project-data.starter.ru.js, assets/project-schema.js, assets/project-view.js, example-ru/build.py, example-ru/project-data.js, example-ru/project-schema.js, example-ru/project-view.js, example/build.py, example/project-data.js, example/project-schema.js, example/project-view.js

What it does and when to use it

[Orbit 3.1.1 Maps & diagrams] Interactive project map in one HTML: phases, steps in reading order, transitions, links to code. Use when: «карта проекта», «схема проекта», «как устроено», «интерактивная карта репозитория», «покажи как устроен проект»; project map, how the project works.

Original author description

[Orbit 3.1.1 Maps & diagrams] Interactive project map in one HTML: phases, steps in reading order, transitions, links to code. Use when: «карта проекта», «схема проекта», «как устроено», «интерактивная карта репозитория», «покажи как устроен проект»; project map, how the project works.

How it works

  1. When to use
  2. Inputs
  3. Procedure
  4. Output
  5. Check
  6. Example
  7. Pitfalls
  8. Portability
  9. What's improved vs the source
  10. Based on
Original SKILL.md headings · 157 lines, 1,321 words
SKILL.md preview
---
name: project-map
description: '[Orbit 3.1.1 Maps & diagrams] Interactive project map in one HTML: phases, steps in reading order, transitions, links to code. Use when: «карта проекта», «схема проекта», «как устроено», «интерактивная карта репозитория», «покажи как устроен проект»; project map, how the project works.'
---

# project-map — interactive project map

> **Orbit · ③ Operate · step 3.1.1 Maps & diagrams**  
> **Input:** graph / project knowledge ← `ship-k8s`  
> **Output:** `docs/project-map/project.html` → next `project-diagram`  
> **Works with:** `map-knowledge`, `run-spec-loop`, `onboard-people`  
> **Shared rules:** reply in the user's language per `speak-plain`; generated content defaults to English; stay in scope; artifacts go to `.orbit/` (contract: `ARTIFACTS.md` at the pack root).

Builds one standalone `project.html`:

- schema on top: blocks, phase bands ①②③, arrows with **step numbers in reading order**, highlighted transitions, routed-around backward links;
- below: step-by-step scenarios, tables, modules, links to files on GitHub or GitLab;
- clicking a block, chip or number opens a card with details and code links.

No external dependencies; opens with a double click and publishes as a static page (GitHub Pages, GitLab Pages, any web server). Text is in the audience's language; for a **static picture** use `project-diagram`.

## When to use

- Explain how a project works to a person: onboarding, hand-over, demo.
- Show a process by phases and steps: pipeline, lifecycle, end-to-end scenario.
- Show integrations between repositories and where in code each link lives.
- Keep "how it really works" next to the code and update it with the code.
- Not for a slide image (`project-diagram`) or a logo stack (`draw-stack`).

## Inputs

- `.orbit/knowledge/graph.json` and `.orbit/knowledge/overview.md` — best from `map-knowledge`; no sources — `reverse-app`;
- `.orbit/task/<id>/plan.md` — the scope the map must show;
- `assets/project-data.starter.js`, `references/authoring-guide.md`, live `example/project.html`;
- the repo: every block and link needs a real file.

If the graph is missing, run `map-knowledge` or build the block list from the repo and mark unverified facts as hypotheses.

### Language

Default: **English** — UI (`META.lang = "en"`: tabs, labels, cards) and all data texts. Start from `assets/project-data.starter.js`; live example — `example/`. Another language only if the user asks or the repo's docs use it: set `META.lang` to `"en"` or `"ru"` and write data texts in it (both starters and both examples ship with the skill).

### Files

| File | Contents | Edited |
|---|---|---|
| `project-data.js` | `META`, `N` blocks, `E` links, `CHIP`, `KIND`, `LAYOUT`, `PAGES` | **yes — the only one** |
| `project-schema.js` | auto-layout, routing, step numbers | no |
| `project-view.js` | tabs, block view, cards | no |
| `project.template.html` | styles and skeleton | no |
| `build.py` | inlines everything into one `project.html` | no |

No coordinates: the engine computes sizes, wrapping, rows, bands, arrow routes and numbers, so blocks never overlap, text stays in its box, and arrows never cut through blocks.

## Procedure

1. **Facts from code, not memory.** Read the repo (`map-knowledge` gives a graph with evidence; no sources — `reverse-app`). Per block: what it is, how it works (3–6 points), files. Per link: what flows and where.
2. **Copy the engine** from `assets/` into `docs/project-map/` (`project.template.html`, `project-schema.js`, `project-view.js`, `build.py`); base `project-data.js` on `project-data.starter.js`.
3. **Fill `project-data.js`** per the model below.
4. **Order in `LAYOUT`:** `top` — the entry; `bands` — phases top to bottom; inside a band, blocks in step order left to right.
5. **Sections in `PAGES`:** step-by-step scenarios (`flow`), tables, modules (`mod`), limitations.
6. **Build:** `python3 build.py [dir]`; fill `REPO_ROOTS` to verify linked paths.
7. **Look at it.** Open `project.html`, click blocks and arrows, switch to "Block view". Console errors (`LAYOUT: нет блока…`, `E: нет блока для связи…`) mean a key mismatch.
8. **Publish:** commit the sources and `project.html` together so the page never drifts from its data.
9. **Keep it alive.** Regenerate it in the same change as the code (`run-spec-loop`); a map updated "later" lies.

### Steps, phases and transitions — how the map reads

- **Phases.** Each band gets ①②③ (off: `LAYOUT.options.numberBands = false`).
- **Steps.** Numbers follow reading order: entry → phase ① left to right → transition ①→② → phase ② → … The number is identical on the schema, in the block view, the link list and the card.
- **Transition** — thick line, ringed number, bold label, tagged "переход ① → ②".
- **Backward link** (next loop, rework) — right corridor; in the block view dashed along the bottom; tagged "возврат".
- **Custom order:** `LAYOUT.steps = [E indices…]`.

### Data model `project-data.js`

```js
const GL = "https://github.com";                 // link base; GitLab works too
const REPO = { app: ["your-org/app", "main"] };  // alias -> [repository, branch]

// Block: [title, caption, what, [how], [[repo,path]], [[chip,label]]]
const N = {
  ui:  ["Web UI", "React · SPA", "Operator interface.", ["Routes — <code>src/routes.tsx</code>."], [["app", "web/src/"]]],
  api: ["API", "Go · HTTP", "Takes requests.", ["Entry — <code>cmd/api/main.go</code>."], [["app", "cmd/api/main.go"]], [["h", "Handlers"]]],
  db:  ["PostgreSQL", "store", "Orders and users.", [], [["app", "migrations/"]]],
};
const CHIP = { h: ["Handlers", ["Validation."], [["app", "internal/http/"]]] };

// Link: [from, to, kind, title, summary, [how], [[repo,path]]]
const E = [["ui", "api", "ctrl", "UI → API", "REST /api/v1", [], [["app", "web/src/api.ts"]]]];
const KIND = { ctrl: ["#6f8fc9", "requests"], data: ["#7aa36f", "data"] };   // 3–5 kinds

const LAYOUT = { top: ["ui"], bands: [["Server", "", ["api"]], ["Data", "", ["db"]]], labels: { 0: "REST" } };
const META = { title: "How App works", kicker: "App · project map" };
const PAGES = () => [["flows", "Flows", "What happens", "", flow([["User clicks Buy", "web/src/cart.tsx"]])]];
```

Text rules: one idea per point; exact names and paths in `<code>`; never show secrets (only the fact they exist). Details — `references/authoring-guide.md`; example — `example/project.html`.

## Output

`docs/project-map/project.html` plus five source files; sources are edited, HTML is generated.

```text
docs/project-map/
  project-data.js        # the only file you edit
  project-schema.js      # engine
  project-view.js        # engine
  project.template.html  # styles and skeleton
  build.py               # inliner + optional link check
  project.html           # build output, committed with the sources
```

## Check

```bash
cd docs/project-map && python3 build.py          # "built: …/project.html"
test -f project.html
grep -n '<script src=' project.html              # nothing: all inlined
grep -c 'href="https://github.com' project.html  # > 0: code links exist
grep -niE 'password|secret|token|10\.[0-9]+\.[0-9]+\.[0-9]+' project.html
```

Pass rule: build exits 0, the HTML is self-contained, no console warnings; numbers run 1, 2, 3 without jumps; phases/layers follow the flow top-down; ≤ ~15 links; every link opens the right branch and file; ≥1 end-to-end scenario in `PAGES`; hypotheses marked; the security grep prints nothing.

## Example

The quickest run uses the shipped engine and example (`HOW-TO-DEMO.md` has the 5-minute version):

```bash
SKILL="${CLAUDE_PLUGIN_ROOT}/skills/project-map"
python3 "$SKILL/assets/build.py" "$SKILL/example"   # 1. shipped example builds
mkdir -p docs/project-map && cd docs/project-map    # 2. copy the engine
cp "$SKILL/assets/"{project.template.html,project-schema.js,project-view.js,build.py} .
cp "$SKILL/assets/project-data.starter.js" project-data.js
# 3. edit project-data.js: blocks N, links E, LAYOUT bands
python3 build.py && open project.html
```

## Pitfalls

- **Facts from memory.** The map then documents an imagined system. Write what the code shows; mark the rest as a hypothesis.
- **A block key that does not match.** Keys in `E` or `LAYOUT` missing from `N` are skipped with a console warning: the picture looks plausible but is incomplete.
- **Tangled arrows.** Reorder blocks in a band (linked ones adjacent) or layers (flow top-down); drop secondary links into a section below.
- **Too many `KIND`s or jumping numbers.** More than 3–5 colours is noise; set `LAYOUT.steps` when numbers have gaps.
- **Coordinates or an uncommitted source.** The engine owns layout. Commit `project-data.js` and `project.html` together or the page cannot be regenerated.

## Portability

A browser is the only runtime; the engine is plain JavaScript inlined by `build.py` — no network, no package manager, no subagents. Any agent can fill `project-data.js` and run `python3 build.py`. Without `python3`, serve the four files plus data directly. Slash commands are optional; "make an interactive map" triggers the same method.

## What's improved vs the source

- The engine lays out the schema itself: no coordinates, no overlapping blocks, no arrows through blocks.
- Step numbers in reading order, phase numbers ①②③, highlighted transitions and routed-around backward links.
- The map is built from the knowledge graph (`map-knowledge`) and updated in the `run-spec-loop` cycle.

## Based on

- Orbit's own skill.
Files in this package (22)
  • HOW-TO-DEMO.md 2 KB
  • HOW-TO-DEMO.ru.md 2 KB
  • SKILL.md 10 KB
  • assets/build.py 2 KB
  • assets/project-data.starter.js 3 KB
  • assets/project-data.starter.ru.js 5 KB
  • assets/project-schema.js 24 KB
  • assets/project-view.js 13 KB
  • assets/project.template.html 11 KB
  • example/build.py 2 KB
  • example/project-data.js 7 KB
  • example/project-schema.js 24 KB
  • example/project-view.js 13 KB
  • example/project.html 55 KB
  • example/project.template.html 11 KB
  • example-ru/build.py 2 KB
  • example-ru/project-data.js 10 KB
  • example-ru/project-schema.js 24 KB
  • example-ru/project-view.js 13 KB
  • example-ru/project.html 58 KB
  • example-ru/project.template.html 11 KB
  • references/authoring-guide.md 7 KB

Versions

RepositoryScoreLicence
This page · tojim00d/Orbit-skills100MIT
mgionas/ai-dev-guild100MIT
perweum/project-map100MIT

Database snapshot: 13.11.2026 · package version 46c3253d7930 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100interactive-map
    Builds an interactive system map (components, connections, animated flows, build order and a guided tour) and delivers it as a single self-contained HTML file that opens offline from file://, with no server. Use when the user asks to map, diagram or explain how a system or a…
  • 100map-knowledge
    [Orbit 1.2.1 Code recon] Knowledge graph of the codebase: modules and links with file:line evidence + system overview. Use when: «разберись в репозитории», «как устроен проект», «граф знаний», «построй карту кода», «с чего начать в чужом коде»; understand codebase, knowledge graph.
  • 100survey-codebase
    [Orbit 1.2.3 Code recon] Codebase state in 7 documents: stack, integrations, architecture, structure, conventions, tests, concerns. Use when: «оцени кодовую базу», «состояние проекта», «техдолг и стек», «проведи аудит репозитория», «что тут происходит»; codebase audit, map codebase.
  • 100pr-map
    Turn a GitHub pull request into an interactive review map with AI insights, reviewed in the browser. Use when the user asks to review, map, or visualize a PR.
  • 100interactive-map-repo
    Explains how a code repository works as an interactive C4-style map (system context, then containers and their key components, with animated request and data flows). Use when the user asks to map, explain or onboard onto a repository, a service or a codebase. Builds on the…
  • 100impact-map
    Use when the user asks for a map of their project, what depends on what, what would be affected or break if they change or delete something, or what permissions they have given Claude Code ("خريطة الأثر", "شو بيتأثر لو حذفت", "impact map", "what breaks if"). Builds a local HTML…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.