nexus/.planning/milestone-queue/v1.4-ROADMAP.md

Roadmap: v1.4 Hermes as Default Inference Provider + Web Control Plane

Milestone: v1.4 Phases: 27–34 Coverage: 62/62 requirements mapped Depends on: v1.2.0.1 (nxr), v1.2.1 (Universal Skills), v1.3 (Web Chat)

---

Phases

• Phase 27: Data Model — libSQL schema additions for agents table, model_scores table, and onboarding table
• Phase 28: Model Scoring Engine — Deterministic scoring function, per-role selection algorithm, scoring API
• Phase 29: Default Skillsets and Agent Templates — Curated skill assignments for PM, Engineer, Hermes, and custom category templates
• Phase 30: Free-by-Default Onboarding — CLI and web wizard flows that create three agents on free models with zero API key
• Phase 31: API Key Upgrade Flow — nxr upgrade commands and web bulk-upgrade that switch agents from free to paid models
• Phase 32: Scanner Updates — Post-scan rescoring, better-model notifications, rate limit prediction
• Phase 33: nxr Agent Commands — nxr agents recommend, rescore, create; TUI Tab 5 create wizard
• Phase 34: Web Control Plane — Nexus Hub pages for process control, model switching, agent management, budget, and notifications

---

Phase Details

Phase 27: Data Model

Goal: The libSQL database in hermes_tracking.db has all schema additions v1.4 requires — agents table columns for role and skill metadata, a model_scores table for scoring history, and an onboarding table for wizard state — so every subsequent phase can read and write without migration surprises Depends on: v1.2.0.1 (existing hermes_tracking.db schema) Requirements: DATA-01, DATA-02, DATA-03, DATA-04, DATA-05, DATA-06, DATA-07 Success Criteria (what must be TRUE):

1. The agents table has all six new columns (role, skillset, model_score, model_auto_assigned, workspace_id, is_default) with correct types and defaults, addable via ALTER TABLE without touching upstream Paperclip migrations
2. The model_scores table exists with all defined columns, the UNIQUE(model_id, role, scored_at) constraint, and indexes on role and is_free; queries against it return zero rows on a fresh DB without errors
3. The onboarding table exists with all defined columns; inserting a record and querying completed_at IS NOT NULL works as expected
4. All schema additions use libSQL (not modernc.org/sqlite or any other driver) and are applied via the same migration mechanism used by the rest of nxr Plans: TBD

Phase 28: Model Scoring Engine

Goal: A deterministic Go scoring function can take any agent role and the current free model catalog, apply the scoring formula, enforce role-specific requirements, and return the best available model — callable from both the CLI and the HTTP API Depends on: Phase 27 Requirements: SCORE-01, SCORE-02, SCORE-03, SCORE-04, SCORE-05, SCORE-06 Success Criteria (what must be TRUE):

1. Given identical catalog input, the scoring function always returns the same model for the same role (deterministic output verified by test)
2. Running the scorer for each of the six roles (pm, engineer, hermes, creative, research, custom) returns a model that satisfies that role's minimum requirements (tools support, context window, etc.); if no model qualifies, the fallback chain (openrouter/free → local Qwen) is used
3. Scoring results are written to the model_scores libSQL table with all sub-scores populated and a scored_at timestamp
4. POST /api/models/rescore triggers the scorer and returns the updated best model per role; GET /api/models/best-free?role=<role> returns the current top pick for that role
5. GET /api/models/roster returns all free models with their scores for all roles in a single response Plans: TBD

Phase 29: Default Skillsets and Agent Templates

Goal: When any agent is created — through onboarding, nxr agents create, or the web wizard — the correct curated skillset is automatically applied based on role, and the Paperclip adapter can see those skills via listSkills/syncSkills Depends on: Phase 27 Requirements: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07 Success Criteria (what must be TRUE):

1. A newly created PM agent has exactly 8 skills in its skillset column (planning, task-breakdown, prioritization, status-reporting, dependency-mapping, sprint-planning, risk-assessment, stakeholder-comms)
2. A newly created Engineer agent has exactly 8 skills (coding, debugging, git-workflow, testing, code-review, refactoring, architecture, documentation) and Hermes agent has exactly 8 skills (memory, web-search, file-ops, cron, usage-tracker, model-scanner, skill-creator, session-search)
3. The listSkills adapter API call on any default agent returns the correct skill list so Paperclip heartbeats can read it
4. Selecting a custom agent category (tech, creative, business, research, media, personal) during creation pre-populates the skill selector with that category's defined template; all 6 categories have templates
5. Adding or removing skills after creation is possible and does not break the syncSkills round-trip Plans: TBD

Phase 30: Free-by-Default Onboarding

Goal: A user can run nxr init or open /setup in the browser and within 5 minutes have three working agents (PM, Engineer, Hermes) running on free models with zero API key, zero cost, and zero manual configuration Depends on: Phase 28, Phase 29 Requirements: ONBOARD-01, ONBOARD-02, ONBOARD-03, ONBOARD-04, ONBOARD-05, ONBOARD-06, ONBOARD-07, ONBOARD-08, NXR-01, NXR-02, NXR-03 Success Criteria (what must be TRUE):

1. nxr init on a fresh install completes in under 5 minutes, creates all three default agents with free models assigned by the scoring algorithm, and prints each agent's name, model, and skillset in the confirmation output
2. nxr init --free runs without prompting for an API key; nxr init --key sk-or-... accepts a key non-interactively and uses it during setup
3. The CLI onboarding detects Ollama and faster-whisper availability and records the findings in the onboarding DB table; auxiliary task routing is configured for local processing when Ollama is found
4. The web wizard at /setup completes the same five steps and results in the same DB state as the CLI flow; running both flows does not create duplicate agents
5. The onboarding table record is created with completed_at, agents_created, and initial_free_models populated; re-running either flow detects the existing record and skips agent creation
6. The zero-key free tier limits are displayed clearly at the end of both flows, with instructions for upgrading via nxr config set openrouter-key Plans: TBD UI hint: yes

Phase 31: API Key Upgrade Flow

Goal: A user with a working free-tier workspace can add an OpenRouter API key in one command or one button click, see per-agent upgrade recommendations, and switch all agents to paid models — with a revert path if they change their mind Depends on: Phase 28, Phase 30 Requirements: UPGRADE-01, UPGRADE-02, UPGRADE-03, UPGRADE-04, UPGRADE-05, UPGRADE-06, NXR-04, NXR-05, NXR-06 Success Criteria (what must be TRUE):

1. nxr upgrade validates the OpenRouter API key, detects account balance, and displays the correct free tier tier (50/day or 1000/day) based on credit balance
2. The interactive upgrade prompt shows every agent's current free model alongside its recommended paid replacement with pricing; the user can select Y, n, or custom and each path executes without error
3. nxr upgrade --all switches all agents to paid models non-interactively; nxr upgrade --agent "<name>" upgrades exactly one agent
4. nxr upgrade --revert switches all agents back to their last free model assignments; agent memory, skills, and session history are intact after both upgrade and revert
5. The web agent manager's "Bulk Upgrade" button calls the API and shows the same per-agent recommendations and confirmation; individual agent upgrade controls work per-agent
6. After any upgrade or revert, nxr agents recommend output reflects the current model assignments correctly Plans: TBD

Phase 32: Scanner Updates

Goal: The 6-hourly OpenRouter scanner automatically rescores all models after each scan, creates actionable notifications when better free models are available, and proactively warns the workspace before it hits daily rate limits Depends on: Phase 27, Phase 28 Requirements: SCAN-01, SCAN-02, SCAN-03, SCAN-04, SCAN-05 Success Criteria (what must be TRUE):

1. After each scan run, the scanner writes fresh rows to model_scores for every role category; the scored_at timestamps in the table match the scan time
2. When a re-score reveals a higher-scoring free model for an active agent's role, a notification record is created with the old model name, new model name, role, and score delta; the notification includes a one-click upgrade action
3. The auto_upgrade_free_models config flag (default false) controls whether the scanner auto-switches agents or only creates notifications; setting it true and triggering a re-score automatically updates agent model assignments
4. nxr budget displays the projected daily request total based on current usage rate and hours remaining, with a clear indicator if the workspace is on track to hit the limit
5. Rate limit warnings appear in the dashboard at 70% consumption, a Telegram notification fires at 90% (when gateway is configured), and agents queue tasks at 100% rather than erroring Plans: TBD

Phase 33: nxr Agent Commands

Goal: Users can ask nxr for model recommendations per agent, re-run scoring on demand, and create new agents with auto-selected models and skill templates — all from the terminal — and the TUI Tab 5 provides the same create flow visually Depends on: Phase 28, Phase 29, Phase 31 Requirements: NXR-07, NXR-08, NXR-09 Success Criteria (what must be TRUE):

1. nxr agents recommend prints a table with one row per agent showing: agent name, current model, recommended model for its role, and whether an upgrade is available
2. nxr agents rescore re-runs the scoring algorithm for all agents, writes updated rows to model_scores, and reports any agents where the recommended model has changed since the last score
3. nxr agents create --role <role> --name <name> --free creates a new agent, assigns the best free model for the role, applies the role's skill template, and confirms creation with a summary line
4. The TUI Tab 5 "Create Agent" wizard walks through: category selection → auto model recommendation display → skill template pre-fill → name input → confirm; the created agent appears in the agent list immediately Plans: TBD

Phase 34: Web Control Plane

Goal: Every capability available in the nxr terminal TUI is also accessible from the Nexus Hub browser — process control, model slot switching, agent management with recommendations, budget tracking, and notification management Depends on: Phase 30, Phase 31, Phase 32, Phase 33 Requirements: WEBCP-01, WEBCP-02, WEBCP-03, WEBCP-04, WEBCP-05, WEBCP-06, WEBCP-07, WEBCP-08, WEBCP-09, WEBCP-10, WEBCP-11, WEBCP-12, WEBCP-13, WEBCP-14 Success Criteria (what must be TRUE):

1. The /hermes page shows live process status (PID, uptime, model, tmux viewers) and Start/Stop/Restart buttons that work correctly; the Ollama status card appears when Ollama is running
2. The /models/switch page slot editor shows all 7 routing slots with current assignments; clicking a slot opens a fuzzy-search model picker with filter toggles and a price comparison panel; confirming a pick writes config.yaml atomically
3. The /agents/manage page lists all agents with role-aware model recommendations, heartbeat recency, cost, and error rate; skill assignment and the "Create Agent" wizard produce the same result as nxr agents create
4. The /budget page shows the free tier gauge updating in real time, per-agent cost breakdowns for today/7d/30d, the cost projection graph, and the rate limit event log; CSV export downloads correctly
5. The /notifications page shows all notification types including v1.4 additions (rate limit warnings, auto-upgrade events, model availability alerts); Telegram forwarding toggles persist correctly; unread count badge in navigation updates after marking read Plans: TBD UI hint: yes

---

Coverage Validation

All 62 v1.4 requirements are mapped to exactly one phase. No orphans.

Requirement	Phase
DATA-01	Phase 27
DATA-02	Phase 27
DATA-03	Phase 27
DATA-04	Phase 27
DATA-05	Phase 27
DATA-06	Phase 27
DATA-07	Phase 27
SCORE-01	Phase 28
SCORE-02	Phase 28
SCORE-03	Phase 28
SCORE-04	Phase 28
SCORE-05	Phase 28
SCORE-06	Phase 28
SKILL-01	Phase 29
SKILL-02	Phase 29
SKILL-03	Phase 29
SKILL-04	Phase 29
SKILL-05	Phase 29
SKILL-06	Phase 29
SKILL-07	Phase 29
ONBOARD-01	Phase 30
ONBOARD-02	Phase 30
ONBOARD-03	Phase 30
ONBOARD-04	Phase 30
ONBOARD-05	Phase 30
ONBOARD-06	Phase 30
ONBOARD-07	Phase 30
ONBOARD-08	Phase 30
NXR-01	Phase 30
NXR-02	Phase 30
NXR-03	Phase 30
UPGRADE-01	Phase 31
UPGRADE-02	Phase 31
UPGRADE-03	Phase 31
UPGRADE-04	Phase 31
UPGRADE-05	Phase 31
UPGRADE-06	Phase 31
NXR-04	Phase 31
NXR-05	Phase 31
NXR-06	Phase 31
SCAN-01	Phase 32
SCAN-02	Phase 32
SCAN-03	Phase 32
SCAN-04	Phase 32
SCAN-05	Phase 32
NXR-07	Phase 33
NXR-08	Phase 33
NXR-09	Phase 33
WEBCP-01	Phase 34
WEBCP-02	Phase 34
WEBCP-03	Phase 34
WEBCP-04	Phase 34
WEBCP-05	Phase 34
WEBCP-06	Phase 34
WEBCP-07	Phase 34
WEBCP-08	Phase 34
WEBCP-09	Phase 34
WEBCP-10	Phase 34
WEBCP-11	Phase 34
WEBCP-12	Phase 34
WEBCP-13	Phase 34
WEBCP-14	Phase 34

---

Progress

Phase	Milestone	Plans Complete	Status	Completed
27. Data Model	v1.4	0/?	Not started	-
28. Model Scoring Engine	v1.4	0/?	Not started	-
29. Default Skillsets and Agent Templates	v1.4	0/?	Not started	-
30. Free-by-Default Onboarding	v1.4	0/?	Not started	-
31. API Key Upgrade Flow	v1.4	0/?	Not started	-
32. Scanner Updates	v1.4	0/?	Not started	-
33. nxr Agent Commands	v1.4	0/?	Not started	-
34. Web Control Plane	v1.4	0/?	Not started	-