nexus/.planning/milestones/v1.2.1-ROADMAP.md

Roadmap: Nexus

Overview

Transform Paperclip into Nexus through four phases of increasing surface area. Phase 1 establishes the containment structure (new files only, zero upstream touches). Phase 2 makes the lowest-risk upstream edits — one-line constant changes, home directory pointer, and branding assets. Phase 3 completes the surface-level string renames across UI and CLI. Phase 4 delivers the flagship UX change: zero-friction onboarding with predefined PM and Engineer agent templates. Every phase produces a rebase-clean state that can sync upstream without compound conflicts.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Foundation - Scaffold branding package, zone taxonomy, and git workflow (new files only, no upstream touches) (completed 2026-03-30)
• Phase 2: Constants and Directory - One-line upstream constant edits, home directory pointer mechanism, and startup branding
• Phase 3: UI and CLI Strings - Rename all Company/CEO/Board strings across UI components and CLI output
• Phase 4: Onboarding - Zero-friction root-directory wizard, predefined PM and Engineer templates, Add Agent dialog

Phase Details

Phase 1: Foundation

Goal: The containment structure exists — branding package, zone taxonomy, and commit discipline are in place before any upstream file is touched Depends on: Nothing (first phase) Requirements: FOUND-01, FOUND-02, FOUND-03, FOUND-04 Success Criteria (what must be TRUE):

1. packages/branding/ exists and exports a VOCAB constant importable by other packages
2. A zone taxonomy document in .planning/ classifies every rename target as display-safe, code (don't touch), or stored (don't touch)
3. A pre-commit hook rejects any commit whose message lacks the [nexus] prefix
4. git rerere is enabled and a rebase runbook exists in .planning/ documenting git range-diff workflow Plans: 2/2 plans complete Plans:

• 01-01-PLAN.md — Branding package with VOCAB constant and tests
• 01-02-PLAN.md — Zone taxonomy, commit hook, git rerere, rebase runbook

Phase 2: Constants and Directory

Goal: The core vocabulary constant and home directory mechanism are live — all downstream components can import correct labels and the pointer-file pattern is established with a safe migration fallback Depends on: Phase 1 Requirements: TERM-05, BRND-02, DIR-01, DIR-02, DIR-03, DIR-04, DIR-05 Success Criteria (what must be TRUE):

1. Running the app shows "NEXUS" in the server startup ASCII banner (not "PAPERCLIP")
2. AGENT_ROLE_LABELS.ceo returns "Project Manager" at runtime (verifiable via agent config page)
3. A ~/.nexus file containing a root path causes the server and CLI to use that root directory
4. If ~/.nexus does not exist the server and CLI fall back to ~/.paperclip without error
5. Agent directories created under the user-chosen root use human-readable slugified names, not UUIDs Plans: TBD

Phase 3: UI and CLI Strings

Goal: Every user-facing surface uses Nexus vocabulary — no "Company", "CEO", "Board", "Hire", or "Fire" visible anywhere in the UI or CLI output Depends on: Phase 2 Requirements: TERM-01, TERM-02, TERM-03, TERM-04, TERM-06, BRND-01, BRND-03, BRND-04 Success Criteria (what must be TRUE):

1. The browser tab and top-left logo area display "Nexus" (not "Paperclip")
2. The sidebar, settings pages, and all dialogs show "Workspace" where "Company" appeared, "Project Manager" where "CEO" appeared, "Owner" where "Board" appeared, and "Add" / "Remove" where "Hire" / "Fire" appeared
3. Running nexus --help displays Nexus vocabulary throughout (no Paperclip branding in user-facing help text)
4. The favicon and logo assets are Nexus-branded
5. A post-rename grep audit of ui/src, cli/src, and server/src finds zero unintentional remaining occurrences of the old terms Plans: TBD UI hint: yes

Phase 4: Onboarding

Goal: A fresh install asks for exactly one thing (root directory), auto-creates PM and Engineer agents with predefined templates, and drops the user directly in the dashboard — no corporate metaphors anywhere in the flow Depends on: Phase 3 Requirements: ONBD-01, ONBD-02, ONBD-03, ONBD-04, ONBD-05, ONBD-06, ONBD-07, TERM-07 Success Criteria (what must be TRUE):

1. The UI onboarding wizard shows a single root directory picker with no company name, mission, or first-task fields
2. Completing UI onboarding automatically creates a PM agent and an Engineer agent, each pre-loaded with their respective SOUL.md, AGENTS.md, HEARTBEAT.md, and TOOLS.md content
3. After onboarding completes the user lands directly on the dashboard (no extra steps)
4. Running nexus onboard from the CLI mirrors the UI flow: pick root, auto-create agents, done
5. The "Add Agent" button opens a dialog with a template dropdown listing PM and Engineer as options (no "Hire" language) Plans: TBD UI hint: yes

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3 -> 4

Phase	Plans Complete	Status	Completed
1. Foundation	2/2	Complete	2026-03-30
2. Constants and Directory	0/?	Not started	-
3. UI and CLI Strings	0/?	Not started	-
4. Onboarding	0/?	Not started	-