# 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.