Nix Flake Architect

Nix Flake Architect

Skill Routing

Boundaries worth stating to the user rather than guessing at: authoring and distributing an overlay is this skill, while consuming one inside a devenv environment is devenv2-environment-generator; devenv outputs are not flake packages and never appear under nix flake show; a devenv project consumed through the Nix flakes integration cannot use SecretSpec, so surface that conflict before generating anything; and a dendritic repository is still a flake-parts flake, so references/flake-parts-semantics.md and references/troubleshooting.md apply unchanged.

Phase 0: Verify Before Writing

Nix knowledge goes stale quickly, and a wrong attribute path or option name produces an evaluation error rather than a graceful degradation — so verify names against the nixos-tools MCP server rather than recalling them. It exposes two tools: mcp__nixos-tools__nix takes an action plus query and narrows with source and type; mcp__nixos-tools__nix_versions returns version history from NixHub.

Load references/mcp-nixos-guide.md for the full action matrix, browsing option trees, binary-cache and store queries, and disambiguation strategy.

If nixos-tools is unavailable, say so in the output and mark every package attribute path and option name as unverified rather than presenting it as confirmed.

Phase 1: Triage — Mode and Output Type

Step 1A picks the distribution mode; it shapes the entire output structure.

Default to Mode 1 when unsure — an incorrect Mode 2 choice removes the CLI surface users expect.

For Mode 2: read references/overlays-only-pattern.md in full before proceeding, and present the CLI Impact Matrix (§3) so the trade-offs are explicit.

Step 1B picks the primary output type. Mode 1 covers devShell, package, nixosConfig, nixosModule, homeConfig, an overlay published by a flake that also builds packages, a composite of several of these, and migration of a legacy default.nix / shell.nix. Mode 2 is overlays-only — a nixpkgs extension with an inputs-only API. A flake that consumes an overlays-only input is Mode 1 with a Mode 2 dependency.

For migration read references/flake-patterns.md § Migration; for overlays-only read references/overlays-only-pattern.md; for consuming one load templates/overlay-consumer-integration.nix.

Phase 2: Architecture Selection

Default to flake-parts for all new flakes, and for any existing flake-parts flake. Use flake-utils only to maintain existing code built on eachDefaultSystem, and raw Nix only for a trivial single-system one-off. Load references/flake-patterns.md for framework guidance and boilerplate.

flake-parts Contribution Rules

perSystem is not an attribute — it is a deferred module. Every definition of it is collected into a list and evaluated together, once per system. Two consequences cause most flake-parts failures:

• A perSystem definition that evaluates to nothing is indistinguishable from one that was never written. There is no error, no warning, and no empty-set diagnostic. A mkIf with a false condition, an enable option left at its false default, a module file missing from imports, and an import-tree path containing /_ all produce the same outcome: a flake that evaluates cleanly and has no outputs. An opt-in module needs a companion perSystem = { myFeature.enable = true; }; written in the same change. Verify contributions with nix eval .#packages.<system> --apply builtins.attrNames before reporting success.
• pkgs, system, inputs', and self' exist only inside perSystem; inputs, self, withSystem, and getSystem exist only outside it. Build derivations inside perSystem. When a flake.* output needs a package, reach in with withSystem "<system>" ({ pkgs, ... }: …) rather than pulling pkgs outward. These errors are lazy — builtins.attrNames reports names without forcing values, so force the value to surface them.

Before writing a flake-parts module, read references/flake-parts-semantics.md. When outputs are missing but nothing errored, read references/troubleshooting.md.

Phase 3: System Architecture

Standard system strings: x86_64-linux (most servers and Linux desktops), aarch64-linux (ARM servers, Raspberry Pi), x86_64-darwin (Intel Macs), aarch64-darwin (Apple Silicon). With flake-parts, set systems and use perSystem; do not hardcode system strings in outputs. With flake-utils, use eachDefaultSystem or eachSystem. With raw Nix, hardcode only when single-system is intentional and documented. Under import-tree, systems must live in a module file — see references/import-tree-and-dendritic.md.

Phase 4: Inputs — Composition and Pinning

Purity rule (non-negotiable): flake evaluation is hermetic — no environment variables, no ~/.config, no network access during evaluation, every dependency declared as an input. Read references/purity-and-hermetics.md before adding one.

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  home-manager = {
    url = "github:nix-community/home-manager";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  flake-parts.url = "github:hercules-ci/flake-parts";
};

Set inputs.<name>.follows = "nixpkgs" for every input that transitively depends on nixpkgs; skipping it causes duplicate nixpkgs evaluations and bloated closures. Verify third-party input URLs with nix {"action":"search","query":"<name>","source":"flakehub"}.

Phase 5: Build the Flake

Populate templates with attribute paths and option names verified in Phase 0, and with the output shapes in references/flake-schema.md. For Mode 2, also confirm the new attribute names do not collide with existing top-level nixpkgs attrs.

Phase 6: Validation Checklist

Run before delivering. Mode 2 adds a second checklist in references/overlays-only-pattern.md § Validation.

• Every perSystem contribution verified present: nix eval .#packages.<system> --apply builtins.attrNames
• No perSystem module gated on an enable option that nothing sets to true
• No pkgs, system, inputs', or self' referenced outside a perSystem function
• src = ./<dir> consumers address files at the root of $src, not under <dir>/
• All inputs.<name>.follows set for inputs that consume nixpkgs
• No hardcoded system strings when using flake-parts or flake-utils
• No evaluation-time impurities (env vars, builtins.readFile outside src, avoidable IFD)
• nixpkgs.config.allowUnfree declared explicitly if needed, never implicit
• nixosConfigurations.<name>.system not set (deprecated); use pkgs.system from module args
• packages.<system>.default points to the primary deliverable
• devShells.<system>.default present for nix develop
• New files staged with git add — untracked files are invisible to nix, silently
• All package versions and option names verified via nixos-tools, not assumed

Phase 7: CLI Guidance

Provide the exact commands to test the flake — nix flake check, nix develop, nix build, nix run, nix flake show, nix flake update. Load references/cli-workflows.md for the full command map; Mode 2's narrower surface is documented in references/overlays-only-pattern.md §3.

Reference Routing

Load reference files when the routing signal appears — at design time for the first group, at failure time for the symptom group. Never load all of them: each is a standalone document and only the routed ones are relevant.

Templates are routed by output type in Phase 5.

Output Format

Deliver a complete, commented flake.nix; any supporting modules/, homes/, or pkgs/ stubs; the exact CLI commands to build, enter, and check it; and a note on which values were confirmed via nixos-tools versus inferred. Deliver complete expressions — do not truncate with # ... rest here.