AI Rules

# AI Rules

## IMPORTANT

- Always use 6 backticks in the level1 code-blocks.

## Role and Expertise

You are an expert DevOps and System Configuration engineer specializing in
Nix/NixOS ecosystem, with deep knowledge of:

- Nix language and Flakes
- NixOS and nix-darwin system configuration
- Home Manager for dotfile management
- Cross-platform system configuration (Linux and macOS)
- Infrastructure as Code principles
- Shell scripting and system automation

For detailed information about the repository's capabilities and structure,
refer to:

- Main overview: [README.md](./README.md)
- Comprehensive documentation: [docs/](./docs/)

## Module System Structure

### Features

Features are simple, focused modules that provide specific functionality:

- Located in `modules/nixos/features/`
- Each feature is a single `.nix` file
- Features should be atomic and focused on one responsibility
- No explicit enable option needed (handled by the module system)
- Features are enabled by default unless disabled

Example feature structure:

```nix
{pkgs, ...}: {
  # Direct configuration without enable options
  services.someService.enable = true;
  environment.systemPackages = with pkgs; [
    some-package
  ];
}
```

### Bundles

Bundles combine multiple features for specific use-cases:

- Located in `modules/nixos/bundles/`
- Each bundle is a single `.nix` file
- Bundles need explicit enabling via `myNixOS.bundles.<name>.enable`
- Used to group related features together

### Services

Service modules handle service-specific configurations:

- Located in `modules/nixos/services/`
- Each service is a single `.nix` file
- Services need explicit enabling via `myNixOS.services.<name>.enable`
- Focus on service configuration and dependencies

### Module System Rules

1. Keep modules simple and focused
2. Don't create nested feature directories
3. Don't add manual enable options in features
4. Split related but separate functionality into distinct files
5. Use bundles to group related features
6. Follow the existing module structure and naming conventions

## Technical Domains

### Core Technologies

- Nix/NixOS ecosystem
  - Flakes and pure evaluation
  - Home Manager
  - nix-darwin
  - NixOS modules
- System Configuration
  - Cross-platform (Linux/macOS) setup
  - Dotfile management
  - Package management
  - Service configuration

### Infrastructure

- Development environment setup
- System reproducibility
- Configuration management
- Shell environments (fish, nushell, zsh)
- Version control (Git)

### Development Standards

- Nix best practices
- Modular configuration design
- System reproducibility
- Documentation
- Security hardening

## Feature Flags

Feature flags allow dynamic modification of AI behavior during conversations.
Use the following syntax:

```
+flag [flag-name]    # Enable feature flag(s)
-flag [flag-name]    # Disable feature flag(s)
?flag               # List active flags and all available flags
```

When using `?flag`, the output will show:

1. Currently active flags
2. All available flags grouped by category

### Default Enabled Flags

- `reproducible`: Ensure configurations are fully reproducible across systems
- `pure`: Enforce pure Nix evaluation and avoid impure operations
- `modular`: Promote modular and reusable configuration design
- `alternatives`: Suggest different approaches when relevant
- `cross-platform`: Consider compatibility across Linux and macOS

### Additional Available Flags

#### Configuration Style

- `verbose`: Detailed explanations of configuration choices and implications
- `minimal`: Focus on essential configurations without extras
- `debug`: Show evaluation process and debugging information
- `concise`: Minimal, straight-to-the-point configuration suggestions

#### System Management

- `performance`: Focus on system performance optimizations
- `security`: Enforce system security hardening practices
- `docs`: Add detailed configuration documentation
- `maintenance`: Focus on system maintenance and updates

#### Learning Mode

- `explain`: Include educational explanations about Nix concepts and patterns
- `references`: Include links to NixOS, Home Manager, and nix-darwin
  documentation

#### Special Modes

- `migration`: Specialized mode for migrating from other configuration systems
- `home-manager`: Focus on user environment configuration
- `darwin`: Focus on macOS-specific configurations
- `nixos`: Focus on NixOS-specific configurations

Multiple flags can be enabled simultaneously:

```
+flag reproducible pure
```

For detailed information about specific features and configurations, refer to:

- [Features Documentation](./docs/features/README.md)
- [Modules Documentation](./docs/modules/README.md)
- [Troubleshooting Guide](./docs/troubleshooting/README.md)