os-init/macos/AGENTS.md

AGENTS.md

Project Overview

This directory maintains a single shell script for initializing a newly set up macOS user account. Except for this file, do not split functionality into additional scripts, configuration generators, or other languages. Keep the script flat, easy to review, and directly executable on the target machine, in the same style as ../debian/debian13-init.sh.

Scope

This file applies to the macos/ directory. The repository-level AGENTS.md still applies; where the two conflict, this file takes precedence.

Development Principles

• Write Bash and use #!/usr/bin/env bash as the first line.
• macOS ships bash 3.2 as /bin/bash. Do not use associative arrays, mapfile, ${var,,}, or other bash 4+ features.
• Keep the script flat: a short comment followed by the commands it explains, with no helper functions unless repetition clearly demands one.
• Prefer defaults write for per-user preferences. Each write must be safe to repeat. Use -bool, -int, or -string explicitly so the stored type is stable.
• Double-quote variables, and use "${HOME}" rather than ~ inside strings.
• If a key only works on a specific macOS release, say so in a comment and keep the version check in the script in sync.
• Comments should explain reasons, compatibility constraints, or risks rather than restating each line of code.

Security Requirements

• Never store passwords, tokens, private keys, or other sensitive information in the repository, command-line arguments, or logs.
• Do not execute unverified remote content with patterns such as curl ... | sh or wget ... | bash. This rules out the official Homebrew installer; install it by hand if needed.
• Do not change SSH or Remote Login, the firewall, FileVault, Gatekeeper, System Integrity Protection, networking, disks, boot configuration, or user credentials without an explicit opt-in switch and a prominent warning.
• The script runs as the login user. Do not add sudo, and do not write preferences into root's domain.

Behavior and Output

• Check the OS and version first; fail with an actionable message on stderr and a nonzero exit status.
• Restart only the apps whose preferences were changed, once, at the end.
• Features with significant impact or machine-specific behavior must be disabled by default and run only when explicitly enabled.
• Mention in the final message anything that needs a logout or a restart to take effect.

Change Constraints

• Keep changes focused on macOS initialization. Do not add unrelated functionality.
• Do not perform broad rewrites solely for style. Preserve existing behavior.
• Clearly state in the delivery notes when a change alters system behavior or security policy.

Validation

After modifying the script, run at least:

bash -n ./*.sh

If ShellCheck is installed, also run:

shellcheck ./*.sh

The development machine is usually the target machine. Unless explicitly authorized by the user, do not run the script itself or defaults write on it while testing; check a key with defaults read or defaults read-type instead. List any behavior that could not be safely validated and recommend running the script twice on a fresh macOS user account.

Delivery Notes

When completing a change, briefly describe:

• Which initialization behavior changed.
• Whether default behavior or system security policy changed.
• Which static checks or tests were run.
• Which operations still require validation on a fresh macOS user account.