nexus/.planning/ROADMAP.md

# Roadmap: v1.3 Web Chat Interface

**Milestone:** v1.3
**Status:** Queued (not yet active)
**Phases:** 21-26 (6 phases)
**Granularity:** Standard
**Coverage:** 65/65 requirements mapped

---

## Phases

- [x] **Phase 21: Chat Foundation** — Persistent conversation storage, sidebar, CRUD, markdown rendering, theme integration, keyboard shortcuts (completed 2026-04-01)
- [ ] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions
- [ ] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat
- [ ] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks
- [ ] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking
- [ ] **Phase 26: PWA & Performance** — Service worker, Web App Manifest, responsive mobile layout, push notifications, install prompt, performance targets

---

## Phase Details

### Phase 21: Chat Foundation
**Goal**: Users can open Nexus, create and manage conversations, and read fully rendered agent responses — with persistent storage and correct theme styling from the start
**Depends on**: Nothing (first phase of v1.3; depends on v1.2 milestone being shipped)
**Requirements**: CHAT-02, CHAT-03, CHAT-04, CHAT-05, CHAT-06, INPUT-01, INPUT-07, HIST-01, HIST-02, HIST-03, HIST-05, HIST-06, THEME-01, THEME-02
**Success Criteria** (what must be TRUE):
  1. User can create a new conversation, give it a title, and see it appear in the sidebar conversation list
  2. User can delete, archive, and pin conversations from the sidebar
  3. Agent messages render with full markdown: code blocks with syntax highlighting and a copy button, tables, lists, headings, links, and inline images
  4. Conversations and all messages are stored in libSQL and survive a server restart
  5. The chat interface applies Catppuccin Mocha, Tokyo Night, and Catppuccin Latte themes correctly; code block highlighting matches the active theme
**Plans:** 7/7 plans complete

Plans:
- [x] 21-00-PLAN.md — Wave 0 test stubs (chat-service, chat-routes, ChatMarkdownMessage, ChatInput)
- [x] 21-01-PLAN.md — DB schema (chat_conversations + chat_messages) and shared types/validators
- [x] 21-02-PLAN.md — Markdown renderer with rehype-highlight, code block copy button, theme CSS
- [x] 21-03-PLAN.md — Server chat service and REST API routes (CRUD + pagination)
- [x] 21-04-PLAN.md — ChatPanel shell, ChatPanelContext, ChatInput, Layout integration
- [x] 21-05-PLAN.md — Full UI wiring: API client, conversation list, message thread, infinite scroll
- [x] 21-06-PLAN.md — Gap closure: conversation search/filter (HIST-02) + Cmd+K shortcut (INPUT-07)

**UI hint**: yes

### Phase 22: Agent Streaming
**Goal**: Users receive live streaming responses from any agent they select, with full control to stop, edit, or retry — and agent identity is clearly visible on every message
**Depends on**: Phase 21
**Requirements**: CHAT-01, CHAT-08, CHAT-10, CHAT-11, CHAT-12, INPUT-05, INPUT-06, AGENT-04, THEME-03, PERF-02, PERF-03
**Success Criteria** (what must be TRUE):
  1. Tokens from an agent appear in the chat window as they are generated; the first token appears in under 500ms
  2. User can switch the active agent for a conversation at any time via the agent selector
  3. Every assistant message shows the agent's name and avatar; agent colors are distinguishable across all three themes
  4. User can click Stop to cancel an in-progress streaming response
  5. User can edit a previous message to regenerate the response, or click Retry on any existing assistant message; conversations with 1,000+ messages scroll without jank via a virtualized list
  6. Slash commands (`/brainstorm`, `/ask-pm`, `/ask-engineer`, `/task`, `/search`) route messages to the correct agent; `@mention` syntax routes to the named agent
**Plans:** 5/6 plans executed

Plans:
- [x] 22-00-PLAN.md — Wave 0: DB migration, shared types, install virtualizer, agent-role-colors, CSS, test stubs
- [x] 22-01-PLAN.md — SSE streaming endpoint + useStreamingChat hook
- [x] 22-02-PLAN.md — Agent identity bar, streaming cursor, agent selector
- [x] 22-03-PLAN.md — Edit/retry/stop message action controls
- [x] 22-04-PLAN.md — Slash commands and @mention popovers
- [ ] 22-05-PLAN.md — Virtualized message list + full ChatPanel integration
**UI hint**: yes

### Phase 23: Brainstormer Flow
**Goal**: Users can open Nexus, start a conversation with the Brainstormer, receive structured clarifying questions, approve a spec, and watch it become real Nexus tasks — without ever touching the dashboard
**Depends on**: Phase 22
**Requirements**: AGENT-01, AGENT-02, AGENT-03, AGENT-05, AGENT-06, AGENT-07, CHAT-09
**Success Criteria** (what must be TRUE):
  1. The Brainstormer is the default agent when a user opens a new conversation; it greets the user and begins a structured questioning flow
  2. After the user answers clarifying questions, the Brainstormer produces a formatted spec card with What / Why / Constraints / Success fields and action buttons (Send to PM, Edit, Save as Draft)
  3. When the user clicks "Send to PM," a handoff indicator appears in the chat showing "Brainstormer → PM" with the spec content
  4. The PM agent creates one or more Nexus issues from the spec; the user can see task IDs referenced in the PM's reply
  5. When an Engineer or Generalist completes a task, a status update message appears in the relevant chat conversation
**Plans:** 6 plans

Plans:
- [x] 22-00-PLAN.md — Wave 0: DB migration, shared types, install virtualizer, agent-role-colors, CSS, test stubs
- [x] 22-01-PLAN.md — SSE streaming endpoint + useStreamingChat hook
- [x] 22-02-PLAN.md — Agent identity bar, streaming cursor, agent selector
- [x] 22-03-PLAN.md — Edit/retry/stop message action controls
- [ ] 22-04-PLAN.md — Slash commands and @mention popovers
- [ ] 22-05-PLAN.md — Virtualized message list + full ChatPanel integration
**UI hint**: yes

### Phase 24: Search, History & Branching
**Goal**: Users can find any message across all conversations in under 500ms, export conversations, bookmark key messages, and branch from any point in a conversation
**Depends on**: Phase 21
**Requirements**: CHAT-07, CHAT-13, CHAT-14, HIST-04, PERF-04
**Success Criteria** (what must be TRUE):
  1. Cmd+K opens a search overlay; typing a query returns matching messages from all conversations in under 500ms, even with 10,000+ messages stored
  2. User can bookmark any message and later filter or navigate to bookmarked messages
  3. Editing a message that already has a response creates a new branch; both the original and the new branch are preserved and the user can switch between them
  4. User can export any conversation as a Markdown file or as a JSON file containing all messages and metadata
**Plans:** 6 plans

Plans:
- [ ] 22-00-PLAN.md — Wave 0: DB migration, shared types, install virtualizer, agent-role-colors, CSS, test stubs
- [ ] 22-01-PLAN.md — SSE streaming endpoint + useStreamingChat hook
- [ ] 22-02-PLAN.md — Agent identity bar, streaming cursor, agent selector
- [ ] 22-03-PLAN.md — Edit/retry/stop message action controls
- [ ] 22-04-PLAN.md — Slash commands and @mention popovers
- [ ] 22-05-PLAN.md — Virtualized message list + full ChatPanel integration
**UI hint**: yes

### Phase 25: File System
**Goal**: Users and agents can upload, generate, preview, and download files in chat, with all files tracked in libSQL, version-controlled by git, and accessible across devices
**Depends on**: Phase 21
**Requirements**: FILE-01, FILE-02, FILE-03, FILE-04, FILE-05, FILE-06, FILE-07, FILE-08, FILE-09, FILE-10, FILE-11, FILE-12, FILE-13, INPUT-02, INPUT-03, INPUT-04
**Success Criteria** (what must be TRUE):
  1. User can drag-and-drop a file or image onto the chat input, see an inline preview, and send it; the file is stored on disk under `<nexus-root>/files/` and its metadata is written to libSQL
  2. User can paste an image from the clipboard directly into the chat input and send it
  3. Images attached to messages render inline in the message; PDFs show a first-page preview; code files show a syntax-highlighted preview; any file can be downloaded with one click
  4. Every file operation (upload, agent generation, replacement, deletion) produces a git commit in the `files/` repository; user can view the git log for any file
  5. When an agent generates a placeholder asset, `PLACEHOLDERS.md` is updated in the project directory; when the placeholder is replaced, the DB records the replacement chain and the manifest reflects the change
  6. A file uploaded in a conversation linked to a project lives in `files/projects/<slug>/`; a file from an unlinked conversation lives in `files/chat/<conversation-id>/`; the user can promote a chat file to project scope
  7. Voice input is available when local AI is enabled: user can hold the record button, speak, see a transcription preview, and confirm to send
**Plans:** 6 plans

Plans:
- [ ] 22-00-PLAN.md — Wave 0: DB migration, shared types, install virtualizer, agent-role-colors, CSS, test stubs
- [ ] 22-01-PLAN.md — SSE streaming endpoint + useStreamingChat hook
- [ ] 22-02-PLAN.md — Agent identity bar, streaming cursor, agent selector
- [ ] 22-03-PLAN.md — Edit/retry/stop message action controls
- [ ] 22-04-PLAN.md — Slash commands and @mention popovers
- [ ] 22-05-PLAN.md — Virtualized message list + full ChatPanel integration
**UI hint**: yes

### Phase 26: PWA & Performance
**Goal**: Nexus is installable as a standalone app on any device, loads under 2 seconds, and works offline — delivering the full chat experience on phone, tablet, and desktop
**Depends on**: Phase 22
**Requirements**: PWA-01, PWA-02, PWA-03, PWA-04, PWA-05, PWA-06, PWA-07, PWA-08, PERF-01, PERF-05
**Success Criteria** (what must be TRUE):
  1. On first mobile visit, the browser shows an "Add to Home Screen" prompt; after installation the app opens as a standalone window with no browser chrome
  2. The installed app has a Nexus icon and theme-aware splash screen on iOS, Android, macOS, and Windows
  3. When the device goes offline, the cached UI loads in under 1 second and queues outgoing messages; messages are delivered automatically when the connection returns
  4. On a phone, the input bar is sticky at the bottom of the screen, touch targets are large enough to tap without errors, and the layout resizes correctly when the software keyboard appears
  5. Pulling down on the conversation list on mobile triggers a refresh; push notifications arrive for agent mentions, task completions, and handoff requests where the platform supports them
  6. The initial page load on broadband completes in under 2 seconds and on a 3G connection in under 5 seconds; PWA cached load completes in under 1 second
**Plans:** 6 plans

Plans:
- [ ] 22-00-PLAN.md — Wave 0: DB migration, shared types, install virtualizer, agent-role-colors, CSS, test stubs
- [ ] 22-01-PLAN.md — SSE streaming endpoint + useStreamingChat hook
- [ ] 22-02-PLAN.md — Agent identity bar, streaming cursor, agent selector
- [ ] 22-03-PLAN.md — Edit/retry/stop message action controls
- [ ] 22-04-PLAN.md — Slash commands and @mention popovers
- [ ] 22-05-PLAN.md — Virtualized message list + full ChatPanel integration
**UI hint**: yes

---

## Coverage Validation

All 65 v1 requirements are mapped to exactly one phase. No orphans.

| Requirement | Phase |
|-------------|-------|
| CHAT-01 | 22 |
| CHAT-02 | 21 |
| CHAT-03 | 21 |
| CHAT-04 | 21 |
| CHAT-05 | 21 |
| CHAT-06 | 21 |
| CHAT-07 | 24 |
| CHAT-08 | 22 |
| CHAT-09 | 23 |
| CHAT-10 | 22 |
| CHAT-11 | 22 |
| CHAT-12 | 22 |
| CHAT-13 | 24 |
| CHAT-14 | 24 |
| INPUT-01 | 21 |
| INPUT-02 | 25 |
| INPUT-03 | 25 |
| INPUT-04 | 25 |
| INPUT-05 | 22 |
| INPUT-06 | 22 |
| INPUT-07 | 21 |
| AGENT-01 | 23 |
| AGENT-02 | 23 |
| AGENT-03 | 23 |
| AGENT-04 | 22 |
| AGENT-05 | 23 |
| AGENT-06 | 23 |
| AGENT-07 | 23 |
| HIST-01 | 21 |
| HIST-02 | 21 |
| HIST-03 | 21 |
| HIST-04 | 24 |
| HIST-05 | 21 |
| HIST-06 | 21 |
| PWA-01 | 26 |
| PWA-02 | 26 |
| PWA-03 | 26 |
| PWA-04 | 26 |
| PWA-05 | 26 |
| PWA-06 | 26 |
| PWA-07 | 26 |
| PWA-08 | 26 |
| THEME-01 | 21 |
| THEME-02 | 21 |
| THEME-03 | 22 |
| PERF-01 | 26 |
| PERF-02 | 22 |
| PERF-03 | 22 |
| PERF-04 | 24 |
| PERF-05 | 26 |
| FILE-01 | 25 |
| FILE-02 | 25 |
| FILE-03 | 25 |
| FILE-04 | 25 |
| FILE-05 | 25 |
| FILE-06 | 25 |
| FILE-07 | 25 |
| FILE-08 | 25 |
| FILE-09 | 25 |
| FILE-10 | 25 |
| FILE-11 | 25 |
| FILE-12 | 25 |
| FILE-13 | 25 |

---

## Progress

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 21. Chat Foundation | v1.3 | 7/7 | Complete    | 2026-04-01 |
| 22. Agent Streaming | v1.3 | 5/6 | In Progress|  |
| 23. Brainstormer Flow | v1.3 | 0/? | Not started | - |
| 24. Search, History & Branching | v1.3 | 0/? | Not started | - |
| 25. File System | v1.3 | 0/? | Not started | - |
| 26. PWA & Performance | v1.3 | 0/? | Not started | - |