create-onboarding-guide

Create Onboarding Guide

Produce one self-contained HTML file that takes a newcomer from zero to "I know where things live and how the main flows run" in one sitting.

1. Resolve the output directory

Same per-installer configuration as this plugin's other guide skills:

1. ${CLAUDE_PLUGIN_ROOT}/config.json → outputDir (shared across this plugin's skills)
2. config.json next to this SKILL.md → outputDir (skill-level override)
3. Neither exists → read config.example.json for the shape, ask the user for a real absolute path, then write the skill-level config.json (git-ignored).

Honor openAfterGenerate (default true).

2. Confirm the target

Confirm which repository (and, for a monorepo, which package/area) the guide covers, and who it's for (new engineer on the team vs. external contributor) — that decides how much project-specific context to assume. Default: the whole current repo, for a new team engineer.

3. Explore the codebase — the guide is only as true as this step

• Map the layout: top-level directories, build/config files, README/docs.
• Identify the architecture: layers/modules and the dependencies between them, traced from real imports/references (Grep), not directory names alone.
• Trace 2–3 key flows end-to-end (e.g. a request from route → handler → service → persistence; app startup; the primary user action). Record actual file:line hops.
• Note conventions a newcomer must know: naming patterns, where tests live, how config/env is loaded, codegen or other "don't edit by hand" areas.
• Completion criterion: every module in the architecture diagram and every hop in a flow walkthrough is backed by a file you actually read.

4. Generate the HTML guide

One self-contained .html file: inline <style>, <script>, SVG — no CDN. Prose in the user's conversation language; identifiers and paths as-is. Sections, in order:

1. Header — repo, purpose in one sentence, tech stack, date generated.
2. Architecture diagram — inline SVG of layers/modules with dependency arrows; a legend; each node listing its main directory.
3. Directory map — collapsible tree of the significant directories, each with a one-line role ("what lives here / when you'd touch it"). Skip vendored/generated noise.
4. Key flow walkthroughs — one per traced flow: a numbered sequence diagram (SVG) plus a step table of file → function → what happens.
5. Conventions & gotchas — the step-3 conventions list, including anything marked "don't edit by hand".
6. Recommended reading order — an ordered path of ~5–10 files to read first, each with one line on why it's on the path.
7. Getting started — real setup/build/test commands taken from the repo's README or scripts, in copyable code blocks.

Interactivity: sticky table of contents, collapsible directory tree and flow sections.

5. Save, open, report

• Filename: <repo>-onboarding-<yyyyMMdd>.html in the resolved output directory (create it if missing).
• If openAfterGenerate, open it: start <path> (fall back to explorer.exe <path>).
• Report the saved path and which flows the guide walks through.

Failure modes

• Repo too large to trace honestly in one pass → scope the guide to the agreed area from step 2 and say so in the header, rather than diluting the whole repo into vagueness.
• No obvious key flows (pure library) → walk the public API surface and one representative usage instead.