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

• 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: 4/4 plans complete Plans:

• 21-01-PLAN.md — DB schema, shared types, service layer, and REST API for conversations and messages
• 21-02-PLAN.md — ChatMarkdownMessage with syntax highlighting/copy button, ChatInput with auto-resize/keyboard shortcuts, theme CSS
• 21-03-PLAN.md — Chat API client, panel context, hooks, ChatPanel/ConversationList/MessageList, Layout integration
• 21-04-PLAN.md — Full test suite verification and visual/functional checkpoint 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: 1/4 plans executed Plans:

• 22-01-PLAN.md — DB migration (editedContent/editedAt), SSE stream endpoint, edit message route, agent selection, server tests
• 22-02-PLAN.md — Agent color utility, parseMessageIntent (slash/mention), ChatAgentBadge, AgentSelector, UI tests
• 22-03-PLAN.md — useStreamMessage hook, VList virtualization, ChatInput stop/popover, ChatPanel integration
• 22-04-PLAN.md — Full test suite verification and visual/functional checkpoint 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: TBD 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: TBD 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: TBD 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: TBD 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	4/4	Complete	2026-04-01
22. Agent Streaming	v1.3	1/4	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	-