Charles N Wyble
97ff9c321d
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>
77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# 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.
|