spine

spine turns an unfamiliar repository into a verified onboarding guide.

spine terminal demo

In one run it gives you:

a small architecture diagram built from verified static-analysis edges only
a prioritized reading order for the files that matter first
a short mental model, subsystem summary, and gotchas
a shareable mermaid.live link

If you open a repo and think "where do I even start?", spine is for that moment.

Why it exists

Most onboarding docs are stale, too broad, or guessed. spine takes a narrower approach:

it detects likely entry points
it extracts a small verified spine from real source relationships
it refuses to invent edges it cannot prove
it turns that verified structure into a readable tour

That makes it useful both for humans and for Claude Code.

What you get

`/map`

Use /map when you want the fastest deterministic preview.

no synthesis step
no ONBOARDING.md
just the validated Mermaid graph and mermaid.live link

`/onboard`

Use /onboard when you want the full guide.

ONBOARDING.md
verified architecture map
reading order
mental model
subsystem summaries
gotchas
estimated read time

Quick start

Install from npm

npm install -g @spine-io/onboard

Then run:

onboard .

Or for the map only:

onboard . --map-only

Run from source

npm install
npm run onboard -- .

For the deterministic map-only path:

npm run map -- .

Use with Claude Code

The v1 Claude Code distribution lives in .claude-plugin/skills/:

.claude-plugin/skills/onboard/ for /onboard
.claude-plugin/skills/map/ for /map

The intended flow is:

Run /map for a fast, token-free architecture preview.
Run /onboard when you want the full reading tour.
Let spine refresh .claude/REPO_CONTEXT.md so later Claude sessions inherit repo context.

Why this is useful for Claude Code users:

spine can write .claude/REPO_CONTEXT.md when you opt in with --write-context-file
that file captures a compact verified snapshot of the repo
later Claude sessions can start more grounded instead of re-discovering the same project shape from scratch
the built-in Anthropic path supports prompt caching and cost reporting for repeated runs

If you are not using Claude Code skills yet, the CLI gives the same core output:

onboard .
onboard . --map-only

Best first demo

Start with axios.

Why axios is the best launch benchmark:

the repo is well known, so the output is easy to judge
the architecture is real but still compact
the verified spine is small enough to understand at a glance
the before/after value shows up quickly

Use the built-in benchmark catalog:

npm run benchmark:list
npm run benchmark:clone -- axios
npm run onboard -- benchmarks/repos/axios

Other strong follow-up demos:

glow for a clean Go CLI story
poetry for a larger Python codebase
log for a compact Rust library

Example output

Typical ONBOARDING.md sections:

TL;DR
Architecture map
Mental model
Reading order
Entry points found
Subsystems
Gotchas
Estimated read time

Typical CLI output:

Detected library in javascript.
Found 1 entry point(s).
Synthesis source: deterministic.
Wrote ONBOARDING.md
Estimated cost: ~$0.008 input + ~$0.010 output = ~$0.018
This tour covers 7 spine file(s) and 4 subsystems.
Estimated savings: ~3.5 hours of manual exploration for ~$0.02 of LLM cost.

Commands

npm run onboard -- .                         # full guide
npm run map -- .                             # map only
npm run onboard -- . --prompt-out prompt.txt
npm run onboard -- . --synthesis-input .onboard-response.json
npm run onboard -- . --synthesis-command "your-command-here"
npm run onboard -- . --cost-model sonnet-4.6
npm run onboard -- . --diff-against ONBOARDING.md
npm run onboard -- . --dry-run
npm run onboard -- . --write-context-file

The built CLI also supports:

onboard . --out custom-onboarding.md
onboard . --map-only --out architecture.mmd
onboard --help
onboard . --dry-run
onboard . --write-context-file

Supported languages

Current verified spine coverage includes:

TypeScript / JavaScript
Python
Go
Rust
PHP

Product rules

verified edges only
one small diagram, not a giant graph dump
if Mermaid validation fails twice, the diagram is omitted
the synthesis layer may summarize verified structure, but may not invent architecture

Benchmarks and launch assets

benchmark catalog: src/benchmarks/catalog.ts
before/after examples: docs/before-after.md
launch blog draft: docs/blog-v1.md
media prompts: docs/media-prompts.md
launch cover image: assets/spine-cover.png
launch storyboard: assets/spine-storyboard.png
static hero image: assets/spine-hero.png

Development

npm run check
npm run test
npm run build

npm run onboard and npm run map execute the built CLI so the release path and local path stay aligned.

Contributing and testing

Contributions and real-repo testing are very welcome.

open a bug report if spine finds the wrong entry points or produces misleading output
open repo test feedback if you try spine on a real codebase and want to share what matched reality and what did not
open a PR if you want to improve detection, docs, benchmarks, or output quality

Start here: