onboardlisted

Companion to `/ai:handoff`. **Handoff** leaves a machine; **onboard** arrives at a project. Write a project-scoped `ONBOARDING.md` at the repo root, confirm the contents with the user, then publish via the harness `ShareOnboardingGuide` tool to get a sharable short-link. ## When to use - New teammate or contractor joins the repo. - Fresh machine — your own or someone else's. - Agent (Claude Code / Cursor / Codex) will pick up the project with no conversation history. - After a major structural change (new module, framework upgrade) — refresh the guide so newcomers don't start from a stale picture. Skip when the project already has a current `ONBOARDING.md` and nothing material has changed — re-running re-uploads the same content for no signal. ## Process 1. **Detect prior state.** If `./ONBOARDING.md` exists, read it first and treat the run as an update (Section "Re-runs" below). 2. **Survey the repo.** Pull from the sources that already exist; do NOT invent facts. - `CONTEXT.md` or `CONTEXT-MAP.md` (domain language) - `README.md` (one-line purpose, install steps) - `package.json` / `composer.json` / `pyproject.toml` / equivalent (commands, scripts, deps) - `.ai-kit-setup` (which Tier B branches the project opted into) - `docs/adr/` (load-bearing decisions) - `docs/architecture.md` if present 3. **Audience.** If the user passed an argument, scope the guide to it (e.g. "backend dev" → skip frontend tooling section). Default audience: