---
name: deliver-onboarding
description: "Use when newcomer-facing documentation needs creation or refresh — triggered by phrases like 'write the README', 'getting started guide', 'new developer setup', 'architecture overview', 'onboarding doc', 'how do I get this running', 'document this for a new hire'. Proposes a docs plan scoped to the actual project shape (small CLI gets README + LICENSE; library gets README + API reference + CONTRIBUTING; multi-service backend gets architecture overview + per-service runbooks + day-1 walkthrough), the user confirms, and only confirmed docs get produced. Skip for non-runnable projects (research dump, archived code, internal-only spike with no runtime) — onboarding docs imply a path from zero to running."
---

# Deliver: Onboarding

## Overview

Good onboarding documentation means a new developer can go from `git clone` to running tests in under 5 minutes. This skill generates onboarding documentation derived from actual project state — verified by execution, updated when the project changes.

A small CLI does not need the same docs as a multi-service backend. Producing a hardcoded suite for every project is doc bulk — sections that nobody reads, sections that go stale, sections that lie. This skill plans the docs first (what fits this repo shape), confirms with the user, then produces only the confirmed docs.

## When to Use

- New project reaches a runnable state (after `build-scaffold`)
- Major feature adds new concepts, patterns, or setup steps
- After deployment changes how the project runs
- New team member is about to start (verify docs are current)
- User explicitly asks for documentation
- `/feature` command completes and introduces new patterns

**Do NOT use when:**
- Project is not yet runnable (wait for scaffold/build)
- Only internal refactoring with no new concepts or setup changes
- Documentation is already current and verified

## When to load references

- **`references/document-templates.md`** — onboarding document templates with full markdown structure and per-document generation process. Load this when you're about to write any of the documents the user confirmed in the plan.

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | Working project (builds, runs, tests pass) |
| **Produces** | Confirmed subset of onboarding docs in project docs directory |
| **Feeds into** | -- (final deliverable, consumed by humans) |
| **Updates** | `.forge/work/{type}/{name}/manifest.yaml` if triggered as part of a feature |

### Input Analysis

Before proposing the docs plan, analyze the project to extract facts:

```
Project root/
  package.json / pyproject.toml / go.mod    -> Dependencies and scripts
  Dockerfile / docker-compose.yml            -> Container setup
  .env.example                               -> Required environment variables
  README.md                                  -> Existing documentation (preserve or enhance)
  src/ or equivalent                         -> Source code structure
  tests/ or equivalent                       -> Test structure and runners
  .claude/                                   -> forge configuration (skills, agents, hooks)
```

If the project uses a non-default docs directory (e.g., `wiki/`, `documentation/`, Docusaurus), adapt to that structure. ASK the user if unsure about the target directory.

## Agent Dispatch

Dispatch the **doc-writer** subagent to generate the documentation. It has Write tool access and specializes in generating accurate, newcomer-friendly docs from the actual codebase. Dispatch it only AFTER the docs plan is confirmed in Step 2 — Step 1 (planning) and Step 2 (confirmation) are done in the main thread.

## Step 1: Propose a Docs Plan

Read the project to infer its shape, then propose a docs plan scoped to what this shape actually needs.

### Shape inference

Identify which of these the project most resembles. A project can mix shapes — pick the dominant frame and note adjacent traits.

| Shape | Signals | Typical docs that fit |
|---|---|---|
| **Small CLI / utility** | Single executable, small surface area, no services, install + run is the whole flow | README, LICENSE |
| **Library / SDK** | Package consumed by other code, public API surface, no runtime services | README, API reference, CONTRIBUTING |
| **Web app (single service)** | One service, frontend + backend, runs locally for dev | README, getting-started, local-setup |
| **Multi-service backend** | Multiple services, orchestrated by docker-compose or k8s, infra setup | README, architecture overview, per-service runbooks, day-1 walkthrough |
| **Monorepo** | Multiple packages/apps, shared tooling, build matrix | README, monorepo layout, per-package quickstarts |
| **Research dump / spike** | No runtime path, not meant to be cloned and run | (none — skip per "Do NOT use when") |

### Candidate documents

Pull from this menu when assembling the plan. Add anything project-specific that the shape demands; drop anything that does not earn its keep.

| Doc | Key question answered | Default fit |
|---|---|---|
| `README.md` | "What is this and why would I use it?" | Every shape |
| `docs/getting-started.md` | "How do I get this running?" (zero to tests in 5 min) | Web app, multi-service, monorepo |
| `docs/architecture-overview.md` | "How is this organized?" (components, data flow, stack) | Multi-service, monorepo, non-trivial web apps |
| `docs/local-setup.md` | "How do I configure my environment?" (tools, env vars, DB) | Anything with non-trivial setup |
| `docs/testing-guide.md` | "How do I test my changes?" (test types, commands, CI) | Anything with a meaningful test suite |
| `docs/common-tasks.md` | "How do I do X?" (feature, bugfix, migration, deploy) | Multi-service, monorepo, mature web apps |
| `docs/glossary.md` | "What does this term mean?" (project-specific terms) | Domains with non-obvious vocabulary |
| `docs/api-reference.md` | "What does this library expose?" (functions, types, examples) | Library / SDK |
| `CONTRIBUTING.md` | "How do I contribute?" (workflow, style, review) | Library, OSS-facing, larger teams |
| `LICENSE` | "What can I do with this code?" | Anything published or shared externally |
| `docs/runbooks/{service}.md` | "How do I operate this service?" (start, stop, recover, debug) | Multi-service backend |
| `docs/day-1-walkthrough.md` | "What does a new hire do on day 1?" | Multi-service, larger teams |

### Plan output format

Present the plan as a checklist. Mark each candidate document checked (recommended for this shape) or unchecked (available but not recommended). Justify each entry briefly.

```
DOCS PLAN — <project shape>
---------------------------
[x] README.md                  — entry point, always needed
[x] docs/getting-started.md    — non-trivial setup (Docker compose, multiple services)
[x] docs/architecture-overview.md — 4 services + 2 datastores, hard to grasp from code
[ ] docs/glossary.md           — domain terms are standard; can add later if needed
[ ] CONTRIBUTING.md            — internal-only project; add when going OSS
...
```

Include shape-specific extras as needed (e.g. per-service runbooks for a backend). Do not include docs that would be empty or boilerplate for this project.

## Step 2: User Confirms the Plan

Present the plan from Step 1. The user can:

- **Accept** — produce all checked items
- **Modify** — check/uncheck items, add docs not in the menu, change target paths
- **Reject** — skill ends; no docs are produced

Default behavior is **produce only the checked items**. Anything unchecked is deferred — it can be added later by re-running the skill.

Do NOT proceed to Step 3 until the user has explicitly confirmed the final checklist. If the user is non-responsive, stop and surface the open question.

## Step 3: Produce the Confirmed Docs

### Codex Mode Check

Run the Codex consent flow from `protocols/codex.md` before generating any documentation.

- **Takeover selected:** Dispatch Codex to generate the confirmed docs from the project analysis and config files. Claude reviews generated docs for accuracy before writing to disk.
- **Verify selected** or **Skip / Codex unavailable:** Claude (via the doc-writer subagent) generates the confirmed docs. If Verify was selected, Codex reviews them before writing to disk.

### Generation

For each document on the confirmed list:
- Open `references/document-templates.md`, find the matching section, and follow its **Structure** and **Generation Process** blocks.
- If a confirmed document is project-specific and not in the templates file, draft a structure consistent with the rest of the suite (purpose, structure, generation process). Prefer concrete sections grounded in actual project state over generic boilerplate.

Skip any document not on the confirmed list. Do not produce "starter stubs" for unchecked items — empty or near-empty docs are worse than no docs.

## Generation Standards

### Accuracy Over Completeness

- Every command in the docs MUST work when copy-pasted
- If you are unsure about a command, verify it before including
- Better to say "check with your team lead" than to include a wrong command
- Never include placeholder values that look real (use `YOUR_API_KEY_HERE` not `sk-abc123`)

### Template Usage

If `templates/` exists, use those templates as the starting structure. Adapt content to the actual project but maintain the template's organization.

### Maintaining Docs

When to update onboarding docs:
- After `build-scaffold` completes (initial generation)
- After `deliver-deploy` if deployment process changed
- After `deliver-db-migration` if database setup changed
- After any change to project prerequisites
- When a gotcha related to setup is recorded in `support-gotcha`

### Tone and Style

- Write for someone who is smart but has never seen this project
- Prefer concrete examples over abstract descriptions
- Use exact commands, exact file paths, exact URLs
- Avoid jargon unless it is defined in the glossary
- Keep sentences short and direct
- Use numbered steps for procedures, bullet points for lists

## Codex Documentation Verify

After the confirmed docs are generated (by Claude or Codex depending on mode), check the mode recorded at Codex Mode Check. If **Verify** was selected, dispatch Codex to review the generated docs for accuracy against actual project state — command correctness, env var coverage, broken references, stale instructions. Address any CRITICAL findings before writing to disk. If **Takeover** was selected, skip this step (Codex already generated). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.

## Verification Checklist

Before considering onboarding docs complete, run the checks that apply to the docs that were actually produced. Skip rows for docs not on the confirmed list.

```
ONBOARDING DOCUMENTATION VERIFICATION
--------------------------------------
[  ] README: Does it answer "what is this and why use it" in the first screen?
[  ] Getting Started: Can a new developer go from clone to tests passing in 5 min?
[  ] Architecture: Does the system diagram match the actual codebase?
[  ] Local Setup: Are all environment variables documented?
[  ] Local Setup: Do Docker commands work as written?
[  ] Testing Guide: Can every test command be copy-pasted and run?
[  ] Common Tasks: Do the workflows match the actual project process?
[  ] Glossary: Are all project-specific terms defined?
[  ] API Reference: Does every public symbol have a usable example?
[  ] CONTRIBUTING: Are the workflow, style, and review steps current?
[  ] Runbooks: Can someone start/stop/recover each service using only the runbook?
[  ] No secrets: No real API keys, passwords, or tokens in any document
[  ] No broken links: All referenced files and URLs exist
[  ] No stale info: Docs match the current state of the project
```

## Red Flags -- STOP and Reconsider

| Thought | Reality |
|---|---|
| "Everyone knows how to do this" | New developers do not. Document it. |
| "The code is self-documenting" | Self-documenting code still needs setup instructions. |
| "We can fill in details later" | Empty sections are worse than no docs. Write it now or mark as TODO. |
| "Just read the Dockerfile" | Docs translate Docker configs into human-readable instructions. |
| "The README covers it" | READMEs are often outdated. Verify every claim. |
| "It's obvious from the project structure" | Obvious to you. Not to someone seeing it for the first time. |

## Graphify Context (Static-only)

**Protocol:** `protocols/graphify.md` | **Mode:** Static-only — read graph files if they exist, skip if absent. No guard, no build prompts, no CLI queries.

**How graph data maps to this skill:**
- **Community labels** → name the subsystems in the architecture overview
- **God nodes** → highlight as key entry points for new developers
- **`graph.html`** → reference as an interactive architecture diagram in the onboarding docs ("open `graphify-out/graph.html` for an interactive dependency map")

---

## Codex Integration
**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`

- **Verify:** Claude generates docs, Codex reviews for accuracy and completeness.
- **Takeover:** Codex generates the confirmed docs, Claude reviews before writing to disk.

**When:** After the docs plan has been confirmed (Step 2) and the project has been analyzed (config files read, conventions identified, structure mapped) — but before writing the documentation files.

**Context to pass:**
- The confirmed docs list from Step 2 (which documents to produce, with target paths)
- Path to `.forge/work/{type}/{name}/codebase-analysis.md` (if available)
- Path to project config files (package.json, pyproject.toml, Dockerfile, etc.)
- Path to `graphify-out/GRAPH_REPORT.md` (if available)

**What Codex generates:**
- Only the documents on the confirmed list — no extras

**Prompt focus:** "Generate the confirmed onboarding documents from the project analysis and config files. Follow the templates and structure defined in the skill for each document. Produce only the documents on the confirmed list. Each document should be accurate to the actual project setup — do not use placeholder values."

**Presentation:** Claude reviews Codex's generated docs for accuracy against actual project state before writing to disk.

---

## Integration with Other Skills

- **build-scaffold** triggers initial onboarding doc generation
- **deliver-deploy** triggers doc updates when deployment process changes
- **deliver-db-migration** triggers doc updates when database setup changes
- **support-gotcha** provides common troubleshooting items for docs
- **discover-codebase-analysis** provides the structural understanding this skill documents