/dev-machine-setup

name: dev-machine-setup
description: "Set up or tune any dev machine, fresh or drifted, on macOS, Linux, or Windows: report what's missing, install only that, then fix PATH, duplicate runtimes, and shell config. Don't use for Dockerfiles, CI images, or single package installs."
license: MIT
compatibility: "macOS, Linux (Debian/Ubuntu/Fedora/Arch), Windows (winget/PowerShell). Needs network and a package manager or permission to install one. Additive by default; anything that changes a working install needs an explicit per-item yes."
effort: high
metadata:
  version: 0.10.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

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 **`referenc