Refactor Emacs config into modules

1 files changed, 152 insertions, 0 deletions

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.