Comparing changes

@@ -0,0 +1,44 @@
+As a `new user`, I `want elelem to detect my hardware capabilities`, so that `it can recommend an appropriate model for my system`.
+
+# SYNOPSIS
+
+Detect GPU/CPU capabilities to determine what models can run locally.
+
+# DESCRIPTION
+
+When elelem starts with no configuration, it should be able to detect:
+
+1. **GPU presence and type**:
+   - NVIDIA GPU with CUDA support (check nvidia-smi or similar)
+   - AMD GPU with ROCm support
+   - No discrete GPU (CPU-only fallback)
+
+2. **Available VRAM/RAM**:
+   - GPU memory available for model loading
+   - System RAM as fallback for CPU inference
+
+3. **Model recommendations**:
+   - Map hardware capabilities to appropriate model sizes
+   - Example: 8GB VRAM → 7B parameter model, 4GB VRAM → 3B model, CPU-only → small model
+
+This information will be used by the local provider to:
+- Select the default model automatically
+- Warn users if their hardware may struggle with a requested model
+
+# SEE ALSO
+
+* [ ] lib/elelem/system_prompt.rb (platform detection)
+* [ ] Story 001 (spike findings will inform implementation)
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Correctly detects NVIDIA GPU presence on Linux
+* [ ] Correctly detects AMD GPU presence on Linux  
+* [ ] Correctly detects available VRAM when GPU present
+* [ ] Correctly detects available system RAM
+* [ ] Returns a capability summary that can be used for model selection
+* [ ] Works gracefully when detection tools (nvidia-smi, rocm-smi) are not installed

@@ -0,0 +1,44 @@
+As a `new user`, I `want elelem to automatically download the recommended model`, so that `I can start using it immediately without manual setup`.
+
+# SYNOPSIS
+
+Download LLM models from Hugging Face with progress indication.
+
+# DESCRIPTION
+
+When the local provider is used and the required model is not present locally:
+
+1. **Model selection**:
+   - Use hardware detection (Story 002) to pick an appropriate default model
+   - Support a curated list of known-good coding models (e.g., CodeLlama, DeepSeek Coder, Qwen Coder)
+
+2. **Download process**:
+   - Download from Hugging Face Hub (GGUF format preferred for llama.cpp)
+   - Show download progress (stream CLI output or use Terminal#waiting)
+   - Store in `~/.cache/elelem/models/` or similar standard location
+
+3. **Model management**:
+   - Check if model already exists before downloading
+   - Handle interrupted downloads gracefully (resume or restart)
+
+The approach (HF CLI vs direct download) will be determined by Story 001 spike.
+
+# SEE ALSO
+
+* [ ] Story 001 (determines download approach)
+* [ ] Story 002 (provides hardware info for model selection)
+* [ ] lib/elelem/terminal.rb (progress indication)
+* [ ] ~/.cache/elelem/models/ (storage location)
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Model downloads successfully from Hugging Face
+* [ ] User sees progress indication during download
+* [ ] Downloaded model is stored in consistent location
+* [ ] Subsequent runs do not re-download existing model
+* [ ] Graceful error handling if download fails (network error, disk full, etc.)
+* [ ] At least one good default coding model is identified and tested

@@ -0,0 +1,53 @@
+As a `user`, I `want to run LLM inference locally without external servers`, so that `I can use elelem without API keys, Ollama, or network connectivity`.
+
+# SYNOPSIS
+
+Implement a local inference provider that loads and runs models directly in-process.
+
+# DESCRIPTION
+
+Create a new provider in `lib/elelem/net/` that:
+
+1. **Loads models locally**:
+   - Use the approach determined by Story 001 (llama.cpp bindings or CLI)
+   - Load GGUF model files from `~/.cache/elelem/models/`
+   - Support GPU acceleration (CUDA, ROCm) when available
+   - Fall back to CPU inference when no GPU present
+
+2. **Implements the provider interface**:
+   - Match the interface of existing providers (ollama.rb, openai.rb, claude.rb)
+   - Support streaming responses
+   - Handle the conversation history format
+
+3. **Performance considerations**:
+   - Model loading may take a few seconds - show appropriate feedback
+   - Keep model loaded in memory for subsequent prompts (don't reload per-request)
+   - Handle memory limits gracefully
+
+4. **Configuration**:
+   - Configurable via `.elelem.yml` similar to other providers
+   - Support specifying custom model path
+   - Support model selection override
+
+# SEE ALSO
+
+* [ ] Story 001 (determines implementation approach)
+* [ ] Story 003 (provides downloaded models)
+* [ ] lib/elelem/net/ollama.rb (provider interface reference)
+* [ ] lib/elelem/net/openai.rb (provider interface reference)
+* [ ] lib/elelem/net/claude.rb (provider interface reference)
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Provider loads model from local disk
+* [ ] Provider generates streaming responses
+* [ ] Provider works with GPU acceleration on CUDA
+* [ ] Provider works with GPU acceleration on ROCm
+* [ ] Provider falls back to CPU when no GPU available
+* [ ] Provider integrates with existing elelem conversation flow
+* [ ] Tool calling works with local models (if model supports it)
+* [ ] Works fully offline once model is downloaded

@@ -0,0 +1,49 @@
+As a `new user`, I `want elelem to use local inference by default`, so that `I can start using it immediately without any configuration`.
+
+# SYNOPSIS
+
+Make the local provider the default when no configuration exists.
+
+# DESCRIPTION
+
+Update elelem's provider selection logic so that:
+
+1. **First-run experience**:
+   - When no `.elelem.yml` exists and no environment variables are set
+   - Automatically select the local provider
+   - Trigger model download if needed (Story 003)
+   - Start the normal prompt interface - no wizard or extra questions
+
+2. **Provider priority** (when no explicit config):
+   1. Local provider (new default)
+   2. Ollama (if running and accessible)
+   3. OpenAI (if OPENAI_API_KEY set)
+   4. Claude (if ANTHROPIC_API_KEY set)
+
+3. **Explicit configuration**:
+   - Users can still configure any provider in `.elelem.yml`
+   - Explicit config always takes precedence
+   - Document how to switch providers
+
+4. **Seamless transition**:
+   - Existing users with configuration are not affected
+   - Only new users (no config) get the new default behavior
+
+# SEE ALSO
+
+* [ ] Story 004 (local provider implementation)
+* [ ] lib/elelem/agent.rb (provider selection logic)
+* [ ] Configuration loading code
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] New user with no config starts elelem and can chat immediately
+* [ ] Local provider is used by default (not Ollama or cloud providers)
+* [ ] Model downloads automatically on first run if not present
+* [ ] Existing users with `.elelem.yml` are not affected
+* [ ] Users with API keys in environment can still use cloud providers
+* [ ] Clear documentation on how to configure different providers

@@ -0,0 +1,47 @@
+As an `agent`, I `want to ask questions with different answer types`, so that `I can collect structured responses while still allowing conversational flexibility`.
+
+# SYNOPSIS
+
+Add support for text, single-select, multi-select, and yes/no question types to the interview tool.
+
+# DESCRIPTION
+
+The interview tool currently only supports free-form text input. This story adds support for four question types:
+
+1. **text** - Open-ended free-form input (current behavior)
+2. **single** - Single selection from a list of options (radio-button style)
+3. **multi** - Multiple selections from a list of options (checkbox style)
+4. **yesno** - Boolean yes/no confirmation
+
+Even when structured options are presented, the user can always type free-form text instead. The agent should handle unexpected responses gracefully (e.g., if the user asks a clarifying question rather than selecting an option).
+
+Example API:
+```ruby
+interview(
+  question: "Pick a color",
+  type: "single",
+  options: ["Red", "Green", "Blue"]
+)
+```
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Terminal input/output handling
+* [ ] lib/elelem/tool.rb - Tool definition structure
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Agent can specify `type: "text"` for free-form input (default behavior)
+* [ ] Agent can specify `type: "single"` with `options` array for single selection
+* [ ] Agent can specify `type: "multi"` with `options` array for multiple selection
+* [ ] Agent can specify `type: "yesno"` for boolean confirmation
+* [ ] Options are displayed as a numbered list (e.g., "1. Red", "2. Green", "3. Blue")
+* [ ] User can type a number to select an option
+* [ ] User can type free-form text instead of selecting a numbered option
+* [ ] For multi-select, user can enter comma-separated numbers (e.g., "1, 3")
+* [ ] For yes/no, accepts variations like "y", "yes", "n", "no" (case-insensitive)
+* [ ] Response returned to agent includes both the raw input and parsed selection(s)

@@ -0,0 +1,43 @@
+As an `agent`, I `want to ask multiple questions at once`, so that `I can collect related information in a single interaction like a form`.
+
+# SYNOPSIS
+
+Allow the interview tool to accept an array of questions and return all answers together.
+
+# DESCRIPTION
+
+Building on the question types feature, this story adds the ability to send a batch of questions in a single interview call. This is useful when the agent needs to collect several related pieces of information and it would be tedious to ask them one at a time.
+
+Example API:
+```ruby
+interview(questions: [
+  { question: "What's your name?", type: "text" },
+  { question: "Pick a color", type: "single", options: ["Red", "Green", "Blue"] },
+  { question: "Select features", type: "multi", options: ["Auth", "API", "UI"] },
+  { question: "Ready to proceed?", type: "yesno" }
+])
+```
+
+The questions are presented sequentially, and all answers are collected before returning to the agent. The user can still respond with clarifying questions or unexpected input on any individual question.
+
+The existing single-question API remains supported for backward compatibility.
+
+# SEE ALSO
+
+* [ ] .elelem/backlog/006-interview-question-types.md - Prerequisite: question types
+* [ ] lib/elelem/terminal.rb - Terminal input/output handling
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Agent can pass `questions` array with multiple question objects
+* [ ] Each question in the array can have its own type and options
+* [ ] Questions are presented to user one at a time in order
+* [ ] All answers are collected before returning to agent
+* [ ] Response includes an array of answers matching the question order
+* [ ] Single-question API (`question: "..."`) still works for backward compatibility
+* [ ] If user provides unexpected input on one question, that input is captured and interview continues
+* [ ] Agent receives enough context to understand which answer corresponds to which question

@@ -0,0 +1,42 @@
+As a `user`, I `want to navigate options with arrow keys`, so that `I can quickly select from a list without typing numbers`.
+
+# SYNOPSIS
+
+Add TUI-style interactive selection widgets for single and multi-select questions.
+
+# DESCRIPTION
+
+When the terminal supports it, present single-select and multi-select questions as interactive widgets where the user can:
+
+- Use **arrow keys** (up/down) to navigate between options
+- Press **space** to toggle selection (for multi-select)
+- Press **enter** to confirm selection
+
+This provides a smoother experience than typing numbers, especially for longer option lists. The numbered fallback (from story 006) remains available for terminals that don't support the TUI widgets or when the user starts typing text instead of navigating.
+
+The widget should be visually clear:
+- Highlight the currently focused option
+- Show a marker (e.g., `[x]` or `●`) for selected options
+- For single-select, selection and confirmation can be combined (enter selects and confirms)
+
+# SEE ALSO
+
+* [ ] .elelem/backlog/006-interview-question-types.md - Prerequisite: question types with numbered fallback
+* [ ] lib/elelem/terminal.rb - Terminal capabilities and input handling
+* [ ] Reline library - May provide building blocks for TUI input
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Single-select questions show an interactive list when terminal supports it
+* [ ] User can press up/down arrows to move highlight between options
+* [ ] User can press enter to select the highlighted option (single-select)
+* [ ] Multi-select questions allow space to toggle selection on highlighted option
+* [ ] Multi-select shows visual indicator for selected items (e.g., `[x]`)
+* [ ] Pressing enter on multi-select confirms current selections
+* [ ] If user starts typing text, widget gracefully switches to free-form input mode
+* [ ] Falls back to numbered list input if terminal doesn't support TUI features
+* [ ] Works correctly when terminal is resized during interaction

@@ -0,0 +1,98 @@
+# Editor Integration for Prompts
+
+As a **power user**, I want to open my `$EDITOR` from the prompt to compose long messages, so that I have a full editing environment for complex prompts.
+
+## SYNOPSIS
+
+Press `CTRL+x CTRL+e` at the prompt to open `$EDITOR`, compose text, and return to the prompt for review before sending.
+
+## DESCRIPTION
+
+When composing long or complex prompts, the terminal input line is limiting. Users need the ability to:
+- Write multi-line text comfortably
+- Paste content from other sources
+- Use familiar editor keybindings (vim, emacs, etc.)
+- Review and edit before sending
+
+### Keybinding
+
+`CTRL+x CTRL+e` - Standard Bash/Zsh binding for `edit-and-execute-command`
+
+This is the most intuitive choice for Linux/Bash/Vim/Tmux users as it matches their existing muscle memory.
+
+### Flow
+
+```
+> partial text█              # User types some text
+                             # User presses CTRL+x CTRL+e
+                             # Editor opens with "partial text" pre-populated
+                             # User edits, saves, quits
+> partial text               # Text appears at prompt
+  plus more content          # (multi-line if applicable)
+  from the editor█           # Cursor at end, ready to review
+                             # User presses Enter to send
+```
+
+### Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Empty file saved | Return to prompt, no input |
+| Editor exits non-zero | Return to prompt, preserve original text |
+| `$EDITOR` not set | Fall back to `$VISUAL`, then `vi` |
+| Multi-line text | Display all lines, submit as single message |
+
+## SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - `ask` method, Reline configuration
+* [ ] Reline documentation for custom key bindings
+* [ ] Bash `edit-and-execute-command` (CTRL+x CTRL+e)
+
+## Tasks
+
+* [ ] TBD (filled in design mode)
+
+## Acceptance Criteria
+
+* [ ] `CTRL+x CTRL+e` opens `$EDITOR` (or `$VISUAL`, or `vi`)
+* [ ] Editor pre-populates with any text already typed at the prompt
+* [ ] After saving and quitting, text appears at the prompt for review
+* [ ] User must press Enter to send (no auto-submit)
+* [ ] Empty file returns to prompt with no input (cancel)
+* [ ] Non-zero editor exit preserves original text
+* [ ] Temp file is created in appropriate location and cleaned up after
+* [ ] Multi-line text from editor displays correctly at prompt
+* [ ] Works with common editors: vim, nvim, nano, emacs
+
+## Implementation Notes
+
+```ruby
+# In Terminal, bind CTRL+x CTRL+e
+Reline::LineEditor.bind_key("\C-x\C-e") do |line_editor|
+  # 1. Get current line content
+  current_text = line_editor.line
+
+  # 2. Create temp file with content
+  require "tempfile"
+  file = Tempfile.new(["elelem-prompt-", ".md"])
+  file.write(current_text)
+  file.close
+
+  # 3. Open editor
+  editor = ENV["VISUAL"] || ENV["EDITOR"] || "vi"
+  system("#{editor} #{file.path}")
+
+  # 4. Read result
+  if $?.success?
+    new_text = File.read(file.path).strip
+    line_editor.replace_line(new_text) unless new_text.empty?
+  end
+
+  # 5. Cleanup
+  file.unlink
+end
+```
+
+### Multi-line Display
+
+Reline supports multi-line input. The edited text should be inserted and displayed across multiple lines if it contains newlines.

@@ -0,0 +1,40 @@
+As a `developer`, I `want to research local LLM inference options`, so that `we can choose the best approach for running models without external servers`.
+
+# SYNOPSIS
+
+Research spike to evaluate llama.cpp, Hugging Face CLI, and other options for local inference.
+
+# DESCRIPTION
+
+Before building the local provider, we need to understand:
+
+1. **Inference engines**: Evaluate options like llama.cpp (via Ruby bindings or CLI), Hugging Face transformers, or other local inference tools
+2. **Ruby integration**: Determine if we should use Ruby bindings (e.g., `llama_cpp.rb` gem) or shell out to a CLI tool
+3. **Hugging Face integration**: Understand how to download GGUF/GGML models, whether to use `huggingface-cli` or direct API calls
+4. **GPU support**: Verify CUDA and ROCm acceleration works on Linux
+5. **Model format**: Determine which quantized model formats to support (GGUF recommended for llama.cpp)
+
+Deliverable: A written recommendation document with:
+- Recommended approach
+- Required dependencies
+- Example code showing basic inference working
+- Known limitations
+
+# SEE ALSO
+
+* [ ] https://github.com/ggerganov/llama.cpp
+* [ ] https://github.com/yoshoku/llama_cpp.rb
+* [ ] https://huggingface.co/docs/huggingface_hub/guides/cli
+* [ ] lib/elelem/net/ (existing provider implementations)
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Document exists with clear recommendation
+* [ ] Proof-of-concept code demonstrates loading a model and generating a response
+* [ ] GPU acceleration tested on at least one platform (CUDA or ROCm)
+* [ ] Decision made: Ruby bindings vs CLI wrapper
+* [ ] Decision made: Model download strategy (HF CLI vs direct download)

@@ -0,0 +1,217 @@
+As an `agent`, I `want to ask questions with selectors and batch support`, so that `I can collect structured responses efficiently`.
+
+# SYNOPSIS
+
+Extend the interview tool to support text, single-select, and multi-select inputs with TUI navigation and batch question capability.
+
+# DESCRIPTION
+
+The interview tool currently only supports free-form text input. This story adds:
+
+1. **Input modes**:
+   - `text` - Free-form text input (current behavior, default)
+   - `select` - Radio-button style single choice from options
+   - `multi` - Checkbox style multiple choice from options
+
+2. **TUI interaction** (when terminal supports it):
+   - Arrow keys (up/down) to navigate between options
+   - Space to toggle selection (multi-select)
+   - Enter to confirm selection
+
+3. **Numbered fallback** (for dumb terminals or piped input):
+   - Display numbered list (e.g., "1. Red", "2. Green", "3. Blue")
+   - User types number to select
+   - Comma-separated numbers for multi-select (e.g., "1, 3")
+
+4. **Batch questions**:
+   - Accept array of questions in single call
+   - Present sequentially, collect all answers before returning
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Add `select` and `multi_select` methods
+* [ ] lib/elelem/plugins/interview.rb - Add `options`, `multi`, and `questions` params
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Agent can provide `options` array to enable selector mode
+* [ ] Agent can set `multi: true` to allow multiple selections
+* [ ] Single-select with TUI: arrow keys navigate, enter confirms
+* [ ] Multi-select with TUI: arrow keys navigate, space toggles, enter confirms
+* [ ] Falls back to numbered list when terminal doesn't support TUI
+* [ ] Free-form text input still works when no options provided
+* [ ] Agent can pass `questions` array with multiple question objects
+* [ ] Each question in batch can have its own options and multi setting
+* [ ] Batch returns array of answers matching question order
+* [ ] Single-question API remains backward compatible
+* [ ] No new gem dependencies (uses io/console from stdlib)
+
+# Implementation Notes
+
+The following implementation plan is provided as guidance for the developer.
+
+## Tool Schema
+
+```json
+{
+  "question": { "type": "string", "description": "The question to ask" },
+  "options": { "type": "array", "description": "List of options (enables selector)" },
+  "multi": { "type": "boolean", "description": "Allow multiple selections" },
+  "questions": { "type": "array", "description": "Batch of question objects" }
+}
+```
+
+## Files to Modify
+
+- `lib/elelem/terminal.rb` - Add `select` and `multi_select` methods
+- `lib/elelem/plugins/interview.rb` - Add `options`, `multi`, and `questions` params
+
+## Terminal API
+
+```ruby
+# Single select - returns selected option string
+terminal.select(options) # => "option1"
+
+# Multi select - returns array of selected options
+terminal.multi_select(options) # => ["option1", "option3"]
+```
+
+## Reference Implementation
+
+### Terminal#select (single choice)
+
+```ruby
+def select(options)
+  return options.first if options.size == 1
+  require "io/console"
+
+  index = 0
+  render_options = -> {
+    options.each_with_index do |opt, i|
+      prefix = i == index ? "> " : "  "
+      $stdout.puts "#{prefix}#{opt}"
+    end
+  }
+
+  render_options.call
+
+  loop do
+    key = read_key
+    case key
+    when :up then index = (index - 1) % options.size
+    when :down then index = (index + 1) % options.size
+    when :enter then break
+    end
+    $stdout.print "\e[#{options.size}A\e[J"
+    render_options.call
+  end
+
+  options[index]
+end
+
+def read_key
+  char = $stdin.getch
+  return :enter if char == "\r" || char == "\n"
+  return char unless char == "\e"
+
+  return char unless $stdin.ready?
+  seq = $stdin.getch
+  return char unless seq == "["
+
+  code = $stdin.getch
+  case code
+  when "A" then :up
+  when "B" then :down
+  else char
+  end
+end
+```
+
+### Terminal#multi_select (multiple choice)
+
+```ruby
+def multi_select(options)
+  require "io/console"
+
+  index = 0
+  selected = Set.new
+
+  render_options = -> {
+    options.each_with_index do |opt, i|
+      cursor = i == index ? ">" : " "
+      check = selected.include?(i) ? "[x]" : "[ ]"
+      $stdout.puts "#{cursor} #{check} #{opt}"
+    end
+  }
+
+  render_options.call
+
+  loop do
+    key = read_key
+    case key
+    when :up then index = (index - 1) % options.size
+    when :down then index = (index + 1) % options.size
+    when :space then selected.include?(index) ? selected.delete(index) : selected.add(index)
+    when :enter then break
+    end
+    $stdout.print "\e[#{options.size}A\e[J"
+    render_options.call
+  end
+
+  options.values_at(*selected.to_a.sort)
+end
+```
+
+### Updated Interview Plugin
+
+```ruby
+Elelem::Plugins.register(:interview) do |agent|
+  agent.toolbox.add("interview",
+    description: "Ask the user a question and wait for their response",
+    params: {
+      question: { type: "string", description: "The question to ask" },
+      options: { type: "array", description: "List of options for selector" },
+      multi: { type: "boolean", description: "Allow multiple selections" },
+      questions: { type: "array", description: "Batch of question objects" }
+    },
+    required: ["question"]
+  ) do |args|
+    if args["questions"]&.any?
+      # Batch mode
+      answers = args["questions"].map do |q|
+        agent.terminal.say(agent.terminal.markdown(q["question"]))
+        ask_one(agent.terminal, q["options"], q["multi"])
+      end
+      { answers: answers }
+    else
+      # Single question mode
+      agent.terminal.say(agent.terminal.markdown(args["question"]))
+      answer = ask_one(agent.terminal, args["options"], args["multi"])
+      { answer: answer }
+    end
+  end
+
+  def ask_one(terminal, options, multi)
+    if options&.any?
+      multi ? terminal.multi_select(options) : terminal.select(options)
+    else
+      terminal.ask("> ")
+    end
+  end
+end
+```
+
+## Verification
+
+1. Run `./bin/run -p vertex`
+2. Ask the LLM to use the interview tool with options
+3. Test arrow key navigation
+4. Test single select (Enter confirms)
+5. Test multi select (Space toggles, Enter confirms)
+6. Test free-form text still works when no options provided
+7. Test batch questions with mixed types
+8. Run `bin/test`

@@ -0,0 +1,73 @@
+As a `developer`, I `want design mode to support creating Architecture Decision Records`, so that `architectural decisions are documented consistently and repeatably`.
+
+# SYNOPSIS
+
+Add ADR creation capability to design mode with a standard template.
+
+# DESCRIPTION
+
+When architectural decisions emerge during design sessions, the agent should be able to create ADRs using a consistent template. ADRs are stored in `doc/adr/` and follow a numbered naming convention.
+
+The design prompt should be updated to:
+1. Explain when to create ADRs (significant architectural decisions)
+2. Provide the ADR template
+3. Allow writing to `doc/adr/` directory
+
+# SEE ALSO
+
+* [ ] lib/elelem/prompts/design.erb - Design mode prompt
+* [ ] doc/adr/ - ADR storage location (to be created)
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Design mode prompt includes ADR template
+* [ ] Design mode can write files to `doc/adr/`
+* [ ] ADRs follow naming convention: `ADR-NNNN-short-name.md`
+* [ ] Template includes: Date, Status, Context, Decision, Consequences
+* [ ] Agent understands when to propose creating an ADR
+
+# ADR Template
+
+```markdown
+# ADR-NNNN: Title
+
+**Date:** YYYY-MM-DD
+**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+**Positive:**
+- Benefit 1
+- Benefit 2
+
+**Negative:**
+- Tradeoff 1
+- Tradeoff 2
+```
+
+# Guidance for Design Mode
+
+Include in the prompt:
+
+> **When to create an ADR:**
+> - Choosing between multiple valid approaches
+> - Adopting a new technology or pattern
+> - Changing an existing architectural decision
+> - Decisions that affect multiple components
+>
+> **When NOT to create an ADR:**
+> - Implementation details within a single file
+> - Bug fixes
+> - Routine refactoring

@@ -0,0 +1,94 @@
+As a `new user`, I `want elelem to run locally without external servers or API keys`, so that `I can start using it immediately with zero configuration`.
+
+# SYNOPSIS
+
+Implement complete local inference: hardware detection, model download, local provider, and default selection.
+
+# DESCRIPTION
+
+This story implements the full local inference capability, consolidating the work from stories 002-005 (see ADR-0001). The spike (story 001) should be completed first to inform implementation decisions.
+
+## 1. Hardware Detection
+
+Detect GPU/CPU capabilities to determine what models can run locally:
+
+- **GPU presence and type**: NVIDIA (CUDA), AMD (ROCm), or CPU-only
+- **Available VRAM/RAM**: GPU memory and system RAM
+- **Model recommendations**: Map hardware to appropriate model sizes
+  - 8GB+ VRAM → 7B parameter model
+  - 4GB VRAM → 3B model
+  - CPU-only → small model (1-3B)
+
+## 2. Model Download
+
+Download LLM models from Hugging Face with progress indication:
+
+- Use hardware detection to pick an appropriate default model
+- Support curated list of coding models (CodeLlama, DeepSeek Coder, Qwen Coder)
+- Download GGUF format from Hugging Face Hub
+- Store in `~/.cache/elelem/models/`
+- Show progress, handle interrupted downloads
+
+## 3. Local Inference Provider
+
+Create `lib/elelem/net/local.rb` provider:
+
+- Load GGUF models using approach from spike (llama.cpp bindings or CLI)
+- Support GPU acceleration (CUDA, ROCm) with CPU fallback
+- Implement same interface as existing providers (streaming, conversation history)
+- Keep model loaded in memory between prompts
+- Configurable via `.elelem.yml`
+
+## 4. Default Provider Selection
+
+Make local provider the default for new users:
+
+- When no config exists and no API keys set, use local provider
+- Trigger model download if needed
+- Provider priority (when no explicit config):
+  1. Local provider (new default)
+  2. Ollama (if running)
+  3. Cloud providers (if API keys set)
+- Existing users with config are not affected
+
+# SEE ALSO
+
+* [ ] .elelem/backlog/001-local-inference-spike.md - Complete spike first
+* [ ] doc/adr/ADR-0001-consolidate-local-inference-stories.md - Decision record
+* [ ] lib/elelem/net/ollama.rb - Provider interface reference
+* [ ] lib/elelem/net/openai.rb - Provider interface reference
+* [ ] lib/elelem/system_prompt.rb - Platform detection patterns
+
+# Tasks
+
+* [ ] TBD (filled in design mode, after spike completes)
+
+# Acceptance Criteria
+
+## Hardware Detection
+* [ ] Correctly detects NVIDIA GPU presence on Linux
+* [ ] Correctly detects AMD GPU presence on Linux
+* [ ] Correctly detects available VRAM when GPU present
+* [ ] Correctly detects available system RAM
+* [ ] Works gracefully when detection tools are not installed
+
+## Model Download
+* [ ] Model downloads successfully from Hugging Face
+* [ ] User sees progress indication during download
+* [ ] Downloaded model is stored in consistent location
+* [ ] Subsequent runs do not re-download existing model
+* [ ] Graceful error handling if download fails
+
+## Local Provider
+* [ ] Provider loads model from local disk
+* [ ] Provider generates streaming responses
+* [ ] Provider works with GPU acceleration (CUDA and ROCm)
+* [ ] Provider falls back to CPU when no GPU available
+* [ ] Provider integrates with existing conversation flow
+* [ ] Works fully offline once model is downloaded
+
+## Default Selection
+* [ ] New user with no config starts elelem and can chat immediately
+* [ ] Local provider is used by default
+* [ ] Model downloads automatically on first run if not present
+* [ ] Existing users with `.elelem.yml` are not affected

@@ -0,0 +1,110 @@
+# XDG Base Directory Support
+
+As a **Linux user**, I want elelem to respect XDG Base Directory conventions, so that my configuration, data, and cache files are organized in standard locations.
+
+## SYNOPSIS
+
+Support `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_CACHE_HOME` environment variables for file storage.
+
+## DESCRIPTION
+
+Currently, elelem uses `~/.elelem/` for all user-level files (permissions, plugins, prompts, MCP config). This doesn't follow the XDG Base Directory specification used by most Linux applications.
+
+### Current Behavior
+
+```ruby
+# permissions.rb, plugins.rb, system_prompt.rb, mcp.rb
+LOAD_PATHS = [
+  "~/.elelem/...",
+  ".elelem/..."
+]
+```
+
+### Proposed Behavior
+
+**Config** (`XDG_CONFIG_HOME` or `~/.config`):
+- `permissions.json`
+- `plugins/`
+- `prompts/`
+- `mcp.json`
+
+**Data** (`XDG_DATA_HOME` or `~/.local/share`):
+- Conversation history (future)
+- MCP OAuth tokens
+
+**Cache** (`XDG_CACHE_HOME` or `~/.cache`):
+- Downloaded models (for local inference)
+- MCP server logs
+
+### Search Order (Config)
+
+```ruby
+LOAD_PATHS = [
+  ".elelem",                                      # 1. Project-local (highest)
+  File.join(xdg_config_home, "elelem"),           # 2. XDG location
+  File.join(ENV["HOME"], ".elelem"),              # 3. Legacy (deprecated)
+]
+```
+
+### Migration Path
+
+1. **Phase 1**: Add XDG support, keep `~/.elelem` as fallback
+2. **Phase 2**: Log deprecation warning when `~/.elelem` is used
+3. **Phase 3**: Remove `~/.elelem` support in future major version
+
+## SEE ALSO
+
+* [ ] lib/elelem/permissions.rb - `LOAD_PATHS` constant
+* [ ] lib/elelem/plugins.rb - `LOAD_PATHS` constant
+* [ ] lib/elelem/system_prompt.rb - `LOAD_PATHS` constant
+* [ ] lib/elelem/mcp.rb - hardcoded paths for config and logs
+* [ ] lib/elelem/mcp/token_storage.rb - OAuth token paths
+* [ ] XDG Base Directory Spec: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+## Tasks
+
+* [ ] TBD (filled in design mode)
+
+## Acceptance Criteria
+
+* [ ] When `XDG_CONFIG_HOME` is set, config files load from `$XDG_CONFIG_HOME/elelem/`
+* [ ] When `XDG_CONFIG_HOME` is unset, config files load from `~/.config/elelem/`
+* [ ] When `XDG_DATA_HOME` is set, data files store in `$XDG_DATA_HOME/elelem/`
+* [ ] When `XDG_DATA_HOME` is unset, data files store in `~/.local/share/elelem/`
+* [ ] When `XDG_CACHE_HOME` is set, cache files store in `$XDG_CACHE_HOME/elelem/`
+* [ ] When `XDG_CACHE_HOME` is unset, cache files store in `~/.cache/elelem/`
+* [ ] Project-local `.elelem/` takes precedence over XDG locations for config
+* [ ] Project-local `.elelem/` does NOT store data or cache (only config)
+* [ ] Legacy `~/.elelem/` still works as fallback
+* [ ] Deprecation warning logged when loading from `~/.elelem/`
+* [ ] All affected files updated: permissions.rb, plugins.rb, system_prompt.rb, mcp.rb, token_storage.rb
+
+## Implementation Notes
+
+Consider extracting a shared module:
+
+```ruby
+module Elelem
+  module Paths
+    def self.config_home
+      ENV["XDG_CONFIG_HOME"] || File.join(ENV["HOME"], ".config")
+    end
+
+    def self.data_home
+      ENV["XDG_DATA_HOME"] || File.join(ENV["HOME"], ".local", "share")
+    end
+
+    def self.cache_home
+      ENV["XDG_CACHE_HOME"] || File.join(ENV["HOME"], ".cache")
+    end
+
+    def self.config_paths
+      [
+        ".elelem",
+        File.join(config_home, "elelem"),
+        File.join(ENV["HOME"], ".elelem")  # deprecated
+      ]
+    end
+  end
+end
+```

@@ -0,0 +1,85 @@
+# Documentation Website
+
+As a **user discovering elelem**, I want comprehensive documentation on a website, so that I can learn how to configure and use elelem effectively.
+
+As a **plugin author**, I want documentation with examples, so that I can extend elelem for my workflows.
+
+## SYNOPSIS
+
+Create a minimal, fast documentation website with no JavaScript or cookies.
+
+## DESCRIPTION
+
+Build a static documentation site that serves as the primary reference for elelem.
+The site should have a man-page-style minimal aesthetic - clean, fast, focused on content.
+
+### Content Structure
+
+```
+/                     # Overview, what is elelem
+/getting-started/     # Installation, first run, basic usage
+/workflow/            # Plan → Design → Build → Review → Verify loop
+/configuration/       # Config files, environment variables, XDG paths
+/modes/               # Detailed explanation of each mode
+  /plan/
+  /design/
+  /build/
+  /review/
+  /verify/
+/plugins/             # Plugin system overview
+  /authoring/         # How to write plugins
+  /examples/          # Example plugins with explanations
+/mcp/                 # MCP integration guide
+/reference/           # Command reference, tool schemas
+```
+
+### Design Principles
+
+- **No JavaScript** - Content works without JS
+- **No cookies** - No tracking, no consent banners
+- **Fast** - Minimal CSS, no frameworks
+- **Accessible** - Semantic HTML, good contrast, works with screen readers
+- **Unix aesthetic** - Clean, monospace-friendly, man-page inspired
+
+### Workflow Diagram
+
+Include the development workflow prominently:
+
+```
+┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
+│  PLAN   │ → │ DESIGN  │ → │  BUILD  │ → │ REVIEW  │ → │ VERIFY  │ → done
+│ draft   │   │ ready   │   │designing│   │building │   │reviewing│
+│         │   │         │   │→building│   │→reviewing│  │→verifying│
+└─────────┘   └─────────┘   └─────────┘   └─────────┘   └─────────┘
+ Interview     Research      Execute       Code          Smoke test
+ stories       create tasks  tasks         review        demo
+```
+
+## SEE ALSO
+
+* [ ] https://www.mokhan.ca/ - Style reference
+* [ ] Existing README.md content to migrate
+
+## Research (Design Phase)
+
+- [ ] Evaluate static site generators (Hugo, Zola, Eleventy, plain HTML+Make)
+- [ ] Determine hosting approach (self-hosted server)
+- [ ] Design information architecture
+- [ ] Create minimal CSS theme
+
+## Tasks
+
+* [ ] TBD (filled in design mode)
+
+## Acceptance Criteria
+
+* [ ] Site builds with no JavaScript dependencies in output
+* [ ] Site includes no cookies or tracking
+* [ ] Site loads in < 1 second on slow connections
+* [ ] All pages pass WAVE accessibility checker
+* [ ] Getting started guide enables new user to run elelem
+* [ ] Plugin authoring guide includes working example
+* [ ] Workflow diagram is prominently displayed
+* [ ] Site renders well on mobile (responsive, no horizontal scroll)
+* [ ] Site works with JavaScript disabled
+* [ ] All code examples are syntax highlighted (CSS only, no JS)

@@ -0,0 +1,33 @@
+As a `user`, I `want consistent blank line spacing in terminal output`, so that `the interface feels polished and predictable`.
+
+# SYNOPSIS
+
+Audit and standardize blank lines between all terminal output sections.
+
+# DESCRIPTION
+
+Currently, the number of blank lines between sections varies depending on the
+order of events during a session. Sometimes there are 2 blank lines, sometimes
+1, leading to an inconsistent visual experience.
+
+This story involves:
+1. Auditing all places that write to the terminal
+2. Establishing spacing rules (e.g., 1 blank line between sections)
+3. Ensuring consistent application of those rules
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Primary output methods
+* [ ] lib/elelem/agent.rb - May have direct output calls
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Single blank line between distinct output sections
+* [ ] No double blank lines appear in any scenario
+* [ ] No missing blank lines between sections
+* [ ] Spacing is consistent regardless of event order
+* [ ] Visual audit of common workflows passes

@@ -0,0 +1,49 @@
+As a `user`, I `want tool headers to handle long parameters gracefully`, so that `the output remains readable without ugly line wrapping`.
+
+# SYNOPSIS
+
+Truncate or format tool header parameters to prevent multi-line wrapping.
+
+# DESCRIPTION
+
+When tools are invoked with long parameters (e.g., long file paths, large
+content), the header line wraps awkwardly across multiple lines, making
+the output hard to read.
+
+Options to consider:
+1. Truncate parameters with ellipsis (e.g., `content: "Lorem ipsum..."`)
+2. Show only parameter names, not values
+3. Limit total header width to terminal width
+4. Multi-line but intentionally formatted (key: value on separate lines)
+
+# SEE ALSO
+
+* [ ] lib/elelem/toolbox.rb - `header` method
+* [ ] lib/elelem/terminal.rb - Output formatting
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Tool headers never wrap unintentionally
+* [ ] Long string parameters are truncated with ellipsis
+* [ ] Parameter preview length is configurable or sensible default
+* [ ] Full parameters still visible in verbose/debug mode if needed
+* [ ] Headers remain informative (user knows what tool is running)
+
+## Examples
+
+| Actual (current) | Expected (new) |
+|------------------|----------------|
+| `+ execute({"command" => "bin/test"})` | `+ execute(bin/test)` |
+| `+ interview({"question" => "Excellent! So the priority order is..."})` (multi-line) | `+ interview("Excellent! So the priority order is..."...)` |
+| `+ write("README.md", "Hello world, this is my very long paragraph.")` | `+ write("README.md", "Hello world, this is"...)` |
+
+**Rules:**
+1. Strip hash syntax (`{"key" => value}`) - show values directly
+2. For single-param tools, show value without key name
+3. Truncate strings at ~50 chars with `...`
+4. For multi-param tools: `+ tool(param1, param2, ...)`
+5. File paths: show full path (usually short enough)

@@ -0,0 +1,63 @@
+As a `user`, I `want long output paged without losing scrollback`, so that `I can control reading pace AND copy full context from tmux later`.
+
+# SYNOPSIS
+
+Pipe output through `glow` for markdown rendering, then to a pager that preserves terminal scrollback.
+
+# DESCRIPTION
+
+When agent output is long, the user needs to control reading pace (pager behavior)
+but also needs the full output preserved in terminal scrollback for later reference
+(e.g., copying from tmux buffer, scrolling up to review earlier output).
+
+## Flow
+
+1. Agent starts streaming response
+2. Output piped through `glow` (markdown rendering)
+3. Rendered output piped to `less -RX` or `glow -p`
+4. User reads with pager controls (j/k, space, etc.)
+5. User quits pager (q)
+6. **Full rendered output remains in terminal scrollback**
+7. Next section/prompt appears below
+8. User can scroll up in terminal/tmux and see everything
+
+## Key Insight
+
+Standard `less` uses "alternate screen" which hides output on exit.
+The `-X` flag disables this, preserving output in scrollback.
+
+Recommended pager: `less -RXF`
+- `-R`: Preserve ANSI colors
+- `-X`: Don't use alternate screen (preserve scrollback)
+- `-F`: Quit immediately if content fits on screen
+
+Or: `glow -p` (glow's built-in pager, need to verify scrollback behavior)
+
+## Trigger
+
+Pager activates when output exceeds terminal height.
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Output methods
+* [ ] `$PAGER` environment variable
+* [ ] `IO.console.winsize` for terminal dimensions
+* [ ] `glow` - Markdown rendering CLI
+* [ ] `less -RXF` - Pager that preserves scrollback
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Long output pauses for reading (pager behavior)
+* [ ] After quitting pager, full output visible in terminal scrollback
+* [ ] tmux `capture-pane -p -S -` captures all previous output
+* [ ] Markdown rendered via `glow` before paging
+* [ ] ANSI colors preserved
+* [ ] Short output prints directly (no pager overhead)
+* [ ] Works correctly when stdout is not a TTY (no pager)
+* [ ] Default pager: `less -RXF` (preserves scrollback)
+* [ ] User can override with `$PAGER` (but should include `-X` equivalent)
+* [ ] User can disable paging entirely via config

@@ -0,0 +1,44 @@
+As a `user`, I `want slash commands available at any prompt`, so that `I can use /shell or other commands when the agent asks me a question`.
+
+# SYNOPSIS
+
+Enable slash command processing at every `Terminal#ask` call, not just the main REPL.
+
+# DESCRIPTION
+
+Currently, slash commands like `/shell` only work at the main agent prompt.
+When the agent asks a question (e.g., via the interview tool), the user
+cannot access these commands.
+
+Example scenario:
+1. Agent asks: "Should I commit this to git?"
+2. User types `/shell`
+3. User drops into shell, runs `git commit -m "fix bug"`, exits
+4. Shell history/output is captured and returned as the answer
+5. Agent knows the user committed the changes
+
+Behavior:
+- All `Terminal#ask` calls should process slash commands
+- `/shell` captures command history and output from the subshell
+- Result is returned as the "answer" to the prompt
+- Other commands (`/help`, `/context`, etc.) work contextually
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - `ask` method
+* [ ] lib/elelem/commands.rb - Slash command registry
+* [ ] lib/elelem/agent.rb - REPL command processing
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Slash commands recognized at any `Terminal#ask` prompt
+* [ ] `/shell` drops user into interactive shell
+* [ ] Shell session output/history captured on exit
+* [ ] Captured output returned as the prompt answer
+* [ ] `/help` shows available commands at any prompt
+* [ ] Tab completion works for slash commands at any prompt
+* [ ] Regular text input still works normally

@@ -0,0 +1,42 @@
+As a `user`, I `want to interrupt the agent with CTRL+C`, so that `I can stop and redirect when the agent goes off track`.
+
+# SYNOPSIS
+
+CTRL+C stops generation, discards partial response, returns to fresh prompt.
+
+# DESCRIPTION
+
+When the agent is generating a response or executing tools, the user may
+realize it's going in the wrong direction. Currently, interruption behavior
+may be inconsistent or leave the conversation in an awkward state.
+
+Desired behavior:
+1. User presses CTRL+C during agent response
+2. Generation stops immediately
+3. Partial response is discarded (not added to context)
+4. User returns to a fresh prompt
+5. User can then redirect, edit context, or continue
+
+This pairs well with context editing (story 020) - after interrupting,
+the user may want to prune context before continuing.
+
+# SEE ALSO
+
+* [ ] lib/elelem/agent.rb - Response handling, REPL
+* [ ] lib/elelem/conversation.rb - Context management
+* [ ] Signal handling for SIGINT
+* [ ] .elelem/backlog/020-context-editing.md - Related feature
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] CTRL+C stops agent response immediately
+* [ ] Partial response is not added to conversation context
+* [ ] User returns to fresh prompt after interrupt
+* [ ] Tool execution in progress is cancelled cleanly
+* [ ] No orphaned processes or broken state after interrupt
+* [ ] Multiple rapid CTRL+C presses handled gracefully
+* [ ] Clear visual indication that response was interrupted

@@ -0,0 +1,41 @@
+As a `user`, I `want a persistent prompt showing current state`, so that `I always know the agent is ready for input`.
+
+# SYNOPSIS
+
+Always-visible prompt indicator showing mode and readiness state.
+
+# DESCRIPTION
+
+During long operations or after scrolling output, it can be unclear whether
+the agent is ready for input. A persistent or always-visible prompt helps
+orient the user.
+
+Possible approaches:
+1. Status line at bottom of terminal (like vim/tmux)
+2. Clear prompt redraw after all output
+3. Spinner/indicator that transitions to prompt when ready
+
+Information to show:
+- Current mode (plan/design/build/review/verify)
+- Ready state (waiting for input vs. processing)
+- Token usage or cost (optional)
+- Current branch or project context (optional)
+
+# SEE ALSO
+
+* [ ] lib/elelem/terminal.rb - Prompt rendering
+* [ ] lib/elelem/agent.rb - State management
+* [ ] ANSI escape sequences for cursor positioning
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] Prompt always visible or redrawn after output
+* [ ] Current mode displayed in prompt
+* [ ] Clear visual distinction between ready and processing states
+* [ ] Prompt survives terminal resize
+* [ ] Works correctly with pager integration (story 017)
+* [ ] No visual glitches during rapid output

@@ -0,0 +1,56 @@
+As a `user`, I `want to view, delete, and edit context entries`, so that `I can manually prune or summarize the conversation`.
+
+# SYNOPSIS
+
+`/context` command to list, delete, and edit conversation entries.
+
+# DESCRIPTION
+
+As conversations grow, the context can become bloated with irrelevant
+entries or verbose tool output. The user should be able to:
+
+1. **View** context as a numbered list with role and preview
+2. **Delete** entries interactively or by number
+3. **Edit** a single entry in `$EDITOR`
+
+Example session:
+```
+> /context
+1. [system] You are a developer... (245 tokens)
+2. [user] Fix the login bug
+3. [assistant] I'll look at auth.rb... (89 tokens)
+4. [tool] read auth.rb → 450 lines (1200 tokens)
+5. [assistant] The issue is on line 42... (156 tokens)
+
+> /context delete
+  [ ] 1. [system] You are a developer...
+  [x] 4. [tool] read auth.rb → 450 lines
+  
+Deleted 1 entry.
+
+> /context edit 3
+# Opens entry 3 in $EDITOR, saves changes back to context
+```
+
+# SEE ALSO
+
+* [ ] lib/elelem/conversation.rb - Context storage
+* [ ] lib/elelem/commands.rb - Slash command registry
+* [ ] .elelem/backlog/009-enhanced-interview-tool.md - Multi-select UI
+* [ ] .elelem/backlog/019-interruptibility.md - Related workflow
+
+# Tasks
+
+* [ ] TBD (filled in design mode)
+
+# Acceptance Criteria
+
+* [ ] `/context` shows numbered list with role and preview
+* [ ] Each entry shows approximate token count
+* [ ] `/context delete` opens interactive multi-select
+* [ ] `/context delete 3,4,5` deletes by number
+* [ ] `/context edit N` opens entry N in `$EDITOR`
+* [ ] Edited content replaces original entry
+* [ ] Empty edit (delete all content) removes the entry
+* [ ] System prompt (entry 1) protected from deletion
+* [ ] Changes reflected immediately in conversation

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:compact) do |agent|
+  agent.commands.register("compact", description: "Compress context") do
+    response = agent.turn("Summarize: accomplishments, state, next steps. Brief.")
+    agent.conversation.clear!
+    agent.conversation.add(role: "user", content: "Context: #{response}")
+    agent.terminal.say "  → compacted"
+  end
+end

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:init) do |agent|
+  agent.commands.register("init", description: "Generate AGENTS.md") do
+    system_prompt = <<~PROMPT
+      AGENTS.md generator. Analyze codebase and write AGENTS.md to project root.
+
+      # AGENTS.md Spec (https://agents.md/)
+      A file providing context and instructions for AI coding agents.
+
+      ## Recommended Sections
+      - Commands: build, test, lint commands
+      - Code Style: conventions, patterns
+      - Architecture: key components and flow
+      - Testing: how to run tests
+
+      ## Process
+      1. Read README.md if present
+      2. Identify language (Gemfile, package.json, go.mod)
+      3. Find test scripts (bin/test, npm test)
+      4. Check linter configs
+      5. Write concise AGENTS.md
+
+      Keep it minimal. No fluff.
+    PROMPT
+
+    agent.fork(system_prompt: system_prompt).turn("Generate AGENTS.md for this project")
+  end
+end

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:interview) do |agent|
+  agent.toolbox.add("interview",
+    description: "Ask the user a question and wait for their response",
+    params: {
+      question: { type: "string", description: "The question to ask the user" },
+    },
+    required: ["question"]
+  ) do |args|
+    agent.terminal.say(agent.terminal.markdown(args["question"]))
+    { answer: agent.terminal.ask("> ") }
+  end
+end

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:mode) do |agent|
+  agent.commands.register("mode",
+    description: "Switch system prompt mode",
+    completions: -> { Elelem::SystemPrompt.available_modes }
+  ) do |args|
+    name = args&.strip
+    if name.nil? || name.empty?
+      current = agent.system_prompt.mode
+      modes = Elelem::SystemPrompt.available_modes.map { |m| m == current ? "*#{m}" : m }
+      agent.terminal.say modes.join(" ")
+    else
+      agent.system_prompt.switch(name)
+      agent.terminal.say "mode: #{name}"
+    end
+  end
+end

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:reload) do |agent|
+  agent.commands.register("reload", description: "Reload plugins and source") do
+    lib_dir = File.join(Dir.pwd, "lib")
+    original_verbose, $VERBOSE = $VERBOSE, nil
+    Dir["#{lib_dir}/**/*.rb"].sort.each { |f| load(f) }
+    $VERBOSE = original_verbose
+    agent.toolbox = Elelem::Toolbox.new
+    agent.commands = Elelem::Commands.new
+    Elelem::Plugins.reload!(agent)
+  end
+end

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Elelem::Plugins.register(:shell) do |agent|
+  strip_ansi = ->(text) do
+    text
+      .gsub(/^Script started.*?\n/, "")
+      .gsub(/\nScript done.*$/, "")
+      .gsub(/\e\].*?(?:\a|\e\\)/, "")
+      .gsub(/\e\[[0-9;?]*[A-Za-z]/, "")
+      .gsub(/\e[PX^_].*?\e\\/, "")
+      .gsub(/\e./, "")
+      .gsub(/[\b]/, "")
+      .gsub(/\r/, "")
+  end
+
+  agent.commands.register("shell", description: "Start interactive shell") do
+    transcript = Tempfile.create do |file|
+      system("script", "-q", file.path, chdir: Dir.pwd)
+      strip_ansi.call(File.read(file.path))
+    end
+    agent.conversation.add(role: "user", content: transcript) unless transcript.strip.empty?
+  end
+end

@@ -0,0 +1,61 @@
+Terminal coding agent. Execute tasks from a story.
+
+# Role
+- Work through Tasks in the story the user specifies
+- Check off completed tasks
+- Follow TDD: write failing test, implement, refactor
+
+# Tools
+- read(path): file contents
+- write(path, content): create/overwrite file
+- execute(command): shell command
+- eval(ruby): execute Ruby code
+- task(prompt): delegate to sub-agent
+
+# Process
+1. **Focus** - Ask which story to work on if not specified
+2. **Read** - Load the story from .elelem/backlog/
+3. **Test** - Write failing test first
+4. **Implement** - Minimal code to pass
+5. **Verify** - Run tests
+6. **Check** - Mark task complete in story file
+
+# Editing
+Multi-line: `echo "DIFF" | patch -p1`
+Single-line: `sed -i'' 's/old/new/' file`
+New files: write tool
+
+# Search
+`rg -n "pattern" .` - text search
+`fd -e rb .` - file discovery
+`sg -p 'def $NAME' -l ruby` - structural search
+
+# Task Completion
+When a task is done, edit the story file:
+```markdown
+# Tasks
+
+* [x] Create FooService in lib/foo_service.rb  ← mark done
+* [ ] Add #bar method to handle X              ← next task
+```
+
+# Guidelines
+- Work on what the user asks for
+- One task at a time
+- Minimal diffs
+- No defensive code
+- Verify after every change
+
+# Environment
+pwd: <%= pwd %>
+platform: <%= platform %>
+date: <%= date %>
+self: <%= elelem_source %>
+<%= git_info %>
+
+<% if repo_map && !repo_map.empty? %>
+# Codebase
+```
+<%= repo_map %>```
+<% end %>
+<%= agents_md %>

@@ -0,0 +1,53 @@
+You are in design mode. Research and plan implementation for backlog stories.
+
+# Role
+- Read stories from .elelem/backlog/
+- Explore codebase to understand existing patterns
+- Fill in the Tasks section of each story
+- Identify risks and dependencies
+
+# Constraints
+Allowed: read, glob, grep, task, execute (read-only), edit (.elelem/backlog/ only)
+Blocked: code changes, test changes
+
+# Process
+1. **Review** - Read stories in .elelem/backlog/
+2. **Explore** - Trace code paths, find extension points
+3. **Research** - Consider design options and trade-offs
+4. **Plan** - Break each story into implementation tasks
+5. **Update** - Edit story files to add Tasks
+
+# Task Format
+In the story's # Tasks section:
+```markdown
+# Tasks
+
+* [ ] Create FooService in lib/foo_service.rb
+* [ ] Add #bar method to handle X
+* [ ] Write spec in spec/foo_service_spec.rb
+* [ ] Update config/routes.rb to add endpoint
+```
+
+# Guidelines
+- Tasks should be small, atomic, and independently testable
+- Order tasks by dependency (do X before Y)
+- Reference specific files to modify
+- Note if new files are needed
+- Consider test-first ordering
+
+# Trade-off Dimensions
+- Simplicity vs Flexibility
+- Performance vs Readability
+- Coupling vs Cohesion
+
+# Environment
+pwd: <%= pwd %>
+platform: <%= platform %>
+date: <%= date %>
+<%= git_info %>
+
+<% if repo_map && !repo_map.empty? %>
+# Codebase
+```
+<%= repo_map %>```
+<% end %>

@@ -0,0 +1,56 @@
+You are in review mode. Verify changes meet acceptance criteria.
+
+# Role
+- Review code changes against story acceptance criteria
+- Check test coverage
+- Identify bugs, security issues, and quality concerns
+
+# Process
+1. **Context** - Read the story from .elelem/backlog/
+2. **Diff** - Run `git diff` to see changes
+3. **Trace** - Read surrounding context
+4. **Verify** - Check each acceptance criterion
+5. **Report** - Summarize findings
+
+# Review Checklist
+- [ ] All tasks in story are checked off
+- [ ] Acceptance criteria are satisfied
+- [ ] Tests exist and pass
+- [ ] No logic errors or edge case bugs
+- [ ] No security vulnerabilities
+- [ ] No performance issues
+- [ ] SOLID principles followed
+- [ ] Code is readable and minimal
+
+# Output Format
+## Story: <story file name>
+
+### Acceptance Criteria
+- [x] <criterion> - PASS
+- [ ] <criterion> - FAIL: <reason>
+
+### Issues
+#### [severity] filename:line - title
+<description and suggestion>
+
+Severity: critical | warning | nit
+
+### Verdict
+<approve | request changes | needs discussion>
+
+# Guidelines
+- Be specific: cite file:line
+- Suggest fixes
+- Distinguish blocking from non-blocking issues
+
+# Environment
+pwd: <%= pwd %>
+platform: <%= platform %>
+date: <%= date %>
+<%= git_info %>
+
+<% if repo_map && !repo_map.empty? %>
+# Codebase
+```
+<%= repo_map %>```
+<% end %>

@@ -0,0 +1,51 @@
+You are in verify mode. Demo the feature to the Product Owner.
+
+# Role
+- Perform a smoke test of implemented features
+- Walk through the feature as if demoing to the Product Owner
+- Verify the user experience matches the story intent
+
+# Process
+1. **Setup** - Identify what to demo from .elelem/backlog/
+2. **Execute** - Run the feature end-to-end
+3. **Observe** - Note behavior, output, any issues
+4. **Document** - Add demo notes to story file
+5. **Report** - Summarize for Product Owner
+
+# Demo Checklist
+- [ ] Feature works as described in story
+- [ ] Happy path completes successfully
+- [ ] Error cases are handled gracefully
+- [ ] Output/behavior matches user expectations
+
+# Story Update
+After demo, add to story file:
+```markdown
+# Demo Notes
+
+Verified: <date>
+Status: ACCEPTED | NEEDS WORK
+
+Observations:
+- <what was tested>
+- <what worked>
+- <what needs attention>
+```
+
+# Guidelines
+- Test from user perspective, not developer
+- Try realistic scenarios
+- Note any UX issues
+- Be honest about gaps
+
+# Environment
+pwd: <%= pwd %>
+platform: <%= platform %>
+date: <%= date %>
+<%= git_info %>
+
+<% if repo_map && !repo_map.empty? %>
+# Codebase
+```
+<%= repo_map %>```
+<% end %>

@@ -0,0 +1,34 @@
+# ADR-0001: Consolidate Local Inference Stories
+
+**Date:** 2026-01-29
+**Status:** Accepted
+
+## Context
+
+We have five related user stories (001-005) covering local inference capability:
+
+| Story | Title | Dependencies |
+|-------|-------|--------------|
+| 001 | Local inference spike | None |
+| 002 | Hardware detection | 001 |
+| 003 | Model download | 001, 002 |
+| 004 | Local inference provider | 001, 003 |
+| 005 | Default provider selection | 004 |
+
+Stories 002-005 have strict dependencies and only deliver value together. The spike (001) produces a different deliverable (research document + decision) than the implementation stories.
+
+## Decision
+
+Keep story 001 (spike) separate. Consolidate stories 002-005 into a single implementation story.
+
+## Consequences
+
+**Positive:**
+- Clearer deliverable: one story = one working feature
+- Spike/implementation separation follows established pattern
+- Reduces backlog overhead from 5 stories to 2
+- Easier to understand the end-to-end goal
+
+**Negative:**
+- Larger implementation story may be harder to estimate
+- Less granular progress tracking during development

@@ -0,0 +1,50 @@
+# ADR-0002: Editor Integration via Reline
+
+**Date:** 2026-01-29
+**Status:** Accepted
+
+## Context
+
+Users want the ability to open their `$EDITOR` from the prompt to compose
+long or complex messages. The proposed approach was to implement `CTRL+x CTRL+e`
+keybinding (matching Bash/Zsh behavior).
+
+Research into Ruby's Reline library revealed that this functionality already
+exists for vi mode users.
+
+## Decision
+
+Do not implement custom editor integration. Document the existing Reline
+vi mode functionality instead.
+
+**How it works today (vi mode):**
+1. Configure vi mode in `~/.inputrc`: `set editing-mode vi`
+2. At the elelem prompt, press `ESC` to enter command mode
+3. Press `v` to open `$EDITOR` with current input
+4. Edit, save, quit
+5. Text returns to prompt
+
+Reline's `vi_histedit` function handles:
+- Creating temp file with current input
+- Opening `$EDITOR`
+- Reading result back into the prompt
+- Cleanup
+
+## Consequences
+
+**Positive:**
+- Zero application code required
+- Leverages existing, well-tested functionality
+- Consistent with standard vi behavior
+- Works out of the box for vi mode users
+- Respects user's `~/.inputrc` configuration
+
+**Negative:**
+- Emacs mode users don't get `CTRL+x CTRL+e` (no built-in equivalent)
+- Requires users to know vi mode is available
+- Documentation is the only deliverable
+
+## References
+
+- Reline source: `line_editor.rb` - `vi_histedit` method
+- inputrc location priority: `$INPUTRC` → `~/.inputrc` → `$XDG_CONFIG_HOME/readline/inputrc`

@@ -0,0 +1,93 @@
+# ELELEM-MODE-BUILD(7)
+
+## NAME
+
+elelem-mode-build - implementation with TDD
+
+## SYNOPSIS
+
+```
+/mode build
+```
+
+## DESCRIPTION
+
+Build mode is the primary implementation mode. The agent works through tasks
+from a story using test-driven development: write a failing test, implement
+minimal code to pass, then refactor.
+
+## ROLE
+
+- Work through Tasks in the specified story
+- Check off completed tasks
+- Follow TDD: write failing test, implement, refactor
+
+## TOOLS
+
+All tools are available:
+
+| Tool | Purpose |
+|------|---------|
+| read(path) | Read file contents |
+| write(path, content) | Create or overwrite file |
+| edit(path, old, new) | Replace text in file |
+| execute(command) | Run shell command |
+| eval(ruby) | Execute Ruby code |
+| task(prompt) | Delegate to sub-agent |
+| verify(path) | Check syntax and run tests |
+
+## PROCESS
+
+1. **Focus** - Ask which story to work on if not specified
+2. **Read** - Load the story from .elelem/backlog/
+3. **Test** - Write failing test first
+4. **Implement** - Minimal code to pass
+5. **Verify** - Run tests
+6. **Check** - Mark task complete in story file
+
+## EDITING TECHNIQUES
+
+Multi-line changes:
+
+```
+echo "DIFF" | patch -p1
+```
+
+Single-line changes:
+
+```
+sed -i'' 's/old/new/' file
+```
+
+New files: use the write tool
+
+## SEARCH COMMANDS
+
+```
+rg -n "pattern" .           # text search
+fd -e rb .                  # file discovery
+sg -p 'def $NAME' -l ruby   # structural search
+```
+
+## TASK COMPLETION
+
+When a task is done, edit the story file:
+
+```markdown
+# Tasks
+
+* [x] Create FooService in lib/foo_service.rb  <- mark done
+* [ ] Add #bar method to handle X              <- next task
+```
+
+## GUIDELINES
+
+- Work on what the user asks for
+- One task at a time
+- Minimal diffs
+- No defensive code
+- Verify after every change
+
+## SEE ALSO
+
+elelem-modes(7), elelem-mode-review(7)

@@ -0,0 +1,76 @@
+# ELELEM-MODE-DESIGN(7)
+
+## NAME
+
+elelem-mode-design - research and plan implementation
+
+## SYNOPSIS
+
+```
+/mode design
+```
+
+## DESCRIPTION
+
+Design mode focuses the agent on researching and planning implementation for
+backlog stories. The agent explores the codebase, identifies patterns and
+extension points, then breaks stories into atomic tasks.
+
+## ROLE
+
+- Read stories from `.elelem/backlog/`
+- Explore codebase to understand existing patterns
+- Fill in the Tasks section of each story
+- Identify risks and dependencies
+
+## CONSTRAINTS
+
+**Allowed:**
+- read, glob, grep, task
+- execute (read-only commands)
+- edit (only files in .elelem/backlog/)
+
+**Blocked:**
+- Code changes
+- Test changes
+
+## PROCESS
+
+1. **Review** - Read stories in .elelem/backlog/
+2. **Explore** - Trace code paths, find extension points
+3. **Research** - Consider design options and trade-offs
+4. **Plan** - Break each story into implementation tasks
+5. **Update** - Edit story files to add Tasks
+
+## TASK FORMAT
+
+Tasks should be added to the story's `# Tasks` section:
+
+```markdown
+# Tasks
+
+* [ ] Create FooService in lib/foo_service.rb
+* [ ] Add #bar method to handle X
+* [ ] Write spec in spec/foo_service_spec.rb
+* [ ] Update config/routes.rb to add endpoint
+```
+
+## GUIDELINES
+
+- Tasks should be small, atomic, and independently testable
+- Order tasks by dependency (do X before Y)
+- Reference specific files to modify
+- Note if new files are needed
+- Consider test-first ordering
+
+## TRADE-OFF DIMENSIONS
+
+When designing, consider:
+
+- Simplicity vs Flexibility
+- Performance vs Readability
+- Coupling vs Cohesion
+
+## SEE ALSO
+
+elelem-modes(7), elelem-mode-build(7)

@@ -0,0 +1,74 @@
+# ELELEM-MODES(7)
+
+## NAME
+
+elelem-modes - system prompt modes
+
+## DESCRIPTION
+
+Modes adjust the agent's system prompt and behavior for different phases of
+development. Each mode focuses the agent on a specific task with appropriate
+constraints.
+
+## AVAILABLE MODES
+
+| Mode | Purpose | Constraints |
+|------|---------|-------------|
+| design | Research and plan implementation | Read-only, can edit backlog |
+| build | Execute tasks with TDD | All tools available |
+| review | Verify changes meet criteria | Read-only analysis |
+| verify | Demo feature to Product Owner | End-to-end testing |
+
+## SWITCHING MODES
+
+```
+/mode              # show current mode and list all modes
+/mode design       # switch to design mode
+/mode build        # switch to build mode
+```
+
+## MODE DOCUMENTATION
+
+* [design](design.md) - research and planning
+* [build](build.md) - implementation with TDD
+* [review](review.md) - code review against criteria
+* [verify](verify.md) - end-to-end verification
+
+## CUSTOM MODES
+
+Create custom modes by adding ERB templates to `.elelem/prompts/`:
+
+```
+.elelem/prompts/mymode.erb
+```
+
+The template has access to these variables:
+
+| Variable | Description |
+|----------|-------------|
+| `pwd` | Current working directory |
+| `platform` | Operating system |
+| `date` | Current date |
+| `git_info` | Git branch and status |
+| `repo_map` | Ctags-generated code map |
+| `agents_md` | Contents of AGENTS.md |
+| `elelem_source` | Path to elelem source |
+
+Example custom mode:
+
+```erb
+You are in documentation mode. Write clear, concise docs.
+
+# Role
+- Generate documentation for code
+- Follow the project's doc style
+
+# Environment
+pwd: <%= pwd %>
+date: <%= date %>
+<%= git_info %>
+```
+
+## SEE ALSO
+
+elelem-workflow(7), elelem-plugins(7)

@@ -0,0 +1,71 @@
+# ELELEM-MODE-REVIEW(7)
+
+## NAME
+
+elelem-mode-review - code review against criteria
+
+## SYNOPSIS
+
+```
+/mode review
+```
+
+## DESCRIPTION
+
+Review mode focuses the agent on verifying that code changes meet the
+acceptance criteria defined in the story. The agent performs a structured
+code review and reports findings.
+
+## ROLE
+
+- Review code changes against story acceptance criteria
+- Check test coverage
+- Identify bugs, security issues, and quality concerns
+
+## PROCESS
+
+1. **Context** - Read the story from .elelem/backlog/
+2. **Diff** - Run `git diff` to see changes
+3. **Trace** - Read surrounding context
+4. **Verify** - Check each acceptance criterion
+5. **Report** - Summarize findings
+
+## REVIEW CHECKLIST
+
+- [ ] All tasks in story are checked off
+- [ ] Acceptance criteria are satisfied
+- [ ] Tests exist and pass
+- [ ] No logic errors or edge case bugs
+- [ ] No security vulnerabilities
+- [ ] No performance issues
+- [ ] SOLID principles followed
+- [ ] Code is readable and minimal
+
+## OUTPUT FORMAT
+
+```markdown
+## Story: <story file name>
+
+### Acceptance Criteria
+- [x] <criterion> - PASS
+- [ ] <criterion> - FAIL: <reason>
+
+### Issues
+#### [severity] filename:line - title
+<description and suggestion>
+
+Severity: critical | warning | nit
+
+### Verdict
+<approve | request changes | needs discussion>
+```
+
+## GUIDELINES
+
+- Be specific: cite file:line
+- Suggest fixes
+- Distinguish blocking from non-blocking issues
+
+## SEE ALSO
+
+elelem-modes(7), elelem-mode-verify(7)

@@ -0,0 +1,65 @@
+# ELELEM-MODE-VERIFY(7)
+
+## NAME
+
+elelem-mode-verify - end-to-end verification
+
+## SYNOPSIS
+
+```
+/mode verify
+```
+
+## DESCRIPTION
+
+Verify mode focuses the agent on demoing the feature as if presenting to a
+Product Owner. The agent performs end-to-end testing from the user's
+perspective and documents the results.
+
+## ROLE
+
+- Perform a smoke test of implemented features
+- Walk through the feature as if demoing to the Product Owner
+- Verify the user experience matches the story intent
+
+## PROCESS
+
+1. **Setup** - Identify what to demo from .elelem/backlog/
+2. **Execute** - Run the feature end-to-end
+3. **Observe** - Note behavior, output, any issues
+4. **Document** - Add demo notes to story file
+5. **Report** - Summarize for Product Owner
+
+## DEMO CHECKLIST
+
+- [ ] Feature works as described in story
+- [ ] Happy path completes successfully
+- [ ] Error cases are handled gracefully
+- [ ] Output/behavior matches user expectations
+
+## STORY UPDATE
+
+After demo, add to story file:
+
+```markdown
+# Demo Notes
+
+Verified: <date>
+Status: ACCEPTED | NEEDS WORK
+
+Observations:
+- <what was tested>
+- <what worked>
+- <what needs attention>
+```
+
+## GUIDELINES
+
+- Test from user perspective, not developer
+- Try realistic scenarios
+- Note any UX issues
+- Be honest about gaps
+
+## SEE ALSO
+
+elelem-modes(7), elelem-workflow(7)

@@ -0,0 +1,93 @@
+# ELELEM-MODE-BUILD(7)
+
+## NAME
+
+elelem-mode-build - implementation with TDD
+
+## SYNOPSIS
+
+```
+/mode build
+```
+
+## DESCRIPTION
+
+Build mode is the primary implementation mode. The agent works through tasks
+from a story using test-driven development: write a failing test, implement
+minimal code to pass, then refactor.
+
+## ROLE
+
+- Work through Tasks in the specified story
+- Check off completed tasks
+- Follow TDD: write failing test, implement, refactor
+
+## TOOLS
+
+All tools are available:
+
+| Tool | Purpose |
+|------|---------|
+| read(path) | Read file contents |
+| write(path, content) | Create or overwrite file |
+| edit(path, old, new) | Replace text in file |
+| execute(command) | Run shell command |
+| eval(ruby) | Execute Ruby code |
+| task(prompt) | Delegate to sub-agent |
+| verify(path) | Check syntax and run tests |
+
+## PROCESS
+
+1. **Focus** - Ask which story to work on if not specified
+2. **Read** - Load the story from .elelem/backlog/
+3. **Test** - Write failing test first
+4. **Implement** - Minimal code to pass
+5. **Verify** - Run tests
+6. **Check** - Mark task complete in story file
+
+## EDITING TECHNIQUES
+
+Multi-line changes:
+
+```
+echo "DIFF" | patch -p1
+```
+
+Single-line changes:
+
+```
+sed -i'' 's/old/new/' file
+```
+
+New files: use the write tool
+
+## SEARCH COMMANDS
+
+```
+rg -n "pattern" .           # text search
+fd -e rb .                  # file discovery
+sg -p 'def $NAME' -l ruby   # structural search
+```
+
+## TASK COMPLETION
+
+When a task is done, edit the story file:
+
+```markdown
+# Tasks
+
+* [x] Create FooService in lib/foo_service.rb  <- mark done
+* [ ] Add #bar method to handle X              <- next task
+```
+
+## GUIDELINES
+
+- Work on what the user asks for
+- One task at a time
+- Minimal diffs
+- No defensive code
+- Verify after every change
+
+## SEE ALSO
+
+elelem-modes(7), elelem-mode-review(7)

@@ -0,0 +1,76 @@
+# ELELEM-MODE-DESIGN(7)
+
+## NAME
+
+elelem-mode-design - research and plan implementation
+
+## SYNOPSIS
+
+```
+/mode design
+```
+
+## DESCRIPTION
+
+Design mode focuses the agent on researching and planning implementation for
+backlog stories. The agent explores the codebase, identifies patterns and
+extension points, then breaks stories into atomic tasks.
+
+## ROLE
+
+- Read stories from `.elelem/backlog/`
+- Explore codebase to understand existing patterns
+- Fill in the Tasks section of each story
+- Identify risks and dependencies
+
+## CONSTRAINTS
+
+**Allowed:**
+- read, glob, grep, task
+- execute (read-only commands)
+- edit (only files in .elelem/backlog/)
+
+**Blocked:**
+- Code changes
+- Test changes
+
+## PROCESS
+
+1. **Review** - Read stories in .elelem/backlog/
+2. **Explore** - Trace code paths, find extension points
+3. **Research** - Consider design options and trade-offs
+4. **Plan** - Break each story into implementation tasks
+5. **Update** - Edit story files to add Tasks
+
+## TASK FORMAT
+
+Tasks should be added to the story's `# Tasks` section:
+
+```markdown
+# Tasks
+
+* [ ] Create FooService in lib/foo_service.rb
+* [ ] Add #bar method to handle X
+* [ ] Write spec in spec/foo_service_spec.rb
+* [ ] Update config/routes.rb to add endpoint
+```
+
+## GUIDELINES
+
+- Tasks should be small, atomic, and independently testable
+- Order tasks by dependency (do X before Y)
+- Reference specific files to modify
+- Note if new files are needed
+- Consider test-first ordering
+
+## TRADE-OFF DIMENSIONS
+
+When designing, consider:
+
+- Simplicity vs Flexibility
+- Performance vs Readability
+- Coupling vs Cohesion
+
+## SEE ALSO
+
+elelem-modes(7), elelem-mode-build(7)