Project Onboarding

---
name: project-onboarding
description: "Use when starting in a new project repo, when /update-docs reports tracker_missing, or on first coordinator-plugin run."
description-budget: 175
version: 1.0.0
---

# Project Onboarding

## When to Use

- Starting work in a new project repository for the first time
- `/update-docs` reports `tracker_missing` — the project lacks coordination infrastructure
- PM asks to set up project tracking in an existing repo
- **Marketplace first-run** — new coordinator plugin user setting up their first project

## Prerequisites

- You are in the project's working directory (not `~/.claude`)
- PM is available for 3 questions (Step 2)

## Phases

### Phase 1: DETECT — Survey Existing State

Before scaffolding, check what already exists. **Never overwrite existing files.**

Check for each of these and record status (exists / missing / incomplete):

```
├── CLAUDE.md                           — project conventions
├── docs/README.md                      — documentation index (wikis, research, specs, reference)
├── docs/project-tracker.md             — workstream tracking
├── docs/wiki/                          — wiki guides (LAZY — created by coordinator:distill on first guide extraction)
├── docs/wiki/DIRECTORY_GUIDE.md        — guide index with decision record mapping
├── docs/plans/                         — implementation plans (LAZY — created when first plan is copied from ~/.claude/plans/)
├── docs/research/                      — research outputs (LAZY — created by deep-research:research on first run)
├── tasks/lessons.md                    — engineering patterns (LAZY — created by coordinator:session-end on first lesson)
├── archive/completed/                  — completion archive (LAZY — created by coordinator:session-end on first completion)
├── tasks/handoffs/                     — session continuity (LAZY — created by coordinator:handoff on first handoff)
├── CONTEXT.md                          — domain glossary (LAZY — never scaffold; produced when first term is resolved)
├── DIRECTORY.md                        — source index
└── .gitignore                          — check for .claude/settings.local.json entry
```

**If `docs/project-tracker.md` already exists:** This skill becomes a health check — verify the format matches the standard template, flag deviations, and skip to Phase 4 (REPORT).

**Global detection:** Check if `~/.claude/CLAUDE.md` exists. If yes, the generated CLAUDE.md will include an "extends global" reference. If not, the template is fully self-contained — no dependency on global config.

**Repo classification (PM ask):** Check if `.gitignore` excludes session infrastructure directories (`tasks/`, `archive/`, `tasks/handoffs/`). Capture this as a hint string — do not make a decision from it:

- 2+ of these are gitignored → hint = `_(detected: 2+ of 3 session dirs gitignored — looks like a distribution repo)_`
- Fewer or none gitignored → hint = `_(detected: standard working-tree layout)_`

Always ask the PM:

> **Is this repo:**
> - **(a) a working repo** — for active development, with session artifacts tracked
> - **(b) a published artifact / template** — distributed for downstream consumers; no session infrastructure
> - **(c) both** — a working repo that publishes itself as the artifact
>
> _(detected: {hint})_

**Branch on the PM's answer:**

- **(a)** → proceed to Phase 1.5 / Phase 2 unchanged. No injection.
- **(b)** → STOP. Do not proceed to Phase 2. Report:
  > _"You answered (b) — distribution repo. Onboarding infrastructure doesn't belong here. Track work on this repo from your parent project's tracker instead."_
- **(c)** → proceed exactly like (a), AND inject a one-line note in the generated CLAUDE.md (Phase 3a) and the generated tracker (Phase 3b):
  > _"This repo is published as its own working artifact — consumers see the full directory shape including `tasks/` and `archive/`."_

Report what exists and what needs to be created before proceeding.

**Project type short-circuit:** Check if `coordinator.local.md` exists at the repo root:

```bash
test -f coordinator.local.md && echo "exists" || echo "missing"
```

If it exists, read it and capture `project_type` and `project_subtypes` (if present). Emit a one-line confirmation:

> Project type: {type}{ +subtypes: [{subtypes}] if any}. From coordinator.local.md — skipping Phase 2 question 2.

If `coordinator.local.md`'s `project_type` differs from the `detected_type` derived from the marker scan, append this one-line challenge immediately after the confirmation (PM remains authoritative — this is informational only, not a re-ask):

> *`coordinator.local.md` says `{type}` but detected stack is mostly `{detected_type}` — keeping the file value (PM authoritative). If wrong, edit `coordinator.local.md` and re-run.*

If `coordinator.local.md` is missing, proceed to Phase 2 question 2 (cold-ask) as normal.

Also check for legacy values in the file: if `project_type` is `unreal`, `meta`, or bare `web`, emit a one-line warning with the migration hint (e.g. `unreal` → `project_type: game-dev` + `project_subtypes: [unreal]`). Do not auto-rewrite.

**Runtime marker scan:** Run `bash "$HOME/.claude/plugins/coordinator/bin/detect-project-runtime.sh"` and capture the output. Show to PM in Phase 2 above question 2 as `_(detected stack: <one-line summary>)_`. PM's answer is authoritative; detection is sanity-check only. Output is advisory stdout — no skill/agent/hook reads it programmatically (adding a consumer requires a separate plan per `archive/specs/2026-05-06-detect-project-runtime.md`).

**Derived type from markers:** Once the marker scan returns, derive a `detected_type` (and `detected_subtypes` if applicable) using these rules, in priority order:

- `*.uplugin` or `*.uproject` present → `detected_type: game-dev`, `detected_subtypes: [unreal]`
- `package.json` + any of `next.config.js`, `vite.config.*`, `nuxt.config.*`, `svelte.config.*`, `remix.config.*` present → `detected_type: web-dev`
- `requirements.txt` or `pyproject.toml` present (and no UE markers) → `detected_type: data-science`
- `Cargo.toml`, `go.mod`, or none of the above → `detected_type: general`

Capture these as part of the Phase 1 profile. If `coordinator.local.md` already exists and its `project_type` differs from `detected_type`, emit a one-line challenge inline in the Phase 1 report (see **Project type short-circuit** block above for the exact wording).

### Phase 1.5: INVESTIGATE — Read substrate, draft proposals

Skip when Phase 1 found a genuinely empty repo (no README, no CONTRIBUTING, no top-level manifest).

**Substrate-first onboarding.** Read the project's accumulated institutional memory before asking the PM cold: `README.md`, `CLAUDE.md`, `tasks/lessons.md`, `tasks/improvement-queue.md` if present (1.5a); most-recent 5 handoffs for stack/tooling clues if `tasks/handoffs/` exists (1.5b); sibling `CLAUDE.md` files for stack-shared conventions via `~/.claude/tasks/repo-registry.md` `stack_tags` (1.5c). Output: a 5–10 line substrate snapshot. Cold-ask is the fallback when substrate is empty.

**Roadmap orientation (run immediately after the substrate snapshot):** Query the completed archive for recent roadmap items — especially valuable when joining cold.

```bash
bin/query-records --type completion --since "90d" --where "nature=roadmap" \
  --sort "-loe.tshirt" --limit 10 --format markdown-list
```

Render under `#### Recent roadmap (last 90d, top-10 by size)` in the Phase 4 REPORT (count-always per `docs/wiki/orientation-surfacing-doctrine.md`; `(none)` is expected on new repos). Otherwise:

1. Read top-level `README.md` / `README.rst` / `README.txt` if present.
2. Read `CONTRIBUTING.md` if present.
3. Read top-level manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.uplugin`, `*.uproject`, etc. — whichever exist.
4. Skim recent commit subjects: `git log --oneline -20`.

Draft proposals from what you read:

- **Project name** — from README H1 or repo directory name.
- **Project type + subtypes** — from manifest signals + README role description, reconciled with Phase 1 runtime-marker output. If proposal differs from `detected_type`, surface both with proposal winning and emit:

  > *Detected stack suggests `{detected_type}`. README/manifests suggest `{proposed_type}`. Going with `{proposed_type}` — confirm or override.*
- **Initial workstreams (1-3)** — derived from README "what this does" + recent commit subjects + any "Roadmap" / "TODO" / "Status" sections. If the repo names sibling repos (path on disk, GitHub URL, or "split" / "addon" / "upstream" / "downstream" language), capture each as `peer_repo_candidates`.

Present proposals to the PM for ratification:

> Before I scaffold, here's what I found:
>
> **Project name:** {proposed}
> **Project type:** {proposed}{, subtypes: [...] if any}
> **Workstreams (proposed):**
> 1. {WS1} — {2-3 deliverables}
> 2. {WS2} — {...}
>
> **Sibling repos referenced:** {list with file:line citations from README/CONTRIBUTING}
>
> Ratify, correct, or say "go cold" to skip this and ask from scratch.

On ratification: skip Phase 2's name + workstreams questions; only ask if PM corrected something or said "go cold."

On peer-repo presence: ask once whether to dispatch parallel Explore scouts (recommended). If yes, dispatch each with: *"Read README, CONTRIBUTING, and recent commits. Identify shared schemas, integration contracts, and shipped vs in-flight work relevant to {this repo's name}. Reply with file:line citations."* Wait for results before drafting tracker workstreams.

### Phase 2: ASK — PM Input

**Skip questions Phase 1.5 already ratified. Phase 1.5 may have already pinned project name and/or workstreams; only ask the questions whose answers are still missing.** **If `coordinator.local.md` was found in Phase 1**, skip question 2 — project type already pinned. Ask:

> **1. Project name** — short name (e.g., "Geneva MVP", "DroneSim")
> **2. Initial workstreams** (1-3) — name, 2-3 deliverables, optional deps/blockers. Say "stubs" for placeholders.

**If `coordinator.local.md` was NOT found** (cold-ask path), present all three:

> **1. Project name** — short name (e.g., "Geneva MVP", "DroneSim")
> _(detected stack: <one-line summary>)_
> **2. Project type:**
>    - `game-dev` — Game development (adds the Game Dev Reviewer reviewer, game-dev domain agents)
>    - `web-dev` — Web frameworks (adds the Front-End Reviewer for front-end review, the UX Reviewer for UX)
>    - `data-science` — Notebooks, pipelines (adds the Data Science Reviewer reviewer)
>    - `general` — Standard conventions only
> **3. Initial workstreams** (1-3) — name, 2-3 deliverables, optional deps/blockers. Say "stubs" for placeholders.

Wait for PM response before proceeding.

### Phase 3: GENERATE — Create Missing Files

Create only what's missing. Use the templates in this skill's `templates/` directory as the base.

#### Lazy-creation discipline

Only scaffold files that have **meaningful day-1 content**. A placeholder header trains agents to ignore the directory; empty scaffolding has zero signal value. Create files and directories only when there is a real artifact to write.

**Audit verdict — Phase 3 scaffold items:**

| Item | Verdict | Reasoning |
|------|---------|-----------|
| `CLAUDE.md` | EAGER | Project conventions apply immediately; filled in Phase 2 |
| `docs/project-tracker.md` | EAGER | Workstreams established in Phase 2; real content on day 1 |
| `docs/README.md` | EAGER | Structural index with project name, pointers to plans/research/wikis |
| `.gitignore` entry | EAGER | Prevents accidental credential commits from first commit onwards |
| Post-commit hook | EAGER | Auto-push crash insurance is needed from the very first commit |
| `cross-repo/` dir | EAGER (contract-bearing) | Inbound cross-repo memo channel — sibling EMs address this repo's `cross-repo/` by name; must exist before any memo arrives. Scaffolded with `README.md` (real content, not `.gitkeep`) by `scaffold-canonical-structure.sh`. Schema: `cross-repo-memo`. Source of truth: `canonical-structure.yaml`; plan: `docs/plans/2026-05-23-cross-repo-single-surface-and-canonical-scaffold.md § Lazy-vs-eager reconciliation`. |
| `tasks/lessons.md` | LAZY | Header + comment only; no lessons exist until first session runs |
| `tasks/handoffs/` dir | LAZY | No handoffs until first session ends via `/handoff` |
| `archive/completed/` dir | LAZY | No completed work until first work item ships |
| `docs/wiki/` dir | LAZY | Wiki guides come from `/distill` after artifacts accumulate |
| `docs/plans/` dir | LAZY | Plans come from plan mode; none exist on day 1 |
| `docs/research/` dir | LAZY | Research outputs come from `/deep-research` pipelines |
| `tasks/review-trail/` dir | LAZY | Review records written by `/session-end` and `/handoff` |

LAZY items are NOT created here. Each has a designated "create on first use" owner noted in its section below.

#### 3a. CLAUDE.md (if missing)

Use `templates/CLAUDE.md.template` via `bin/render-template.sh`. The template contains ONLY literal `{{KEY}}` substitutions — no conditionals. Construct the substitution values before calling the helper:

**1. Construct `GLOBAL_EXTENDS_LINE`:**
- If `~/.claude/CLAUDE.md` exists: set to `Extends global \`~/.claude/CLAUDE.md\`.`
- If no global CLAUDE.md exists: set to empty string `""`

**2. Construct `PROJECT_TYPE_BLOCK`:**
Concatenate block bodies for each selected type (in selection order); blank line between multiple blocks.

- **`game-dev` block:**
  ```
  ## Unreal Engine Conventions

  - **Engine version:** UE5.x (specify)
  - **Build command:** <!-- e.g., UnrealBuildTool invocation -->
  - **Cook command:** <!-- platform-specific cook -->
  - **Blueprint vs C++:** <!-- project policy on when to use each -->
  - **Naming conventions:** <!-- UE naming standards: A_ for assets, BP_ for blueprints, etc. -->
  - **Key modules:** <!-- list primary C++ modules -->
  ```

- **`web-dev` block:**
  ```
  ## Web Development

  - **Framework:** <!-- e.g., Next.js, React, Vue, Svelte -->
  - **Dev server:** <!-- e.g., npm run dev, port -->
  - **Component conventions:** <!-- file structure, naming, styling approach -->
  - **State management:** <!-- e.g., Zustand, Redux, signals -->
  - **CSS approach:** <!-- e.g., Tailwind, CSS Modules, styled-components -->
  - **Key routes/pages:** <!-- list primary routes -->
  ```

- **`data-science` block:**
  ```
  ## Data Science Conventions

  - **Notebook conventions:** <!-- naming, cell organization, output clearing policy -->
  - **Data pipelines:** <!-- tools, orchestration, storage locations -->
  - **Model versioning:** <!-- MLflow, DVC, manual, etc. -->
  - **Environment management:** <!-- conda, venv, poetry -->
  - **Key datasets:** <!-- list primary data sources -->
  ```

- **`general` type:** no block body — `PROJECT_TYPE_BLOCK` is empty string `""`.
- **Multi-type projects** (e.g., `game-dev` + `data-science`): concatenate both block bodies with a blank line between them.

**3. Call the render helper:**

```bash
bash "$HOME/.claude/plugins/coordinator/bin/render-template.sh" \
  "$HOME/.claude/plugins/coordinator/skills/project-onboarding/templates/CLAUDE.md.template" \
  -o CLAUDE.md \
  PROJECT_NAME="<derived-name>" \
  PROJECT_TYPE="<type>" \
  SUBTYPES="<comma-separated-list-or-empty>" \
  GLOBAL_EXTENDS_LINE="<line-or-empty>" \
  PROJECT_TYPE_BLOCK="<concatenated-blocks-or-empty>"
```

The helper substitutes all `{{KEY}}` placeholders, exits non-zero if any remain (template/key drift guard). Use absolute `$HOME`-anchored paths — relative paths resolve against the project root, not the plugin directory. Leave `<!-- Fill in -->` comments as-is; they are prompts for the PM.

**Runtime conventions section:** populate the `## Runtime conventions` section bullets from the Phase 1 marker-scan output — one bullet per detected stack line. If the script reported "no known stack markers", replace the placeholder bullets with `- <!-- no runtime markers detected; PM to fill -->`. Do not edit other `<!-- Fill in -->` placeholders.

#### 3b. docs/project-tracker.md (if missing)

Use `templates/tracker.md.template`:

1. Replace `[PROJECT_NAME]`, `[DATE]` (today), `[YEAR]`, `[MONTH]`
2. Replace `[WORKSTREAMS]` with formatted workstream blocks from PM input:

For each workstream the PM provided:
```markdown
### N. [Workstream Name]
**Status:** Ready
**Specs:** <!-- link when spec is written -->

- [ ] [Deliverable 1]
- [ ] [Deliverable 2]
- [ ] [Deliverable 3]
```

If PM said "stubs": create one placeholder workstream:
```markdown
### 1. [Define workstreams]
**Status:** Ready

- [ ] _PM: Define initial workstreams and deliverables_
```

#### 3c. tasks/lessons.md — SKIP (lazy)

Do NOT create this file during onboarding — no meaningful day-1 content. Created by `coordinator:session-end` on first lesson capture.

#### 3d. docs/README.md (if missing)

Create `docs/README.md` — the documentation index maintained by `/update-docs`. Structure:

```markdown
# [Project Name] — Documentation Index

Central entry point for all project documentation. Maintained by `/update-docs`.

---

## Wikis and Guides
→ **[`docs/wiki/DIRECTORY_GUIDE.md`](guides/DIRECTORY_GUIDE.md)** — full guide index
_No guides yet. Created by `/distill` as knowledge accumulates._

---

## Plans
→ [`docs/plans/`](plans/) — plans start in `~/.claude/plans/`, copied here on approval.

---

## Research
→ [`docs/research/`](research/) — `/deep-research` outputs; key findings extracted by `/distill`.

---

## Reference Documentation
| Doc | Purpose |
|-----|---------|
| [project-tracker.md](project-tracker.md) | Active workstreams and priorities |

---
*Last updated: [DATE]. Maintained by `/update-docs`.*
```

Replace `[Project Name]` and `[DATE]` with the appropriate values.

#### 3e. Directories

Only create directories with real day-1 content or referenced by files being written in this phase:

```bash
mkdir -p docs   # for project-tracker.md (3b) and README.md (3d)
mkdir -p tasks  # for feature work; lessons.md is lazy (see 3c)
```

**Scaffold contract-bearing directories** by invoking `scaffold-canonical-structure.sh`. This is idempotent — safe to re-run; never clobbers existing content:

```bash
# Resolve scaffold script from the coordinator plugin location, not cwd.
_scaffold_script="$HOME/.claude/plugins/coordinator/bin/scaffold-canonical-structure.sh"
# Pass --root explicitly so the scaffold targets the project repo, not the coordinator plugin root.
bash "$_scaffold_script" --root "$(pwd)"
```

The script reads `canonical-structure.yaml` and creates every `creation: eager` directory entry with a `README.md` (not a `.gitkeep`). Currently that means `cross-repo/` with its schema-documenting README — the file an inbound sender's EM looks for before writing a memo.

**Do NOT pre-create the LAZY directories above** (`tasks/handoffs/`, `archive/completed/`, `docs/wiki/`, `docs/plans/`, `docs/research/`, `tasks/review-trail/`) **with `.gitkeep` files** — they are created by the skill that first writes to them (see table above). Contract-bearing dirs (`cross-repo/`) are scaffolded with READMEs by `scaffold-canonical-structure.sh`.

#### 3f. .gitignore handling

Ensure `.gitignore` contains the canonical block (per `docs/wiki/gitignore-policy.md`):

```
# Machine-specific Claude settings (do not commit)
.claude/settings.local.json

# Scratch — transient agent output, investigation notes, workstream byproduct.
# `scratch/` matches at any depth (top-level scratch/, tasks/scratch/, etc.)
scratch/
tasks/_*.log
```

Procedure:

1. **If `.gitignore` doesn't exist:** Create it with the canonical block above.
2. **If `.gitignore` exists but is missing any of the three rules:** Append only the missing rules under a single comment header (`# Coordinator universal — scratch + machine-local settings`).
3. **If all three rules are present:** Skip silently.

**Warning checks:**

- If `.gitignore` ignores all of `.claude/` (`.claude/` or `.claude/*`), warn: only `.claude/settings.local.json` needs ignoring.
- If tracked content exists under `scratch/` or `tasks/_*.log`, surface count and offer `git rm --cached -r` cleanup (confirm with PM first — don't auto-untrack).

#### 3f.5. Auto-push post-commit hook

Check for `.git/hooks/post-commit`. If absent, install one that delegates to the canonical helper (SSH remotes on Windows → PowerShell; HTTPS → git directly):

```bash
cat > .git/hooks/post-commit <<'HOOK'
#!/bin/bash
# Auto-push to remote on work/* or feature/* branches — crash insurance.
# Delegates to coordinator-auto-push helper.
exec "$HOME/.claude/plugins/coordinator/bin/coordinator-auto-push"
HOOK
chmod +x .git/hooks/post-commit
```

If the repo already has a post-commit hook (e.g. Git LFS prefix), preserve the existing block(s) and append the helper invocation backgrounded:

```bash
# === Auto-push (crash insurance) ===
( "$HOME/.claude/plugins/coordinator/bin/coordinator-auto-push" ) &
exit 0
```

Skip if a custom auto-push hook already exists and the PM has signed off on it.

#### 3g. DIRECTORY.md

Do NOT create this file directly — requires source file analysis handled by `/update-docs` Phase 2. Note in the report that the PM should run `/update-docs`.

### Phase 4: REPORT

If Phase 1.5 dispatched peer-repo scouts, ensure the tracker's workstream blocks include `file:line` citations from the scout reports.

Present what was done:

```
## Onboarding Complete — [Project Name]

### Created
- [list each file/directory created]

### Already Existed (untouched)
- [list each file that was skipped]

### Needs Attention
- [any warnings — .gitignore issues, incomplete CLAUDE.md sections to fill in]

### Recent Roadmap (last 90d, top-10 by size)
_(Results from Phase 1.5 roadmap orientation query — one bullet per row. Render "(none)" when the query returns zero rows. Heading always present — count-always per orientation-surfacing-doctrine.)_

### Next Steps
1. **Fill in CLAUDE.md** — the `<!-- Fill in -->` sections need project-specific details
2. **Run `/update-docs`** — generates DIRECTORY.md source index, refreshes docs/README.md, and creates orientation cache
3. **Run `/session-start`** — verifies everything is wired up correctly
4. **Introspect coordinator / plugin bindings** — run the envelope-branch check below to verify the coordinator sees this project correctly.

   ```sh
   # Compact JSON output — pipe through python -m json.tool if you want pretty-print.
   # No --json flag needed — default output is compact JSON.
   python3 -m coordinator_whoami.project_rag        # POSIX / macOS
   py -3   -m coordinator_whoami.project_rag        # Windows Git Bash / PowerShell
   ```

   Parse `binding.kind` and `binding.target` from the JSON envelope (`cross-plugin-whoami-contract.md §Operator wiring`):

   - **`binding.kind == "bound"` AND `binding.target` matches cwd:** emit `Coordinator binding healthy: project-rag is bound to <binding.target>.`
   - **`binding.kind == "bound"` AND `binding.target` does NOT match cwd:** emit a mismatch block:
     ```
     Binding mismatch:
       envelope binding.target : <binding.target>
       expected (cwd)          : <cwd>
     Run /project-rag:setup to re-register this project root.
     ```
   - **`binding.kind == "unbound"`:** emit:
     `project-rag is not bound to this project. Run /project-rag:setup to register this project root.`
   - **Import fails (`ModuleNotFoundError`) OR the command exits non-zero:** emit:
     `coordinator_whoami is not installed. Run /coordinator:setup to install the introspection package.`

   Full probe suite: [`docs/wiki/coordinator-doctor.md`](../docs/wiki/coordinator-doctor.md).
5. **If `machine-local get repos.*` fails** — the machine-local registry is not yet bootstrapped for this project. See [`coordinator-doctor.md`](../docs/wiki/coordinator-doctor.md) probes P-1 through P-4 to bootstrap the registry.

### Documentation System
The documentation index is live at `docs/README.md`. Subdirectories are created lazily as artifacts accumulate:
- **`docs/wiki/`** — created by `/distill` when first guide is extracted
- **`docs/plans/`** — created when first plan is written in plan mode
- **`docs/research/`** — created by `/deep-research` on first run
- `/update-docs` maintains docs/README.md; `/distill` creates wiki guides from session artifacts
```

## Coordinator Conventions — Discovery Summary

When a new project is onboarded, surface these convention introductions so the EM has them at hand from day one. These are one-line pointers; the canonical docs hold the full mechanics.

- **Acceptance oracle (outer-loop):** Non-trivial reviewed plans declare bindable acceptance criteria gated at `/merging-to-main`. See `docs/wiki/writing-plans.md` § Acceptance Oracle.

## Onboarding Bug Fixes — Three-Layer Rule

Any onboarding bug fix that doesn't ship all three layers will recur:

**Layer 1 — Prevention:** Fix the install/setup script so future runs don't hit the failure.

**Layer 2 — Reactive repair:** A targeted recovery path for users who already hit the failure and won't re-run the full installer. Valid shapes: a `doctor`-style script (`--fix` flag), or an idempotent slash command safe to re-run against broken state. What matters is the ability to recover without a clean-slate install.

**Layer 3 — Searchable docs:** A row in the troubleshooting table keyed on the **literal error text** the user would see.

```markdown
| Error | Cause | Fix |
|-------|-------|-----|
| `ModuleNotFoundError: No module named 'coordinator_whoami'` | coordinator-whoami package was not installed | Run `/coordinator:setup` to install the introspection package |
```

Layer 2 recovery: doctor probe P-5 in [coordinator-doctor.md](../../docs/wiki/coordinator-doctor.md).

**When onboarding flags a new failure:** Verify all three layers exist before closing — missing layers are part of the same fix, not a follow-up task.

## Notes

- This skill creates the **skeleton**; `/update-docs` handles ongoing tracker maintenance. Tracker format matches the tracker-maintenance skill for consistency.
- Handoffs live at `tasks/handoffs/` (git-tracked); `settings.local.json` in `.gitignore`.
- **Template architecture:** One base CLAUDE.md template with conditional blocks per project type — NOT 4 separate files (stays under 12-file ceiling). Works standalone for marketplace users; DETECT phase adds "extends global" reference if `~/.claude/CLAUDE.md` exists.