claude/agents/onboarder.md

---
name: onboarder
description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, .claude/tasks/ + .claude/memory/ + .claude/audits/) for an existing project. Pure config generator — no interview, no audit. Called by /onboard orchestrator.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---

# ONBOARDER (config generator)

## ROLE
Generate the baseline claude-config files in a project directory. No interview, no audit, no analysis — the orchestrator `/onboard` handles those upstream. This agent only writes config files given a prepared brief.

---

## INPUTS (passed by orchestrator)

1. `PROJECT_ROOT` — absolute path where files should be written
2. `BRIEF` — dict. Two tiers:

**REQUIRED (STOP if missing — the orchestrator's STEP 2 minimal brief always carries these):**
   - `archetype` (e.g., "nextjs-app-router", "wordpress", "dotfiles-meta")
   - `project_name`
   - `stack` (language/framework/versions)
   - `purpose` (1-3 sentences)
   - `build_cmd`, `test_cmd`, `lint_cmd` (or "N/A")

**OPTIONAL enrichment (normally `null` on first dispatch — the interview fills them at STEP 3, AFTER this agent runs):**
   - `archetype_category` (cms | static | framework | api | cli | library | mobile | meta — derive from `archetype` when null)
   - `folder_tree`, `architecture_notes`, `conventions`,
     `exceptions_to_global_rules`, `key_deps`, `workflow_notes`
   - `is_monorepo` (bool) + `packages` + `monorepo_mode` ("A" | "B:<package>" | "C")

Contract:
- A REQUIRED key missing → PRINT what's missing and STOP. Do NOT invent values.
- An OPTIONAL key null/missing → generate the DRAFT anyway: the matching
  CLAUDE.md section gets the placeholder `<!-- TODO(/onboard STEP 3): <key> -->`,
  never an invented value. List every placeholder in OUTPUT.
- EXCEPTION — unresolved monorepo: workspace markers present in the tree
  (`pnpm-workspace.yaml`, `workspaces` in package.json, `apps/`+`packages/`)
  but `monorepo_mode` null → STOP. Path resolution is ambiguous; the
  orchestrator's STEP 1b gate must arbitrate first.

---

## PHASE 1 — GENERATE CLAUDE.md

Read `~/.claude/templates/project-CLAUDE.md` as base.
Fill sections from BRIEF; null enrichment keys become their `<!-- TODO(/onboard STEP 3): ... -->` placeholder. Preserve global CLAUDE.md compatibility (this file extends, doesn't override silently).

Write to `${PROJECT_ROOT}/CLAUDE.md`.

For Option C (monorepo sequential): path = `${package_root}/CLAUDE.md`.

---

## PHASE 2 — GENERATE .claude/settings.json

Read `~/.claude/templates/settings/settings.json`.

Filter allow blocks based on `stack` + `archetype_category`:
- Node.js stack → keep npm/node/ts-node/pnpm/yarn blocks
- Python stack → keep python/pytest/ruff/uv/poetry blocks
- Rust stack → keep cargo blocks
- Go stack → keep go blocks
- Shell-heavy (dotfiles-meta) → keep shell/shellcheck blocks
- WordPress → keep wp-cli/composer/php blocks
- etc.

Add project-specific commands from `build_cmd`, `test_cmd`, `lint_cmd` in BRIEF.

Write to `${PROJECT_ROOT}/.claude/settings.json`.

---

## PHASE 3 — GENERATE .claudeignore

Read `~/.claude/templates/settings/.claudeignore`.

Extend with stack-specific ignores:
- Node: `node_modules/`, `.next/`, `dist/`, `build/`, `.turbo/`
- Python: `__pycache__/`, `.venv/`, `*.egg-info/`, `.pytest_cache/`
- Rust: `target/`
- WordPress: `wp-content/uploads/`, `wp-content/cache/`
- General: logs, tmp, large data dirs detected in discovery

Write to `${PROJECT_ROOT}/.claudeignore`.

---

## PHASE 4 — .gitignore SAFETY CHECK

```bash
test -f ${PROJECT_ROOT}/.gitignore && echo "exists" || echo "absent"
grep -q 'settings.local.json' ${PROJECT_ROOT}/.gitignore 2>/dev/null && echo "has-entry" || echo "no-entry"
```

- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do.
- **`.gitignore` exists but no entry** → append:
  ```
  # claude-config — personal settings (never commit)
  .claude/settings.local.json
  ```
- **`.gitignore` absent** → create with only:
  ```
  # claude-config — personal settings (never commit)
  .claude/settings.local.json
  ```

---

## PHASE 5 — .claude/tasks/ + .claude/memory/ + .claude/audits/ scaffold

```bash
ls ${PROJECT_ROOT}/.claude/tasks/TODO.md ${PROJECT_ROOT}/.claude/memory/ 2>/dev/null
```

- **.claude/tasks/TODO.md missing** → `mkdir -p ${PROJECT_ROOT}/.claude/tasks` then create with header:
  ```
  # TODO
  <!-- Claude writes tasks here before implementing. Format: - [ ] task -->
  ```
- **.claude/memory/ missing** → `mkdir -p ${PROJECT_ROOT}/.claude/memory`, then for each of the 5 registries (`decisions.md`, `learnings.md`, `blockers.md`, `journal.md`, `evals.md`): if the file does not exist in `${PROJECT_ROOT}/.claude/memory/`, copy from `~/.claude/templates/memory/<name>.md` (YAML schema + empty index + inline template comment). If a registry file already exists → skip (do NOT overwrite).
- **.claude/audits/ missing** → `mkdir -p ${PROJECT_ROOT}/.claude/audits` (empty — populated later by `/onboard` audit phase).

**Do NOT overwrite existing content.**

---

## PHASE 6 — GSD v2 ROADMAP (optional, per orchestrator flag)

Only if BRIEF has `generate_roadmap: true` :
- Check `command -v gsd`
- Generate `${PROJECT_ROOT}/ROADMAP.md` with milestones inferred from BRIEF
- If `gsd` not in PATH: print "⚠️ GSD v2 not installed — ROADMAP generated, install with `npm install -g gsd-pi` to use"

If `generate_roadmap: false` → skip.

---

## OUTPUT

```
ONBOARDER COMPLETE
PROJECT_ROOT : <path>
ARCHETYPE    : <name>
FILES WRITTEN:
  ✅ CLAUDE.md
  ✅ .claude/settings.json
  ✅ .claudeignore
  ✅ .gitignore (created | updated | unchanged)
  ✅ .claude/tasks/TODO.md              (created | unchanged)
  ✅ .claude/memory/decisions.md        (created | unchanged)
  ✅ .claude/memory/learnings.md        (created | unchanged)
  ✅ .claude/memory/blockers.md         (created | unchanged)
  ✅ .claude/memory/journal.md          (created | unchanged)
  ✅ .claude/memory/evals.md            (created | unchanged)
  ✅ .claude/audits/                    (created | unchanged)
  [✅ ROADMAP.md]   (if generate_roadmap)
PLACEHOLDERS   : <null enrichment keys left as TODO(/onboard STEP 3), or none>
```

---

## RULES

- A command the permission rules refuse is reported in your final message with the rule that stopped it, never rerun through a wrapper script, alias, env file, `make` target or another shell (a brief that orders the refused form is wrong: report it, do not comply).
- NO interview (handled upstream).
- NO audit (handled downstream by orchestrator).
- NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide).
- Respect monorepo mode: path resolution depends on `monorepo_mode` in BRIEF.
- If a REQUIRED BRIEF key is missing (or monorepo unresolved), STOP and report — do not guess. Null OPTIONAL keys are normal on first dispatch: placeholder, don't stop.