Files

T

Charles N Wyble 97ff9c321d docs(agents): document repo layout and autonomous git policy

Make AGENTS.md actionable for future agents by recording what was learned
while fixing the provisioning scripts:

- Add a Repository Layout section: the KNELShellFramework is vendored
  under vendor/.../KNELShellFramework (not at repo root), scripts must
  self-locate via BASH_SOURCE, configs are read locally (no CDN), and
  some .sh agents are actually PHP
- Replace the vague "commit immediately" note with an explicit
  Autonomous Git Workflow section authorizing agents to commit AND push
  without being asked, grouped into coherent atomic commits

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

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

2026-07-25 13:49:55 -05:00

3.0 KiB

Raw Blame History

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:

Commit atomically: Each logical change should be its own commit
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
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:

Stage only the files belonging to that logical change.
Commit with a conventional, well-formed message (see above).
Push to origin (git push). The branch tracks origin/main.
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.