1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
# 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 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/`.
- `~/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/`.
- 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.
- 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.
## 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.
- 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.
- 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.
- 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.
|
