From ef3a9fcc5b797ea354039dd7779bd9b74ba511c7 Mon Sep 17 00:00:00 2001 From: Nexus Dev Date: Thu, 2 Apr 2026 15:29:40 +0000 Subject: [PATCH] docs: define milestone v1.4 requirements (16 requirements) --- .planning/REQUIREMENTS.md | 218 ++++++++------------------------------ 1 file changed, 47 insertions(+), 171 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 3fb930b2..34956c78 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -1,183 +1,59 @@ -# Requirements: v1.3 Web Chat Interface +# Requirements — Milestone v1.4: Hermes Default Provider -**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 +## Hermes Integration (7) + +- [ ] **HERM-01** — Hermes adapter is installed, enabled, and appears in the "Add Agent" dropdown +- [ ] **HERM-02** — User can create a Hermes agent with config options (model selection, tool permissions) +- [ ] **HERM-03** — Heartbeat execution spawns `hermes chat -q`, processes task, returns result +- [ ] **HERM-04** — Session persistence works across heartbeats via `--resume` flag +- [ ] **HERM-05** — Nexus-managed skills are visible alongside Hermes native skills in agent config +- [ ] **HERM-06** — Cost tracking captures token usage and model costs for Hermes agents +- [ ] **HERM-07** — Dashboard shows Hermes-specific info (model name, memory usage, native skill count) + +## Ollama Integration (5) + +- [ ] **OLLA-01** — Nexus detects whether Ollama is installed locally +- [ ] **OLLA-02** — User can see a list of available Ollama models when configuring a Hermes agent +- [ ] **OLLA-03** — User can configure a Hermes agent with any local Ollama model +- [ ] **OLLA-04** — Model recommendation based on RAM/VRAM from a shipped catalog +- [ ] **OLLA-05** — If Ollama is not present, user is offered installation instructions + +## Default Provider Logic (4) + +- [ ] **DFLT-01** — If no cloud provider (Claude Code, etc.) is detected, Hermes + Ollama is offered as default during onboarding +- [ ] **DFLT-02** — Default agent templates (PM, Engineer, Generalist) work correctly with Hermes runtime +- [ ] **DFLT-03** — GSD workflow functions correctly with Hermes as the agent runtime +- [ ] **DFLT-04** — Fresh install with only Hermes + Ollama works end-to-end (no paid subscription or API key required) --- -## Categories +## Future Requirements -### Chat Core (14) +None deferred — all PRD items included in this milestone. -- [x] **CHAT-01** — Real-time streaming responses: tokens appear as they are generated, not after completion -- [x] **CHAT-02** — Markdown rendering in messages: code blocks with syntax highlighting, tables, lists, headings, links, images -- [x] **CHAT-03** — Code blocks have a one-click copy button and a language label -- [x] **CHAT-04** — Multiple concurrent conversations: sidebar shows the full conversation list -- [x] **CHAT-05** — Conversation titles: auto-generated from the first message, manually editable by the user -- [x] **CHAT-06** — Delete, archive, and pin conversations -- [x] **CHAT-07** — Full-text search across all conversations -- [x] **CHAT-08** — Agent selector: switch which agent you are talking to mid-conversation or per-conversation -- [x] **CHAT-09** — System message indicator: when the Brainstormer hands off to PM, or PM delegates to Engineer, the handoff is visible in chat -- [x] **CHAT-10** — Message editing: edit a previous message and regenerate the response -- [x] **CHAT-11** — Response regeneration: retry button on any assistant message -- [x] **CHAT-12** — Stop generation: cancel button available while a response is streaming -- [x] **CHAT-13** — Message reactions / bookmarks: mark important messages for later reference -- [x] **CHAT-14** — Conversation branching: editing a mid-conversation message creates a branch; both branches are preserved +## Out of Scope -### Input (7) - -- [x] **INPUT-01** — Multi-line text input with auto-resize: grows with content up to a max height before scrolling -- [x] **INPUT-02** — File/image upload via drag-and-drop or button with inline preview before sending -- [x] **INPUT-03** — Paste image from clipboard directly into the chat input -- [x] **INPUT-04** — Voice input via Whisper (when local AI is enabled): record button with transcription preview before sending -- [x] **INPUT-05** — Slash commands: `/brainstorm`, `/ask-pm`, `/ask-engineer`, `/task`, `/search` -- [x] **INPUT-06** — `@mention` agents: type `@engineer` to route a message to a specific agent -- [x] **INPUT-07** — Keyboard shortcuts: Enter to send, Shift+Enter for newline, Cmd+K for search, Escape to cancel - -### Agent Integration (7) - -- [x] **AGENT-01** — Default agent is the Brainstormer (Generalist with a Superpowers-style system prompt, or a dedicated 4th Brainstormer agent) -- [x] **AGENT-02** — Brainstormer follows a structured questioning flow: asks clarifying questions, produces a spec template, and hands off to PM -- [x] **AGENT-03** — PM agent can receive specs from chat and create Nexus tasks/issues from them -- [x] **AGENT-04** — Agent responses show which agent is speaking with avatar and name -- [x] **AGENT-05** — Handoff indicators visible in chat: "Brainstormer → PM: Here's the spec for approval" -- [x] **AGENT-06** — Task creation from chat: user or agent can say "create a task for this" and it becomes a Nexus issue -- [x] **AGENT-07** — Status updates from agents appear in chat: "Engineer completed task X" notification in the relevant conversation - -### History & Persistence (6) - -- [x] **HIST-01** — All conversations persisted in libSQL -- [x] **HIST-02** — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent -- [x] **HIST-03** — Infinite scroll in the conversation list sidebar -- [x] **HIST-04** — Conversation export: download as Markdown or JSON -- [x] **HIST-05** — Cross-device sync: conversations accessible from any device on the network via the Nexus server API -- [x] **HIST-06** — Chat history survives server restarts: no in-memory-only state - -### PWA & Mobile (8) - -- [x] **PWA-01** — Service worker for offline capability: cached UI loads instantly, queues messages until back online -- [x] **PWA-02** — Web App Manifest: installable on iOS, Android, macOS, and Windows as a standalone app -- [x] **PWA-03** — Responsive layout: adapts to phone, tablet, and desktop screen sizes -- [x] **PWA-04** — Mobile-optimized input: large touch targets, sticky input bar at bottom, keyboard-aware resize -- [x] **PWA-05** — Pull-to-refresh on the mobile conversation list -- [x] **PWA-06** — Push notifications (where supported): agent mentions, task completions, handoff requests -- [x] **PWA-07** — App icon and splash screen with Nexus branding, theme-aware -- [x] **PWA-08** — "Add to Home Screen" prompt on first mobile visit - -### Theme Integration (3) - -- [x] **THEME-01** — Chat interface respects the Nexus theme system (Catppuccin Mocha, Tokyo Night, Catppuccin Latte) -- [x] **THEME-02** — Code blocks use theme-appropriate syntax highlighting colors -- [x] **THEME-03** — Agent avatars/colors are visually distinguishable in all three themes - -### Performance (5) - -- [x] **PERF-01** — Initial load under 2 seconds on broadband, under 5 seconds on 3G -- [x] **PERF-02** — Streaming response latency under 100ms from server to UI -- [x] **PERF-03** — Conversations with 1,000+ messages scroll smoothly via a virtualized list -- [x] **PERF-04** — Full-text search returns results in under 500ms across 10,000+ messages -- [x] **PERF-05** — PWA cached load under 1 second - -### File System (13) - -- [x] **FILE-01** — Local file storage directory structure under `/files/` with subdirectories: `projects//assets/`, `projects//docs/`, `projects//generated/`, `projects//placeholders/`, `chat//`, and `exports/` -- [x] **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 -- [x] **FILE-03** — libSQL `file_references` table enabling a single file to be referenced from multiple conversations without duplication -- [x] **FILE-04** — Dual scoping: a file uploaded during a project-linked conversation lives in `files/projects//` but is also referenced by the chat message; a file in a general chat (no project context) lives in `files/chat//` -- [x] **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 -- [x] **FILE-06** — Inline file preview in chat: images render inline, PDFs show a first-page preview, code files show a syntax-highlighted preview -- [x] **FILE-07** — One-click file download from chat for any attached or generated file -- [x] **FILE-08** — Agent-generated files (code output, specs, presentations) stored in `files/projects//generated/`, linked to the originating task and conversation in libSQL -- [x] **FILE-09** — Git integration: `files/` is a git repository; every file operation (upload, generate, replace, delete) creates a commit with a descriptive message -- [x] **FILE-10** — Version history: user can view the git log for any file and see its change history -- [x] **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 -- [x] **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 -- [x] **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) - ---- +- Multi-provider model routing (Hermes can use OpenRouter/Anthropic/OpenAI but that's Hermes config, not Nexus) +- Hermes MCP server management (Hermes handles its own MCP connections) +- Custom Hermes skill authoring UI (skills are file-based, not GUI-managed) ## 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 | Complete | -| PWA-03 | Phase 26 | Complete | -| PWA-04 | Phase 26 | Complete | -| PWA-05 | Phase 26 | Complete | -| PWA-06 | Phase 26 | Complete | -| PWA-07 | Phase 26 | Complete | -| PWA-08 | Phase 26 | Complete | -| 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 | +| HERM-01 | TBD | Pending | +| HERM-02 | TBD | Pending | +| HERM-03 | TBD | Pending | +| HERM-04 | TBD | Pending | +| HERM-05 | TBD | Pending | +| HERM-06 | TBD | Pending | +| HERM-07 | TBD | Pending | +| OLLA-01 | TBD | Pending | +| OLLA-02 | TBD | Pending | +| OLLA-03 | TBD | Pending | +| OLLA-04 | TBD | Pending | +| OLLA-05 | TBD | Pending | +| DFLT-01 | TBD | Pending | +| DFLT-02 | TBD | Pending | +| DFLT-03 | TBD | Pending | +| DFLT-04 | TBD | Pending |