understand-onboardWrites an onboarding guide for someone joining a codebase, built from the knowledge graph of the Understand-Anything plugin and checked against the repository: how to run the project, a map of its layers, a reading route, the files everything depends on and the risky ones. Use when someone says "write an onboarding guide for this repo", "a new developer sta…
Independent GitHub snapshot · Automated classification · Original documentation governs
Understand-Anything is an open-source plugin for coding agents. Its /understand command analyses a repository and saves a knowledge graph as JSON: every file with a summary, the relationships between them, a grouping into architectural layers and an ordered tour. /understand-onboard turns that graph into a document a newcomer can follow.
A graph dump is not an onboarding guide. A person who starts on Monday needs to get the project running, know which five files matter, read them in a sensible order and learn where not to make a first change. This skill generates the factual skeleton from the graph with a script, then adds what the graph does not contain (setup commands, first tasks, team conventions) from the repository itself, and verifies every path and command before the file is saved.
Graph content the guide is built from:
| In the graph | Becomes in the guide |
|---|---|
project: name, description, languages, frameworks, gitCommitHash, analyzedAt | the opening paragraph and the provenance line |
layers[]: name, description, nodeIds | the map, one table per layer |
tour[]: order, title, description, nodeIds, languageLesson | the reading route |
nodes[]: type, filePath, summary, complexity, tags | table rows, the risk list, the vocabulary |
edges[]: imports, calls, tested_by and others | entry points, the most depended-on files, missing tests |
If the project has no graph, install the plugin (Claude Code: /plugin marketplace add Egonex-AI/Understand-Anything, then /plugin install understand-anything) and run /understand; the understand-chat skill covers other hosts and the analysis options.
Ask at most three questions, and skip any the request already answers:
docs/UA_ONBOARDING.md; use that unless the team has a docs convention.Look for what already exists before writing anything: ls README* CONTRIBUTING* docs/ 2>/dev/null. An existing setup section is linked, not copied, and an existing onboarding file is updated in place.
G=.ua/knowledge-graph.json
[ -d .understand-anything ] && G=.understand-anything/knowledge-graph.json
jq -r '"\(.project.name): \(.nodes | length) nodes, \(.layers | length) layers, \(.tour | length) tour steps, kind \(.kind // "codebase")"' "$G"
SHA=$(jq -r '.project.gitCommitHash' "$G")
git rev-parse --verify --quiet "$SHA^{commit}" >/dev/null &&
git diff --name-only "$SHA" HEAD -- . ':(exclude).ua' ':(exclude).understand-anything' | wc -l
| Finding | Decision |
|---|---|
| no graph file | stop; the project needs /understand first (in a git worktree, look in the main checkout) |
kind is knowledge or design | wrong input: this guide needs a codebase graph |
| zero layers or zero tour steps | the analysis did not finish; ask for /understand --full |
| 0 changed files | proceed |
| a few changed files, none in the map's key files | proceed and put the count in the provenance line |
| many changed files, or new top-level folders | ask for an incremental /understand first; a guide that sends a newcomer to deleted files costs more than it saves |
| the hash does not resolve | proceed, and rely on step 5 to catch dead paths |
Save as ua-onboard.mjs in a scratch folder. The second argument limits the rows per layer (default 10), keeping the most depended-on files.
import { readFileSync } from "node:fs";
const g = JSON.parse(readFileSync(process.argv[2], "utf8"));
const perLayer = Number(process.argv[3] ?? 10);
const byId = new Map(g.nodes.map((n) => [n.id, n]));
const path = (id) => byId.get(id)?.filePath;
const TOP = new Set(["file", "config", "document", "service", "pipeline", "table", "schema", "resource", "endpoint"]);
const row = (...cells) => `| ${cells.map((c) => String(c).replace(/\|/g, "\\|").replace(/\s+/g, " ")).join(" | ")} |`;
// Usage counted per file, so that function-level edges roll up to the file they live in.
const USES = new Set(["imports", "calls", "depends_on", "inherits", "implements", "reads_from", "writes_to"]);
const usedBy = new Map(), usesOthers = new Set();
for (const e of g.edges) {
const from = path(e.source), to = path(e.target);
if (!USES.has(e.type) || !from || !to || from === to) continue;
usedBy.set(to, (usedBy.get(to) ?? new Set()).add(from));
usesOthers.add(from);
}
const fanIn = (f) => usedBy.get(f)?.size ?? 0;
const testEdges = g.edges.filter((e) => e.type === "tested_by");
const tests = new Set(testEdges.map((e) => path(e.target)));
const covered = new Set(testEdges.map((e) => path(e.source)));
const p = g.project, out = [];
out.push(`# Getting started with ${p.name}`, "", p.description, "", `Stack: ${[...p.languages, ...p.frameworks].join(", ")}.`,
"", "## Run it on day one", "", "(to be filled in step 4)", "", "## The map", "");
for (const l of g.layers) {
const members = l.nodeIds.map((id) => byId.get(id)).filter((n) => n && TOP.has(n.type))
.sort((a, b) => fanIn(b.filePath) - fanIn(a.filePath));
out.push(`### ${l.name}`, "", l.description, "", row("Path", "What it does", "Complexity"), row("---", "---", "---"));
for (const n of members.slice(0, perLayer))
out.push(row(`\`${n.filePath ?? n.name}\`${n.lineRange ? ` (${n.name})` : ""}`, n.summary, n.complexity));
if (members.length > perLayer) out.push("", `Plus ${members.length - perLayer} less connected files.`);
out.push("");
}
out.push("## Reading route", "");
for (const s of [...g.tour].sort((a, b) => a.order - b.order)) {
const files = [...new Set(s.nodeIds.map(path).filter(Boolean))].map((f) => `\`${f}\``).join(", ");
out.push(`${s.order}. **${s.title}**. ${s.description} Open: ${files}.${s.languageLesson ? ` Language note: ${s.languageLesson}` : ""}`);
}
out.push("", "## Where execution starts", "");
for (const n of g.nodes.filter((n) => n.type === "file" && !tests.has(n.filePath) && usesOthers.has(n.filePath) && !fanIn(n.filePath)))
out.push(`- \`${n.filePath}\`: ${n.summary}`);
out.push("", "## Files the rest leans on", "", row("Path", "Used by", "Linked test"), row("---", "---", "---"));
for (const [f, users] of [...usedBy].sort((a, b) => b[1].size - a[1].size).slice(0, 8))
out.push(row(`\`${f}\``, `${users.size} file(s)`, covered.has(f) ? "yes" : "none"));
out.push("", "## Handle with care", "");
for (const n of g.nodes.filter((n) => n.complexity === "complex"))
out.push(`- \`${n.filePath}\`${n.lineRange ? ` lines ${n.lineRange.join("-")}` : ""} (${n.type} ${n.name}): ${n.summary}${covered.has(n.filePath) ? "" : " No test is linked to this file."}`);
const tags = new Map();
for (const n of g.nodes) for (const t of n.tags) if (t !== "tested") tags.set(t, (tags.get(t) ?? 0) + 1);
out.push("", "## Vocabulary", "", [...tags].sort((a, b) => b[1] - a[1]).slice(0, 12).map(([t, c]) => `${t} (${c})`).join(", "),
"", "---", `Generated from the knowledge graph of commit ${p.gitCommitHash.slice(0, 7)}, analysed ${p.analyzedAt.slice(0, 10)}.`);
console.log(out.join("\n"));
mkdir -p docs && node ua-onboard.mjs "$G" 10 > docs/UA_ONBOARDING.md
What each generated section means, and how far to trust it:
| Section | Derived from | Caveat |
|---|---|---|
| The map | layers, file-level nodes ordered by how many files use them | layer names and assignments are the analysing model's reading of the project |
| Reading route | the tour, in order | written for a general reader; reorder for the newcomer's first task |
| Where execution starts | code files that use others and are used by none | also lists dead code and scripts; confirm each against the manifest's start command |
| Files the rest leans on | incoming imports, calls and similar edges, counted per file | a change here is felt widely; a good place to read, a bad place for a first pull request |
| Handle with care | nodes whose complexity is complex, plus the absence of a tested_by edge | complexity is a three-level label, not a measurement |
| Vocabulary | most frequent tags | a word list only; the definitions are written in step 4 |
Fill these from the repository, reading the files and not guessing:
jq -r '.scripts | to_entries[] | "\(.key)\t\(.value)"' package.json, or the targets of a Makefile, pyproject.toml, Cargo.toml. Give them in the order install, configure, migrate, start, test, each with what success looks like (a port, a passing count). Name the environment variables the code reads and where a newcomer gets their values. Never copy values out of .env files.simple, tested file.simple complexity. Bad candidates are everything under "Handle with care".Then edit the generated parts for the reader from step 1: move the layer they will work in to the top, cut rows a newcomer will not open in the first month, and rewrite summaries that read like file listings.
D=docs/UA_ONBOARDING.md
grep -o '`[^` ]*[/.][^` ]*`' "$D" | tr -d '`' | sort -u | while read -r f; do [ -e "$f" ] || echo "missing: $f"; done
wc -l "$D"
Report the file path, its length, which sections came from the graph and which from the repository, anything that could not be verified, and the graph commit it is based on. Suggest committing the guide, and name the refresh rule: regenerate after an /understand run that follows a structural change (new layer, moved folders, a replaced framework), and rerun the path check from step 5 in between. Mention /understand-dashboard as the companion for the first day: its Start Tour button walks the same route visually.
clinic-bookingRequest: "Tomás starts Monday on the booking API, he knows TypeScript but not Fastify. Write him an onboarding guide." Step 2 prints clinic-booking: 25 nodes, 4 layers, 4 tour steps, kind codebase and 0 changed files. The script produces 90 lines, among them:
## Where execution starts
- `src/server.ts`: Creates the Fastify app, registers the slot and appointment routes and listens on the configured port.
## Files the rest leans on
| Path | Used by | Linked test |
| --- | --- | --- |
| `src/config.ts` | 4 file(s) | none |
| `src/services/scheduler.ts` | 3 file(s) | yes |
| `src/lib/time.ts` | 2 file(s) | none |
| `src/db/appointments-repo.ts` | 2 file(s) | none |
## Handle with care
- `src/services/scheduler.ts` (file scheduler.ts): Core booking rules: computes free slots, books one with a conflict check, cancels a booking.
- `src/services/scheduler.ts` lines 23-31 (function bookSlot): Re-checks availability, inserts the appointment and queues its reminder.
The agent then writes the parts the graph cannot supply. package.json has three scripts (dev, test, migrate), and the CI workflow runs npm ci and npm test on Node.js 22, so the first section becomes:
## Run it on day one
1. `npm ci` (Node.js 22, the version CI uses)
2. Set `DATABASE_URL` to a local PostgreSQL database; `src/config.ts` falls back to `postgres://localhost:5432/clinic`
3. `npm run migrate` creates the two tables from `src/db/schema.sql`
4. `npm run dev` starts the API on port 4010; `curl "http://127.0.0.1:4010/slots?practitioner=9b2f6c1e-4d7a-4e0b-8a53-1c2d3e4f5a6b&day=2026-10-05"` returns a `slots` array
5. `npm test` runs one Vitest file; it mocks the database, so it passes without PostgreSQL
## First tasks
- Add a test for `overlaps` in `src/lib/time.ts`: small, pure, used by two files and currently has no test.
- Not yet: anything in `bookSlot`. It checks availability and inserts without a transaction; ask before changing it.
Because Tomás is new to Fastify, the tour's language note on route generics stays in step 2 of the reading route. The path check prints nothing. The final file is 128 lines.
freightline has 1,900 files; the graph in services/dispatch/.ua/ covers that one service and step 2 counts 37 files changed since the analysis, including a new src/pricing/ folder. The agent does not generate anything yet. It explains that the map would miss the pricing module, asks for an incremental /understand services/dispatch, and after that run generates the skeleton from inside services/dispatch with a row limit of 6 per layer. The result names nine layers; the agent orders them by the newcomer's assignment (routing first) and moves the four infrastructure layers to a closing "you will not need these in month one" list.
A product manager wants to understand how the system is put together. The developer guide is the wrong artefact. The agent writes one page from project.description, the layer names with their descriptions, and the tour titles, with no file tables and no setup, and points to the dashboard's Overview mode, which hides functions and classes.
tested_by edge from that file. Tests that reach code indirectly, or live outside the analysed folder, are not counted. Phrase it as a prompt to check, not as a coverage figure./understand --language). Generate the guide in the same language, or have the graph rebuilt in the one the team reads./understand-explain for a specific file, existing architecture documents) instead of inlining it.