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

docs: create milestone v1.4 roadmap (3 phases)

Browse source
This commit is contained in:
Nexus Dev 2026-04-02 16:07:58 +00:00
parent ef3a9fcc5b
commit 07c0fa2385
3 changed files with 85 additions and 234 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
.planning/REQUIREMENTS.md
View file

@ -41,19 +41,19 @@ None deferred — all PRD items included in this milestone.
| Requirement | Phase | Status |
|-------------|-------|--------|
| 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 |
| HERM-01 | Phase 27 | Pending |
| HERM-02 | Phase 27 | Pending |
| HERM-03 | Phase 27 | Pending |
| HERM-04 | Phase 27 | Pending |
| HERM-05 | Phase 28 | Pending |
| HERM-06 | Phase 28 | Pending |
| HERM-07 | Phase 28 | Pending |
| OLLA-01 | Phase 28 | Pending |
| OLLA-02 | Phase 28 | Pending |
| OLLA-03 | Phase 28 | Pending |
| OLLA-04 | Phase 28 | Pending |
| OLLA-05 | Phase 28 | Pending |
| DFLT-01 | Phase 29 | Pending |
| DFLT-02 | Phase 29 | Pending |
| DFLT-03 | Phase 29 | Pending |
| DFLT-04 | Phase 29 | Pending |

268
.planning/ROADMAP.md
View file

@ -1,229 +1,84 @@
# Roadmap: v1.3 Web Chat Interface
# Roadmap: v1.4 Hermes Default Provider
**Milestone:** v1.3
**Status:** Queued (not yet active)
**Phases:** 21-26 (6 phases)
**Granularity:** Standard
**Coverage:** 65/65 requirements mapped
**Milestone:** v1.4
**Status:** Active
**Phases:** 27-29 (3 phases)
**Granularity:** Coarse
**Coverage:** 16/16 requirements mapped
---
## Phases
- [x] **Phase 21: Chat Foundation** — Persistent conversation storage, sidebar, CRUD, markdown rendering, theme integration, keyboard shortcuts (completed 2026-04-01)
- [x] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions (completed 2026-04-01)
- [x] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat (completed 2026-04-01)
- [x] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks (completed 2026-04-01)
- [x] **Phase 25: File System** — Local file storage with dual scoping, libSQL tracking, inline preview, download, agent-generated files, git versioning, placeholder tracking (gap closure in progress) (completed 2026-04-02)
- [x] **Phase 26: PWA & Performance** — Service worker, Web App Manifest, responsive mobile layout, push notifications, install prompt, performance targets (completed 2026-04-02)
- [ ] **Phase 27: Hermes Adapter** — Install and enable the Hermes adapter, expose it in the Add Agent dialog, and deliver working heartbeat execution with session persistence
- [ ] **Phase 28: Ollama Integration & Agent Surface** — Detect Ollama, list and recommend models, expose skill/cost/dashboard data for Hermes agents
- [ ] **Phase 29: Default Provider & End-to-End** — Onboarding fallback to Hermes, agent template compatibility, GSD workflow validation, full end-to-end smoke test
---
## 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
### Phase 27: Hermes Adapter
**Goal**: Users can create a Hermes agent in Nexus, configure it, and have it execute heartbeats that spawn `hermes chat -q`, return a result, and persist the session across runs
**Depends on**: Nothing (first phase of v1.4; depends on v1.3 milestone being shipped)
**Requirements**: HERM-01, HERM-02, HERM-03, HERM-04
**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)
1. "Hermes" appears in the "Add Agent" dropdown and can be selected to create a new agent
2. When creating a Hermes agent, the user can pick a model and toggle tool permissions; the agent is saved and appears in the agent list
3. When a heartbeat fires for a Hermes agent, Nexus spawns `hermes chat -q` with the task, the process completes, and the result is written back as a task update
4. A second heartbeat on the same Hermes agent resumes the prior session via `--resume`; context from the previous run is accessible
**Plans**: TBD
### Phase 28: Ollama Integration & Agent Surface
**Goal**: Users can see which Ollama models are available, get a recommendation for their hardware, configure any Hermes agent to use a local model, and see Hermes-specific runtime data in the dashboard and agent config
**Depends on**: Phase 27
**Requirements**: OLLA-01, OLLA-02, OLLA-03, OLLA-04, OLLA-05, HERM-05, HERM-06, HERM-07
**Success Criteria** (what must be TRUE):
1. When Ollama is installed, a status indicator in the Hermes agent config shows "Ollama detected" with the version; when Ollama is absent, the config shows installation instructions with a link
2. A Hermes agent's model selector lists all locally available Ollama models pulled from `ollama list`
3. User can save a Hermes agent with any Ollama model from the list; heartbeats use the selected model
4. The model selector shows a recommended model (highlighted) based on detected RAM/VRAM, derived from a shipped catalog
5. The agent config page shows Nexus-managed skills alongside Hermes native skills in a single unified list
6. The dashboard agent card for a Hermes agent shows model name, memory usage, and native skill count
7. Token usage and estimated model cost are recorded per heartbeat and surfaced in the cost tracking view
**Plans**: TBD
**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
### Phase 29: Default Provider & End-to-End
**Goal**: A fresh Nexus install with only Hermes and Ollama works end-to-end — onboarding offers Hermes as the default, PM and Engineer templates run correctly on the Hermes runtime, and GSD workflow tasks complete successfully
**Depends on**: Phase 28
**Requirements**: DFLT-01, DFLT-02, DFLT-03, DFLT-04
**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:** 6/6 plans complete
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
- [x] 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:** 4/4 plans complete
Plans:
- [x] 23-00-PLAN.md — DB migration (message_type column), shared types/validators, Wave 0 test stubs
- [x] 23-01-PLAN.md — Server: addSystemMessage helper, handoff route, status-update route
- [x] 23-02-PLAN.md — UI: ChatSpecCard, ChatHandoffIndicator, ChatTaskCreatedBadge, ChatStatusUpdateBadge, useBrainstormerDefault
- [x] 23-03-PLAN.md — Wiring: ChatMessage dispatch, ChatMessageList propagation, ChatPanel brainstormer default, chatApi handoff
**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:** 4/4 plans complete
Plans:
- [x] 24-00-PLAN.md — DB migrations (branch columns, tsvector+GIN, bookmarks table), shared types, Wave 0 test stubs
- [x] 24-01-PLAN.md — Server: search, bookmark, branch, export service methods and Express routes
- [x] 24-02-PLAN.md — UI: ChatSearchDialog, ChatMessageBookmark, ChatBookmarkList, ChatBranchSelector, API client, hooks
- [x] 24-03-PLAN.md — Wiring: ChatPanel integration, CommandPalette search item, scroll-to-message, bookmark toggle, branch-on-edit
**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:** 9/9 plans complete
Plans:
- [x] 25-00-PLAN.md — DB schema (chat_files + chat_file_references), shared types/validators, test stubs
- [x] 25-01-PLAN.md — Server: chatFileService + chatFileRoutes (upload, download, list, references)
- [x] 25-02-PLAN.md — UI: ChatInput file upload (drag-drop, paste, file picker), useChatFileUpload hook
- [x] 25-03-PLAN.md — UI: ChatFilePreview/ChatFileCard components, ChatMessage/ChatPanel wiring
- [x] 25-04-PLAN.md — Gap: Code syntax-highlighted preview (FILE-06) + admin claims (FILE-07, FILE-13)
- [x] 25-05-PLAN.md — Gap: File scope promotion API + UI (FILE-12)
- [x] 25-06-PLAN.md — Gap: Git integration for file operations + version history (FILE-09, FILE-10)
- [x] 25-07-PLAN.md — Gap: Agent-generated files + placeholder tracking (FILE-08, FILE-11)
- [x] 25-08-PLAN.md — Gap: Voice input via Whisper (INPUT-04) + admin claims (INPUT-02, INPUT-03)
**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:** 5/5 plans complete
Plans:
- [x] 26-00-PLAN.md — Foundation: SW rewrite (cache-first), deps (idb, web-push), PWA types, Wave 0 test stubs
- [x] 26-01-PLAN.md — Performance: React.lazy route splitting + Vite vendor chunk splitting
- [x] 26-02-PLAN.md — Mobile responsive: MobileChatView, MobileNavBar, PullToRefresh, ChatPanel/ChatInput mobile wiring
- [x] 26-03-PLAN.md — PWA features: InstallPromptBanner, OfflineBanner, useOfflineQueue (IndexedDB message queue)
- [x] 26-04-PLAN.md — Push notifications: DB schema, server VAPID/routes, client subscription hook, permission prompt
**UI hint**: yes
1. During onboarding, if no cloud provider API key is detected, the setup flow offers "Use Hermes (local, free)" as the default provider with a one-click path to configure it
2. Creating a PM agent or Engineer agent from the predefined templates and assigning it to a Hermes runtime produces a working agent — heartbeats execute and return meaningful results
3. Running a full GSD workflow task (create issue, assign to Engineer, execute heartbeat, mark complete) with Hermes as the sole runtime completes without errors
4. A machine with only Nexus, Hermes, and Ollama installed (no Anthropic/OpenAI key) can complete the entire onboarding-to-first-task flow with no paywalls or missing-key errors
**Plans**: TBD
---
## Coverage Validation
All 65 v1 requirements are mapped to exactly one phase. No orphans.
All 16 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 |
| HERM-01 | 27 |
| HERM-02 | 27 |
| HERM-03 | 27 |
| HERM-04 | 27 |
| HERM-05 | 28 |
| HERM-06 | 28 |
| HERM-07 | 28 |
| OLLA-01 | 28 |
| OLLA-02 | 28 |
| OLLA-03 | 28 |
| OLLA-04 | 28 |
| OLLA-05 | 28 |
| DFLT-01 | 29 |
| DFLT-02 | 29 |
| DFLT-03 | 29 |
| DFLT-04 | 29 |
---
@ -231,9 +86,6 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 21. Chat Foundation | v1.3 | 7/7 | Complete | 2026-04-01 |
| 22. Agent Streaming | v1.3 | 6/6 | Complete | 2026-04-01 |
| 23. Brainstormer Flow | v1.3 | 4/4 | Complete | 2026-04-01 |
| 24. Search, History & Branching | v1.3 | 4/4 | Complete | 2026-04-01 |
| 25. File System | v1.3 | 9/9 | Complete | 2026-04-02 |
| 26. PWA & Performance | v1.3 | 5/5 | Complete | 2026-04-02 |
| 27. Hermes Adapter | v1.4 | 0/? | Not started | - |
| 28. Ollama Integration & Agent Surface | v1.4 | 0/? | Not started | - |
| 29. Default Provider & End-to-End | v1.4 | 0/? | Not started | - |

19
.planning/STATE.md
View file

@ -2,12 +2,12 @@
gsd_state_version: 1.0
milestone: v1.4
milestone_name: Hermes Default Provider
status: planning
status: active
stopped_at: null
last_updated: "2026-04-02T15:10:00.000Z"
last_activity: 2026-04-02
progress:
total_phases: 0
total_phases: 3
completed_phases: 0
total_plans: 0
completed_plans: 0
@ -21,16 +21,16 @@ progress:
See: .planning/PROJECT.md (updated 2026-04-02)
**Core value:** Nexus works out of the box without any paid subscription or API key.
**Current focus:** Defining requirements for v1.4 Hermes Default Provider
**Current focus:** Phase 27 — Hermes Adapter
## Current Position
Phase: Not started (defining requirements)
Phase: 27 — Hermes Adapter
Plan: —
Status: Defining requirements
Status: Not started
Last activity: 2026-04-02
Progress: [██████████] 100%
Progress: [__________] 0%
### Upstream Rebase Log
@ -184,11 +184,10 @@ None yet.
### Blockers/Concerns
- Phase 4: `POST /api/companies` required fields not fully documented — read `server/src/routes/companies.ts` before implementing new wizard
- Phase 3: Exact count of test files asserting on old display strings unknown — grep audit needed as first step
None identified yet.
## Session Continuity
Last session: 2026-04-02T02:33:59.681Z
Stopped at: Completed 26-04-PLAN.md
Last session: 2026-04-02T15:10:00.000Z
Stopped at: Roadmap created for v1.4
Resume file: None