Refactor Emacs config into modules

2 files changed, 233 insertions, 0 deletions

diff --git a/docs/plans/2026-04-09-modular-emacs-architecture-design.md b/docs/plans/2026-04-09-modular-emacs-architecture-design.md
new file mode 100644
index 0000000..1c2ce14
--- /dev/null
+++ b/docs/plans/2026-04-09-modular-emacs-architecture-design.md
@@ -0,0 +1,81 @@
+# Modular Emacs Architecture Design
+
+**Date:** 2026-04-09
+
+## Goal
+
+Refactor the repository from a single literate `config.org` source into a
+hand-edited modular Emacs configuration built around `init.el`,
+`early-init.el`, and a small set of domain-based Lisp modules under `lisp/`,
+while preserving existing behavior as closely as possible.
+
+## Scope
+
+This change is an architectural refactor, not a workflow redesign. Existing
+startup behavior, packages, capture flows, agenda rules, CRM commands,
+completion setup, and keybindings should remain materially the same unless a
+small structural adjustment is required by the new module boundaries.
+
+## Architecture
+
+### Entry points
+
+- `early-init.el` remains a standalone file and contains only true early
+  startup concerns that must exist before the first GUI frame.
+- `init.el` becomes the hand-edited runtime entry point.
+- `init.el` adds `lisp/` to `load-path`, defines a central
+  `ss-enabled-features` list, requires `ss-core`, and conditionally loads and
+  sets up each high-level feature module.
+
+### Module boundaries
+
+- `lisp/ss-core.el`
+  Owns Emacs version checks, package bootstrap, shared constants and helper
+  functions, note-system paths, and small shared editor defaults that other
+  modules depend on.
+- `lisp/ss-ui.el`
+  Owns theme, fonts, frame behavior, modeline, and terminal-versus-GUI UI
+  setup.
+- `lisp/ss-org.el`
+  Owns base Org configuration, shared Org helpers, startup MOC behavior, and
+  note-opening helpers.
+- `lisp/ss-agenda.el`
+  Owns agenda file discovery rules and agenda command setup.
+- `lisp/ss-capture.el`
+  Owns journal capture helpers and `org-capture` templates.
+- `lisp/ss-denote.el`
+  Owns Denote configuration and note creation helpers.
+- `lisp/ss-crm.el`
+  Owns all people CRM logic, including parsing, cache management, abbrevs,
+  CAPF, lookup, open/find/insert/add/report commands, and prompt helpers.
+- `lisp/ss-gptel.el`
+  Owns the experimental `gptel` integration.
+- `lisp/ss-keys.el`
+  Owns central global keybindings only.
+
+### Dependency shape
+
+- `ss-core` is the only unconditional module.
+- Other modules may depend on `ss-core` helpers and shared path constants.
+- `ss-keys` binds commands provided by other modules but should not implement
+  workflow logic itself.
+- Side effects should happen in each module's `ss-...-setup` function rather
+  than during `require`, except for definitions that are harmless at load time.
+
+## Migration decisions
+
+- Remove `config.org` entirely after extraction. There will be no transitional
+  dual system and no compatibility tangling layer.
+- Keep `build` only if it remains useful for the modular setup; otherwise
+  remove or repurpose it truthfully.
+- Keep `reset` only if it still aligns with the hand-edited architecture;
+  update it so it no longer treats `init.el` or `early-init.el` as generated
+  artifacts.
+
+## Validation
+
+- Primary validation: `emacs --batch -Q --load ./init.el`
+- If the refactor preserves terminal-specific UI behavior, also verify in a
+  real `emacs -nw` session when practical.
+- Documentation must be updated in the same change so `README.md` and
+  `AGENTS.md` describe the modular architecture truthfully.
diff --git a/docs/plans/2026-04-09-modular-emacs-refactor.md b/docs/plans/2026-04-09-modular-emacs-refactor.md
new file mode 100644
index 0000000..ad44ca1
--- /dev/null
+++ b/docs/plans/2026-04-09-modular-emacs-refactor.md
@@ -0,0 +1,152 @@
+# Modular Emacs Refactor Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the literate `config.org` runtime with a modular hand-edited Emacs configuration centered on `init.el`, `early-init.el`, and `lisp/ss-*.el`.
+
+**Architecture:** Keep `early-init.el` minimal, move reusable runtime logic into domain modules under `lisp/`, and make `init.el` the single composition layer that enables features explicitly and calls one setup function per module. Preserve current behavior unless a structural refactor requires a minimal change.
+
+**Tech Stack:** Emacs Lisp, built-in `package.el`, `use-package`, Org mode, Denote, gptel
+
+---
+
+### Task 1: Create the modular file layout
+
+**Files:**
+- Create: `early-init.el`
+- Create: `init.el`
+- Create: `lisp/ss-core.el`
+- Create: `lisp/ss-ui.el`
+- Create: `lisp/ss-org.el`
+- Create: `lisp/ss-agenda.el`
+- Create: `lisp/ss-capture.el`
+- Create: `lisp/ss-denote.el`
+- Create: `lisp/ss-crm.el`
+- Create: `lisp/ss-gptel.el`
+- Create: `lisp/ss-keys.el`
+
+**Step 1: Create `early-init.el` with only early frame settings**
+
+Write the standalone early startup file and keep it limited to frame defaults
+that previously had to exist before the first GUI frame.
+
+**Step 2: Create `init.el` as the composition root**
+
+Add `lisp/` to `load-path`, define `ss-enabled-features`, require `ss-core`,
+and conditionally require each optional module before calling its setup
+function.
+
+**Step 3: Create module skeletons**
+
+Add one `ss-...-setup` function per module and provide each feature.
+
+### Task 2: Extract shared runtime and UI behavior
+
+**Files:**
+- Modify: `lisp/ss-core.el`
+- Modify: `lisp/ss-ui.el`
+
+**Step 1: Move version checks, package bootstrap, shared paths, and editing defaults into `ss-core.el`**
+
+Keep shared constants and helper functions in one place and avoid hidden
+cross-module state.
+
+**Step 2: Move theme, fonts, frame behavior, and modeline setup into `ss-ui.el`**
+
+Preserve the current GUI-versus-terminal behavior and keep side effects in
+`ss-ui-setup`.
+
+### Task 3: Extract Org, agenda, capture, and Denote domains
+
+**Files:**
+- Modify: `lisp/ss-org.el`
+- Modify: `lisp/ss-agenda.el`
+- Modify: `lisp/ss-capture.el`
+- Modify: `lisp/ss-denote.el`
+
+**Step 1: Move shared Org paths and note helpers into `ss-org.el`**
+
+Keep `~/org` invariants unchanged and preserve startup MOC behavior.
+
+**Step 2: Move agenda discovery and agenda command wiring into `ss-agenda.el`**
+
+Preserve explicit include and exclude rules.
+
+**Step 3: Move journal capture helpers and `org-capture` templates into `ss-capture.el`**
+
+Keep the existing templates and journal structure intact.
+
+**Step 4: Move Denote setup into `ss-denote.el`**
+
+Preserve prompts, keywords, and key-facing commands.
+
+### Task 4: Extract CRM and gptel domains
+
+**Files:**
+- Modify: `lisp/ss-crm.el`
+- Modify: `lisp/ss-gptel.el`
+
+**Step 1: Move all CRM logic into `ss-crm.el`**
+
+Keep parsing, cache invalidation, abbrevs, CAPF, reports, and commands
+together in the CRM module only.
+
+**Step 2: Move experimental Copilot-backed gptel setup into `ss-gptel.el`**
+
+Preserve existing commands and defaults.
+
+### Task 5: Centralize keybindings
+
+**Files:**
+- Modify: `lisp/ss-keys.el`
+
+**Step 1: Bind the existing workflow commands in one place**
+
+Move global bindings out of the feature modules so feature inclusion remains
+centralized and explicit.
+
+### Task 6: Update scripts and documentation
+
+**Files:**
+- Modify: `README.md`
+- Modify: `AGENTS.md`
+- Modify or delete: `build`
+- Modify: `reset`
+- Delete: `config.org`
+
+**Step 1: Rewrite documentation to describe the modular architecture truthfully**
+
+Remove stale references to tangling, generated startup files, and `config.org`
+as the source of truth.
+
+**Step 2: Update helper scripts**
+
+Remove or rewrite anything that only made sense for the literate build path.
+
+**Step 3: Remove `config.org`**
+
+Delete the literate source once the extracted runtime files are in place.
+
+### Task 7: Validate the new startup path
+
+**Files:**
+- Verify: `init.el`
+- Verify: `early-init.el`
+- Verify: `lisp/ss-*.el`
+
+**Step 1: Run batch load verification**
+
+Run: `emacs --batch -Q --load ./init.el`
+
+Expected: startup completes without load errors.
+
+**Step 2: Run a terminal startup check if practical**
+
+Run: `emacs -nw`
+
+Expected: terminal UI behavior still matches the previous configuration.
+
+**Step 3: Summarize validation and any intentional behavior changes**
+
+Note any small structural changes required by the refactor, and call out
+whether `README.md` and `AGENTS.md` were updated.