---
name: onboarding-express
description: |
  AI-guided architectural tour of any codebase — entry points, business logic, and the most complex
  module in one structured pass, powered by Graph-It-Live. Use this skill whenever someone is new to
  a codebase or wants a quick orientation. Trigger for: "I just joined this team", "explain this repo
  to me", "give me a project overview", "where is the main logic", "what is the entry point",
  "I need to understand the architecture before starting", "walk me through this codebase",
  "which module is the most complex", "find the business logic", "I'm about to refactor and need
  to understand the structure first", onboarding, project walkthrough, architecture tour,
  découvrir le projet, visite guidée, point d'entrée, logique métier, module complexe.
argument-hint: 'Which project or folder do you want to explore?'
context: fork
---

# Onboarding Express

AI-guided architectural tour of any codebase for a new developer.
Powered by Graph-It-Live — extracts entry points, business logic, and the most complex module in one structured pass.

## CLI and Capability Discovery

Prefer the Graph-It CLI. At the first activation of any Graph-It skill in a session, check
`graph-it --version` when the CLI and terminal are available; use only its existing newer-version
notice and do not poll npm. Share discovery, version, and update decisions across Graph-It skills
for the session. Run `graph-it tool --list` once, consult `graph-it --help` or command help as
needed, and refresh only when the CLI/version, server, or workspace changes or a requested tool is
unknown. Examples are illustrative, not a fixed inventory. Do not install automatically. If the
CLI is unavailable or unsuitable, use MCP only when the connected host advertises a structurally
equivalent tool and its schema; otherwise explain the gap. `graph-it tool <name>` invokes analysis
directly through CLI; `graph-it serve` starts MCP. CLI `--format` and MCP `response_format` are
distinct.

If the CLI reports a newer version, interactive use requires explicit positive confirmation before
running `graph-it update`; silence, timeout, refusal, non-TTY, or generic Agent mode is not consent.
When automatic mode is explicitly enabled and pre-authorized, default the update decision to yes and
run `graph-it update` without another prompt. After success, refresh the version and `--list`,
invalidate cached capabilities, and advise that a running MCP server needs a host-authorized restart.
On failure, keep using the existing CLI only if it remains usable; otherwise explain the failure
and stop CLI analysis. Warn briefly and do not retry in a loop.

These instructions require Graph-It-Live CLI **1.21.0 or later** (`check-architecture`, `architecture
--level units`, `--matrix`, and the 24 MCP tools). Compare the reported `graph-it --version` with
1.21.0 at the same first activation. If it is older, say so once, name the commands it lacks, and
offer `graph-it update` under the confirmation policy above; until it is updated, use only commands
listed by that CLI's `--help` and `tool --list`, and never present output of a missing command as a
result. If the version cannot be read, treat it as older.

## Choose the Workspace Root

Graph-It-Live analyzes one workspace root and skips every import that resolves outside it. Without
`--workspace`, the CLI uses the nearest directory holding `package.json` or `tsconfig.json`; an
explicit `graph-it -w <dir>` is used exactly as given. The index and cache (`.graph-it/`) are
created in the chosen root.

- **Monorepo tour, entry points, dependents, impact, cross-package questions**: use the monorepo
  root through `graph-it -w <monorepoRoot> <command>` rather than `cd` into a package.
- **One package only**: scan that package, then say in the report that sibling packages are not
  covered.
- If `scan` prints `Warning: N imports resolve outside the workspace root`, the results cover the
  current root only. Rerun with the `--workspace` it names, or report the limitation; never present
  the narrow results as workspace-wide. `graph-it tool get_index_status` reports the same
  `outOfRootImports` count and `monorepoRoot`.

## When to Use

- A developer joins the team and needs a codebase overview
- You want to understand an unfamiliar project quickly
- You need to identify where business logic lives before a refactor
- You want to find the most complex/risky module before making changes

---

## Workflow — Step by Step

### Step 1 — Build the index

```bash
graph-it scan
```

Run it once first; all subsequent commands depend on it. It is incremental and cached, so no
timeout wrapper is needed. Check its stderr for the out-of-root warning (see Choose the Workspace Root).

---

### Step 2 — Workspace overview

```bash
graph-it architecture --format toon
```

Parse the output to identify:
- Top-level files and their role
- Candidate **entry point files** (look for: `index`, `main`, `app`, `server`, `cli`, `bootstrap`, `startup` in filenames or in exported symbols)
- Candidate **business logic folders** (look for: `services`, `domain`, `core`, `usecases`, `business`, `handlers`, `controllers`)

If the graph is too large, restrict the initial pass:

```bash
graph-it architecture --maxFiles 300 --format toon
```

---

### Step 3 — Identify the 3 main entry points

For each candidate entry file (max 5), run both directions:

```bash
# Outgoing: what this file calls and imports
graph-it explain <filePath> --format toon

# Incoming: who imports/calls this file
graph-it tool find_referencing_files --targetPath=<path>
```

`<path>` may be absolute or relative to the workspace root (for example `apps/worker/src/a.ts`).

Rank by:
1. **Highest fan-out** (outgoing) + **0 fan-in** (nothing imports it) → true root entry points
2. **High fan-out** + **few importers** → secondary entry points (e.g., CLI, alternative bootstraps)
3. **High fan-in** (imported by many) + **exports many symbols** → shared core, not an entry point
4. Presence of bootstrap / initialization patterns in the call tree

Select the **top 3** and for each, produce:

> **Entry point `<filename>`** — `<one-line role description>`
> Called by: `<callers or "root — no callers (true entry point)">` 
> Calls into: `<top 3–5 downstream modules>`

---

### Step 4 — Locate the business logic

For each candidate business logic file, run **both directions** to build a complete dependency picture:

```bash
# Outgoing: what this file exports, imports, and calls internally
graph-it tool generate_codemap --filePath=<path> --format toon

# Incoming: who depends on this file across the project
graph-it tool find_referencing_files --targetPath=<path>
```

The combination of both tells you:
- **generate_codemap** → what the file does (exported symbols, internal call depth, its own dependencies)
- **find_referencing_files** → how central it is (how many other files rely on it)

Look for files that score high on both axes: many exports **and** many importers. A file with rich exports but no importers may be an entry point, public API, or dead-code candidate; confirm references and external use before classifying. A file with many importers but few exports is a utility hub. The real business logic sits at the intersection.

Pick the **1–3 files** with the highest combination of fan-in + exported symbol count. These are the business logic core.

---

### Step 5 — Find the most complex module

For a representative sample of files (top 20 by size, or all files for small projects under 50 files), run:

```bash
graph-it explain <path> --format toon
```

Score each file using this heuristic:

| Signal | Weight |
|---|---|
| Internal call depth (max recursion level) | High |
| Number of internal cycles (circular calls) | High |
| Number of exported symbols | Medium |
| Number of distinct callers (fan-in) | Medium |
| Number of distinct callees (fan-out) | Medium |

The file with the highest combined score is the **most complex module**.

For an open-ended follow-up, use the natural-language query as a hypothesis generator, then
verify the answer with the deterministic scores above:

```bash
graph-it query "which module has the deepest call stack and widest impact"
```

---

### Step 6 — Trace the critical path

From the highest-scored entry point, trace the full execution chain:

```bash
graph-it trace <entryFile>#<mainFunction> --format mermaid
```

The output names each node by its symbol and workspace-relative file; calls into external modules
are dashed `:::external` nodes:

```mermaid
graph TD
  S0["main · src/index.ts"]
  S1["parse · src/parser.ts"]
  S2["tokenize · src/parser.ts"]
  S3(["readFileSync · node:fs"]):::external
  S0 --> S1
  S1 --> S2
  S0 --> S3
  classDef external stroke-dasharray: 4 2
```

Use `--format mermaid` here because the output is intended for a human — the Mermaid diagram renders as a visual flowchart in VS Code, GitHub, Obsidian, and most Markdown preview panes. For all other graph-it calls in this workflow, prefer `--format toon` (token-efficient, AI-readable).

---

## Output Format

Synthesize steps 3–6 into this structured report:

---

### Project Tour — `<ProjectName>`

**3 Main Entry Points**

| # | File | Role | Type |
|---|------|------|------|
| 1 | `src/index.ts` | Application bootstrap, wires all modules | True entry (no callers) |
| 2 | `src/api/router.ts` | HTTP routing, dispatches to controllers | Called by index.ts |
| 3 | `src/cli.ts` | CLI interface, alternative entry point | True entry (no callers) |

**Business Logic Core**

| File | Exported Symbols | Referenced By |
|------|-----------------|---------------|
| `src/services/orderService.ts` | 12 | 8 files |
| `src/domain/pricing.ts` | 7 | 5 files |

**Most Complex Module**

> `src/services/orderService.ts` — 4 levels of internal call depth, 2 internal cycles, imported by 8 files.
> **Recommendation**: Any change here has high blast radius. Run `get_impact_analysis` before modifying.

**Critical Path (Mermaid)**

```mermaid
<trace output here>
```

---

## Tips

- On a **monorepo**, tour from the monorepo root with `graph-it -w <monorepoRoot> ...` (see Choose the Workspace Root). Narrow to one package with `--maxFiles` or per-package file paths, not by changing the root.
- If the architecture graph returns too much data, lower `--maxFiles` or tour one package/folder at a time.
- If indexing is incomplete or `scan` warns about out-of-root imports, report the unanalysed area rather than guessing.
- The "most complex module" heuristic is architectural, not cyclomatic. For line-level complexity, combine with a linter.
- After the tour, run the **dead-code-hunter** skill to find safe cleanup targets before the new developer starts writing code — a clean codebase is much easier to onboard into.
- For deeper call-graph questions ("what calls this function?", "what breaks if I change X?"), use the **graph-it-live** skill directly.
- Before merging an onboarding-driven change, use **pr-review** to inspect its diff and static-impact limitations.