# 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.

- [x] **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:
- [x] 01-01-PLAN.md — Branding package with VOCAB constant and tests
- [x] 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 | - |
