v0.6.0 to v0.9.0

- description: "Set up or tune any machine — factory laptop or daily driver — on macOS, Linux, or Windows: report what's missing, install only that, then fix PATH, duplicate runtimes, shell config. Don't use for Dockerfiles, CI images, or single package installs."

- version: 0.6.0

- This is an orchestrator: per-OS command tables live in `references/`, so only the current platform loads.

- ## Additive vs mutating

- The load-bearing distinction for every approval in this skill:

- - **Additive** — installs something that is *absent*. Nothing working can break. Batch-approvable per phase.

- `curl | sh`, PATH rewrites, replacing a runtime. Needs an explicit **per-item yes**, with the risk named,

- and any rc file backed up first (`optimize.md` § top).

-

- On a daily driver, mutating steps are the real hazard — not missing packages. A prior yes never carries

- forward to another mutating item.

-

- ## Human-in-the-loop (mandatory)

-

- Every phase runs a strict five-step loop. Do not skip a step; do not batch phases into one approval.

-

- 1. **Present** — exactly what will run, as **run-blocks** (§ Presenting commands): each command, what it

- changes, and its **additive/mutating** tag.

- 2. **Approve** — wait for an explicit go-ahead. A blanket "do everything" covers additive steps only.

- 3. **Execute** — only what was approved. On failure, stop and re-present; never silently widen scope.

- 4. **Verify** — confirm the phase actually took (version checks, file presence, exit codes).

- 5. **Record** — write the outcome to the **session file** (§ Pausing and resuming) before moving on, so a

- pause, a crash, or a closed terminal never loses what was already decided and done.

-

- **Read-only probes are exempt from step 2** — `detect_env.py`, version checks, `winget list`, `brew outdated`.

- Say what you are running, then run it. The gate exists to guard *changes*; making the user approve a read that

- changes nothing trains them to rubber-stamp the approvals that matter.

-

- The session file *is* the running log (✓ / ✗ + evidence per item). The final report is built from it, never

- from memory.

-

- ## Presenting commands (run-blocks)

-

- Every command you propose ships as a **run-block**: a fenced block the user can copy whole and run without

- editing it first. Every phase, not just phase 5.

-

- **Never put a command in a table cell** — cells wrap mid-token and produce something nobody can copy. Tables

- carry `finding id · severity · what breaks today · additive/mutating` and *name* the mechanism ("Oh My Zsh

- installer, `curl | sh`"); the command goes in the block underneath.

-

- A run-block is:

-

- - **One item per block**, headed by the finding id or item name and its additive/mutating tag.

- - **Self-contained** — no assumed cwd (`cd` inside the block, or use an absolute path), no `$` prompt

- prefixes, no `<placeholders>`. If a value must come from the user (git identity, an npm prefix), **ask

- first, then present the block with it filled in.**

- - **One purpose per block.** Inspect and fix never share a block — pasting one must not run the other.

- - **Tagged with who runs it.** `you run this` for anything needing a password prompt (`chsh`), a GUI dialog

- (`xcode-select --install`), a browser login, or a shell replacement (`exec zsh -l`); otherwise

- `I can run this`. Says *where it runs*, never a substitute for additive/mutating, which says *what it risks*.

- - Followed by its **verify** block where one is worth running.

-

- Ask for approval as a numbered list, so the user answers `1` or `1,3` instead of retyping ids. Approved

- `you run this` blocks may then be concatenated into one paste-once block — built **only** from items that

- each already got their own yes, in approval order. A combined block is never the thing being approved.

-

- **Example** — two low findings, presented right:

-

- ````markdown

- | Finding | Sev | What breaks today | Tag |

- |---------|-----|-------------------|-----|

- | `login-shell-not-zsh` | low | zsh is installed but bash is still your login shell | mutating |

- | `oh-my-zsh-missing` | low | no completion/plugin baseline for zsh | additive |

-

- **1 · `login-shell-not-zsh`** — mutating · you run this (asks for your password; corporate policy or LDAP

- may refuse it, which is not a failure — we just skip it)

-

- ```bash

- chsh -s "$(command -v zsh)"

- ```

-

- **2 · `oh-my-zsh-missing`** — additive · I can run this (downloads and runs the installer from

- github.com/ohmyzsh, and creates `~/.zshrc`)

-

- ```bash

- sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

- ```

-

- Approve which — `1`, `2`, `1,2`, or `none`?

- ````

-

- ## Pausing and resuming

-

- Machine setup is long, interruptible work, so state lives on disk rather than in the conversation.

-

- **Session file:** `~/.dev-machine-setup/session.json` (PowerShell: `$HOME\.dev-machine-setup\session.json`).

- Create it at the end of phase 1 and rewrite it at every **Record** step — after each phase, and after each

- individual approve/decline/execute inside phases 2–5. Schema and the write command are in

- `references/session.md`.

-

- The user can say "pause" at any point. Answer with three things and nothing else: the session file path, what

- is left, and a **paste-once block of the remaining approved commands** so they can finish by hand if they

- never come back. Never leave a half-applied rc edit behind at a pause.

- Resuming needs no arguments — triggering the skill again is enough (phase 0).

- - Optional clone of `https://github.com/luongnv89/inbash` — preferred source for Unix/mac scripts this user

- already maintains.

- | `references/macos.md` | macOS: Homebrew, Node, Python+uv, zsh |

- | `references/linux.md` | Linux: apt/dnf/pacman, NodeSource LTS, python3-pip |

- | `references/session.md` | Phase 0 and every **Record** step — session-file schema, write command, reconcile rules |

- | `references/edge-cases.md` | No python3, Windows ARM64, WSL, containers, re-runs, inbash distro limits |

- Every phase runs the five-step loop above. Do not advance until the current phase verifies green, self-skips

- on an empty gap set, or is explicitly deferred by the user.

-

- ### 0. Resume check

-

- - Read `~/.dev-machine-setup/session.json`. **Absent, or `status: complete`** → say nothing, start at phase 1.

- - **Present and unfinished** → show one screen (mode, phases done, items done / approved-but-not-run /

- declined, next step) and offer **resume** (default) · **start fresh** · **discard**.

- - On resume, **always re-run `detect_env.py` first and reconcile** — the machine moved on while you were away,

- possibly because the user pasted the remaining blocks themselves. Rules in `references/session.md`.

- - Stale — `machine` mismatches this host, or the file is over 30 days old — say so and default to start fresh.

- - **Discard** deletes the file immediately; a discarded session left on disk is what makes a later resume

- replay decisions the user threw away. **Start fresh** keeps it until phase 1 overwrites it.

-

- **Phase 0 done when:** the run is resuming from a reconciled session file, or starting clean with any

- discarded session deleted.

-

- ### 1. Detect and build the gap report

-

- - **Present:** say what it does — read-only, no network, no changes; reports OS, arch, package managers,

- installed versions, what's missing, what's misconfigured. Read-only, so no approval needed.

- - **Execute:** `python3 <skill-dir>/scripts/detect_env.py`, pathed from the skill's own directory, never the

- user's cwd. Needs Python 3.9+; without `python3`, use the fallbacks in `references/detect.md`.

- - **Verify:** the JSON parses and contains `os`, `arch`, `tools`, `missing`, `findings`.

-

- Then **show the gap report** as three short lists before doing anything else:

-

- ```

- Present: git 2.55 · node v26.7 · python 3.14 · uv 0.11 · zsh · claude · codex

- Missing: baseline → uv agents → pi, opencode

- Findings: 1 high · 0 medium · 2 low (npm-global-bin-not-on-path, path-duplicates, oh-my-zsh-missing)

- ```

-

- Read **only** the matching OS reference (`windows.md` / `macos.md` / `linux.md`), and confirm the mode if the

- request was ambiguous.

-

- **Phase 1 done when:** the gap report JSON is captured, the three lists are shown, the mode is fixed, the

- matching OS reference is loaded, and the session file exists with phase 1 recorded `done`.

-

- ### 2. Debloat — fresh Windows only, opt-in

-

- Skip entirely unless the machine is Windows **and** the user asked to clean OEM junk — never on a daily

- driver, container, or remote host. Factory Windows boxes ship trial AV, OEM utilities, and partner games

- (inspired by [XFreeze](https://x.com/xfreeze/status/2090189407659999603)). **List before delete.**

-

- - **Present** the read-only inventory commands (`winget list`, `Get-AppxPackage`) as a run-block.

- - **Execute** `references/windows.md` § Inventory; build a `keep / review / remove-candidate` table.

- - Then **per removal** (mutating): one run-block per package naming what is lost, an explicit yes for that

- one package, then execute, verify it no longer lists, and record it.

-

- **Phase 2 done when:** skipped with a reason logged, or the inventory is shown and every removal is

- individually confirmed and verified.

-

- ### 3. Baseline gaps *(skipped in `tune`)*

-

- **Blocking findings first.** Four findings make installs fail or land invisibly, so they are fixed *here*

- rather than in phase 5: `no-package-manager`, `no-sudo`, `brew-bin-not-on-path`, `npm-global-bin-not-on-path`.

- Fix per `references/optimize.md`, then continue. (A missing package manager arrives as a finding, not as a

- `missing.baseline` entry.)

-

- Then act only on `missing.baseline`. **Empty list → print `✓ baseline complete — nothing to install` and skip

- to phase 4.** Never reinstall or upgrade something already present — an upgrade is mutating, and belongs to

- phase 5.

-

- | Missing item | Install command lives in |

- |--------------|--------------------------|

- | `git` (+ curl, wget, editor) | the OS reference § Baseline |

- | `zsh` / Oh My Zsh | `macos.md` / `linux.md` § Zsh (Unix only; Windows keeps PowerShell) |

- | `node`, `npm` | the OS reference § Node.js LTS |

- | `python3`, `uv` | the OS reference § Python |

-

- - **Present:** one run-block per missing item, tagged additive. Flag anything that would touch an existing

- Node or Python — that is mutating and needs its own yes.

- - **Verify:** `git --version`, `node -v`, `npm -v`, `python3 --version`, `uv --version` (Unix also

- `zsh --version`) succeed for the items just installed.

-

- **Phase 3 done when:** every item that was in `missing.baseline` verifies green, or is logged as deferred.

-

- ### 4. Agent CLI gaps *(skipped in `tune`)*

-

- Acts only on `missing.agents`, in this order: Claude Code → Codex → Pi → OpenCode. **Empty list → print

- `✓ all agent CLIs present` and skip.** Ask which the user actually wants; do not assume all four.

-

- - **Present:** one run-block per CLI from `references/agent-clis.md`, with any `curl | sh` URL visible inside

- the block (mutating — needs its own yes).

- - **Execute:** install only the requested missing ones. Requires Node on PATH from phase 3.

- - **Verify:** each prints a version (`claude --version`, `codex --version`, `pi --version`,

- `opencode --version`). If a just-installed CLI is "not found", that is

- `optimize.md#npm-global-bin-not-on-path` — carry it into phase 5 rather than reinstalling.

-

- Auth is the first interactive run of each CLI. Never write API keys into the log or into `~/.zshrc`.

-

- **Phase 4 done when:** every requested agent CLI verifies green, or is explicitly declined.

-

- ### 5. Optimize

-

- Acts on `findings[]`, highest severity first. Each finding's `fix_ref` names its section in

- `references/optimize.md`; read only the sections for findings that actually fired.

- - **Present** one table — finding id · severity · what breaks today · **additive/mutating** — then one

- run-block per finding beneath it (§ Presenting commands). No command goes in the table.

- - **Approve:** ask as a numbered list. Additive fixes can be batched. **Every mutating fix needs its own

- yes** — and back up any rc file before editing it. Record each decision as it is made, not at the end.

- - **Execute** approved fixes only. A declined finding is recorded, not retried.

- - **Verify** by re-running `detect_env.py` and confirming the fixed ids are gone from `findings`. That re-run

- is the phase's proof — never verify from memory. **PATH and rc-file fixes keep reporting until a new shell

- reads them:** re-run in a fresh login shell (`zsh -l -c '<skill-dir>/scripts/detect_env.py'`, or a new

- PowerShell window); with no fresh shell available, confirm the rc file contains the line and log the finding

- as *fixed — needs new shell*.

- Deep checks (`brew outdated`, `winget upgrade`, `npm outdated -g`) need network and are opt-in — `optimize.md`

- § Deep checks. Never volunteer disk cleanup during a setup run.

- **Phase 5 done when:** the verification re-run shows every approved fix gone from `findings` — or logged as

- *fixed — needs new shell* — and each remaining finding is recorded as declined or deferred with its severity.

- ### 6. Final report

- Nothing executes. Assemble the report from the session file (`references/report-template.md`), then set its

- `status` to `complete` so the next run starts clean instead of offering a resume.

- **Phase 6 done when:** the report is printed with a `Result` line, every gap and finding is accounted for as

- fixed, declined, or deferred, and the session file is marked `complete`.

- Beyond the additive/mutating rule above:

- the session file. `Result` is decided by these three rules:

- - Blocking findings (`no-package-manager`, `no-sudo`, `brew-bin-not-on-path`, `npm-global-bin-not-on-path`)

- were fixed at the top of phase 3, not deferred.

- - The session file existed from phase 1 on, was rewritten at every Record step, and is `complete` by phase 6 —

- an interrupted run resumes by triggering the skill again.

- - Phase 5 verified by **re-running** `detect_env.py`; the report's counts come from that re-run. On a resumed

- run that re-run and its reconcile happened before any new work.

- No `python3`, Windows ARM64, WSL, containers and remote-SSH hosts, interrupted runs, and inbash distro limits

- live in `references/edge-cases.md`. Machine states the probe reports as findings are in `references/optimize.md`,

- keyed by finding id.