mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/.planning/REQUIREMENTS.md
Nexus Dev d4c98016d7 docs(26-03): complete PWA install prompt, offline banner, and message queue plan 
- InstallPromptBanner: 7-day cooldown, iOS fallback, beforeinstallprompt CTA
- OfflineBanner: amber theming, queue count, 3s auto-dismiss on reconnect
- useOfflineQueue: IndexedDB nexus-offline/message_queue, flush on online event
- ChatPanel: offline guard in handleSend, OfflineBanner + InstallPromptBanner wired
- Requirements PWA-01, PWA-02, PWA-08 marked complete
2026-04-04 03:55:48 +00:00

10 KiB
Raw Blame History

Requirements: v1.3 Web Chat Interface

Milestone: v1.3 Status: Queued Source PRD: ~/Downloads/nexus-v1.3-prd-web-chat.md Depends on: v1.2 (Skill Aggregator + Generalist Agent) Total v1 requirements: 65

Categories

Chat Core (14)

  • CHAT-01 — Real-time streaming responses: tokens appear as they are generated, not after completion
  • CHAT-02 — Markdown rendering in messages: code blocks with syntax highlighting, tables, lists, headings, links, images
  • CHAT-03 — Code blocks have a one-click copy button and a language label
  • CHAT-04 — Multiple concurrent conversations: sidebar shows the full conversation list
  • CHAT-05 — Conversation titles: auto-generated from the first message, manually editable by the user
  • CHAT-06 — Delete, archive, and pin conversations
  • CHAT-07 — Full-text search across all conversations
  • CHAT-08 — Agent selector: switch which agent you are talking to mid-conversation or per-conversation
  • CHAT-09 — System message indicator: when the Brainstormer hands off to PM, or PM delegates to Engineer, the handoff is visible in chat
  • CHAT-10 — Message editing: edit a previous message and regenerate the response
  • CHAT-11 — Response regeneration: retry button on any assistant message
  • CHAT-12 — Stop generation: cancel button available while a response is streaming
  • CHAT-13 — Message reactions / bookmarks: mark important messages for later reference
  • CHAT-14 — Conversation branching: editing a mid-conversation message creates a branch; both branches are preserved

Input (7)

  • INPUT-01 — Multi-line text input with auto-resize: grows with content up to a max height before scrolling
  • INPUT-02 — File/image upload via drag-and-drop or button with inline preview before sending
  • INPUT-03 — Paste image from clipboard directly into the chat input
  • INPUT-04 — Voice input via Whisper (when local AI is enabled): record button with transcription preview before sending
  • INPUT-05 — Slash commands: /brainstorm, /ask-pm, /ask-engineer, /task, /search
  • INPUT-06 — @mention agents: type @engineer to route a message to a specific agent
  • INPUT-07 — Keyboard shortcuts: Enter to send, Shift+Enter for newline, Cmd+K for search, Escape to cancel

Agent Integration (7)

  • AGENT-01 — Default agent is the Brainstormer (Generalist with a Superpowers-style system prompt, or a dedicated 4th Brainstormer agent)
  • AGENT-02 — Brainstormer follows a structured questioning flow: asks clarifying questions, produces a spec template, and hands off to PM
  • AGENT-03 — PM agent can receive specs from chat and create Nexus tasks/issues from them
  • AGENT-04 — Agent responses show which agent is speaking with avatar and name
  • AGENT-05 — Handoff indicators visible in chat: "Brainstormer → PM: Here's the spec for approval"
  • AGENT-06 — Task creation from chat: user or agent can say "create a task for this" and it becomes a Nexus issue
  • AGENT-07 — Status updates from agents appear in chat: "Engineer completed task X" notification in the relevant conversation

History & Persistence (6)

  • HIST-01 — All conversations persisted in libSQL
  • HIST-02 — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent
  • HIST-03 — Infinite scroll in the conversation list sidebar
  • HIST-04 — Conversation export: download as Markdown or JSON
  • HIST-05 — Cross-device sync: conversations accessible from any device on the network via the Nexus server API
  • HIST-06 — Chat history survives server restarts: no in-memory-only state

PWA & Mobile (8)

  • PWA-01 — Service worker for offline capability: cached UI loads instantly, queues messages until back online
  • PWA-02 — Web App Manifest: installable on iOS, Android, macOS, and Windows as a standalone app
  • PWA-03 — Responsive layout: adapts to phone, tablet, and desktop screen sizes
  • PWA-04 — Mobile-optimized input: large touch targets, sticky input bar at bottom, keyboard-aware resize
  • PWA-05 — Pull-to-refresh on the mobile conversation list
  • PWA-06 — Push notifications (where supported): agent mentions, task completions, handoff requests
  • PWA-07 — App icon and splash screen with Nexus branding, theme-aware
  • PWA-08 — "Add to Home Screen" prompt on first mobile visit

Theme Integration (3)

  • THEME-01 — Chat interface respects the Nexus theme system (Catppuccin Mocha, Tokyo Night, Catppuccin Latte)
  • THEME-02 — Code blocks use theme-appropriate syntax highlighting colors
  • THEME-03 — Agent avatars/colors are visually distinguishable in all three themes

Performance (5)

  • PERF-01 — Initial load under 2 seconds on broadband, under 5 seconds on 3G
  • PERF-02 — Streaming response latency under 100ms from server to UI
  • PERF-03 — Conversations with 1,000+ messages scroll smoothly via a virtualized list
  • PERF-04 — Full-text search returns results in under 500ms across 10,000+ messages
  • PERF-05 — PWA cached load under 1 second

File System (13)

  • FILE-01 — Local file storage directory structure under <nexus-root>/files/ with subdirectories: projects/<slug>/assets/, projects/<slug>/docs/, projects/<slug>/generated/, projects/<slug>/placeholders/, chat/<conversation-id>/, and exports/
  • FILE-02 — libSQL files table tracking all file metadata: id, filename, original_filename, mime_type, size_bytes, storage_path, git_hash, checksum, dual-scope fields (project_id, conversation_id, message_id, agent_id, workspace_id, task_id), source, category, placeholder fields, and lifecycle timestamps
  • FILE-03 — libSQL file_references table enabling a single file to be referenced from multiple conversations without duplication
  • FILE-04 — Dual scoping: a file uploaded during a project-linked conversation lives in files/projects/<slug>/ but is also referenced by the chat message; a file in a general chat (no project context) lives in files/chat/<conversation-id>/
  • FILE-05 — File upload from chat input via drag-and-drop or button; file is stored on disk and its metadata is written to libSQL
  • FILE-06 — Inline file preview in chat: images render inline, PDFs show a first-page preview, code files show a syntax-highlighted preview
  • FILE-07 — One-click file download from chat for any attached or generated file
  • FILE-08 — Agent-generated files (code output, specs, presentations) stored in files/projects/<slug>/generated/, linked to the originating task and conversation in libSQL
  • FILE-09 — Git integration: files/ is a git repository; every file operation (upload, generate, replace, delete) creates a commit with a descriptive message
  • FILE-10 — Version history: user can view the git log for any file and see its change history
  • FILE-11 — Placeholder asset tracking: Nexus auto-maintains a PLACEHOLDERS.md manifest in each project directory; when a placeholder is replaced by a final asset, the manifest and DB are updated with the replacement chain
  • FILE-12 — File scope promotion: a chat-scoped file can be promoted to a project scope; a project file can be referenced in any chat conversation
  • FILE-13 — Cross-device file access: files are served via the Nexus server API so a file uploaded on one device is accessible on any other device on the network

Out of Scope (v1.4+)

The following are explicitly deferred:

  • Voice call / audio conversation mode
  • Video sharing / screen recording in chat
  • Collaborative chat (multiple human users in one conversation)
  • End-to-end encryption
  • Chat API for third-party integrations
  • Custom chat themes beyond the Nexus theme system
  • Chat-based agent configuration / settings changes
  • Telegram bridge (Telegram messages appearing in web chat and vice versa)

Traceability

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