mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: define milestone v1.4 requirements (16 requirements)

Browse source
This commit is contained in:
Nexus Dev 2026-04-02 15:29:40 +00:00
parent 2d93fd37a8
commit ef3a9fcc5b
1 changed files with 47 additions and 171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

218
.planning/REQUIREMENTS.md
View file

@ -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 `<nexus-root>/files/` with subdirectories: `projects/<slug>/assets/`, `projects/<slug>/docs/`, `projects/<slug>/generated/`, `projects/<slug>/placeholders/`, `chat/<conversation-id>/`, 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/<slug>/` but is also referenced by the chat message; a file in a general chat (no project context) lives in `files/chat/<conversation-id>/`
- [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/<slug>/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 |