diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f41e7d5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md + +## Project Purpose + +This repository is for the creation and maintenance of Emacs 30 configuration files. + +## Repository Layout + +- `config.org` is the single hand-edited source of truth for the configuration. +- `init.el` and `early-init.el` are generated from `config.org` and should not be edited directly. +- Structure the literate config by startup responsibility first, then by workflow domain. +- The current Org workflow lives under `~/org/` with `daily/`, `projects/`, `areas/`, `areas/people/`, `resources/`, and `archives/`. +- Daily notes stay as plain Org files under `~/org/daily/`; longer-lived notes are handled through Denote in the same root. +- Agenda files are discovered dynamically from the project, area, and resource directories rather than from a fixed file list. +- The config also includes a small gptel workflow that uses GitHub Copilot as the backend. +- Do not treat `auto-save-list/` as source content. + +## Editing Expectations + +- Prefer small, focused changes over broad rewrites. +- Edit `config.org` first, then regenerate the derived files instead of patching generated output by hand. +- Preserve existing Emacs Lisp style and naming where patterns already exist. +- Avoid unrelated refactors while working on a specific configuration task. +- Keep narrative prose close to the configuration it explains, especially around the note-taking workflow and startup behavior. +- Be explicit about GUI-versus-terminal behavior. If a change affects `emacs -nw`, avoid moving terminal UI changes earlier in startup unless that timing is intentional. +- If the literate file starts to lose coherence, improve its sectioning and prose before introducing new generated helper files. + +## Validation Expectations + +- For Emacs Lisp changes, tangle `config.org` and verify the generated configuration loads cleanly before claiming completion. +- When Emacs is available, prefer a batch check such as `emacs --batch -Q --load init.el` from the repository root. +- Keep regression checks aligned with the generated startup path rather than any retired hand-maintained module layout. +- For changes that affect terminal Emacs behavior, verify in an actual `emacs -nw` session as well as batch mode; batch load alone will not catch interactive tty regressions. + +## Documentation Expectations + +- Document non-obvious conventions close to the relevant configuration in `config.org`. +- Update `README.md` whenever configuration or workflow changes alter package usage, startup behavior, keybindings, directory layout, capture flow, or other documented behavior. +- `README.md` must describe the current configuration truthfully. Do not leave stale documentation behind and do not document planned behavior as current behavior. +- Update AGENTS.md when the repo workflow, Org layout, or verification expectations materially change. +- Keep AGENTS.md concise and update it only when the repository structure or working rules actually change.
\ No newline at end of file |