# 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 RULES - READ THESE FIRST ### 1. AUTO-COMMIT & AUTO-PUSH IS MANDATORY **You MUST commit and push AUTOMATICALLY as you work. NEVER wait for user to ask.** - **Commit after EVERY logical change** - Don't batch work - **Push immediately after commit** - `git push origin main` - **Never ask permission to commit** - Just do it - **Never leave uncommitted changes** - At session end, everything is committed ### 2. SDLC COMPLIANCE IS MANDATORY **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 scripts/ # Utility scripts (setup-githooks.sh) githooks/ # Shared git hooks (pre-commit) 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 # Configure git hooks (if not already done) ./scripts/setup-githooks.sh # 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 - Update **JOURNAL.md** with ADRs, lessons learned, session notes (append-only) ### 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 & AUTO-PUSH (CRITICAL) **You MUST commit and push AUTOMATICALLY as you work. NEVER wait for user to ask.** #### Commit Frequency - **Commit early and often** - After EACH logical unit of work - **One atomic commit per change** - Never batch unrelated changes - **Push immediately after commit** - Changes are not complete until pushed #### When to Commit - After writing a failing test (TDD: RED phase) - After making the test pass (TDD: GREEN phase) - After refactoring code - After updating documentation - After fixing a bug - After ANY meaningful change #### Atomic Commits - Each commit should represent ONE logical change - If you changed 3 files for one feature → ONE commit - If you fixed a bug AND updated docs → ONE commit - If you added a feature AND fixed an unrelated bug → TWO commits #### Conventional Commit Format (MANDATORY) ``` : [body - explain WHAT changed, WHY, and context] [footer - references, breaking changes] 💘 Generated with Crush Assisted-by: via Crush ``` **Types:** `feat`, `fix`, `security`, `docs`, `test`, `refactor`, `chore` #### Verbose Commit Messages (MANDATORY) The body MUST explain: 1. **WHAT** changed (brief summary) 2. **WHY** it changed (context/motivation) 3. **HOW** it works (if non-obvious) 4. Any references (PRD requirements, issue numbers) **Example:** ``` security: enforce JOURNAL.md updates in SDLC workflow JOURNAL.md is the AI memory file containing ADRs and lessons learned. It was not being consistently updated during development work. Changes: - AGENTS.md: Added JOURNAL.md to mandatory documentation step - SDLC.md: Added JOURNAL.md to documentation sync requirements - pre-commit hook: Check for JOURNAL.md updates on new functions Reference: docs/SDLC.md section 4 (Documentation-Code-Test Sync) 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush ``` #### The Commit-Push Cycle ``` 1. Make a logical change (code, test, or docs) 2. Run: ./run.sh lint && ./run.sh test:unit 3. git add 4. git commit with verbose conventional message 5. git push origin main 6. Continue working ``` **NEVER:** - Wait for user to ask you to commit - Batch multiple unrelated changes into one commit - Skip the push step - Leave changes uncommitted at end of session ### 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 ### Conventional Commits with Verbose Body (MANDATORY) ``` :