os-init/debian/AGENTS.md

AGENTS.md

Project Overview

This directory maintains a single shell script for initializing a newly installed Debian system. Except for this file and essential project documentation, do not split functionality into additional scripts, configuration generators, or other languages. Keep the initialization logic centralized, easy to review, and directly executable on the target machine.

Scope

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

Target Machine

• During development, debugging, and validation, you may connect to the target machine with ssh 192.168.122.130.
• When the current user lacks sufficient privileges on the target machine, you may elevate privileges with sudo.

Development Principles

• Write Bash and use #!/usr/bin/env bash as the first line.
• New code must be compatible with the current Debian stable release. If a command or option requires a specific version, document it in a comment or the README.
• The script must support repeated execution. Creating users, installing packages, writing configuration, and enabling services should be idempotent wherever possible. Avoid duplicate entries and failures caused by resources that already exist.
• Keep the single-script design. Prefer small functions with clear responsibilities and use a main function as the entry point.
• Prefer set -Eeuo pipefail, and explicitly handle commands that may be expected to fail.
• Double-quote variables unless word splitting or glob expansion is intentionally required. Use local for local variables and clear names for constants and environment variables.
• Prefer native Debian tools and repositories. Do not introduce third-party repositories, runtimes, or external dependencies without a valid reason.
• Comments should explain reasons, compatibility constraints, or risks rather than restating each line of code.

Security Requirements

• Check for root privileges before operations that require them and provide a clear error message. Do not silently elevate privileges inside the script.
• 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.
• Download external files over HTTPS and verify fixed versions, checksums, or signatures whenever possible.
• Confirm target files and directories before changing system configuration. When replacing important configuration, preserve a recoverable backup or use a reviewable atomic write.
• Avoid broad or irreversible commands, including recursive deletion with unvalidated variables, globally relaxed permissions, and unconditional firewall resets.
• Do not change SSH login policy, network connectivity, disk partitions, boot configuration, or existing user credentials without explicit authorization. If the project explicitly requires such an operation, provide a prominent warning and an explicit opt-in switch.
• Scope noninteractive APT settings to only the commands that require them. Do not permanently change the user's environment.

Behavior and Output

• Early in startup, check the runtime environment, Debian version, privileges, and required commands. Fail with actionable error messages.
• Print concise and clear status messages for important steps. Write errors to standard error and exit with a nonzero status.
• Prefer environment variables with safe defaults or command-line options for user-selectable features, and provide --help. Do not unexpectedly block unattended execution.
• Features with significant impact or machine-specific behavior must be disabled by default and run only when explicitly enabled.
• Combine package installation into as few apt-get install operations as practical, and avoid unnecessary apt-get upgrade or distribution upgrades.
• Do not assume a systemd service exists. Confirm that the relevant package and service unit are available before enabling or restarting a service.

Change Constraints

• Keep changes focused on Debian initialization. Do not add unrelated functionality.
• Do not perform broad rewrites solely for style. Preserve existing behavior and configuration options.
• Give new configuration options safe defaults and update script help and related documentation.
• Clearly state in the delivery notes when a change alters system behavior, default packages, or security policy.

Validation

After modifying the script, run at least:

bash -n ./*.sh

If ShellCheck is installed, also run:

shellcheck ./*.sh

For argument parsing or pure function logic, use temporary directories and mock input for targeted tests. Unless explicitly authorized by the user, do not install or remove packages, modify /etc, manage users, change networking, restart services, or reboot the current development machine during testing. List any system-level behavior that cannot be safely validated and recommend validation steps in a fresh Debian virtual machine.

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 in a fresh Debian virtual machine.