football/AGENTS.md

KNEL-Football Secure OS - Agent Behavior Guidelines

Quick Start

You are an AI agent (Crush) working on this project.

Your First Actions

1. Read STATUS.md - Check current project status (build state, blockers, next actions)
2. Read this AGENTS.md file - Understand workflow and guidelines
3. Read docs/PRD.md - Understand requirements (source of truth)
4. Check current state: ls -lh output/ and git log --oneline -10

---

Where to Find Things

Need	File
Current status (build state, blockers)	STATUS.md
Requirements (source of truth)	docs/PRD.md
Development workflow	docs/SDLC.md
Test coverage details	docs/TEST-COVERAGE.md
Verification/compliance	docs/VERIFICATION-REPORT.md
Security architecture	docs/security-model.md
AI memory/ADRs	JOURNAL.md

---

Project Structure

/
├── run.sh                 # MAIN ENTRY POINT - All operations
├── Dockerfile             # Multi-stage build environment
├── README.md              # Project overview
├── AGENTS.md              # THIS FILE - Agent guidelines
├── STATUS.md              # Current status (maintained by AI)
├── JOURNAL.md             # AI memory - ADRs, lessons (append-only)
└── docs/
    ├── PRD.md             # Product Requirements (source of truth)
    ├── SDLC.md            # Development workflow
    ├── TEST-COVERAGE.md   # Test suite details
    ├── VERIFICATION-REPORT.md
    ├── COMPLIANCE.md
    └── security-model.md

src/                       # Source scripts
config/                    # Configuration files
├── includes.installer/    # Installer configs (preseed.cfg)
├── hooks/live/            # Live system hooks
├── hooks/installed/       # Post-install hooks
└── package-lists/         # Package lists

tests/                     # Test suite (BATS framework)
output/                    # Build artifacts

---

Agent Workflow

1. Start Up

# Check current state
ls -lh output/
git log --oneline -10

2. Understand Requirements

• Read docs/PRD.md (source of truth)
• Read docs/SDLC.md for development workflow
• Check MANDATORY SECURITY REQUIREMENTS section below

3. Make Changes

• Read files before editing (Critical!)
• Use exact text matching (whitespace matters)
• Test after every change
• Update relevant documentation

4. Test Changes

./run.sh test              # Run all tests
./run.sh lint              # Run shellcheck
./run.sh test:unit         # Unit tests only
./run.sh test:integration  # Integration tests only
./run.sh test:security     # Security tests only

5. Build ISO (if needed)

./run.sh iso               # Build ISO (60-90 minutes)
tail -f /tmp/knel-iso-build.log

6. Test ISO (optional)

./run.sh test:iso create   # Create and boot test VM
./run.sh test:iso console  # Connect to VM console
./run.sh test:iso status   # Show VM status
./run.sh test:iso destroy  # Remove VM

7. Commit and Push

git status
git diff
git add <files>
git commit -m "type: subject

body (optional)

💘 Generated with Crush


Assisted-by: GLM-4.7 via Crush <crush@charm.land>


"
git push origin main

---

Mandatory Security Requirements

Full Disk Encryption (FDE)

Requirement: ALL systems MUST use LUKS2 encryption

• Cipher: AES-256-XTS (512-bit key)
• Format: LUKS2 with Argon2id KDF
• Passphrase: 14+ chars, mixed case, digit, special char
• Implementation: config/includes.installer/preseed.cfg, config/hooks/installed/encryption-*.sh

Password Complexity

Requirement: ALL passwords MUST meet strict complexity

• Minimum: 14 characters
• Classes: 3 of 4 (upper, lower, digit, special)
• Enforcement: PAM pwquality module
• Implementation: src/security-hardening.sh, config/hooks/live/security-hardening.sh

Host System FDE

Requirement: Build/test host MUST have FDE enabled

• ./run.sh iso will FAIL if host FDE not detected
• ./run.sh test:iso will FAIL if host FDE not detected
• Detection: checks for LUKS devices, /etc/crypttab, dm-crypt

---

Docker Workflow

Why Docker?

• Reproducible builds
• Isolated environment
• No host system pollution

Volumes

Container    Host         Purpose
/workspace   ./           Project root (read-only)
/build       ./tmp        Build intermediates
/output      ./output     Final artifacts

Commands Inside Container

• ./run.sh build - Build Docker image
• ./run.sh test - Run all tests
• ./run.sh lint - Run linting
• ./run.sh iso - Build ISO

Commands on Host

• ./run.sh test:iso - Test ISO with libvirt

NEVER

• Create directories in /home
• Install packages on host
• Modify host system files
• Run live-build commands on host

---

Important Rules

AUTO-COMMIT (Critical)

After completing ANY work:

1. Check git status
2. Stage relevant changes
3. Commit with conventional message
4. Push to remote
5. NEVER wait for user to ask

DO

• Read files before editing
• Use exact text matching (whitespace matters)
• Test after every change
• Run full test suite before committing
• Double-check git status before ANY commit
• Delete unused/obsolete files when refactoring
• Update documentation when changing behavior
• Follow existing code style

DO NOT

• Edit files you haven't read
• Guess at text matches
• Commit without testing
• Skip the test suite
• Break existing tests
• Ignore lint errors
• Make unrelated changes in one commit
• Modify host system directly
• Run destructive git operations without explicit instruction
• Amend commits without explicit approval

---

Commit Message Format

type: subject

body (optional)

Types: feat, fix, docs, test, refactor, chore

---

Error Handling

Build Failures

• Check /tmp/knel-iso-build.log
• Check disk space
• Verify Docker permissions

Test Failures

• Run tests individually: bats tests/unit/file.bats
• Review error messages carefully

Permission Errors

• Ensure run.sh is executable
• Check Docker daemon is running
• Verify user in docker group

---

Success Criteria

• All tests pass (./run.sh test)
• Lint passes (./run.sh lint)
• Documentation updated (if needed)
• Conventional commit message used
• No security requirements violated
• Docker workflow followed
• Changes committed and pushed

---

Remember: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow.

For current status, see STATUS.md.