dev-machine-setup

# Dev Machine Setup Bring **any** machine to a clean, ready-to-develop state: a factory laptop, a half-configured work box, or a daily driver that has drifted. Phase 1 builds a **gap report** of what is missing and misconfigured, and every later phase acts only on that report. **Gap-driven** is the whole design. Each phase self-skips when its slice of the report is empty, so a re-run on an already-good machine installs nothing and still verifies: idempotent by construction. **Self-contained:** no external scripts repo is cloned. The shell config the skill deploys ships in `assets/`. This SKILL.md is the spine; per-OS command tables and per-phase detail live in `references/`, so only the current platform loads and the token budget stays on the machine in front of you. ## Modes Mode comes from the **user's intent**, not from machine state. A machine with gaps is not permission to fill them when the user only asked for a tune-up. | Mode | Selected by | Runs | |------|-------------|------| | `setup` (default) | "set up this machine", "install my dev environment", "get this laptop ready" | Phases 0 → 6 | | `tune` | "*just* optimize what's there", "don't install anything, fix my setup", "why is `claude` not found" | Phases 0, 1, 5, 6 only | **Tie-break:** if the request mentions missing pieces at all, choose `setup` ("verify what's missing and optimize it" is `setup`). Choose `tune` only when the ask is limited to what is already installed. If the mode is still unclear after the gap report is shown, ask the user once, before phase 3. `tune` skips phases 3 and 4 entirely: never bulk-install what the user did not ask for. Phase 5 may still install a package when that *is* the approved fix for a finding (e.g. `uv` for `python-externally-managed`). ## Approvals **Read `references/approvals.md` before phase 2.** It holds the rules every phase runs under. The four to hold from the start: - **Additive**: installs something *absent*. Nothing working can break. Batch-approvable per phase. - **Mutating**: changes something that *already works* (upgrades, removals, `chsh`, rc-file edits, `curl | sh`, PATH rewrites). Needs an explicit **per-item yes** with the risk named. Back up any rc file before editing it. A prior yes never carries forward to another mutating item. - **Five-step loop, every phase:** Present → Approve → Execute → Verify → Record. Read-only probes (`detect_env.py`, version checks, `winget list`) skip the approve step; nothing that changes state does. - **Run-blocks:** every proposed command ships as a copy-whole fenced block, never inside a table cell, never with a `<placeholder>` or an assumed cwd, always tagged `you run this` / `I can run this`. The session file (`~/.dev-machine-setup/session.json`) *is* the running log. Write it at every Record step. Build the final report from it, never from memory. Pause protocol: `references/approvals.md` § Pausing and resuming; schema, reconcile and pause output: `references/session.md`. ## When to Use - "set up this new laptop / fresh install" - "install my dev environment" (Node, Python, agents) - "optimize / clean up my dev setup", "my machine is a mess" - "I installed X but the command isn't found" - Windows OEM bloat, trial antivirus, preinstalled games Don't use for: Dockerfiles, CI runners, or installing a single named package. ## Prerequisites - **Network.** If a package download fails for lack of network, record that item as `deferred` with the reason `no network` and continue. Phases 0, 1, 5 (read-only checks) and 6 still run. - **Admin/sudo (or winget)** for system packages. Without it, offer the user-level install where the OS reference has one. Name each request that the missing access blocks; never fail it silently. ## Reference files (load only what you need) | File | When | |------|------| | `scripts/detect_env.py` | Phase 1 and the phase 5 re-run: prints the gap report JSON (inventory + `missing` + `findings`) | | `references/approvals.md` | Before phase 2: additive/mutating, the five-step loop, run-blocks, pause/resume | | `references/procedure.md` | Every phase: what each phase does, step by step | | `references/detect.md` | Running the probe without `python3`; what every JSON key means | | `references/windows.md` | Windows: inventory, conservative debloat, winget stack | | `references/macos.md` | macOS: Homebrew, Node, Python+uv, zsh, starship | | `references/linux.md` | Linux: apt/dnf/pacman, NodeSource LTS, python3-pip, zsh, starship | | `references/agent-clis.md` | Phase 4: Claude Code, Codex, Pi, OpenCode install + verify | | `references/optimize.md` | Phase 5: one section per finding id, each tagged additive/mutating | | `references/session.md` | Phase 0 and every Record step: session-file schema, write command, reconcile and pause rules | | `references/report-template.md` | Phase 6: the FINAL REPORT block, status rules, outcome map, reader checks | | `references/edge-cases.md` | No python3, Windows ARM64, WSL, containers, re-runs, unsupported distros | | `assets/zshrc-config` | Phases 3 and 5: the `~/.zshrc` deployed by `oh-my-zsh-missing`; owns the theme, plugin list, and starship init | | `assets/starship.toml` | Phases 3 and 5: the prompt config deployed by `starship-config-*`; `cp` it from the skill dir, never inline its contents | ## Procedure Read **`references/procedure.md`** at phase 0 and keep it open: it has the full steps for every phase. This table is the order and the condition to advance. Advance only when the current phase verifies green, self-skips on an empty gap set, or the user explicitly defers it. | # | Phase | Done when | |---|-------|-----------| | 0 | Resume check | Resuming from a reconciled session file, or starting clean with any discarded session deleted | | 1 | Detect and build the gap report | Gap report JSON captured, three lists shown, mode fixed, OS reference loaded, session file written | | 2 | Debloat *(fresh Windows only, opt-in)* | Skipped with a reason logged, or inventory shown and every removal individually confirmed and verified | | 3 | Baseline gaps *(skipped in `tune`)* | Every item in `missing.baseline` verifies green, or is logged as deferred | | 4 | Agent CLI gaps *(skipped in `tune`)* | Every requested agent CLI verifies green, or is explicitly declined | | 5 | Optimize | Verification re-run shows every approved fix gone from `findings`; each remaining one recorded as declined or deferred | | 6 | Final report | Report printed with a `Result` line first, every gap and finding accounted for, session file marked `complete` | Three rules that are easy to miss (detail in `procedure.md`): - **Blocking findings go first, in phase 3:** `no-package-manager`, `no-sudo`, `brew-bin-not-on-path`, `npm-global-bin-not-on-path` make installs fail or land invisibly. - **Phases 3 and 4 act only on `missing.*`.** Never reinstall or upgrade something already present. An upgrade is mutating and belongs to phase 5. - **Phase 5 verifies by re-running `detect_env.py`**, never from memory. PATH and rc-file fixes keep reporting until a new shell reads them: re-run in a fresh login shell, or log the finding as *fixed — needs new shell*. **Zsh config has one source of truth:** `assets/zshrc-config`, deployed by `cp`. Never hand-write its lines into `~/.zshrc`. Deploying it over an **existing** `~/.zshrc` is mutating (backup plus its own yes), and a blanket "do everything" never covers it. Detail: `procedure.md` § 3 and `optimize.md#oh-my-zsh-missing`. ## Step Completion Reports At the end of each phase, print one block. Each check maps to that phase's **Done when** cell; `√` pass, `×` fail, `—` skipped with its reason: ``` ◆ Phase 3 · Baseline gaps missing.baseline handled: √ 2/2 (uv 0.11 · node v22.14) blocking findings first: — none fired session file recorded: √ Result: PASS | PARTIAL | FAIL ``` `PASS` = the Done-when condition holds with nothing deferred. `PARTIAL` = it holds, but an item was deferred, declined, or failed. `FAIL` = the phase could not run; name why and apply the status rules below. ## Safety Beyond the additive/mutating rule: - Never run a third-party "debloat everything" script unattended. OEM audio/chipset tools can be load-bearing. - Never commit secrets, and never write an API key into a shell rc file. Auth for every agent CLI is its own interactive login after install. - Windows ARM64 (Snapdragon / Copilot+): prefer arm64 winget packages; say so when a tool is x64-only. - Report a failed step; do not work around it. Silently switching to `sudo`, `--force`, or `--break-system-packages` to make a command succeed is out of scope for this skill. ## Final Report Phase 6 prints the FINAL REPORT block from `references/report-template.md`, sourced from the session file. It opens with `Result:`, then one line per phase, then `Evidence:`, `Uncertainty:` and `Decision:`. Apply the **first** status rule that matches (full outcome map in the template): 1. **BLOCKED — reason**: the gap report could not be built (`detect_env.py` and the `detect.md` fallbacks both failed), or a blocking finding stayed unfixed so no requested install could run (no package manager and its install was declined or failed; no admin/sudo and no user-level path). 2. **PARTIAL — reason**: any step failed and was not fixed; a `high` finding is declined, deferred, or still in `findings` after the re-run without being recorded *fixed — needs new shell*; in `setup`, a `missing.baseline` item was declined or deferred; or the phase 5 verification re-run could not run. 3. **READY**: none of the above. Declined agent CLIs, declined or deferred low/medium findings, *fixed — needs new shell* items, and a run that found nothing to change are all READY. A user declining a change never produces BLOCKED by itself. A pause is not phase 6: it prints the pause output from `references/session.md`, which opens with `Result: PARTIAL — paused`. Example (a tune run with one fix awaiting a new shell): ``` ◆ Dev machine setup — FINAL REPORT Result: READY Machine: darwin / arm64 / macOS 15.4 Mode: tune ... Evidence: detect_env.py re-run in the same shell: 1 high still listed (the PATH fix); export line confirmed in ~/.zshrc, backup ~/.zshrc.bak.20260820094533 Uncertainty: npm-global-bin-not-on-path fixed — needs new shell (not re-checked in a login shell) Decision: No approval needed. Remaining action: open a new terminal, then run `claude --version` ``` ## Acceptance Criteria - `detect_env.py` printed valid JSON with `os`, `arch`, `tools`, `missing`, `findings`, and the phase-1 gap report was shown before anything was installed. - Mode was fixed before phase 3; in `tune`, phases 3 and 4 installed nothing. - Blocking findings were fixed at the top of phase 3, not deferred. - Phases 3 and 4 acted **only** on `missing.*`: nothing already present was reinstalled or upgraded. - Every command reached the user as a run-block: none in a table cell, none with an unresolved `<placeholder>` or an assumed cwd, each tagged `you run this` / `I can run this`. - The session file existed from phase 1 on, was rewritten at every Record step, and is `complete` by phase 6. - Every mutating step has its own recorded yes; every rc file edited has a backup path in the session file. - Phase 5 verified by **re-running** `detect_env.py`; the report's counts come from that re-run. - A Step Completion Report printed after each phase that ran. - The FINAL REPORT opened with a `Result` chosen by the first matching status rule, accounted for every gap and finding as fixed, declined, or deferred, and meets the four reader checks in `references/report-template.md`: result findable, facts apart from assumptions, claims traceable, next decision clear. **Expected output:** the FINAL REPORT block (`references/report-template.md`). ## Edge Cases No `python3`, Windows ARM64, WSL, containers and remote-SSH hosts, interrupted runs, and distros outside the shipped apt/dnf/pacman tables live in `references/edge-cases.md`. Machine states the probe reports as findings are in `references/optimize.md`, keyed by finding id.