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
effort: high
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."
metadata:
    version: 0.9.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. Never a fresh-install-only script: 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 is an orchestrator. 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.

Tie-break: setup wins whenever the request mentions missing pieces *at all* — "verify what's missing

and optimize it" is setup. Choose tune only when the ask is limited to what is already installed; still

unsure once the gap report is on screen, ask 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, in full. The

four that must be in your head 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, and any rc file backed

up first. 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 and resume protocol: references/approvals.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.
• Admin/sudo (or winget) for system packages. Without it, only user-level installs are possible — say which

requests that blocks rather than failing them silently.

Reference files (load only what you need)

Procedure

Full step-by-step detail for every phase is in references/procedure.md — read it at phase 0 and keep it

open. This table is the spine: the order, and the condition that lets you advance. Do not advance until the

current phase verifies green, self-skips on an empty gap set, or is explicitly deferred by the user.

Three things bite often enough to belong here rather than only in the detail file:

• 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: one source of truth

ZSH_THEME="wedisagree", the four-plugin list, and the starship init zsh line all live in

assets/zshrc-config, which this skill ships and deploys by cp. Never hand-write those lines into

~/.zshrc instead — edit the asset. It is a vendored fork of luongnv89/inbash's config: upstream fixes

do not flow in, which is the price of having no dependency.

Deploying it is not always additive. cp assets/zshrc-config ~/.zshrc overwrites an existing ~/.zshrc,

so it is additive only when none is present and mutating — backup plus its own yes — when one is. A

blanket "do everything" approval never covers the mutating case. Full split in

optimize.md#oh-my-zsh-missing.

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.
• A failed step is reported, not worked around. Silently switching to sudo, --force, or

--break-system-packages to make a command succeed is out of scope for this skill.

Verification report

Phase 6 prints the FINAL REPORT block from references/report-template.md — one line per phase, sourced from

the session file. Result is one of:

• READY — no unresolved high findings, and in setup no baseline gap left unfilled. Declined agent CLIs

and deferred low/medium findings are still READY.

• PARTIAL — a step failed non-fatally, or a high finding was declined.
• BLOCKED — a required phase could not run: no package manager, no sudo for a needed system install, or

approval withheld for a step everything else depends on.

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.
• The FINAL REPORT printed with a Result of READY / PARTIAL / BLOCKED and every gap and finding accounted

for as fixed, declined, or deferred.

• quick_validate.py exits 0 on the shipped SKILL.md.

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.