# KNEL-Football Secure OS - Agent Behavior Guidelines ## Quick Start **You are an AI agent (Crush) working on this project.** ### Your First Actions (MANDATORY) 1. **Read STATUS.md** - Check current project status (build state, blockers, next actions) 2. **Read docs/SDLC.md** - **CRITICAL**: Understand the MANDATORY development workflow 3. **Read docs/PRD.md** - Understand requirements (source of truth) 4. **Check current state**: `ls -lh output/` and `git log --oneline -10` --- ## ⚠️ CRITICAL: SDLC COMPLIANCE IS MANDATORY ### ZERO TOLERANCE FOR SDLC VIOLATIONS **You MUST follow docs/SDLC.md for EVERY change. NO EXCEPTIONS.** The SDLC defines a **MANDATORY** workflow that you MUST follow: ``` ┌─────────────────────────────────────────────────────────────────────┐ │ MANDATORY SDLC WORKFLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 1. READ SDLC.md FIRST - Before starting ANY work │ │ └─ This is NOT optional. Read it. Every time. │ │ │ │ 2. WRITE TESTS FIRST (TDD) │ │ └─ RED: Write failing test BEFORE implementation │ │ └─ Tests MUST exist before you write ANY code │ │ │ │ 3. IMPLEMENT CODE │ │ └─ GREEN: Write minimal code to pass the test │ │ │ │ 4. UPDATE DOCUMENTATION │ │ └─ PRD.md - Add/update requirements │ │ └─ security-model.md - Update architecture │ │ └─ TEST-COVERAGE.md - Document new tests │ │ │ │ 5. RUN ALL TESTS │ │ └─ ./run.sh test MUST pass │ │ └─ ./run.sh lint MUST pass with zero warnings │ │ │ │ 6. COMMIT │ │ └─ Pre-commit hook will verify all checks pass │ │ │ │ 7. PUSH │ │ └─ Changes are not complete until pushed │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Pre-Commit Hook (Automatic Enforcement) A pre-commit hook automatically enforces SDLC requirements: - **Runs `./run.sh lint`** - Blocks commit on any warnings - **Runs `./run.sh test:unit`** - Blocks commit on test failures - **Checks test coverage** - Blocks commit if tests missing for modified code - **Warns on missing docs** - Reminds to update documentation **The hook is a SAFETY NET, not a substitute for following the process.** ### Violations That Will Get You Blocked | Violation | Consequence | |-----------|-------------| | Not reading SDLC.md first | Pre-commit hook will fail | | Writing code before tests | Pre-commit hook will fail | | Missing test files | Pre-commit hook will fail | | Lint warnings | Pre-commit hook will fail | | Test failures | Pre-commit hook will fail | | Missing documentation updates | Pre-commit warning | --- ## Where to Find Things | Need | File | |------|------| | **DEVELOPMENT WORKFLOW** | **docs/SDLC.md** (READ FIRST) | | Current status (build state, blockers) | **STATUS.md** | | Requirements (source of truth) | **docs/PRD.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/ ├── SDLC.md # ⚠️ MANDATORY WORKFLOW - READ FIRST ├── PRD.md # Product Requirements (source of truth) ├── 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 (MANDATORY) ### 1. Start Up ```bash # Check current state ls -lh output/ git log --oneline -10 ``` ### 2. Read SDLC.md (MANDATORY FIRST STEP) ```bash cat docs/SDLC.md ``` ### 3. Understand Requirements - Read **docs/SDLC.md** for MANDATORY development workflow - Read **docs/PRD.md** (source of truth) - Check **Mandatory Security Requirements** section below ### 4. Write Tests FIRST (TDD - MANDATORY) ```bash # Create test file BEFORE implementing vim tests/unit/my_feature_test.bats # Run test to confirm it FAILS (RED phase) ./run.sh test:unit ``` ### 5. Implement Code - **Read files before editing** (Critical!) - Use exact text matching (whitespace matters) - Write minimal code to pass tests (GREEN phase) ### 6. Update Documentation (MANDATORY) - Update **docs/PRD.md** if adding/changing requirements - Update **docs/security-model.md** if changing security architecture - Update **docs/TEST-COVERAGE.md** with new test counts ### 7. Run Tests ```bash ./run.sh lint # MUST pass with zero warnings ./run.sh test:unit # MUST pass ./run.sh test # MUST pass (all tests) ``` ### 8. Commit (Pre-commit Hook Will Verify) ```bash git status git diff git add git commit -m "type: subject body (optional) 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush " # Pre-commit hook runs automatically and verifies SDLC compliance ``` ### 9. Push ```bash 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 docs/SDLC.md FIRST** before starting ANY work - **Write tests FIRST** (TDD is MANDATORY) - 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 - **Skip reading SDLC.md** - This is MANDATORY - **Write code before tests** - TDD is MANDATORY - **Commit without running tests** - Pre-commit will block you - Edit files you haven't read - Guess at text matches - 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, security ``` --- ## 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 - [ ] **Read docs/SDLC.md first** (MANDATORY) - [ ] **Tests written first** (TDD mandatory) - [ ] All tests pass (`./run.sh test`) - [ ] Lint passes (`./run.sh lint`) - [ ] Documentation updated (PRD, security-model, TEST-COVERAGE) - [ ] Conventional commit message used - [ ] No security requirements violated - [ ] Docker workflow followed - [ ] Changes committed and pushed --- **Remember**: This is a security-critical project. SDLC compliance is MANDATORY. Test everything. Read before editing. Follow the workflow. **Read docs/SDLC.md FIRST.** **For current status, see STATUS.md.** --- **Last Updated**: 2026-02-19 **SDLC Enforcement**: Pre-commit hook + mandatory workflow documentation