From 97ff9c321d1708463a2a6a1aa7aa2a746a19b594 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Sat, 25 Jul 2026 13:49:55 -0500 Subject: [PATCH] docs(agents): document repo layout and autonomous git policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 219ff49..032bfff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,27 @@ # 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: @@ -39,7 +61,16 @@ deployment. Assisted-by: GLM-5 via Crush ``` -## Important +## Autonomous Git Workflow -**NEVER wait to be asked to commit and push your work.** -**Commit immediately after each logical unit of work.** +**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.