mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/.planning/research/SUMMARY.md
Mikkel Georgsen 6c4272ce85 [nexus] chore: migrate .planning/ from agent repo to nexus repo 
Planning artifacts (milestones v1.0-v1.2.1, v1.3 queue, PROJECT.md,
STATE.md, config) now live alongside the code they describe.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 03:55:42 +00:00

17 KiB
Raw Blame History

Project Research Summary

Project: Nexus (fork of Paperclip) Domain: Display-layer fork of a TypeScript AI agent orchestration monorepo Researched: 2026-03-30 Confidence: HIGH

Executive Summary

Nexus is a personal-use fork of Paperclip, an open-source AI agent orchestration platform. The project scope is strictly display-layer: rename corporate metaphors (Company, CEO, Board) to solo-developer vocabulary (Workspace, Project Manager, Owner), replace the onboarding wizard with a zero-friction root-directory-picker flow, and ship predefined PM and Engineer agent templates. No engine changes, no schema changes, no route changes. Every functional capability is inherited from upstream — the work is entirely in what the product communicates to its operator.

The recommended approach is rebase-over-upstream with a [nexus] commit prefix convention, all fork-specific strings isolated in a new packages/branding/ package and ui/src/lib/nexus-labels.ts file, and a Vite alias to redirect the OnboardingWizard import to a fully Nexus-owned replacement component. This architecture concentrates the entire mutable surface in new files that upstream will never create, minimising rebase conflict exposure to a small number of well-understood lines in five upstream files.

The principal risk is accidental scope creep into Zone B (code identifiers) or Zone C (dual-purpose stored DB values) during rename work. A single naive find-replace that touches companyService, "ceo" in AGENT_ROLES, or /api/companies routes would shatter rebasability and require a recovery that undoes the entire rename. The mitigation is a strict three-zone taxonomy applied file-by-file from the first commit, combined with a pre-commit hook enforcing the [nexus] prefix and a weekly rebase cadence.

Key Findings

Recommended Stack

Paperclip's existing stack is retained without alteration. The fork adds one new workspace package (@paperclipai/branding) and two new UI files (nexus-labels.ts, branding.css) — all additions, no modifications to package.json names, tsconfig paths, or Tailwind config structure.

The only tooling additions are: git rerere enabled in the repo config to auto-replay recurring conflict resolutions, and a vite.config.ts define block for build-time product name injection into static HTML. Both are zero-dependency changes.

Core tools:

  • git rebase upstream/master + [nexus] prefix convention: fork sync strategy — standard practice used by git-for-windows, VSCodium, microsoft/git
  • git range-diff + git rerere: rebase verification and auto-resolution — official Git tooling, no third-party risk
  • packages/branding/ (@paperclipai/branding): single string mutation surface — new package in existing namespace, zero import-path disruption
  • ui/src/lib/nexus-labels.ts: UI-layer label registry — new file, zero upstream conflict risk
  • ui/src/branding.css: Tailwind v4 CSS custom property overrides — new file, zero upstream conflict risk
  • Vite resolve.alias for OnboardingWizard: build-time component swap — existing vite.config.ts already uses alias syntax

Expected Features

Must have (table stakes) — all already exist in upstream, display rename only:

  • Dashboard with live agent status (SSE-backed, Company → Workspace rename)
  • Real-time run logs and heartbeat transcript
  • Cost visibility per agent (cost_events table already tracked)
  • Task/issue list with status and sub-task hierarchy
  • Agent status indicators (idle/running/paused)
  • One-command startup (nexus run replacing paperclipai run)
  • Human approval workflow (approvals table and routes intact)
  • Agent configuration page with config revision history
  • Scheduled task creation (routines with cron)
  • CLI help text using Nexus vocabulary throughout

Should have (differentiators):

  • Zero-question onboarding — root directory picker, auto-create PM + Engineer agents, no "company name" or "CEO" prompts (highest-impact UX change)
  • Predefined agent templates (PM + Engineer) — SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md for each role
  • Workspace-first mental model — systematic string audit across all UI and CLI surfaces
  • Nexus branding — logo, <title>, CLI binary name (nexus), favicon
  • "Add Agent" dialog with template dropdown replacing the "hire agent" flow
  • Human-readable agent directories under user root (~/RaglanWork/agents/engineer/)

Defer (v2+):

  • Full Catppuccin Mocha theme (high visual risk for v1, CSS custom properties make it addable later as a single-file change)
  • Telegram Channels integration (separate project scope)
  • Recipe Registry plugin (separate project scope)
  • Plugin API event renames (company.created etc.) — would break existing plugins silently
  • MCP connector layer abstraction (upstream adapter system already handles this)

Critical path for differentiators: D2 (Agent Templates) → D1 (Zero-Question Onboarding) → D4 (Human-Readable Directories). D3 (Workspace Mental Model), D5 (Branding), and D6 (Add Agent Dialog) can ship in any order alongside or after.

Architecture Approach

The architecture goal is to confine all fork-specific content to new files that upstream will never create. Two strategies cover every change type: (1) add-only new files for net-new content (zero conflict risk), and (2) minimal inline edits with // [nexus] markers on lines that must touch existing upstream files (string changes only, never identifier renames). For the one component requiring substantial structural rewriting (OnboardingWizard), a Vite alias redirects the import to a fully Nexus-owned file, leaving the upstream file untouched and allowing upstream to evolve it freely.

Major components:

  1. packages/branding/ (NEW) — canonical vocabulary constants (VOCAB, DISPLAY_ROLE_LABELS); the only place Nexus display strings are defined
  2. ui/src/lib/nexus-labels.ts (NEW) — UI-layer label registry imported by components instead of hardcoded strings
  3. ui/src/nexus/OnboardingWizard.tsx (NEW) — full Nexus onboarding replacement; upstream OnboardingWizard.tsx left untouched
  4. server/src/onboarding-assets/pm/ and engineer/ (NEW) — predefined agent template directories; zero conflict risk as net-new paths
  5. ui/src/branding.css (NEW) — Tailwind v4 CSS custom property overrides for brand colors
  6. packages/shared/src/constants.ts (MODIFIED, 1 line) — ceo: "Project Manager" in AGENT_ROLE_LABELS; the only upstream constants file touched
  7. server/src/home-paths.ts (MODIFIED, 1 line) — default home dir ".nexus"
  8. ui/vite.config.ts (MODIFIED, 1 line) — alias entry redirecting OnboardingWizard import

Critical Pitfalls

  1. Renaming a code identifier that is also a stored DB value — "ceo", "hire_agent", "bootstrap_ceo", "board", "company" are stored in DB rows, not just TypeScript constants. Renaming the constant value silently breaks existing installations (old rows no longer match). Mitigation: rename only the label map value (ceo: "Project Manager"), never the key (ceo). Grep for any target string in packages/db/src/schema/ before renaming.

  2. Bulk find-replace contaminating Zone B (code identifiers) — a naive global replace of "company" touches companyService, import paths, and DB schema values alongside JSX strings. Result: hundreds of rebase conflicts in files that should never have been modified. Mitigation: three-zone taxonomy enforced file-by-file; no global find-replace ever.

  3. Upstream rebase cadence drift — fork conflicts accumulate non-linearly. A two-week gap becomes a four-hour archaeology session. Mitigation: weekly rebase on a fixed schedule, [nexus] prefix from the first commit, CI rebase check on a test branch.

  4. Renaming ~/.paperclip config path without a migration — existing installations lose all agents, projects, and API keys on next startup if the config path is renamed without a read-both-paths fallback. Mitigation: check ~/.nexus first, fall back to ~/.paperclip; implement the pointer-file mechanism before shipping the home dir change.

  5. Partial rename — missing occurrences across 12+ files — "CEO" appears in at least 12 distinct files. Without an i18n layer there is no compile-time verification that a rename is complete. Mitigation: run grep -ri "CEO\|company\|board\|hire\|paperclip" ui/src cli/src server/src after each phase and verify every remaining occurrence is intentional (Zone B/C).

Implications for Roadmap

Based on research, suggested phase structure:

Phase 1: Foundation and String Infrastructure

Rationale: Establishes all new files with zero upstream file touches. Creates the containment structure before any existing file is modified. Safe to rebase at any point. Pre-commit hook and zone taxonomy documented here — if these are not in place before Phase 2, all subsequent work is at risk. Delivers: packages/branding/, ui/src/lib/nexus-labels.ts, ui/src/nexus/ directory, server/src/onboarding-assets/pm/ and engineer/ skeleton directories, [nexus] pre-commit hook, zone taxonomy document in .planning/. Addresses: D2 partial (template directories created), D5 partial (branding package scaffold) Avoids: Pitfall 8 (no-prefix commits), Pitfall 2 (Zone B contamination from lack of taxonomy)

Phase 2: Constants, Labels, and Home Directory

Rationale: Touches three upstream files with one-line changes each. These are the lowest-risk upstream file modifications: rarely-changed lines, isolated diffs, immediately verifiable. Completing this phase makes every downstream component able to import correct labels before any component is touched. Delivers: AGENT_ROLE_LABELS.ceo = "Project Manager" live, home dir default changed to .nexus with read-both-paths fallback, DISPLAY_ROLE_LABELS exported from branding package. Addresses: D3 (core vocabulary change), D4 partial (home dir pointer) Avoids: Pitfall 1 (dual-purpose stored values — keys unchanged), Pitfall 4 (config migration — fallback implemented here)

Phase 3: UI and CLI String Renames

Rationale: Surface-area is larger (multiple upstream files) but each change is string-only with // [nexus] markers. Individual commits per file keep each rebase conflict isolated and mechanically resolvable. The branding infrastructure from Phases 1–2 must exist before this phase to avoid scattering string definitions. Delivers: All "Company/CEO/Board" display strings replaced with "Workspace/Project Manager/Owner" across Companies.tsx, CompanyRail.tsx, CompanySettings.tsx, InstanceSidebar.tsx, cli/onboard.ts, startup-banner.ts. CLI binary renamed to nexus atomically with all instructional copy updated. Addresses: D3 (complete), D5 (complete), D6 partial (dialog strings updated) Avoids: Pitfall 6 (atomic CLI rename), Pitfall 7 (post-phase grep audit), Pitfall 10 (test assertions updated in same commits)

Phase 4: Onboarding Redesign

Rationale: Most complex change goes last. Vite alias approach means upstream OnboardingWizard.tsx is never touched and can evolve independently. PM and Engineer template content (written in Phase 1) is wired up here. Onboarding API shape mismatch (workspace name derived from directory basename) must be explicitly resolved. Delivers: ui/src/nexus/OnboardingWizard.tsx full replacement (root dir picker, auto-create PM + Engineer agents, one-step flow), Vite alias in vite.config.ts, ceo/ onboarding asset content replaced with PM framing, PM and Engineer template files populated, "Add Agent" dialog updated with template dropdown. Addresses: D1 (complete), D2 (complete), D4 (complete), D6 (complete) Avoids: Pitfall 3 (ceo/ directory name kept, only content replaced), Pitfall 9 (API shape documented and workspace name derived before implementation)

Phase Ordering Rationale

  • New files before upstream file modifications — zero conflict risk for the majority of work
  • Constants before components — components can import correct labels from day one
  • String renames before onboarding redesign — the vocabulary must be stable before the most complex component is written against it
  • Onboarding last — its Vite alias approach is the most architectural change; having it isolated keeps every earlier phase simple and independently rebaseable
  • Each phase produces a rebasing-clean state — can sync upstream between any two phases without compound conflicts

Research Flags

Phases with well-documented patterns (skip /gsd:research-phase):

  • Phase 1: Standard TypeScript monorepo package creation and git hook setup — no research needed
  • Phase 2: Single-line constant and config path changes — no research needed
  • Phase 3: Mechanical string replacement with documented taxonomy — no research needed

Phases likely benefiting from deeper research during planning:

  • Phase 4: The onboarding API shape mismatch (Pitfall 9) needs the POST /api/companies contract documented before writing the new wizard. A brief codebase read of server/src/routes/companies.ts and the API client should resolve this. Not complex — 30 minutes of reading, not a full research session.

Confidence Assessment

Area Confidence Notes
Stack HIGH Based on direct codebase inspection of live repo + official Git, Vite, Tailwind v4 documentation
Features HIGH (table stakes), MEDIUM (differentiators) Table stakes verified from codebase; differentiator prioritization informed by Paperclip product notes and UX research but not validated against actual users
Architecture HIGH Patterns derived from direct codebase inspection; Vite alias pattern verified against official docs and existing vite.config.ts in the repo
Pitfalls HIGH Primarily from direct audit of CONCERNS.md and codebase; supplemented by fork maintenance community research

Overall confidence: HIGH

Gaps to Address

  • OnboardingWizard API contract: The POST /api/companies required fields are not fully documented in research. Before Phase 4 implementation, read server/src/routes/companies.ts to determine exactly what fields are required and derive a rule for the workspace name field (likely basename(rootDir)).
  • Test suite audit scope: The pre-rename test audit (Pitfall 10) requires running the grep against the actual test files. The exact count of test files asserting on "CEO" / "company" display strings is not known — this should be done as the first step of Phase 3 execution, not planning.
  • localStorage key migration: Whether to keep "paperclip.selectedCompanyId" or migrate it is unresolved. Given it is internal and users never see it, keeping it unchanged is the lowest-risk path and should be the default decision unless there is a specific reason to change it.
  • Catppuccin Mocha theme scope boundary: The branding.css scaffold is included in Phase 1 but full theme is deferred. The exact CSS custom property overrides needed for even minimal brand differentiation (Nexus blue-purple vs Paperclip defaults) should be defined during Phase 3 execution.

Sources

Primary (HIGH confidence)

Secondary (MEDIUM confidence)

Tertiary (LOW confidence)

  • UX claims regarding cognitive load from vocabulary mismatch — reasonable inference, not validated against actual users

Research completed: 2026-03-30 Ready for roadmap: yes