path: root/AGENTS.md

# AGENTS.md

## Project scope

This repository is a compact personal Emacs 30 configuration centred on Org mode as the primary work surface.

The live configuration is intentionally small:

- `early-init.el`
- `init.el`

Treat this as a standalone project. Do not assume hidden modules, generated files, or an older architecture unless the user explicitly adds them.

The immediate focus of the project is the Org core workflow rather than feature expansion. Prioritise the quality of the main operating loop:

- agenda
- capture
- refile
- archive
- speed commands
- narrowing and widening
- predictable window behaviour
- heading-centric navigation

Use `todo.md` as the working list of intended improvements and constraints when it is present in the repo.

## Role and technical standard

Operate as an Emacs Lisp expert working with Emacs 30.

Changes must be:

- idiomatic Elisp
- consistent with standard Emacs and Org conventions
- understandable by a human maintaining a small personal config
- biased toward built-in behaviour before custom behaviour

Do not treat this as a generic editor customisation exercise. Treat it as careful Elisp work on a deliberately small system.

## Design principles

### 1. Keep the configuration small

Prefer direct configuration over abstraction.

- Use built-in variables, hooks, keybindings, and package options first.
- Avoid turning a small config into a framework.
- Do not split code into extra files or modules unless explicitly asked.
- Do not introduce subsystems because they seem generally useful.

### 2. Prefer stock Emacs and package behaviour

Customise packages within their normal boundaries.

- Prefer supported configuration variables and documented hooks.
- Avoid wrapping or extending packages with bespoke behaviour unless there is a real gap.
- Do not build custom behaviour when standard Org functionality already solves the problem well enough.

### 3. Be judicious with helper functions

Minimise helper functions.

- Do not add helpers when a direct configuration form is clear and acceptable.
- Add a helper only when it materially improves clarity, correctness, reuse, or error handling.
- When a new helper or constant is justified, namespace it with the `ss-` prefix.
- Keep helpers small, local in intent, and easy to inspect.

If a change would introduce several helpers or a mini-abstraction layer, that is usually a sign the design should be simplified.

### 4. Optimise for robustness, not cleverness

The configuration should not be brittle.

- Handle missing files gracefully.
- Handle missing directories gracefully.
- Handle missing external executables or optional dependencies gracefully.
- Prefer clear failure modes and useful messages over silent breakage.
- Avoid partial setup that leaves inconsistent state behind.

Do not assume the user's environment is fully prepared.

### 5. Respect the boundary between config and notes

The user's notes live outside this repository, typically under `~/org`.

The configuration may reference that location, but it does not own the note system.

- Do not silently create a large directory structure.
- Do not overwrite user files.
- Do not assume every expected file already exists.
- Check for existence where appropriate.
- Fail safely and clearly when required files are absent.

The repo configures behaviour. It should not behave like a provisioning tool unless explicitly asked.

### 6. Preserve portability

The configuration should work across macOS, Linux, and Windows where practical.

- Avoid platform-specific assumptions unless unavoidable.
- Be careful with path handling.
- Be careful with executable discovery.
- Be careful with shell-specific behaviour.
- Prefer portable Emacs primitives over platform-bound shortcuts.

When platform-specific logic is genuinely needed, keep it explicit and narrow.

## Change bias

When making changes, prefer work that strengthens the current Org operating model instead of adding adjacent capabilities.

Good changes usually improve one of these:

- friction of capture
- clarity of agenda
- refile and archive ergonomics
- navigation speed
- heading-based work patterns
- modal and predictable window behaviour
- resilience when files or tools are missing

Avoid speculative extras unless the user explicitly asks for them.

## Style guidance for code changes

- Prefer clear, flat code over clever abstractions.
- Prefer explicit names over short opaque ones.
- Keep comments useful and sparse.
- Do not add comments that merely restate the code.
- Use `defconst`, `defvar`, and helper functions only when they add real value.
- Namespace constants, variables, and helpers with `ss-` when introducing project-owned definitions.
- Keep custom code small and close to the behaviour it supports.
- Prefer docstrings on non-trivial functions and user commands.
- Keep docstrings short, factual, and action-oriented.

## Package and dependency stance

Prefer built-in packages and standard Org features first.

When using third-party packages:

- keep the package set small
- use them for clear workflow wins
- configure them conservatively
- avoid deep custom extensions unless necessary

Do not add a package when built-in Emacs or Org can solve the problem simply enough.

## User experience stance

This project values a calm, dependable workflow over a feature-rich one.

Changes should aim for:

- predictable windows
- low-friction capture
- fast movement through headings
- minimal surprise
- explicit behaviour
- simple recovery when something is missing

Avoid adding UI noise, background magic, or hidden automation unless explicitly requested.

## Maintenance rules

### Updating `todo.md`

When `todo.md` is present, treat it as the current backlog for the Org core workflow.

- Align proposed work to that list unless the user explicitly changes direction.
- Do not rewrite or reorganise `todo.md` without being asked.
- Mark items complete only when the implementation actually covers them.
- Do not mark exploratory discussion as completed work.
- If a change materially affects an item in `todo.md`, mention that connection clearly.

### Preserving intent in `init.el` and `early-init.el`

- Keep `early-init.el` limited to true early startup concerns.
- Keep operational behaviour in `init.el` unless there is a strong reason otherwise.
- Avoid scattering related behaviour across distant sections when a local edit is clearer.
- Do not introduce generated-file workflows unless explicitly requested.

### Editing discipline

- Make the smallest coherent change that solves the problem.
- Do not refactor unrelated parts of the config while addressing a narrow request.
- Preserve existing behaviour unless the requested change should alter it.
- If a simplification removes custom code in favour of stock behaviour, prefer that.
- Avoid placeholder abstractions for imagined future needs.

## What to avoid

Avoid the following unless the user asks for them:

- large helper layers
- package-specific mini-frameworks
- hidden bootstrapping of external note files
- aggressive auto-creation of directories or content
- over-designed metadata schemes
- custom behaviour that fights normal Org conventions
- platform-specific shortcuts presented as universal solutions

## Output expectations

When proposing or implementing changes:

- keep the solution scoped to the user's request
- preserve the small-project character of the repo
- explain trade-offs plainly when they matter
- prefer the simplest correct implementation
- do not broaden scope without a strong reason

If a design can be solved either with stock configuration or custom machinery, choose stock configuration unless there is a clear downside.