Skip to content

AI Enforcement Framework

This page documents the AI subagent system used to enforce development policies and maintain code quality.

Overview

Bazzite AI uses a specialized subagent architecture where Claude Code invokes purpose-built agents to enforce policies, validate changes, and perform root cause analysis.

Architecture

The main Claude Code agent delegates to specialized subagents at key enforcement points. This ensures consistent policy enforcement and thorough validation.

Subagent System

14 Specialized Agents

Agent Type Purpose
policy-enforcer Blocking Verifies all policies before Edit/Write
root-cause-analyzer Blocking Mandatory 8-step error investigation
testing-validator Blocking Confirms LOCAL verification before "working" claims
justfile-validator Blocking Enforces non-interactive support, file size limits
pre-commit-guardian Blocking Runs hooks, blocks commit if any fail
documentation-validator Blocking Validates MyST syntax in docs/*.md
config-integrity-enforcer Blocking Blocks edits to ~/.config/*
pixi-lock-enforcer Blocking Blocks manual pixi.lock edits
sudo-usage-enforcer Blocking Blocks sudo ujust usage
overlay-testing-enforcer Blocking Blocks just -f for testing
architecture-advisor Advisory Explains immutable OS design decisions
buildcache-validator Advisory Analyzes build performance impact
code-research Advisory Deep architectural exploration
github-actions Advisory CI status and error reporting

Agent Types

Type Behavior When Used
Blocking MUST pass before proceeding Edit/Write, commits, errors
Advisory Provides guidance only Architecture questions, builds

Enforcement Triggers

The following actions automatically trigger subagent invocation:

Trigger Agent Action
Edit pixi.lock pixi-lock-enforcer BLOCK - run pixi install instead
Edit ~/.config/* config-integrity-enforcer BLOCK - edit source in system_files/
Edit *.just files justfile-validator Invoke (also BLOCK if >30K)
Edit docs/*.md documentation-validator Invoke
Edit Containerfile buildcache-validator Advisory
Error in output root-cause-analyzer IMMEDIATE - never rationalize
Claiming "working" testing-validator BLOCK until LOCAL verified
Before git commit pre-commit-guardian BLOCK until 100% hooks pass
Using just -f for testing overlay-testing-enforcer BLOCK - use overlay method
Using sudo ujust sudo-usage-enforcer BLOCK - internal sudo only
Architectural "why?" architecture-advisor Advisory
CI/build status query github-actions Advisory

Self-Check Workflow

Before every response, Claude Code performs this self-check:

  • [ ] Task matches a skill? Use /plugin:skill FIRST
  • [ ] GitHub operation? Use mcp__github__* tools, not gh CLI
  • [ ] Jupyter operation? Use mcp__jupyter__* tools
  • [ ] About to Edit/Write? Check Enforcement Triggers
  • [ ] Observed error/failure? Invoke root-cause-analyzer
  • [ ] About to claim "working"? Invoke testing-validator
  • [ ] About to commit? Invoke pre-commit-guardian

Subagent Invocation

Syntax

Task(subagent_type="<agent-name>",
     description="<short description>",
     prompt="<detailed context and task>")

Example: Policy Enforcer

Task(subagent_type="policy-enforcer",
     description="Verify policy compliance",
     prompt="I plan to edit system_files/.../pod.just. Verify:
     - NOT editing ~/.config/ output files (FORBIDDEN)
     - Changes in source files (system_files/, build_files/)
     - File size <30K (check before/after)")

Example: Root Cause Analyzer

Task(subagent_type="root-cause-analyzer",
     description="Investigate unexpected behavior",
     prompt="UNEXPECTED BEHAVIOR DETECTED:
     Expected: Service starts successfully
     Actual: Service failed with exit code 1
     Command: systemctl --user start jupyter
     Output: [error messages]

     Perform mandatory 8-step root cause analysis.")

Example: Testing Validator

Task(subagent_type="testing-validator",
     description="Verify LOCAL testing completed",
     prompt="Verify LOCAL system testing for jupyter pod:
     - Commands run: ujust jupyter start
     - Verification: systemctl --user status jupyter-1
     - All 8 testing standards met")

Skills-First Policy

Rule

Before using ANY ad-hoc commands, CHECK the existing skill first.

Skill Invocation

Task Use Skill NOT Ad-Hoc
Build OS image /bazzite-ai-dev:build Manual podman commands
Test overlay /bazzite-ai-dev:test Manual just commands
Clean artifacts /bazzite-ai-dev:clean Manual rm/prune commands
Jupyter ML workflows /bazzite-ai-jupyter:* Manual notebook editing
GitHub operations mcp__github__* tools gh CLI commands
Ollama inference /bazzite-ai-ollama:api Manual curl commands
System configuration /bazzite-ai:configure Manual ujust commands

Plugin Inventory

Plugin Skills Count Categories
bazzite 12 apps, audio, boot, desktop, distrobox, gaming, gpu, network, security, storage, system, virtualization
bazzite-ai 20 apptainer, bootc, comfyui, config, deploy, fiftyone, install, jellyfin, jupyter, k3d, localai, ollama, openwebui, pods, portainer, record, runners, tailscale, test, vm
bazzite-ai-dev 6 build, clean, lfs, overlay, record, test
bazzite-ai-jupyter 20 chat, dpo, evaluation, finetuning, gpu, grpo, huggingface, inference, langchain, ollama, openai, peft, qlora, quantization, rag, reward, rloo, sft, transformers, vision

Total: 58 Skills

Skill Syntax

/plugin:skill

Examples:

  • /bazzite-ai-dev:build - Build OS image
  • /bazzite-ai:jupyter - JupyterLab management
  • /bazzite-ai-ollama:api - Ollama API operations

MCP Tools Policy

Rule

Use MCP tools instead of CLI equivalents when available.

GitHub MCP Tools

Use Tool For Instead Of
mcp__github__issue_read Read issue details gh issue view
mcp__github__issue_write Create/update issues gh issue create
mcp__github__list_issues List issues gh issue list
mcp__github__list_workflow_runs Check CI status gh run list
mcp__github__get_job_logs Get CI logs gh run view --log
mcp__github__pull_request_read PR details/diff gh pr view
mcp__github__get_file_contents Remote file contents gh api

Jupyter MCP Tools

Use Tool For
mcp__jupyter__use_notebook Open/activate notebook
mcp__jupyter__execute_cell Run notebook cells
mcp__jupyter__insert_execute_code_cell Add and run code
mcp__jupyter__read_notebook Read cell contents
mcp__jupyter__execute_code Run code directly in kernel

Notebook Modes

  • Use mode="connect" for existing notebooks
  • Use mode="create" ONLY for brand new notebooks (OVERWRITES existing!)
  • If kernel becomes stale, use unuse_notebook then use_notebook with mode="connect"

Agent Definitions

Full agent procedure definitions are located at:

plugins/bazzite-ai-dev/agents/
├── architecture-advisor.md
├── buildcache-validator.md
├── code-research.md
├── config-integrity-enforcer.md
├── documentation-validator.md
├── github-actions.md
├── justfile-validator.md
├── overlay-testing-enforcer.md
├── pixi-lock-enforcer.md
├── policy-enforcer.md
├── pre-commit-guardian.md
├── root-cause-analyzer.md
├── sudo-usage-enforcer.md
└── testing-validator.md

Philosophy

Five Cornerstones of AI Scut Testing

  1. Your Assumptions Are the Enemy - The thing you didn't think to test is the thing that will break.

  2. Small Bugs Have Big Friends - Every issue you dismissed as nonessential is tomorrow's catastrophe.

  3. It's Broken Until It Runs Live - Localhost and mocks are deceptive liars.

  4. Check Every Damn Thing - Methodically. Tediously. No shortcuts.

  5. Then Check It Again - Because you missed something. You always do.

Clean Architecture Principles

  • Always pick the cleanest long-term approach.
  • Prioritize a clean codebase over everything else.
  • Keeping deprecated code or commands hanging around is ALWAYS a bad idea.
  • You have all the time in the world. Taking time to get things done properly is ALWAYS worth the effort.