diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 34956c78..416de587 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -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 | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index a17e8d4c..d17c1dd5 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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 `/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//`; a file from an unlinked conversation lives in `files/chat//`; 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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 48632c4e..2d57022a 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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