# SETUP.md — One-Click Autonomous Developer Setup (Linux · macOS · Windows)

> **AI: this is an executable runbook. Detect the OS, then run every phase in order.**
> You provision the employee's whole environment: toolchain → Claude config →
> eng-suite (auto-activating skills, machine-wide) → graphify (cached code map to
> cut token cost) → verify. Pause only on `[ask]` gates. Never write secret values.

## The one command the employee runs

| OS | One-click command |
|---|---|
| **Linux / macOS** | `bash <(curl -fsSL https://onboarddev.agentixtech.ai/setup.sh)` |
| **Windows** | `irm https://onboarddev.agentixtech.ai/setup.ps1 | iex` |

The bootstrap installs Claude Code, then hands to Claude to follow THIS file.

## Execution Protocol
For each step: run **Check** (exit 0 → skip) → honor **Gate** (`auto` run it / `ask`
pause for human) → run **Do** → run **Verify** (exit 0 = done; retry ≤3). OS variants:
macOS `brew` · Debian/Ubuntu/WSL2 `apt-get` · Windows `winget`/PowerShell.

---

## Phase 1 — Core tools `[auto]`
| Tool | Check | Do (mac / linux / win) | Verify |
|---|---|---|---|
| git | `command -v git` | `brew install git` / `sudo apt-get install -y git` / `winget install Git.Git` | `git --version` |
| mise | `command -v mise` | `curl -fsSL https://mise.run \| sh` / same / `winget install jdx.mise` | `mise --version` |
| gh | `command -v gh` | `brew install gh` / `sudo apt-get install -y gh` / `winget install GitHub.cli` | `gh --version` |

## Phase 2 — Language runtimes `[auto]`
| Runtime | Check | Do | Verify |
|---|---|---|---|
| Node 20 | `node -v \| grep ^v20` | `mise use -g node@20 && mise install` | `node -v` |
| Python 3.12 | `python3 --version \| grep 3.12` | `mise use -g python@3.12 && mise install` | `python3 --version` |

## Phase 3 — Claude Code + config `[auto]`
- Install Claude Code: `npm install -g @anthropic-ai/claude-code` · Verify `claude --version`.
- Write `~/.claude/CLAUDE.md` (team defaults) + `~/.claude/settings.json` (ask-gate for sudo/auth) if absent.

## Phase 4 — eng-suite (machine-wide) `[auto]`
Install once so **every** repo/workspace inherits the workflow skills + self-heal hook.
- **Do:** `bash onboarding/install.sh --yes`   (or plugin path — see INSTALL.md)
- Installs to `~/.claude/`: skills (eng-req-understanding, eng-planning, eng-implementation,
  eng-testing, eng-orchestrator, **graphify**), `/onboard` command, SessionStart hook.
- **Verify:** `test -d ~/.claude/skills/eng-orchestrator && test -d ~/.claude/skills/graphify`

## Phase 5 — graphify (cache/token reduction) `[auto]`
Build a graph-ranked repo map so Claude reads a small cached index, not whole files.
- **Do (per active repo):** `python3 ~/.claude/graphify/graphify.py --repo . --budget-tokens 1500`
- Writes `.claude/REPO_MAP.md` (loaded into the cached prefix → ~0.1x reads).
- **Verify:** `test -f .claude/REPO_MAP.md`
- The graphify skill then auto-refreshes it on entering repos / after big changes.

## Phase 6 — GitHub sign-in `[ask — needs the human]`
- **Check:** `gh auth status` · **Do:** `gh auth login --git-protocol https --web`
  (STOP: tell the human to approve device login in the browser) · **Verify:** `gh auth status`

## Optional — Project workspace (if a repo URL is given)
Clone → `mise install` → install deps → build → run graphify on it.

---

## Finalize — Verification Report (always run last)
```bash
report(){ local pass=*** fail=0 skip=0
 row(){ local n="$1" c="$2"; shift 2; if "$@" >/dev/null 2>&1; then printf '  ✅ %-16s PASS\n' "$n"; pass=***
   elif [ "$c" = required ]; then printf '  ❌ %-16s FAIL\n' "$n"; fail=$((fail+1)); else printf '  ➖ %-16s SKIP\n' "$n"; skip=$((skip+1)); fi; }
 echo "── Setup 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 eng-suite required bash -c 'test -d ~/.claude/skills/eng-orchestrator'
 row graphify required bash -c 'test -f ~/.claude/graphify/graphify.py'
 row repo-map optional bash -c 'test -f .claude/REPO_MAP.md'
 row gh-auth optional gh auth status
 local total=$((pass+fail+skip))
 if [ "$fail" -eq 0 ]; then echo "── ✅ VERIFIED · $pass/$total ──"; touch ~/.onboard/done; else echo "── ❌ FAILED · $pass/$total, $fail required missing ──"; fi; }
report
```
> On Windows, run the equivalent checks in PowerShell (`Get-Command git`, etc.).
Do not claim success unless the report shows **VERIFIED**. On VERIFIED, `~/.onboard/done`
is created so the SessionStart hook stops offering onboarding.

---

## What this achieves (the whole objective)
| Layer | Mechanism | Payoff |
|---|---|---|
| Toolchain + Claude | phases 1–3, cross-OS | machine ready |
| eng-suite | `~/.claude/` install + SessionStart hook | workflow skills auto-active in **every** workspace, self-healing |
| graphify | cached `.claude/REPO_MAP.md` | Claude reads a small cached map, not whole files → big token/cache savings |
| one-click | setup.sh / setup.ps1 → this runbook | one command per OS, fully autonomous except auth |

## Notes for the AI
- Only command blocks/backticked commands are executable; prose is guidance.
- Placeholders (`onboarddev.agentixtech.ai`, package names, REPO_URL, org CLIs) → replace per company.
- Degrade gracefully: if docker or an admin-only step is blocked on a locked-down
  machine, mark it skipped and continue; don't hard-fail the whole run.