---
name: write-onboarding-guide
description: Use when the user says "write the onboarding guide" / "new-engineer onboarding" / "day-1 doc" — reads the engineering context doc and the repo structure (README, CONTRIBUTING, Makefile, package.json scripts, docker-compose, .env.example) via the connected code host, and writes a single running `onboarding-guide.md` at the agent root with First day / First week / First month, repo map, verified setup steps, conventions, ownership (if team > 1), FAQ. Draft only; never auto-commits.
---

# Write Onboarding Guide

## When to use

- User: "write the new-engineer onboarding guide" / "draft the
  onboarding doc" / "day-1 guide for a new hire".
- Rerun any time the stack or repo structure materially changes —
  the guide is a single living file at my agent root, refreshed in
  place.

## Steps

1. **Read engineering context.** Open
   `../head-of-engineering/engineering-context.md`. If missing or
   empty, stop and tell the user:
   > "I can't write an onboarding guide without the engineering
   > context doc — it's the source of truth for stack, architecture,
   > conventions, team shape, and priorities. Run the Head of
   > Engineering's `define-engineering-context` first."

2. **Read config.** `config/docs-home.json` (shapes where to point
   readers for deeper docs — the docs site, if any), and
   `config/doc-audience.md` (usually "new engineers joining" for
   this skill).

3. **Resolve the repo + fetch setup files.**
   - Run `composio search code-hosting` and fetch these files from
     the default branch (skip any that don't exist, note as UNKNOWN):
     - `README.md`
     - `CONTRIBUTING.md`
     - `Makefile`
     - `package.json` (scripts section)
     - `pyproject.toml` / `setup.py` / `requirements.txt`
     - `go.mod`
     - `Cargo.toml`
     - `docker-compose.yml` / `docker-compose.yaml`
     - `.env.example`
     - `.nvmrc` / `.python-version` / `.tool-versions`
     - `CODEOWNERS`
   - Also fetch the top-level directory listing (2 levels deep) for
     the repo map.
   - If no code host is connected, tell the user which category to
     link OR offer to work from the engineering-context.md + the
     user pasting key files.

4. **Verify setup steps.** For every command the guide will include
   (install, build, run, test, migrate), cite its source file and
   line. Example: `make dev` → "from Makefile: `dev:` target runs
   `docker compose up -d && pnpm run dev:watch`". **If a step can't
   be verified against a real file, mark UNKNOWN and ask the user to
   confirm, rather than invent.** This is the single highest-risk
   part of the guide — bad setup steps waste the new hire's first
   day.

5. **Draft the guide.** Structure:

   ```markdown
   # Onboarding Guide — {Company / Product}

   Welcome. This guide gets you productive in three phases:
   first day (running locally), first week (shipping your first
   PR), first month (owning a slice).

   **Last refreshed:** {ISO date}

   ---

   ## Before you start

   - Accounts you'll need: {list from engineering-context.md team
     section — GitHub, CI, chat, etc.}
   - Hardware / OS expectations: {from .tool-versions or explicit
     note; UNKNOWN otherwise}
   - Tool versions: {Node / Python / Go / Rust versions from
     .nvmrc / .python-version / pyproject / go.mod / Cargo.toml}

   ---

   ## First day — run it locally

   1. **Clone.**
      ```bash
      git clone {repo URL}
      cd {repo}
      ```
   2. **Install deps.** ({cite source: package.json scripts / Makefile})
      ```bash
      {verified command}
      ```
   3. **Set env vars.** Copy `.env.example` to `.env` and fill in
      {list required keys}. ({cite source})
   4. **Run services.** ({cite: docker-compose / Makefile})
      ```bash
      {verified command}
      ```
   5. **Run the app.** ({cite})
      ```bash
      {verified command}
      ```
   6. **Verify it works.** Hit `http://localhost:{port}` — you
      should see {what}.
   7. **Run the test suite** to confirm your setup.
      ```bash
      {verified command}
      ```

   If step X breaks, see FAQ below.

   ---

   ## Repo map

   ```
   {repo}/
   ├── {dir-1}/      — {purpose}
   ├── {dir-2}/      — {purpose}
   └── ...
   ```

   (2 levels deep, grounded in the actual repo listing.)

   ---

   ## First week — your first PR

   1. **Pick a starter issue.** {From the engineering-context doc's
      priorities, or label `good-first-issue` if it exists.}
   2. **Branch naming.** {From engineering-context conventions; mark
      UNKNOWN if unspecified.}
   3. **Commit format.** {From conventions; UNKNOWN if unspecified.}
   4. **PR template.** {From `.github/PULL_REQUEST_TEMPLATE.md` if
      present; UNKNOWN otherwise.}
   5. **Review rules.** {From engineering-context quality bar — who
      reviews, how many approvals, what blocks merge.}
   6. **CI expectations.** {What CI runs, typical runtime, what to
      do if it's red.}

   ---

   ## First month — own a slice

   - {From engineering-context priorities: the 1-2 areas a new hire
     would grow into ownership of.}
   - Who to ask: {from CODEOWNERS if team > 1, else "the founder
     (you)".}

   ---

   ## Conventions

   - **Languages / frameworks:** {from engineering-context stack.}
   - **Commit format:** {from conventions.}
   - **Branch naming:** {from conventions.}
   - **PR description:** {from conventions.}
   - **Testing:** {coverage expectations from quality bar.}
   - **Deploys:** {cadence from quality bar.}

   ---

   ## Who owns what

   {If engineering-context says team > 1, list per CODEOWNERS or
   the team shape section. If team is just the founder, write:
   "Team is just the founder — all questions go to them."}

   ---

   ## FAQ

   - **Q: `{setup command}` failed with `{common error}`.** A: {if
     verifiable — otherwise "ask the founder".}
   - **Q: How do I propose an architectural change?** A: Draft a
     design doc (see the Tech Lead agent) and share it for review.
   - **Q: What's the on-call shape?** A: {from engineering-context
     team shape, or "none yet" if not set.}
   ```

6. **Write** to `onboarding-guide.md` at the agent root (single
   file — NOT under a subfolder) atomically (`*.tmp` → rename).
   - If the file exists, refresh it as a whole. Do not append or
     partial-edit — the guide is versioned by `updatedAt`.

7. **Update `outputs.json`** — if an entry with
   `type: "onboarding-guide"` exists, update its `updatedAt` +
   `summary`. Otherwise add a new entry (`id` uuid v4,
   `type: "onboarding-guide"`, `title: "Onboarding guide —
   {Company}"`, `summary: "{sections}: first-day, first-week,
   first-month, repo map, {N} UNKNOWN flags"`,
   `path: "onboarding-guide.md"`, `status: "draft"`, timestamps).
   Read-merge-write atomically.

8. **Summarize to user** — one paragraph: what's covered, any
   UNKNOWN flags (unverified setup steps, missing conventions, etc.),
   and the path. End with: "Review, fill in the UNKNOWNs, commit to
   your repo when you're happy. I never push."

## Hard nos

- **Never invent setup steps.** If a command can't be verified
  against the actual repo files, mark UNKNOWN.
- Never auto-commit the guide to the user's repo.
- Never write the guide under a subfolder — it lives at the agent
  root as a single running document.
- Never write without reading `engineering-context.md` first.

## Outputs

- `onboarding-guide.md` at the agent root (single file, refreshed
  in place).
- Upserts an entry in `outputs.json` with `{ id, type:
  "onboarding-guide", title, summary, path: "onboarding-guide.md",
  status: "draft", createdAt, updatedAt }`.