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

# Requirements Archive: v1.2.1 Universal Skill Management

**Archived:** 2026-04-01
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# Requirements: Nexus

**Defined:** 2026-03-30
**Core Value:** Fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer, drops you in dashboard — no corporate language anywhere.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Foundation

- [x] **FOUND-01**: Branding package (`packages/branding/`) exists with all fork-specific display strings centralized
- [x] **FOUND-02**: Zone taxonomy document classifies every rename target as display (safe), code (don't touch), or stored (don't touch)
- [x] **FOUND-03**: All fork commits use `[nexus]` prefix for upstream rebase visibility
- [x] **FOUND-04**: `git rerere` enabled and `git range-diff` documented for rebase workflow

### Terminology

- [ ] **TERM-01**: "Company" displays as "Workspace" in all UI surfaces
- [ ] **TERM-02**: "CEO" displays as "Project Manager" in all UI surfaces
- [ ] **TERM-03**: "Board" displays as "Owner" in all UI surfaces
- [ ] **TERM-04**: "Hire" displays as "Add" and "Fire" displays as "Remove" in all UI surfaces
- [ ] **TERM-05**: `AGENT_ROLE_LABELS` constant updated (`ceo: "Project Manager"`)
- [ ] **TERM-06**: CLI output strings updated (all user-facing terminal text uses Nexus vocabulary)
- [ ] **TERM-07**: Default agent instruction content rewritten (SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md) with Nexus vocabulary

### Onboarding

- [ ] **ONBD-01**: Predefined PM agent template exists with 4 instruction files (AGENTS.md, HEARTBEAT.md, SOUL.md, TOOLS.md)
- [ ] **ONBD-02**: Predefined Engineer agent template exists with 4 instruction files
- [ ] **ONBD-03**: UI onboarding wizard asks only for root directory (no company name, no mission, no first task)
- [ ] **ONBD-04**: Onboarding auto-creates PM and Engineer agents with predefined templates
- [ ] **ONBD-05**: After onboarding, user lands directly in the dashboard
- [ ] **ONBD-06**: CLI onboarding (`nexus onboard`) mirrors UI: pick root → auto-create agents → done
- [ ] **ONBD-07**: "Add Agent" dialog uses "Add Agent" button text (not "Hire") with template dropdown

### Branding

- [ ] **BRND-01**: App title shows "Nexus" (not "Paperclip") in browser tab and top-left
- [ ] **BRND-02**: Startup banner displays "NEXUS" ASCII art (not "PAPERCLIP")
- [ ] **BRND-03**: CLI help text displays Nexus name and vocabulary
- [ ] **BRND-04**: Favicon and logo assets updated to Nexus branding

### Directory Structure

- [ ] **DIR-01**: `~/.nexus` pointer file mechanism works (single file containing root directory path)
- [ ] **DIR-02**: All data (config, DB, logs, backups, storage, agent data) lives under user-chosen root directory
- [ ] **DIR-03**: Agent directories use human-readable slugified names (e.g., `agents/engineer/`) not UUIDs
- [ ] **DIR-04**: Config resolution in CLI and server respects `~/.nexus` pointer file
- [ ] **DIR-05**: Read-both-paths fallback: server checks `~/.paperclip` if `~/.nexus` not found (migration safety)

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Theming

- **THEME-01**: Full Catppuccin Mocha dark theme applied to entire UI
- **THEME-02**: Dark/light theme toggle with Catppuccin Mocha + Tokyo Night options

### Integrations

- **INTG-01**: Telegram Channels integration for persistent agent sessions
- **INTG-02**: NPM reverse proxy for remote dashboard access
- **INTG-03**: Recipe Registry plugin

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| DB schema renames (companies table, company_id columns) | Upstream sync priority — would create migration hell |
| API route path changes (/api/companies stays) | Upstream sync — UI translates client-side |
| TypeScript identifier renames (companyService etc.) | Thousands of import statements — massive merge conflict surface |
| Package name renames (@paperclipai/* stays) | Every import in the monorepo — nuclear merge conflict |
| Environment variable renames (PAPERCLIP_* stays) | Breaks existing deployments |
| Token prefix changes (pcp_board_* stays) | Would invalidate issued tokens |
| Plugin API contract changes (company.created events) | Breaks third-party plugins |
| .paperclip.yaml export format rename | Breaks upstream import compatibility |
| Multi-workspace support UI overhaul | Existing multi-company feature works, just renamed |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| FOUND-01 | Phase 1 | Complete |
| FOUND-02 | Phase 1 | Complete |
| FOUND-03 | Phase 1 | Complete |
| FOUND-04 | Phase 1 | Complete |
| TERM-01 | Phase 3 | Pending |
| TERM-02 | Phase 3 | Pending |
| TERM-03 | Phase 3 | Pending |
| TERM-04 | Phase 3 | Pending |
| TERM-05 | Phase 2 | Pending |
| TERM-06 | Phase 3 | Pending |
| TERM-07 | Phase 4 | Pending |
| ONBD-01 | Phase 4 | Pending |
| ONBD-02 | Phase 4 | Pending |
| ONBD-03 | Phase 4 | Pending |
| ONBD-04 | Phase 4 | Pending |
| ONBD-05 | Phase 4 | Pending |
| ONBD-06 | Phase 4 | Pending |
| ONBD-07 | Phase 4 | Pending |
| BRND-01 | Phase 3 | Pending |
| BRND-02 | Phase 2 | Pending |
| BRND-03 | Phase 3 | Pending |
| BRND-04 | Phase 3 | Pending |
| DIR-01 | Phase 2 | Pending |
| DIR-02 | Phase 2 | Pending |
| DIR-03 | Phase 2 | Pending |
| DIR-04 | Phase 2 | Pending |
| DIR-05 | Phase 2 | Pending |

**Coverage:**
- v1 requirements: 27 total
- Mapped to phases: 27
- Unmapped: 0

---
*Requirements defined: 2026-03-30*
*Last updated: 2026-03-30 after roadmap creation*