architecture-map

Builds an interactive isometric map of a repository's architecture with measured snapshots and staleness tiers.

Updated Sep 18, 2026
One-click install
npx skills add https://github.com/fern-works/greenline --skill architecture-map-fern-works
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-map
Source: https://github.com/fern-works/greenline/tree/main/corpus/skills/architecture-map
Command: npx skills add https://github.com/fern-works/greenline --skill architecture-map-fern-works

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Codebases grow faster than anyone can explain them, and architecture diagrams rot the moment code moves. This Skill turns a repository into a durable, versioned isometric map under .greenline/map/ where prose is authored by reading the code and counts, coverage, and geometry are measured by scanners, so the map stays honest as the code changes. ## Core Features & Use Cases - Authored-plus-measured map state: map.md holds groups, node prose, edges, flows, and coverage globs; snapshot.json holds measured file counts, line totals, the snapshot commit, and per-node prose provenance. - Self-contained viewer: a prebuilt HTML shell renders the map as an isometric city with animated flows tracing real call paths, requiring no build tooling, framework mounting, or server. - Staleness-aware updates: on re-runs it folds git diff through the coverage globs, reports a staleness tier (fresh, current, drifting, stale), re-reads only dirty nodes, and reuses unchanged prose byte-identical. - Use Case: A new engineer joins a team and asks how the repo fits together; the agent reads the code, authors subsystem prose, measures coverage, and produces architecture.html they can open and explore by playing real flows like sign-in or the main create/read loop. ## Quick Start Ask the agent to build an architecture map of this repository so you can see how the codebase fits together.

Frequently Asked Questions about architecture-map

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate an architecture diagram of my codebase?▼

Ask the agent to map the repository's architecture. It detects the framework and repo shape, runs a coverage proposer script, reads the actual code to author subsystem prose, measures file counts and lines, and renders a self-contained architecture.html viewer under .greenline/map/.

How do I keep an architecture map up to date as code changes?▼

Re-run the skill when .greenline/map/snapshot.json already exists. It folds git diff since the snapshot commit through the coverage globs, reports a staleness tier, re-reads only dirty nodes, and reuses unchanged prose byte-identical before regenerating the viewer.

Does the architecture map require React or a build step in my repo?▼

No. The viewer is a prebuilt, self-contained HTML shell shipped with the skill. Nothing is installed into the repository: no config file, no sync script, no package.json changes, and no framework mounting. Opening the generated file is the viewer.

What languages and repositories can be mapped?▼

The coverage proposer scans TypeScript, JavaScript, Python, Go, Ruby, Rust, Java, Kotlin, Swift, PHP, and C# sources in any repository. It works for monorepos and single packages, and past roughly 25 nodes it folds small siblings or maps one package at a time.

Why does the map show unmapped or unclaimed files?▼

Unclaimed files are source files no node's coverage globs claim, meaning the repo grew something the map has not been told about. Either widen an existing node's glob pattern or append a new node, then re-measure until the unclaimed list is empty.

What are the limitations of an isometric codebase map?▼

Past about 25 buildings the map stops being readable, so large repos should map one package at a time. Node prose is a first draft written by reading code in a single pass, and edges must trace to real calls in the source or they are omitted.