diff --git a/system/flight-plan-emacs-ux-overhaul.org b/system/flight-plan-emacs-ux-overhaul.org new file mode 100644 index 0000000..1a9f4d6 --- /dev/null +++ b/system/flight-plan-emacs-ux-overhaul.org @@ -0,0 +1,53 @@ +#+TITLE: Flight Plan: Emacs Client UX Overhaul +#+DATE: 2026-04-07 +#+FILETAGS: :plan:ux:emacs:interface:psf: + +* Phase A: Demand (Verify State) +- Current state: The `org-agent` Emacs client uses a single buffer for both input and output, or a clunky side-window for reasoning. The interface is rudimentary and lacks modern chat application affordances. +- User feedback indicates that responses and reasoning streams are sometimes missing or hard to read. +- Objective: Design a comprehensive, intuitive, and modern UX for the Emacs client. + +* Key Requirements +1. **Dedicated Input Area**: A text box (minibuffer or dedicated window at the bottom) for user input, distinct from the chat history. +2. **Main History Buffer**: A primary buffer displaying the conversation history, agent outputs, and system logs. +3. **Syntax Highlighting**: Enhanced colorization depending on the syntax (e.g., Lisp code, shell commands, Org-mode elements). +4. **Diff Visualization**: Clear, visual representation of proposed code changes or diffs, akin to modern CLI tools (e.g., `gemini-cli` or `magit`). +5. **Overall Appeal**: A comprehensive design that feels modern and intuitive for users accustomed to tools like Claude Code or ChatGPT interfaces. + +* Phase B: Blueprint (Architectural Design) + +** 1. Window Layout Management +We will abandon the single-buffer approach and adopt a dual-window layout for the chat interface: +- **`*org-agent-chat*` (Top, 80% height)**: A read-only `special-mode` or customized `org-mode` buffer dedicated to displaying the conversation history, agent responses, and tool execution logs. +- **`*org-agent-input*` (Bottom, 20% height)**: A dedicated `markdown-mode` or `org-mode` buffer for composing messages. Pressing `C-c C-c` here will send the contents to the daemon, clear the input buffer, and append the user's message to the main chat buffer. + +** 2. The Output Formatting Engine (Syntax & Color) +To make the main chat buffer appealing, we need a robust formatting engine within `org-agent.el`: +- **Structured Insertion**: When the daemon sends an `:insert-at-end` command, the Emacs client will parse the payload. +- **Font-Lock Extensions**: We will define custom `font-lock` rules for the `*org-agent-chat*` buffer to highlight specific elements: + - *User Messages*: Distinct background or font face. + - *Agent Responses*: Standard Org-mode styling. + - *Tool Executions (Reasoning)*: Dimmed or italicized text for "Thinking..." or "Executing shell command: `ls`". + - *Code Blocks*: Native syntax highlighting for `#+begin_src` blocks using `org-src-fontify-natively`. + +** 3. Diff Visualization Interface +To handle code modifications safely and beautifully: +- When the agent proposes a file change, it will send a structured `:diff` or `:patch` payload rather than raw text. +- The Emacs client will intercept this payload and present it using `diff-mode` or a custom overlay within the chat buffer, providing visual red/green highlights for removals and additions. +- *Interactive Acceptance*: The user can press a key (e.g., `C-c C-y`) on the diff to accept and apply the patch, realizing the "Active Approval Mode" pattern in Emacs. + +** 4. The Reasoning Stream Integration +- Instead of a separate right-side window that clutters the workspace, the reasoning stream (System 1 thoughts, tool calls) will be integrated directly into the main `*org-agent-chat*` buffer. +- It will be presented as a collapsible Org-mode drawer (e.g., `:REASONING:`) or formatted as dimmed, transient text that provides transparency without overwhelming the primary conversation. + +* Phase C: Tester (Verification Strategy) +- Launch `M-x org-agent`. +- Verify the dual-window layout appears correctly. +- Type a message in the input buffer, send it, and verify it clears and appears in the main buffer. +- Trigger a tool call and verify the reasoning stream is formatted clearly (and distinct from the final answer). +- Trigger a file modification and verify the diff visualization is presented elegantly. + +* Migration Strategy +This overhaul requires significant changes to: +1. `projects/org-agent/src/org-agent.el` (The Emacs client). +2. `notes/org-skill-chat.org` (To update the expected payload formats if we move beyond simple `:insert-at-end`).