bazzite-ai-dev

Provide guidance on immutable OS architecture, build system, testing methods, and design decisions. Explains WHY things work the way they do.

Validates build cache layer ordering to prevent cache invalidation. Advisory warnings for changes to stable layers, Containerfile modifications, and build script sequencing.

Deep architectural exploration using chunkhound code_research. Use for understanding component relationships, flows, and patterns across the codebase.

Blocks any attempt to edit ~/.config/* files directly. These are OUTPUT configs generated by ujust commands - edit source code instead.

Enforces documentation system requirements. Validates MyST syntax, myst.yml completeness, cross-references, and file organization before editing docs or committing.

Reports GitHub Actions workflow status and error details using the GitHub MCP Server. Data reporter only - delegates analysis to root-cause-analyzer.

PROACTIVELY enforce justfile coding standards and non-interactive requirements when editing .just files. Validates syntax, patterns, and automation support.

Blocks any `just -f` usage in testing documentation and guides. Enforces Policy

Blocks any manual edit to pixi.lock files. Lock files must be regenerated via `pixi install`, never edited directly.

MUST BE USED before any code changes, commits, or declaring features "working". Enforces critical development policies from CLAUDE.md and docs/developer-guide/policies.md.

MUST BE USED before ANY git commit operation. Runs pre-commit validation and blocks commits if hooks fail. NEVER allows --no-verify.

MUST BE USED when any unexpected behavior, error, warning, or anomaly occurs. Performs deep root cause analysis following mandatory 8-step process. Never accepts "probably expected" without investigation.

Blocks documentation and code suggesting `sudo ujust` or `sudo just`. Enforces Policy

PROACTIVELY verify proper LOCAL system testing was performed before declaring features "working". Ensures all 8 testing standards met. Blocks commits if LOCAL verification missing.

Development: Unified build system for OS images, pods, VMs, and ISOs. Run from repository root with 'just build <subcommand>'. Includes smart cache strategy that matches GitHub Actions for optimal build times.

Development: Cleanup and maintenance for the development environment. Removes build artifacts, caches, containers, and recovers disk space. Run from repository root with 'just clean'. Use when developers need to free disk space or reset the build environment.

Development: Git LFS file management for large binary files in the repository. Handles checkout, status, fetch, and verification of LFS-tracked files. Run from repository root with 'just lfs'. Use when developers need to manage large files like recordings, images, or binary assets.

Development: Overlay session management for bazzite-ai development. Enables live editing of justfiles via symlinks to /usr on immutable OS (OSTree) or traditional Linux systems. Run from repository root with 'just overlay'. Use when developers need to test justfile changes without rebuilding the OS image.

Development: Batch recording system for generating documentation recordings. Creates asciinema recordings of ujust commands organized by category (pods, k8s, vm, tools, config, install, test). Run from repository root with 'just record'. Use when developers need to regenerate documentation recordings for the website.

Runtime verification tests for bazzite-ai installations. Validates GPU access, CUDA/PyTorch, service health, pod lifecycles, k3d clusters, and network connectivity. Run with 'ujust test' on installed systems. Use when developers need to verify their bazzite-ai installation is working correctly.