codehub-onboarding

codehub-onboarding

Produces a single ONBOARDING.md with a ranked reading order drawn from graph centrality. The wedge is the ranked reading list — a generic README scaffold cannot produce this.

Preconditions

1. mcp__codehub__list_repos returns the target. If not, emit Run codehub analyze first — repo <name> is not indexed. and stop.
2. codehub status is fresh. If stale, emit Run 'codehub analyze' first — index is stale and stop. (Spec 001 AC-3-1.)

Arguments

• [output-path] — where to write. Defaults:
  • without --committed: .codehub/ONBOARDING.md (gitignored)
  • with --committed: docs/ONBOARDING.md (gitignored default flipped)
• --committed — write to a committed path instead of .codehub/.

Process

1. Run the preconditions.
2. mcp__codehub__project_profile({repo}) — languages, stacks, entry points, 2-sentence summary.
3. mcp__codehub__route_map({repo}) — HTTP surface (if present).
4. mcp__codehub__tool_map({repo}) — MCP/CLI surface (if present).
5. mcp__codehub__sql({query: "SELECT name, file_path, in_degree + out_degree AS centrality FROM nodes WHERE kind IN ('File','Module','Class') ORDER BY centrality DESC LIMIT 15"}) — top-centrality nodes, the "read these first" candidates.
6. For the top 8 of those: mcp__codehub__context({symbol: <id>}) to pull a one-line summary + owners.
7. mcp__codehub__owners({path}) on the top-3 folders by file count — gives the "ask these humans" list.
8. Dispatch a single Task with the doc-onboarding specialty role (inline in this skill — see references/onboarding-template.md).
9. Assemble the output using the template below.
10. Write to the resolved output path.

Output template

# <repo> · Onboarding

*Generated <ISO-8601>. Refresh via `/codehub-onboarding`.*

## TL;DR

2 sentences: what this repo does + the single most important mental model to hold.

## Stack

| Layer | Tech | Source |
|---|---|---|
| Runtime | Node 22 | `package.json:7` |
| Storage | SQLite (single-file, node:sqlite) | `packages/storage/src/index.ts:12` |
| ... | ... | ... |

## Read these 10 files first (in order)

1. `packages/cli/src/bin.ts` — CLI entry point. `(45 LOC)`
2. `packages/mcp/src/server.ts` — MCP server bootstrap. `(320 LOC)`
3. `packages/ingestion/src/pipeline.ts` — the phase DAG. `(180 LOC)`
... (ranked by centrality; each with a one-sentence reason)

## Walk one process end-to-end

Pick the highest-step-count process and walk it:

1. **Enter** at `packages/cli/src/commands/analyze.ts:14`.
2. **Dispatches** to `packages/ingestion/src/phases/parse.ts:22`.
3. **Writes** via `packages/storage/src/write.ts:88`.
4. **Exits** at `packages/cli/src/commands/analyze.ts:102`.

## Ask these humans

| Area | Owner | Share |
|---|---|---|
| `packages/mcp/` | alice@ | 72% |
| `packages/ingestion/` | bob@ | 45% |
| `packages/storage/` | charlie@ | 68% |

## Next steps

- Run `codehub analyze .` in your checkout to build the local graph.
- Ask the `code-analyst` subagent (or any MCP-aware client) "how does X work" to get a graph-grounded brief.
- Read [architecture/system-overview.md](./docs/architecture/system-overview.md) if `codehub-document` has already produced it.