dev-machine-setup

Imported from ryanspletzer/dev-machine-setup (AGENTS.md). Install upstream with npx skills add ryanspletzer/dev-machine-setup. Copyright stays with the author.

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, Antigravity) when working with code in this repository.

Project Overview

Cross-platform dev machine setup automation for macOS, Windows, Ubuntu, Debian, and Fedora. Each platform has its own directory with an entry-point script, an automation engine, and a vars.yaml configuration file.

Architecture

Platform Automation Engines

All platforms share the same flow: install prerequisites, load vars.yaml, install packages by category, configure Git, run custom commands, run custom script, clean up.

Configuration: vars.yaml

Each platform's vars.yaml is the single source of truth. Package lists are flat YAML arrays grouped by category:

• OS packages: homebrew_formulae / homebrew_casks / choco_packages / apt_packages / snap_packages / dnf_packages / flatpak_packages / appimage_packages
• Cross-platform: powershell_modules, pipx_packages, uv_tools, npm_global_packages, pnpm_global_packages, bun_global_packages, dotnet_tools, vscode_extensions
• Git config: git_user_email, git_user_name
• Custom commands: custom_commands_user (non-elevated), custom_commands_elevated (sudo). Entries support an optional creates file path; the command is skipped once that file exists (keeps reruns idempotent)
• Custom script: custom_script (path to a script run at the end)

Key Differences Between Platforms

• macOS uses flat string arrays for homebrew_formulae and homebrew_casks. All other platforms use objects with a name key.
• Windows choco_packages objects support additional parameters and prerelease keys beyond name.
• Windows custom_commands is a single list (not split into user/elevated) since the script already runs as Administrator.
• Ubuntu has additional external_apt_repositories (deb822 format) and apt_packages_prereqs for bootstrap dependencies.
• Ubuntu uses supported_architectures on some packages to skip amd64-only software on ARM64.
• Fedora has external_dnf_repositories (yum_repository format) and dnf_packages_prereqs for bootstrap dependencies.
• Fedora uses supported_architectures with x86_64/aarch64 values (not amd64/arm64 like Ubuntu).
• Debian shares the APT package format with Ubuntu but uses Flatpak instead of Snap (flatpak_packages like Fedora). Debian prerequisites include gnupg instead of software-properties-common (which is Ubuntu-only for PPA support). Ubuntu PPAs (ppa.launchpad.net URLs) are not compatible with Debian. Docker and Microsoft repos use /linux/debian instead of /linux/ubuntu.
• Fedora uses flatpak_packages (Flathub app IDs) instead of Snap packages.
• Ubuntu/Debian/Fedora support appimage_packages for generic AppImage installation. Each entry has name, url, and optional fields (comment, categories, mime_types, no_sandbox, checksum, supported_architectures). Cursor is installed this way on Linux; macOS uses Homebrew cask cursor, Windows uses Chocolatey cursoride. All platforms reuse the vscode_extensions list for Cursor extension installation.
• uv_tools installs Python CLI tools via uv tool install. On macOS/Windows, pipx_packages is empty (uv is available via Homebrew/Chocolatey); on Linux, pipx_packages retains only uv (pipx bootstraps uv, then uv manages the rest). The uv tools step is guarded on uv being installed -- if uv is not on PATH, the step is silently skipped.
• pnpm_global_packages / bun_global_packages install global CLI tools via pnpm add -g / bun add -g. Like uv_tools, both steps are guarded on the tool being installed -- if pnpm / bun is not on PATH, the step is silently skipped. The binaries are installed as ordinary package-manager entries: Homebrew (pnpm, bun formulae) on macOS, Chocolatey (pnpm, bun) on Windows, and via npm_global_packages (pnpm, bun) on Linux. pnpm needs its global bin directory on PATH, so the steps export PNPM_HOME (~/Library/pnpm on macOS to match the shell configs, ~/.local/share/pnpm on Linux, %LOCALAPPDATA%\pnpm on Windows) and prepend $PNPM_HOME/bin (pnpm's default global bin dir), so no pnpm config file is written.

Running the Setup Scripts

# macOS
cd macOS
chmod 700 ./setup.sh
./setup.sh -e your.email@example.com

# Ubuntu
cd ubuntu
chmod 700 ./setup.sh
./setup.sh -e your.email@example.com

# Debian
cd debian
chmod 700 ./setup.sh
./setup.sh -e your.email@example.com

# Fedora
cd fedora
chmod 700 ./setup.sh
./setup.sh -e your.email@example.com

# Windows (run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force
cd windows
.\setup.ps1 -e your.email@example.com

Common flags: -v (verbose, repeatable), -e (git email), -n (git name), -p (prerequisites only, macOS/Ubuntu/Debian/Fedora), -c (CI mode, skip interactive sudo prompts, macOS/Ubuntu/Debian/Fedora).

Ansible Tags (macOS/Ubuntu/Debian/Fedora)

The Ansible playbooks use tags to run specific sections:

# Run only Homebrew tasks
ansible-playbook setup.yaml --tags homebrew

# Run only VS Code extension installation
ansible-playbook setup.yaml --tags vscode

Editing Guidelines

Adding Packages

Add to the appropriate list in the platform's vars.yaml. Keep entries alphabetically sorted within their group. Comment groups organize packages by purpose.

When adding to multiple platforms, use the correct format for each (flat strings for macOS, name: objects for Ubuntu/Debian/Fedora/Windows).

Commit Messages

Follow conventional commits:

type(scope): brief description

Types: feat, fix, docs, style, refactor, test, chore. Scope is typically the platform name: macOS, windows, ubuntu, debian.

Code Style

• Shell scripts: #!/bin/sh, set -e, snake_case functions
• PowerShell: #Requires directives, PascalCase, Get/Test/Set pattern with verbose logging
• YAML: 2-space indent, comments above entries, group related packages with comment headers
• Ansible tasks: use ignore_errors: yes for package installs, changed_when for idempotency, tag every task

Design Principles

• Flat configuration -- no nested package structures
• Declarative -- vars.yaml describes desired end state
• Idempotent -- safe to run multiple times
• Extend through data -- add packages to vars.yaml, not code to scripts