docs/plans/2026-10-05-agenda.md

Agenda Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: The day/week agenda (org-agenda-list): which entries appear on which day, with org's leaders, times, categories, tags, sort order and time grid, checked line by line against Emacs; an agenda window in the app that jumps to entries.

Architecture: OrgCore/Agenda ports the collectors of org-agenda.el: org-agenda-get-deadlines, -get-scheduled, -get-timestamps, -get-blocks, org-agenda-format-item with the default prefix %i %-12:c%?-12t% s, org-agenda-highlight-todo, org-entries-lessp with (habit-down time-up urgency-down category-keep), org-agenda-add-time-grid-maybe, and the day headers of org-agenda-format-date-aligned. Repeaters go through org-closest-date. An AgendaSource is built per file from its text and tree (headings, planning, timestamps with positions, categories, skip ranges); the app caches sources by file hash and replaces them with the open session's text, which is the overlay the design asks of the index. The index rows don't carry positions or raw timestamp text, so the agenda reads sources rather than SQL.

Tech Stack: Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.

Spec: docs/design.md, "Phase 3", "Workspace, storage and index".

Global Constraints

• Oracle: org-agenda-list over temp files with the clock frozen; each line compared as text (tags realigned to one space) plus type, org-category, time-of-day, extra, urgency and the heading marker.
• Org defaults otherwise: 14 warning days, deadlines and scheduled items shown when done, future repeats shown, overdue items only on today, no habits (phase 6), no diary or diary sexps.

Defaults chosen (user may change)

• Doom's view: 10 days starting 3 days before today.
• Agenda files: the top-level .org files of each workspace root, as Doom's org-agenda-files is the org directory.

---

Task 1: Engine

• Absolute days, ISO weeks; org-closest-date; org-get-wdays.
• AgendaSource from text; collectors; formatting; sorting; time grid; day headers.
• Oracle over synthetic files (repeaters of every unit, warnings, delays, ranges, times in headings, priorities, categories, inherited tags, archived and commented trees, src blocks, done items) for several "today"s, and over the three corpora for a 10-day span.
• Commit "Agenda engine".

Task 2: App

• Agenda window (⌘⇧A, palette): day headers, items with category, time, leader, TODO, title, tags; previous/next span, today; click or RET jumps to the entry; refreshes on saves and open-document edits.
• Settings: span, start offset, agenda folders.
• Commit "Agenda view".