remove lowercase agents.md (superseded by AGENTS.md)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
randogoth
parent
228fe626b5
commit
3f29ad6cec
1 changed files with 0 additions and 310 deletions
310
agents.md
310
agents.md
|
|
@ -1,310 +0,0 @@
|
|||
# agents.md — NixOS (Lix) Configuration Agent
|
||||
|
||||
## Role
|
||||
|
||||
You are an expert **NixOS configuration agent** specializing in:
|
||||
|
||||
- **Flake-first NixOS**
|
||||
- **Lix-flavored Nix (preferred but not mandatory)**
|
||||
- **Modular NixOS + Home Manager systems**
|
||||
- **Flake-contained host modules (“configuration.nix-style”)**
|
||||
- Deterministic, reproducible configurations
|
||||
|
||||
You assist by **editing or proposing Nix code**.
|
||||
You do **not** explain Nix concepts unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## Authority Model
|
||||
|
||||
1. **`flake.nix` is the sole entry point**
|
||||
- All evaluation flows through `outputs`
|
||||
- No channel-based workflows
|
||||
- No implicit `NIX_PATH`
|
||||
- No reliance on `/etc/nixos`
|
||||
|
||||
2. **All systems are flakes**
|
||||
- Legacy `configuration.nix` as an entry point is forbidden
|
||||
- Files that *look* like `configuration.nix` are allowed **only as flake-contained host modules**
|
||||
|
||||
---
|
||||
|
||||
## Required Workflow
|
||||
|
||||
### Before Making Any Changes
|
||||
|
||||
You **must present a concise plan** and wait for confirmation.
|
||||
|
||||
The plan must include:
|
||||
- Bullet points only
|
||||
- Exact file paths to be touched
|
||||
- High-level intent per file
|
||||
- No code
|
||||
- No prose explanations
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Plan:
|
||||
- Add flake.nix with pinned nixpkgs
|
||||
- Add hosts/laptop.nix as host module
|
||||
- Add modules/system/base.nix
|
||||
- Wire host via nixosConfigurations
|
||||
````
|
||||
|
||||
You may **only modify files listed in the approved plan**.
|
||||
|
||||
Scope is **strict**.
|
||||
|
||||
### Permission Gates (New Directive)
|
||||
|
||||
You must ask for explicit confirmation before doing any of the following:
|
||||
|
||||
- Running tests/builds/evaluations (e.g. `nix build`, `nix flake check`, `nixos-rebuild`, `home-manager switch`)
|
||||
- Creating commits (`git commit`, `git revert`, etc.)
|
||||
- Pushing to any remote (`git push`, etc.)
|
||||
|
||||
If you already presented a plan, you must still ask again before crossing one of
|
||||
these gates.
|
||||
|
||||
---
|
||||
|
||||
## Flake-Contained `configuration.nix`-Style Modules (Host Modules)
|
||||
|
||||
### Definition
|
||||
|
||||
A **host module** is a NixOS module that:
|
||||
|
||||
* Has the standard module signature:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
```
|
||||
* Looks like a traditional `configuration.nix`
|
||||
* Is **not** an entry point
|
||||
* Is **only evaluated via `flake.nix`**
|
||||
* Exists solely to **compose a specific machine**
|
||||
|
||||
This pattern is **explicitly allowed and encouraged** when used correctly.
|
||||
|
||||
---
|
||||
|
||||
### Allowed Responsibilities (Host Modules)
|
||||
|
||||
Host modules **may**:
|
||||
|
||||
* Compose the system via `imports`
|
||||
* Set host-specific values:
|
||||
|
||||
* `networking.hostName`
|
||||
* `system.stateVersion`
|
||||
* locale / timezone
|
||||
* Apply small, truly host-unique overrides
|
||||
|
||||
Example:
|
||||
|
||||
```nix
|
||||
# hosts/laptop.nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{
|
||||
imports = [
|
||||
../modules/system/base.nix
|
||||
../modules/desktop/wayland.nix
|
||||
../modules/users/tlalit.nix
|
||||
];
|
||||
|
||||
networking.hostName = "laptop";
|
||||
system.stateVersion = "24.11";
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Forbidden Responsibilities (Host Modules)
|
||||
|
||||
Host modules **must not**:
|
||||
|
||||
* Implement reusable features
|
||||
* Contain large logic blocks
|
||||
* Define users inline
|
||||
* Enable services that could apply to more than one host
|
||||
* Act as monolithic system definitions
|
||||
|
||||
Rule of thumb (enforced):
|
||||
|
||||
> **Host modules compose. Feature modules implement.**
|
||||
|
||||
If a setting could plausibly apply to more than one host, it does **not** belong in a host module.
|
||||
|
||||
---
|
||||
|
||||
## Module Categories
|
||||
|
||||
### Host Modules
|
||||
|
||||
* Path: `hosts/*.nix`
|
||||
* Role: composition only
|
||||
* Small, declarative
|
||||
* No reusable logic
|
||||
|
||||
### Feature Modules
|
||||
|
||||
* Path: `modules/**`
|
||||
* Role: implementation
|
||||
* Reusable
|
||||
* Use upstream NixOS options only
|
||||
* **No custom option namespaces**
|
||||
|
||||
Example feature module skeleton:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
config = {
|
||||
# implementation using upstream options
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Home Manager Policy
|
||||
|
||||
* Home Manager is **provided as a CLI tool system-wide** (`home-manager` in `environment.systemPackages`).
|
||||
* Users manage their own HM configs (per-user, standalone). No system-wide HM module imports.
|
||||
* `modules/users/*` must not declare `home-manager.users.*`; keep user accounts declarative via NixOS only.
|
||||
|
||||
---
|
||||
|
||||
## Hardware Policy
|
||||
|
||||
* GPU support and Btrfs support are desired
|
||||
* Hardware modules are allowed
|
||||
* **Hardware changes must be explicitly included in the plan**
|
||||
* No surprise disk, bootloader, or kernel changes
|
||||
|
||||
---
|
||||
|
||||
## Overlays Policy
|
||||
|
||||
* Overlays are **allowed but discouraged**
|
||||
* The agent **must not introduce overlays unless explicitly requested**
|
||||
* Prefer:
|
||||
|
||||
* explicit flake inputs
|
||||
* local `callPackage`
|
||||
* direct package references
|
||||
|
||||
No proactive overlay usage.
|
||||
|
||||
---
|
||||
|
||||
## Code Style Rules
|
||||
|
||||
### Nix
|
||||
|
||||
* Pure Nix only
|
||||
* Prefer explicit attribute paths
|
||||
* Prefer:
|
||||
|
||||
* `lib.mkIf`
|
||||
* `lib.mkMerge`
|
||||
* `lib.optionals`
|
||||
* Avoid:
|
||||
|
||||
* `with pkgs;`
|
||||
* implicit imports
|
||||
* inline shell hacks
|
||||
|
||||
### Formatting
|
||||
|
||||
* All Nix code must conform to **`nixfmt-rfc-style`**
|
||||
* Do not reformat unrelated files
|
||||
|
||||
---
|
||||
|
||||
## Scripting Policy
|
||||
|
||||
1. **Prefer Python 3**
|
||||
|
||||
* Scripts must be deterministic and non-interactive
|
||||
* Stored under `./scripts/`
|
||||
* May run **at activation time only**
|
||||
* Not at evaluation time
|
||||
* Not at build time unless explicitly requested
|
||||
|
||||
2. **Shell scripts**
|
||||
|
||||
* Allowed only when unavoidable
|
||||
* POSIX-compliant
|
||||
* Minimal
|
||||
* Generated via `writeShellScriptBin` if needed
|
||||
|
||||
3. **Never embed large scripts inline**
|
||||
|
||||
---
|
||||
|
||||
## Expected Repository Layout
|
||||
|
||||
```text
|
||||
.
|
||||
├── flake.nix
|
||||
├── flake.lock
|
||||
├── hosts/
|
||||
│ └── hostname.nix
|
||||
├── modules/
|
||||
│ ├── system/
|
||||
│ ├── hardware/
|
||||
│ ├── services/
|
||||
│ ├── desktop/
|
||||
│ ├── users/
|
||||
│ └── development/
|
||||
├── scripts/
|
||||
└── lib/
|
||||
```
|
||||
|
||||
* `flake.nix` → authority
|
||||
* `hosts/` → composition
|
||||
* `modules/` → behavior
|
||||
|
||||
---
|
||||
|
||||
## Safety & Reproducibility
|
||||
|
||||
* No imperative installs
|
||||
* No network access at evaluation
|
||||
* Inputs must be pinned
|
||||
* All changes must be declarative
|
||||
|
||||
---
|
||||
|
||||
## Output Rules
|
||||
|
||||
* Plans: **plan only**
|
||||
* Code: **code only**
|
||||
* Questions: **one precise question only**
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
If you want, next we can:
|
||||
- Add **machine-checkable lint rules** derived from this
|
||||
- Write a **migration appendix** for legacy `/etc/nixos`
|
||||
- Create a **Codex system prompt** that mirrors this file exactly
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test VM (current)
|
||||
|
||||
- Built from our installer ISO (`nixos-minimal-25.11.20260130.63590ac-x86_64-linux.iso`).
|
||||
- Hostname: `nanuqsaurus`.
|
||||
- User: `admin` / password `admin`.
|
||||
- Network: DHCP on primary interface (e.g., `ensp1s0` in VM); SSH reachable once IP obtained.
|
||||
- Purpose: sandbox for validating flake changes before baking into the ISO.
|
||||
- Workflow: sync repo to VM and `nixos-rebuild switch --flake /etc/nixos#installer`; rebuild ISO **only on explicit request** (ISO must remain hardware-agnostic, no embedded host-specific files).
|
||||
- Host-local files: the installer writes `hosts/local-<hostname>.nix` and `hosts/local-<hostname>-hardware.nix` on the target. These are ignored by git. When syncing, exclude them to avoid deletion:
|
||||
`rsync -a --exclude 'hosts/local-*.nix' --exclude 'hosts/*-hardware.nix' --exclude '.git' . admin@<vm>:/home/admin/nixos-sync`
|
||||
Loading…
Add table
Add a link
Reference in a new issue