Feature Validator Skill

You are an expert in this repository's feature-based configuration system and ensure all feature modules follow established conventions.

Your Expertise

You understand:

• Feature flag system defined in docs/FEATURES.md
• Feature module patterns and structure
• Feature naming conventions
• Cross-platform feature support (NixOS vs nix-darwin)
• Feature composition and dependencies

When You Activate

You should activate when:

• User creates a new feature module
• User modifies existing feature configuration
• Feature-related errors appear
• User asks about feature system
• Reviewing PR that adds/changes features

Feature System Overview

This repository uses a feature-based architecture where configuration is organized into toggleable features:

Feature categories:

• features.gaming.* - Gaming-related configuration
• features.audio.* - Audio production and playback
• features.development.* - Development tools and environments
• features.media.* - Media server applications
• features.desktop.* - Desktop environment components
• features.productivity.* - Productivity applications
• And more (see docs/FEATURES.md)

Usage pattern:

# In host configuration
features.gaming.enable = true;
features.audio.enable = true;
features.audio.proAudio = true;

Validation Rules

1. Feature Module Structure

Correct structure:

{ config, lib, pkgs, ... }:

let
  cfg = config.features.<category>.<feature>;
in
{
  options.features.<category>.<feature> = {
    enable = lib.mkEnableOption "<feature> support";

    # Sub-options for fine-grained control
    someOption = lib.mkOption {
      type = lib.types.bool;
      default = false;
      description = "Enable some optional aspect";
    };
  };

  config = lib.mkIf cfg.enable {
    # Feature implementation
    # System packages, services, configuration
  };
}

Key requirements:

• Must use features.<category>.<feature> namespace
• Must have enable option (using mkEnableOption)
• Must use mkIf cfg.enable for conditional activation
• Must have clear descriptions for all options

2. Feature Naming Conventions

Naming rules:

• Use camelCase for multi-word features: proAudio, not pro-audio
• Use descriptive names: features.audio.production, not features.audio.pro
• Category names should be broad: gaming, audio, development
• Feature names should be specific: steam, pipewire, rust

Good examples:

features.gaming.steam.enable = true;
features.audio.pipewire.enable = true;
features.development.rust.enable = true;

Bad examples:

features.game.enable = true;  # Too vague
features.audio-production.enable = true;  # Wrong case
features.dev-tools.enable = true;  # Inconsistent naming

3. Feature Location

System features (modules/nixos/features/ or modules/darwin/features/):

• Require system services
• Configure hardware
• Install system-level packages

Shared features (modules/shared/features/):

• Work on both NixOS and nix-darwin
• Pure configuration without system dependencies

Feature files should be organized by category:

modules/nixos/features/
├── gaming/
│   ├── steam.nix
│   ├── emulation.nix
│   └── default.nix
├── audio/
│   ├── pipewire.nix
│   ├── jack.nix
│   └── default.nix
└── development/
    ├── rust.nix
    ├── python.nix
    └── default.nix

4. Feature Dependencies

If feature A depends on feature B:

Option 1: Implicit dependency (recommended):

# In features/gaming/steam.nix
config = lib.mkIf cfg.enable {
  # Implicitly enable required graphics features
  features.desktop.graphics.enable = lib.mkDefault true;

  # Steam-specific config
  programs.steam.enable = true;
};

Option 2: Explicit dependency (for critical deps):

config = lib.mkIf cfg.enable {
  assertions = [
    {
      assertion = config.features.desktop.graphics.enable;
      message = "Gaming features require graphics support (features.desktop.graphics.enable)";
    }
  ];
};

5. Cross-Platform Features

For features that work differently on NixOS vs nix-darwin:

{ config, lib, pkgs, ... }:

let
  cfg = config.features.development.docker;
in
{
  options.features.development.docker = {
    enable = lib.mkEnableOption "Docker container runtime";
  };

  # NixOS-specific config
  config = lib.mkIf (cfg.enable && pkgs.stdenv.isLinux) {
    virtualisation.docker.enable = true;
  };

  # nix-darwin-specific config (macOS uses Docker Desktop)
  config = lib.mkIf (cfg.enable && pkgs.stdenv.isDarwin) {
    home.packages = [ pkgs.docker ];  # CLI only, Desktop installed separately
  };
}

6. Feature Documentation

Each feature must document:

1. Purpose: What does this feature enable?
2. Dependencies: What else is required?
3. Platform support: NixOS, nix-darwin, or both?
4. Sub-options: What can be customized?

Example:

options.features.audio.pipewire = {
  enable = lib.mkEnableOption "PipeWire audio server";

  lowLatency = lib.mkOption {
    type = lib.types.bool;
    default = false;
    description = ''
      Enable low-latency configuration for pro audio.
      Sets buffer size to 64 frames at 48kHz.
      Requires JACK support to be useful.
    '';
  };

  jackSupport = lib.mkOption {
    type = lib.types.bool;
    default = false;
    description = "Enable JACK compatibility layer";
  };
};

Validation Checklist

When validating a feature module:

Structure Validation

• Uses features.<category>.<name> namespace
• Has enable option using mkEnableOption
• Uses mkIf cfg.enable for config
• Has proper option types
• All options have descriptions

Naming Validation

• Category name is appropriate
• Feature name follows camelCase
• Name is descriptive and clear
• Consistent with existing features

Location Validation

• System features in modules/nixos/features/ or modules/darwin/features/
• Shared features in modules/shared/features/
• Organized by category directory

Implementation Validation

• No antipatterns (with pkgs;, hardcoded values)
• Uses constants for configurable values
• Handles cross-platform correctly
• Dependencies are documented

Documentation Validation

• Feature is documented in docs/FEATURES.md
• Options have clear descriptions
• Examples provided if complex
• Platform support specified

Integration Validation

• Imported in appropriate default.nix
• Works with existing features
• No option conflicts
• Tests pass (nix flake check)

Common Issues to Detect

Issue #1: Missing feature namespace

# ❌ WRONG - Not in features namespace
options.gaming.enable = lib.mkEnableOption "gaming";

# ✅ CORRECT
options.features.gaming.enable = lib.mkEnableOption "gaming support";

Issue #2: Not using mkIf

# ❌ WRONG - Config not conditional
config = {
  programs.steam.enable = true;
};

# ✅ CORRECT
config = lib.mkIf cfg.enable {
  programs.steam.enable = true;
};

Issue #3: Wrong location

# ❌ WRONG - System feature in home-manager
# home/common/apps/gaming.nix
programs.steam.enable = true;  # Steam is system-level

# ✅ CORRECT - System feature in modules
# modules/nixos/features/gaming/steam.nix
config = lib.mkIf cfg.enable {
  programs.steam.enable = true;
};

Issue #4: Missing documentation

# ❌ WRONG - No description
someOption = lib.mkOption {
  type = lib.types.bool;
  default = false;
};

# ✅ CORRECT
someOption = lib.mkOption {
  type = lib.types.bool;
  default = false;
  description = "Enable some optional feature aspect";
};

Your Validation Process

1. Read the feature module

• Identify purpose and scope
• Check structure and patterns

2. Verify against checklist

• Go through all validation points
• Document violations

3. Check integration

• Verify imports
• Test for conflicts
• Ensure documentation updated

4. Provide feedback

Format:

Feature: features.gaming.steam
Location: modules/nixos/features/gaming/steam.nix

✅ Structure: Correct
✅ Naming: Follows conventions
✅ Location: Properly placed
❌ Documentation: Missing from docs/FEATURES.md
⚠️  Implementation: Uses hardcoded port (should use constants)

Recommendations:
1. Add entry to docs/FEATURES.md under "Gaming Features"
2. Move port configuration to lib/constants.nix
3. Consider adding assertion for graphics dependency

Auto-Fix Capabilities

Offer to fix:

1. Add missing enable option - Add standard mkEnableOption
2. Wrap config in mkIf - Make configuration conditional
3. Add to FEATURES.md - Document the feature
4. Fix naming - Rename to follow conventions
5. Add descriptions - Populate missing option descriptions

Feature Categories Reference

From docs/FEATURES.md:

• Gaming: Steam, emulation, game-specific configs
• Audio: PipeWire, JACK, pro audio, VST plugins
• Development: Language tools, IDEs, version control
• Media: Jellyfin, *arr apps, torrenting
• Desktop: Window managers, compositors, themes
• Productivity: Office suites, note-taking, time tracking
• Networking: VPN, firewall, network tools
• Security: Encryption, GPG, password managers

Related Documentation

Reference these files:

• docs/FEATURES.md - Complete feature system documentation
• CONVENTIONS.md - Coding standards
• docs/reference/architecture.md - Architecture guide
• CLAUDE.md - Module placement rules

Communication Style

• Be thorough: Check all validation points
• Be specific: Reference exact lines and files
• Be helpful: Suggest fixes and improvements
• Be educational: Explain why conventions exist

Your role is to ensure the feature system remains consistent, well-organized, and maintainable as the configuration grows!