# Agent Guidelines

## Repository Layout

Knowing where things live prevents broken edits:

- **Vendored framework**: `KNELShellFramework` lives at
  `vendor/git@git.knownelement.com/29418/KNEL/KNELShellFramework/`, **not** at
  the repo root. Its includes are under `Framework-Includes/` there. Never
  assume `./Framework-Includes` exists relative to the repo root.
- **Self-locating scripts**: All provisioning scripts derive their own
  location via `BASH_SOURCE` and compute `PROJECT_ROOT_PATH` from it. They must
  **never** depend on the current working directory or on `cd`/`realpath ..`
  chains. Run them from anywhere — `sudo bash SetupNewSystem.sh` works.
- **Local config files are the source of truth**: Configs in
  `ProjectCode/ConfigFiles/` are read with `cat`/`cp`. Do **not** re-introduce
  `curl ${DL_ROOT}/...` downloads from `dl.knownelement.com` — that CDN is
  deprecated for this repo.
- **Path variables**: Scripts export `PROJECT_ROOT_PATH`, `CONFIGFILES_PATH`,
  `MODULES_PATH`, `SCRIPTS_PATH`, and `AGENTS_PATH` for locating repo content.
- **Non-bash agents**: Some files under `ProjectCode/Agents/` carry a `.sh`
  extension but are PHP (e.g. `mysql.sh`, shebang `#!/usr/bin/php`). Syntax
  checkers must skip these.

## Git Commit Requirements

When making changes to this repository, ALWAYS:

1. **Commit atomically**: Each logical change should be its own commit
2. **Use conventional commit format**:
   - `feat(scope): description` - New feature
   - `fix(scope): description` - Bug fix
   - `docs: description` - Documentation changes
   - `refactor(scope): description` - Code refactoring
   - `test(scope): description` - Test additions/changes
   - `chore: description` - Maintenance tasks
3. **Write verbose, beautifully formatted messages**:
   - Title line (50 chars max)
   - Blank line
   - Body explaining WHAT and WHY (not how)
   - Reference related files/issues
   - Include footer with attribution

## Example Commit

```
feat(security-hardening): implement SCAP-STIG compliance logic

Refactor apply script to implement comprehensive security hardening:

- Add GRUB bootloader permission hardening (root:root, mode 0400)
- Disable and remove autofs service per STIG requirements
- Deploy modprobe configurations for kernel module blacklisting
- Create STIG-compliant network protocol blacklist

This ensures servers meet DoD security requirements for production
deployment.

🤖 Generated with [Crush](https://github.com/charmassociates/crush)

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

## Autonomous Git Workflow

**Agents are authorized to commit AND push autonomously. Do not wait to be
asked.** After each logical unit of work:

1. Stage only the files belonging to that logical change.
2. Commit with a conventional, well-formed message (see above).
3. Push to `origin` (`git push`). The branch tracks `origin/main`.
4. Repeat per logical unit.

Group changes so each commit is coherent on its own (a reader should
understand the commit without seeing the others). Never batch unrelated
changes into one commit.