Files
nixos-setup/GUIDELINES.md
T
2026-09-11 16:22:22 -04:00

6.7 KiB
Raw Blame History

Agent Guidelines — nixos-setup

Rules and best practices for any AI agent working in this repository. Read this file before making any changes.


Mandatory First Step — Always Present a Plan

Before making any change to this repository, you MUST present a short plan to the user and wait for their approval. This applies to every task, no matter how small.

Your plan must include:

  1. What you intend to change (files, options, packages)
  2. Why the change is needed
  3. How you will do it (which files you will edit, in what order)
  4. What you will NOT do (e.g., "I will not run any builds")

Only after the user approves the plan may you proceed with edits.


Hard Rules — Never Break These

❌ NEVER run builds or system switches — ZERO EXCEPTIONS

DO NOT RUN ANY OF THESE COMMANDS AT ANY TIME, FOR ANY REASON:

nixos-rebuild switch / test / build / dry-build
nh os switch / test / build
skyg os switch / test / build
skyg remote switch / test / build
skyg hm switch / build
nix build
nix flake check
docker/podman build

Why:

  • These commands take 20–40+ minutes
  • They consume significant CPU/RAM on the user's machine
  • They can block the user from their own work
  • They can break the live system if something is wrong
  • The user MUST control when and what gets built

Your job: Make correct edits to source files. The user validates and runs builds themselves.

Even if the user says "go ahead": Do NOT run these. Your role is to write good Nix, not execute it.

❌ NEVER edit flake.lock by hand

This file is managed exclusively by nix flake update. Editing it manually will corrupt the lock file and break all builds.

❌ NEVER edit *.hardware-configuration.nix files

These are generated by nixos-generate-config and reflect the physical hardware. Edits will be overwritten on the next hardware scan and can render a system unbootable.

❌ NEVER touch secrets

Do not read, write, or delete files in secrets/. Encrypted .age files must only be managed with agenix via the skyg secrets commands. Do not modify secrets.nix unless the user explicitly asks and explains the full context.

❌ NEVER add imports = [...] to host files

Host files (hosts/<hostname>.nix) do not use imports. All modules are composed through the makeNixOs call in flake.nix via modules/main.nix. Adding imports to a host file breaks the composition model.

❌ NEVER modify GUIDELINES.md unless explicitly requested by the user

You must live and die by these rules and hold yourself accountable to them. These are not suggestions — they are non-negotiable.

KEEP EVERYTHING CONCISE, shorter concise comments are preferable, less jargon and more common words.


Safe Operations

These are always safe to perform without asking:

  • Reading any .nix, .md, or config file
  • Editing host files (hosts/<hostname>.nix) to add/remove packages or options
  • Editing module files in modules/
  • ABOUTME.md should be seen as the 'living memory' of a folder, it should contain general information about what's in the folder and capture decisions made at the time of development the features.
  • Keep ABOUTME.md current: whenever you add, remove, or rename files, options, commands, or behaviour in a folder, check that folder's ABOUTME.md still matches reality and update it as part of the same change. If you discover an existing ABOUTME.md that is stale (dead file/option/command references, missing entries, wrong paths), fix it in the same way.
  • Adding new packages to pkgs/
  • Editing configs in configs/

When In Doubt

If you are unsure whether a command is safe, assume it is NOT SAFE and don't run it.

Instead: describe what you would do and ask the user for permission.


NixOS Conventions in This Repo

Option Namespace

All custom options live under skyg.*. Never introduce options under any other top-level namespace. Check modules/lib.nix for the full skyg.* structure.

# Correct
skyg.nixos.desktop.enable = true;
skyg.nixos.server.services.comfyui.enable = true;

# Wrong — do not invent new top-level attrs
myOptions.desktop.enable = true;

Enable/Disable Pattern

All modules follow lib.mkIf cfg.enable { ... }. Always gate config behind an enable option. Default should be false unless the feature is universally required.

Host Files vs Shared Modules

  • Host-specific (one machine only): goes in hosts/<hostname>.nix
  • Shared (multiple hosts): goes in the appropriate modules/nixos/ or modules/core/ submodule
  • When in doubt, keep it in the host file and extract later if reuse emerges

Package Placement

  • Packages needed on all desktops → modules/nixos/desktop/default.nix (non-slim mode)
  • Packages for one host only → environment.systemPackages in the host file
  • Custom/third-party packages not in nixpkgs → pkgs/<name>/default.nix with an overlay in modules/core/default.nix

Home Manager

Home Manager config lives inside home-manager.users.<name> blocks. Do not mix system-level and HM-level options. The HM entry point is modules/home/default.nix.

Greeter

Both desktop hosts (fwbook, hl-fwdesk) use DankMaterialShell greeter via:

services.displayManager.dms-greeter = {
  enable = true;
  compositor.name = "niri";
  configHome = "/home/<username>";
};

Do not configure services.greetd manually on these hosts — the DMS module handles it.


Navigation Tips

Question Where to look
What hosts exist? hosts/ + docs/hosts/README.md
What does a skyg.* option do? modules/ — find the defining .nix file
What flake inputs are available? Top of flake.nix
What binary caches are configured? modules/core/nix-substituters.nix
What secrets exist? secrets.nix (lists files + authorized keys)
What custom packages exist? pkgs/
Full API reference docs/modules/README.md
Host details (ports, services, hardware) docs/hosts/README.md

Validation Without Building

If you want to verify syntax without triggering a build, these are safe:

# Check Nix expression syntax only (fast, safe, no eval)
nix-instantiate --parse <file>.nix

But even these are optional. The user will validate by running nh os switch themselves.

Golden rule: When in doubt, don't run anything. Just describe your changes.


Commit / Branch / Git Policy

  • Do NOT commit changes or create branches unless the user explicitly asks
  • Do NOT git add, git commit, or git push autonomously
  • You may run git add only if required for a Nix evaluation (e.g., new files must be tracked for flakes)
  • Describe what you changed in your final message so the user can review before committing