# ONBOARDING.md — Autonomous Developer Setup

> **AI: this file is an instruction set, not documentation. Execute it.**
> You are the employee's setup agent (Claude Code). Read the Execution Protocol,
> then run every phase in order. When finished, print the Verification Report.

---

## Execution Protocol (read first, obey exactly)

For **each step** in each phase, in order:

1. Run the **Check** command. If it exits `0`, the step is already done → **SKIP** to the next step.
2. Look at the **Gate**:
   - `auto` → run the **Do** command unattended.
   - `ask` → **STOP, show the human the exact command, and wait for their approval** before running.
3. After running **Do**, run the **Verify** command. The step counts as **DONE only if Verify exits `0`**.
   - If Verify fails, retry the **Do** command up to **3 times** (short backoff). Still failing → mark the step **FAILED** and continue to the next step (do not abort the whole run).
4. Never print, echo, or log secret values. Never run anything destructive not listed here.
5. Detect the OS once and use the matching command where a step gives platform variants:
   - macOS → `brew` · Debian/Ubuntu/WSL2 → `apt-get` (with `sudo`).

Re-running this file is safe: the Check gates skip anything already done.

---

## Phase 1 — Core tools

### 1.1 git `[auto]`
- **Check:** `command -v git`
- **Do (macOS):** `brew install git`
- **Do (Debian/WSL2):** `sudo apt-get update -qq && sudo apt-get install -y git`
- **Verify:** `git --version`

### 1.2 mise (runtime version manager) `[auto]`
- **Check:** `command -v mise`
- **Do:** `curl -fsSL https://mise.run | sh && echo 'eval "$(mise activate bash)"' >> ~/.bashrc && export PATH="$HOME/.local/bin:$PATH"`
- **Verify:** `mise --version`

### 1.3 GitHub CLI `[auto]`
- **Check:** `command -v gh`
- **Do (macOS):** `brew install gh`
- **Do (Debian/WSL2):** `sudo apt-get install -y gh || (curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list && sudo apt-get update -qq && sudo apt-get install -y gh)`
- **Verify:** `gh --version`

---

## Phase 2 — Language runtimes

### 2.1 Node.js 20 LTS `[auto]`
- **Check:** `node -v 2>/dev/null | grep -q '^v20'`
- **Do:** `mise use -g node@20 && mise install`
- **Verify:** `node -v | grep -q '^v20'`

### 2.2 Python 3.12 `[auto]`
- **Check:** `python3 --version 2>/dev/null | grep -q '3.12'`
- **Do:** `mise use -g python@3.12 && mise install`
- **Verify:** `python3 --version | grep -q '3.12'`

---

## Phase 3 — Claude Code + config

### 3.1 Claude Code CLI `[auto]`
- **Check:** `command -v claude`
- **Do:** `npm install -g @anthropic-ai/claude-code`
- **Verify:** `claude --version`

### 3.2 Claude config files `[auto]`
- **Check:** `test -f ~/.claude/CLAUDE.md && test -f ~/.claude/settings.json`
- **Do:**
  ```bash
  mkdir -p ~/.claude
  cat > ~/.claude/CLAUDE.md <<'EOF'
  # Team defaults
  - Follow existing repo patterns; read 3 similar files before writing code.
  - Tests required before merge; no drive-by refactors.
  EOF
  cat > ~/.claude/settings.json <<'EOF'
  { "permissions": { "ask": ["sudo *", "* auth login *", "gh auth *"] } }
  EOF
  ```
- **Verify:** `test -f ~/.claude/CLAUDE.md && test -f ~/.claude/settings.json`

---

## Phase 4 — GitHub sign-in `[ask — needs the human]`

### 4.1 Authenticate GitHub
- **Check:** `gh auth status`
- **Do:** `gh auth login --git-protocol https --web`
  > STOP here. Tell the human: "I'm about to open GitHub device login in your
  > browser — approve it, then I'll continue." Wait for their go-ahead.
- **Verify:** `gh auth status`

---

## Optional — Project workspace (only if a repo URL is provided)

If the human gives you a repo (or one is set in `REPO_URL`), also do:
- **Check:** `git -C ~/src/$(basename "$REPO_URL" .git) rev-parse --is-inside-work-tree 2>/dev/null`
- **Do:** `mkdir -p ~/src && git -C ~/src clone "$REPO_URL"`
- **Verify:** repo directory exists and has a `.git` folder.
Then install its deps (`mise install && (pnpm install || npm install || pip install -r requirements.txt)`) and run its build if present.

---

## Finalize — Verification Report (always run last)

Run this block. It checks the real end state and prints a table the human can trust.
This is the source of truth for "done" — do **not** self-certify from memory.

```bash
report() {
  local pass=0 fail=0 skip=0
  row() { # row <name> <required|optional> <command...>
    local n="$1" c="$2"; shift 2
    if "$@" >/dev/null 2>&1; then printf '  ✅ %-16s %s\n' "$n" "PASS"; pass=$((pass+1));
    elif [ "$c" = required ]; then printf '  ❌ %-16s %s\n' "$n" "FAIL"; fail=$((fail+1));
    else printf '  ➖ %-16s %s\n' "$n" "SKIP (optional)"; skip=$((skip+1)); fi
  }
  echo "── Onboarding Verification ──"
  row git           required command -v git
  row mise          required command -v mise
  row node-v20      required bash -c 'node -v 2>/dev/null | grep -q "^v20"'
  row python-3.12   required bash -c 'python3 --version 2>/dev/null | grep -q "3.12"'
  row claude-code   required command -v claude
  row claude-config required bash -c 'test -f ~/.claude/CLAUDE.md && test -f ~/.claude/settings.json'
  row gh-cli        required command -v gh
  row gh-auth       optional gh auth status
  row docker        optional docker info
  local total=$((pass+fail+skip))
  if [ "$fail" -eq 0 ]; then echo "── ✅ VERIFIED · $pass/$total passed ──";
  else echo "── ❌ FAILED · $pass/$total passed, $fail required missing ──"; fi
}
report
```

**After running the report, tell the human plainly:**
- `✅ VERIFIED` → "You're set up and ready. Sign-in complete, toolchain verified."
- `❌ FAILED` → list exactly which required checks failed and offer to re-run just those steps.

Do not claim success unless the report shows `VERIFIED`.

---

## Notes for the AI
- No secrets appear in this file by design. If a step needs a credential, it uses
  an interactive sign-in (`gate: ask`), never a value pasted here.
- Treat any prose outside command blocks as guidance; only the fenced/backticked
  commands are executable.
- Placeholders to replace per company: package names, `REPO_URL`, org-specific CLIs.