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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
# AGENTS.md
## Project Purpose
This repository is for the creation and maintenance of Emacs 30 configuration
files.
## Repository Layout
- `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.
- 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 `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.
- 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, 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.
- 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 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.
- Keep `AGENTS.md` concise and update it only when the repository structure or
working rules actually change.
|
