diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 89 |
1 files changed, 59 insertions, 30 deletions
@@ -2,60 +2,89 @@ ## Project Purpose -This repository is for the creation and maintenance of Emacs 30 configuration files. +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 Emacs 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 `journal.org`, `daily/`, `projects/`, `areas/`, `areas/people/people.org`, `resources/`, and `archives/`. +- `init.el` is the hand-edited runtime entry point. +- `early-init.el` is the hand-edited early startup file. +- Runtime implementation lives in domain modules under `lisp/`. +- Keep the module set reasonably chunky and domain-based: + `ss-core.el`, `ss-ui.el`, `ss-org.el`, `ss-agenda.el`, `ss-capture.el`, + `ss-denote.el`, `ss-crm.el`, `ss-gptel.el`, and `ss-keys.el`. +- The current Org workflow lives under `~/org/` with `journal.org`, `daily/`, + `projects/`, `areas/`, `areas/people/people.org`, `resources/`, and + `archives/`. - `~/org/` is external to this repository and must already exist. -- The configuration may open files in `~/org/`, but it must not create directories, create files, or validate note structure. -- `~/org/journal.org` is the operational journal. It must already exist. The configuration may open it, but it must not create or manage it. -- `~/org/moc.org` is a normal note. It must already exist. The configuration may open it, but it must not create or manage it. -- `~/org/areas/people/people.org` is the people CRM file. It must already exist. The configuration may open it, but it must not create or manage it. -- The operational journal lives in `~/org/journal.org`; older daily notes may remain under `~/org/daily/`; durable notes created with Denote live in PARA directories under `~/org/`. -- Agenda files are discovered by explicitly including `~/org/journal.org` and recursively scanning `.org` files under `~/org/projects/`, `~/org/areas/`, and `~/org/resources/`. +- The configuration may open files in `~/org`, but it must not create + directories, create files, or validate note structure. +- `~/org/journal.org` is the operational journal. It must already exist. The + configuration may open it, but it must not create or manage it. +- `~/org/moc.org` is a normal note. It must already exist. The configuration + may open it, but it must not create or manage it. +- `~/org/areas/people/people.org` is the people CRM file. It must already + exist. The configuration may open it, but it must not create or manage it. +- Agenda files are discovered by explicitly including `~/org/journal.org` and + recursively scanning `.org` files under `~/org/projects/`, `~/org/areas/`, + and `~/org/resources/`. - Agenda discovery must exclude `~/org/archives/`. -- PARA is the organising model for durable notes, and folder placement carries meaning. -- The config includes an experimental `gptel` setup that uses GitHub Copilot as the backend. +- PARA is the organising model for durable notes, and folder placement carries + meaning. +- The config includes an experimental `gptel` setup 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. +- Edit `init.el`, `early-init.el`, and the relevant `lisp/` modules directly. +- Keep `init.el` as the central composition layer with explicit feature + inclusion. +- Keep side effects out of require time where practical; modules should expose + setup functions. - 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. +- 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. ## 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. +- For Emacs Lisp changes, verify the hand-edited startup path directly. +- 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 modular startup path documented in + `README.md`. +- 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. ## Git Workflow Expectations - Use a git-based workflow for repository changes. - Assume changes will be committed incrementally as the work progresses. -- Keep changes small and focused so they can be reviewed and committed independently. +- Keep changes small and focused so they can be reviewed and committed + independently. - Treat verification as the gate for each commit-sized unit of work. -- After verification passes for a unit of work, summarize the result and prompt the user before creating the commit. +- After verification passes for a unit of work, summarize the result and prompt + the user before creating the commit. - Keep commit messages concise and specific to the verified change. - Do not bundle unrelated changes into the same commit. ## 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. -- Keep README and AGENTS consistent. State rules explicitly and avoid hidden or heuristic behavior in documentation. +- Document non-obvious conventions close to the relevant Lisp module. +- 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. +- Keep `README.md` and `AGENTS.md` in sync with the modular architecture. - Use `~/org` consistently when describing the external notes directory. -- Before claiming a change is complete or asking to commit it, review whether `README.md` needs an update; if it does not, say so explicitly in the summary. -- 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. +- Before claiming a change is complete or asking to commit it, review whether + `README.md` needs an update; if it does not, say so explicitly in the + summary. +- Keep `AGENTS.md` concise and update it only when the repository structure or + working rules actually change. |