81f97687d9
- AGENTS.md now contains only agent behavior guidelines - STATUS.md is the single source for project status - Updated STATUS.md with current ISO status (built, 816 MB) - Updated recent commits section in STATUS.md 💘 Generated with Crush Assisted-by: GLM-5 via Crush <crush@charm.land>
262 lines
6.6 KiB
Markdown
262 lines
6.6 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
./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)
|
|
```bash
|
|
./run.sh iso # Build ISO (60-90 minutes)
|
|
tail -f /tmp/knel-iso-build.log
|
|
```
|
|
|
|
### 6. Test ISO (optional)
|
|
```bash
|
|
./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
|
|
```bash
|
|
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.**
|