| name | nix-manager |
| description | Manage Nix package, profile, flake, and diagnostic work in this dotfiles repository. Use when changing flake.nix, troubleshooting Nix, applying profile changes, or explaining the locked Nix setup. |
Nix Manager
Outcome
Keep this repository's Nix package profile reproducible across macOS, Ubuntu,
Fedora, and Linux/WSL. The repository defines the package closure; Nix profile
state is a user-owned result of the supported setup flow.
Route First
Use $dotfiles-operations for every repository Nix task. Add the matching
specialist when the task crosses one of these boundaries:
$nix-update for any flake.lock update or package-version comparison.$cross-platform-guardian for bootstrap, package, platform, or profile
behavior that can differ across supported systems.$config-change for a configuration change that also needs a package.
Do not treat this skill's examples as a substitute for the current
flake.nix, Makefile, or operations validation matrix.
Inspect
Before changing Nix-owned files, read the current flake.nix, Makefile, and
the relevant module under src/dotfiles_setup/. Inspect the worktree first:
git status --short
git diff -- flake.nix flake.lock
For a live profile, installation, or verification request, also inspect the
supported state rather than ambient PATH:
./bootstrap.sh doctor
./bootstrap.sh verify
nix profile list --json
Boundaries
flake.nix is the source of package selection and declared systems;
flake.lock pins its inputs.bootstrap.sh is the only root setup entry point. Profile installation and
upgrade use ./bootstrap.sh profile; normal consumers keep committed locks
unchanged.make update is the explicit all-input update path. It is the only normal
workflow here that changes flake.lock; use $nix-update before running it.nix profile rollback is the recovery path for an already-applied profile
generation. It is a user-state mutation and requires explicit authority.- Read the actual flake input when its branch, package version, or supported
output matters. Do not encode a copied branch name or package inventory in
agent guidance.
Workflows
Package change
-
Edit only flake.nix, retaining its existing package grouping and supported
systems. Do not update flake.lock for a package-list change.
-
Run make test-pre, then make test-eval for the four-system contract.
-
After authority to mutate the user profile, run:
./bootstrap.sh profile
./bootstrap.sh verify
-
Report evaluation evidence separately from installed-profile and platform
evidence.
Input update
Use $nix-update. It owns the lock diff, package-version comparison, and
validation sequence. Run make update only for an explicit update request;
then verify the profile and confirm no unrelated lockfile changed.
Diagnosis
Start at the first failed boundary: pending recovery or mutation lock, Nix
availability, exact profile origin, profile store outputs, then managed links.
Use ./bootstrap.sh recover only to inspect; applying recovery needs explicit
authority. Do not repair an exact-profile failure by changing the global Nix
configuration or trusting a binary found on ambient PATH.
Validation and Handoff
Use the validation matrix in $dotfiles-operations; Nix package or system
changes require make test-pre and make test-eval. Cross-platform bootstrap
work also requires Docker and affected-platform evidence. Before finishing:
git diff --check
git diff --exit-code -- flake.lock uv.lock
git status --short
Report the files changed, lockfile intent, commands and results, platform
evidence, profile/recovery state, rollback path, and commit/push status.
References
- Repository architecture and the validation matrix:
$dotfiles-operations.
- Advanced Nix language patterns and standalone-project examples:
REFERENCE.md. They are not the dotfiles repository contract;
load them only when the current flake and operations guidance do not answer
the Nix-language question.
