nexus/.planning/ROADMAP.md

Roadmap: Nexus

Milestones

• ✅ v1.2.1 Universal Skill Management - Phase 1 (shipped 2026-04-01)
• ✅ v1.3 Chat & PWA - Phases 21-26 (shipped 2026-04-02)
• ✅ v1.4 Hermes Default Provider - Phases 27-29 (shipped 2026-04-02)
• 🚧 v1.5 Smart Onboarding + Personal AI Assistant - Phases 30-35 (in progress)

---

✅ v1.2.1 Universal Skill Management (Phase 1) - SHIPPED 2026-04-01

Phase 1: Foundation

Goal: Establish the display-layer rename infrastructure, git hygiene tooling, and rebase safety primitives that all subsequent phases depend on Plans: 2/2 plans complete

Plans:

• 01-01-PLAN.md — Branding package, VOCAB constants, commit-msg hook
• 01-02-PLAN.md — Zone taxonomy, rerere config, rebase safety infrastructure

✅ v1.3 Chat & PWA (Phases 21-26) - SHIPPED 2026-04-02

Phase 21: Chat Foundation

Goal: Users can have real-time chat conversations with agents Plans: 7/7 plans complete

Phase 22: Agent Streaming

Goal: Agent responses stream in real-time with identity, edit, retry, and stop controls Plans: 5/5 plans complete

Phase 23: Brainstormer Flow

Goal: Users can turn a chat conversation into a tracked project with one handoff action Plans: 4/4 plans complete

Phase 24: Search, History & Branching

Goal: Users can find, bookmark, branch, and export any conversation Plans: 4/4 plans complete

Phase 25: File System

Goal: Users can upload, preview, and version files within chat; voice input transcribes speech to text Plans: 9/9 plans complete

Phase 26: PWA & Performance

Goal: Nexus installs as a PWA, works offline, and loads fast on mobile Plans: 5/5 plans complete

✅ v1.4 Hermes Default Provider (Phases 27-29) - SHIPPED 2026-04-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 Plans: 1/1 plans complete

Plans:

• 27-01-PLAN.md — Close four integration gaps: SESSIONED_LOCAL_ADAPTERS, create-mode toolsets bug, duplicate constant, session codec test

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 Plans: 3/3 plans complete

Plans:

• 28-01-PLAN.md — Ollama service, routes, model catalog, and unit tests
• 28-02-PLAN.md — UI model selector dropdown, install callout, Hermes skill badge
• 28-03-PLAN.md — Hermes stateJson runtime data and dashboard HermesRuntimeCard

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 Plans: 2/2 plans complete

Plans:

• 29-01-PLAN.md — Adapter probe route, onboarding wizard Hermes fallback, adapter-neutral templates
• 29-02-PLAN.md — Hermes skill injection via promptTemplate, integration tests

---

🚧 v1.5 Smart Onboarding + Personal AI Assistant (In Progress)

Milestone Goal: The definitive onboarding experience — hardware detection, tiered provider setup (local/free cloud/paid), and a Personal AI Assistant mode that coexists with the Project Builder.

Phases

• Phase 30: Hardware Detection + Mode Selection — Unauthenticated hardware probe, Apple Silicon unified memory handling, model recommendation database, and mode selector that gates all assistant-specific features (completed 2026-04-02)
• Phase 31: Puter.js Zero-Config Cloud — Server-proxied Puter.js adapter with full cost tracking, Google OAuth PKCE tier, and subscription auto-detection; no API keys required for zero-config path
• Phase 32: Multi-Step Onboarding Wizard — Assemble all provider tiers and hardware data into a skippable multi-step wizard; summary screen routes directly into chat
• Phase 33: Persistent Memory + Personal Assistant Mode — File-backed memory with write-time sanitization, PersonalAssistantPage, conversation handoff to PM agent
• Phase 34: Voice — Piper TTS with pre-warm progress, Whisper STT wired into voice service, onboarding voice step activated
• Phase 35: npx buildthis CLI — Standalone bootstrapper package with hardware detection and provider tiering parity with web onboarding

---

Phase Details

Phase 30: Hardware Detection + Mode Selection

Goal: Users see accurate hardware information during onboarding, get a model recommendation matched to their machine, and choose a mode that correctly gates all downstream features — with the probe working before board auth exists Depends on: Phase 29 (v1.4 shipped) Requirements: ONBD-01, ONBD-02, ONBD-03, ONBD-07 Success Criteria (what must be TRUE):

1. On a fresh install (before any board auth token exists), the hardware probe returns GPU, RAM, and Apple Silicon unified memory data within 5 seconds
2. A Mac Mini M4 reports "unified memory" (not VRAM) with the 0.75 multiplier applied and copy that says "runs entirely on your machine"
3. The mode selector (Personal AI Assistant / Project Builder / Both) is visible during onboarding and the selected mode is persisted; assistant-specific UI is hidden when Project Builder-only is chosen
4. The model recommendation shown to the user matches an entry in the pre-built JSON catalog for the detected hardware tier (GPU / Apple Silicon / CPU-only) Plans: 2 plans

Plans:

• 30-01-PLAN.md — Hardware service, nexus-settings service, model catalog extension, routes, and tests
• 30-02-PLAN.md — ModeSelector, HardwareSummaryStep, useHardwareInfo hook, multi-step wizard wiring

Phase 31: Puter.js Zero-Config Cloud

Goal: Users without Ollama installed can reach working AI in one click via Puter.js — all calls server-proxied, tokens server-stored, cost tracked; Google OAuth and subscription auto-detection round out the provider tier Depends on: Phase 30 Requirements: CLOUD-01, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05 Success Criteria (what must be TRUE):

1. A user with no Ollama and no API keys clicks "Continue with Puter" in onboarding, completes the Puter auth popup, and immediately gets a working chat response — no API key entry required
2. All Puter AI calls flow through POST /api/puter-proxy/chat (verifiable in server logs); the Puter auth token is stored server-side via secretService, not in localStorage
3. Token cost for Puter responses appears in the cost tracking view, attributed correctly per conversation
4. A user with Hermes, Claude Code, or OpenClaw already installed sees those tools pre-filled in the provider configuration step with no manual entry
5. A user clicking "Sign in with Google" for Gemini completes PKCE OAuth and gets a Gemini-backed chat response; the UI displays a policy-risk note that Google OAuth may trigger abuse detection Plans: 4 plans

Plans:

• 31-01-PLAN.md — Puter proxy service, routes, unit tests, and app.ts wiring
• 31-02-PLAN.md — Google OAuth PKCE service, routes, API key storage route
• 31-03-PLAN.md — Provider Selection UI step, PuterAuthButton, GoogleOAuthButton, ApiKeyEntryForm, 4-step wizard wiring
• 31-04-PLAN.md — Google OAuth claim endpoint, human verification of full onboarding flow UI hint: yes

Phase 32: Multi-Step Onboarding Wizard

Goal: Users move through a complete, skippable onboarding flow that assembles hardware data, provider selection, and voice options into a summary screen — and can jump straight into chat from there Depends on: Phase 31 Requirements: ONBD-04, ONBD-05, ONBD-06 Success Criteria (what must be TRUE):

1. A user can click "Skip" on every onboarding step (hardware, provider, voice) and reach the summary screen; the resulting workspace has at least one working agent with a valid provider
2. The summary screen shows the configured providers and agent-model pairings for the selected mode; no corporate language ("company", "CEO", "mission") appears anywhere in the flow
3. From the summary screen, one click navigates directly to the Personal Assistant chat or the project dashboard (depending on chosen mode) with no additional prompts Plans: TBD UI hint: yes

Phase 33: Persistent Memory + Personal Assistant Mode

Goal: Users in Personal AI Assistant mode accumulate memory across sessions that shapes future responses — with no risk of credentials leaking into prompts — and can hand off any conversation to a PM agent with context intact Depends on: Phase 32 Requirements: ASST-01, ASST-02, ASST-03, ASST-04 Success Criteria (what must be TRUE):

1. A fact stated in one chat session ("I prefer TypeScript") is referenced correctly by the assistant in a new session started after closing and reopening the browser
2. Pasting an API key or token into chat and then starting a new session results in the assistant having no knowledge of that credential — the sanitization blocklist prevented it from being stored
3. A user clicks "Turn this into a project" in an assistant conversation; a PM agent is created with a system message containing the conversation summary and they land on the project dashboard
4. A user with mode set to "Both" can switch between Personal Assistant chat and the project dashboard without losing context or cross-contaminating assistant memory with project agent messages Plans: TBD UI hint: yes

Phase 34: Voice

Goal: Users can speak to the assistant (Whisper STT) and hear responses read aloud (Piper TTS) — Piper pre-warms visibly so the first synthesis call does not appear broken, and voice is offered during onboarding based on hardware capability Depends on: Phase 32 Requirements: VOICE-01, VOICE-02, VOICE-03 Success Criteria (what must be TRUE):

1. On a CPU-only machine (no GPU), enabling Piper TTS in the assistant produces audible speech output within a reasonable time after the first synthesis (not a silent hang)
2. When Piper's WASM voice model is downloading for the first time, a visible progress indicator is shown before the TTS toggle is enabled; the download completes and TTS works without a page reload
3. The onboarding voice step offers Whisper STT and Piper TTS toggles only when the hardware detection step has confirmed sufficient capability; on hardware below the threshold, the step is skipped or shows a capability warning Plans: TBD

Phase 35: npx buildthis CLI

Goal: A developer can run npx buildthis on a fresh machine and either open an already-running Nexus or be guided through install — with the same hardware detection and provider tiering as the web onboarding Depends on: Phase 30 (hardware detection service must exist) Requirements: CLI-01, CLI-02 Success Criteria (what must be TRUE):

1. Running npx buildthis on a machine where Nexus is already running opens the Nexus UI in the default browser; running it on a machine with no Nexus guides the user through installation steps
2. The CLI bootstrapper detects the same hardware tier (GPU / Apple Silicon / CPU-only) as the web onboarding and presents the matching provider tier recommendations in the terminal prompt Plans: TBD

---

Coverage Validation

All 21 v1.5 requirements are mapped to exactly one phase. No orphans.

Requirement	Phase
ONBD-01	30
ONBD-02	30
ONBD-03	30
ONBD-07	30
CLOUD-01	31
CLOUD-02	31
CLOUD-03	31
CLOUD-04	31
CLOUD-05	31
ONBD-04	32
ONBD-05	32
ONBD-06	32
ASST-01	33
ASST-02	33
ASST-03	33
ASST-04	33
VOICE-01	34
VOICE-02	34
VOICE-03	34
CLI-01	35
CLI-02	35

---

Progress

Phase	Milestone	Plans Complete	Status	Completed
1. Foundation	v1.2.1	2/2	Complete	2026-04-01
21. Chat Foundation	v1.3	7/7	Complete	2026-04-02
22. Agent Streaming	v1.3	5/5	Complete	2026-04-02
23. Brainstormer Flow	v1.3	4/4	Complete	2026-04-02
24. Search, History & Branching	v1.3	4/4	Complete	2026-04-02
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	1/1	Complete	2026-04-02
28. Ollama Integration & Agent Surface	v1.4	3/3	Complete	2026-04-02
29. Default Provider & End-to-End	v1.4	2/2	Complete	2026-04-02
30. Hardware Detection + Mode Selection	v1.5	2/2	Complete	2026-04-03
31. Puter.js Zero-Config Cloud	v1.5	3/4	In Progress
32. Multi-Step Onboarding Wizard	v1.5	0/TBD	Not started	-
33. Persistent Memory + Personal Assistant Mode	v1.5	0/TBD	Not started	-
34. Voice	v1.5	0/TBD	Not started	-
35. npx buildthis CLI	v1.5	0/TBD	Not started	-