162 lines
9.9 KiB
Markdown
162 lines
9.9 KiB
Markdown
# Nexus
|
|
|
|
## What This Is
|
|
|
|
Nexus is a personal fork of Paperclip (MIT, v2026.318.0) that reframes the "companies with CEOs" corporate metaphor as "workspaces with agents." It's a project orchestration tool for a solo developer (Mikkel) managing AI agents across personal and professional projects. The fork stays mergeable with upstream by limiting changes to the display layer (UI strings, CLI output, agent templates, documentation) while leaving DB schema, API routes, code identifiers, and token formats unchanged.
|
|
|
|
v1.3 added a full chat interface with streaming, brainstormer workflow, file system, search/branching, and PWA support. v1.4 made Hermes the default local provider with Ollama integration. v1.5 adds smart onboarding with hardware detection, tiered AI providers, and a Personal AI Assistant mode.
|
|
|
|
## Core Value
|
|
|
|
A fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer agents, and drops you in the dashboard — no company names, missions, or corporate language anywhere.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
- Existing Paperclip agent orchestration engine (heartbeats, task lifecycle, adapters)
|
|
- Plugin system with worker isolation and host/worker RPC
|
|
- Multi-adapter support (Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, Hermes)
|
|
- Issue/task management with sub-issues, priorities, assignments
|
|
- Project entity (groups issues, lead agent, git repo integration)
|
|
- Execution workspaces with git worktree isolation
|
|
- Cost tracking and budget enforcement
|
|
- Routine/cron scheduled task creation
|
|
- Real-time SSE updates to UI
|
|
- CLI tooling (onboard, run, doctor, configure, client commands)
|
|
- Company import/export portability
|
|
- Board authentication (local_trusted + authenticated modes)
|
|
- ✓ Chat Foundation (conversations, messages, rendering, theme) — v1.3
|
|
- ✓ Agent Streaming (SSE, agent identity, edit/retry/stop) — v1.3
|
|
- ✓ Brainstormer Flow (spec approval, task creation from chat) — v1.3
|
|
- ✓ Search, History & Branching (full-text search, bookmarks, branching, export) — v1.3
|
|
- ✓ File System (upload/preview/download, git versioning, voice input) — v1.3
|
|
- ✓ PWA & Performance (installable, offline, mobile responsive, push notifications) — v1.3
|
|
- ✓ Hermes adapter integration (spawn, heartbeat, session, skill sync, cost tracking) — v1.4
|
|
- ✓ Ollama detection, model listing, RAM/VRAM recommendations — v1.4
|
|
- ✓ Default provider logic (fallback to Hermes when no cloud provider) — v1.4
|
|
- ✓ Agent templates working with Hermes runtime — v1.4
|
|
- ✓ Dashboard Hermes-specific info (model, VRAM, native skills) — v1.4
|
|
|
|
### Active
|
|
|
|
- [ ] Mode selection: Personal AI Assistant / Project Builder / Both
|
|
- [ ] Hardware detection with pre-built model database (GPU, Apple Silicon, CPU-only)
|
|
- [ ] Local AI setup via Ollama with RAM-aware model recommendations
|
|
- [ ] Voice features (Whisper + Piper) working on CPU-only hardware
|
|
- [ ] Zero-config cloud via Puter.js (no API keys, no sign-up)
|
|
- [ ] OAuth cloud tier (Google Gemini, OpenAI free tiers)
|
|
- [ ] Subscription/API key auto-detection (Hermes, Claude Code, OpenClaw)
|
|
- [ ] Personal AI Assistant with persistent memory, MCP, voice
|
|
- [ ] Project handoff: assistant conversation → PM with context transfer
|
|
- [ ] Summary screen → straight into chat
|
|
- [ ] `npx buildthis` CLI entry point
|
|
- [ ] Every onboarding step skippable
|
|
|
|
### Out of Scope
|
|
|
|
- DB schema renames (companies table, company_id columns) — upstream sync priority
|
|
- API route path changes (/api/companies stays) — upstream sync priority
|
|
- TypeScript identifier renames (companyService, boardAuthService etc.) — upstream sync priority
|
|
- Package name renames (@paperclipai/* stays) — upstream sync priority
|
|
- Environment variable renames (PAPERCLIP_* stays) — upstream sync priority
|
|
- Token prefix changes (pcp_board_* stays) — would invalidate issued tokens
|
|
- Plugin API contract changes (company.created events, companies.read capability) — breaks plugins
|
|
- .paperclip.yaml export format rename — breaks upstream import compatibility
|
|
- Recipe Registry plugin — separate project
|
|
- Catppuccin Mocha full theme — stretch goal, not v1
|
|
- Telegram Channels integration — future
|
|
- NPM reverse proxy — future
|
|
- Danish business integrations — future
|
|
- Multi-workspace support — works via existing multi-company feature, just renamed
|
|
|
|
## Context
|
|
|
|
**Upstream:** [paperclipai/paperclip](https://github.com/paperclipai/paperclip) — MIT licensed
|
|
**Fork repo:** /Volumes/UsbNvme/repos/nexus/ (origin: git.georgsen.dk/mikkel/nexus)
|
|
**Working directory:** /Volumes/UsbNvme/agent/
|
|
|
|
**Codebase:** TypeScript monorepo (pnpm workspaces). Server (Express), UI (React/Vite), CLI (Commander.js), packages (db/shared/adapter-utils/adapters), plugins (SDK + examples). ~1054 TS/TSX files.
|
|
|
|
**v1.3 additions:** Full chat system (ChatPanel, ChatMessage, ChatInput, ChatConversationList), agent streaming (SSE, useStreamingChat), brainstormer workflow (spec cards, handoff, status updates), file system (upload, preview, git versioning, voice input), PWA (service worker, offline queue, install prompt, push notifications, mobile responsive layout).
|
|
|
|
**Key naming collision resolved:** Paperclip already has a `Project` entity (groups issues, has lead agent, git repo). Original PRD renamed Company→Project but that collides. Decision: Company→Workspace in display layer. Existing Project entity stays unchanged.
|
|
|
|
**Rename strategy:** Display-only. All user-facing surfaces (UI strings, CLI output, agent template content, error messages, documentation) get renamed. All code-level identifiers, DB schema, API routes, env vars, token prefixes stay as upstream for merge compatibility.
|
|
|
|
**Fork maintenance:** [nexus] commit prefix for all Nexus changes. Periodic `git rebase upstream/master` to stay current. Display-only changes minimize conflict surface.
|
|
|
|
## Constraints
|
|
|
|
- **Upstream sync**: All changes must be display-layer only to allow `git rebase upstream/master` with minimal conflicts
|
|
- **Deploy target**: Mac Mini M4 only, local_trusted mode, single user
|
|
- **No data migration**: No changes to DB tables, columns, stored enum values, or migration files
|
|
- **Forgejo**: Push to git.georgsen.dk/mikkel/nexus (SSH port 2222)
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| Company → Workspace (not Project) | Paperclip already has a Project entity; naming collision | -- Pending |
|
|
| Display-only renames | Upstream sync priority; minimize merge conflicts | -- Pending |
|
|
| Keep all @paperclipai/* package names | Thousands of import statements; mechanical but huge merge conflict surface | -- Pending |
|
|
| Keep API routes (/api/companies) | UI translates on client side; server stays upstream-compatible | -- Pending |
|
|
| Keep DB schema unchanged | No migrations, no data migration, clean upstream rebase | -- Pending |
|
|
| ChatPanel as hub component | Central orchestrator for all chat features (streaming, files, offline, mobile) | ✓ Good |
|
|
| Cache-first SW strategy | Faster cached loads; API calls stay network-only | ✓ Good |
|
|
| IndexedDB offline queue (not SW) | Simpler than SW↔main message passing; idb library handles it | ✓ Good |
|
|
| React.lazy for all pages | 37 pages lazy-loaded; main bundle stays manageable | ✓ Good |
|
|
| MobileChatView as separate component | Full-screen mobile experience; responsive breakpoint at 768px | ✓ Good |
|
|
|
|
## Evolution
|
|
|
|
This document evolves at phase transitions and milestone boundaries.
|
|
|
|
**After each phase transition** (via `/gsd:transition`):
|
|
1. Requirements invalidated? → Move to Out of Scope with reason
|
|
2. Requirements validated? → Move to Validated with phase reference
|
|
3. New requirements emerged? → Add to Active
|
|
4. Decisions to log? → Add to Key Decisions
|
|
5. "What This Is" still accurate? → Update if drifted
|
|
|
|
**After each milestone** (via `/gsd:complete-milestone`):
|
|
1. Full review of all sections
|
|
2. Core Value check — still the right priority?
|
|
3. Audit Out of Scope — reasons still valid?
|
|
4. Update Context with current state
|
|
5. **Post-milestone upstream rebase** (see below)
|
|
|
|
## Post-Milestone Upstream Rebase (Nexus-Specific)
|
|
|
|
After every `/gsd:complete-milestone`, perform an upstream rebase before starting the next milestone. This keeps conflicts small and manageable — upstream Paperclip is active (120+ commits since fork).
|
|
|
|
**Steps:**
|
|
1. `git fetch upstream master` — fetch latest upstream
|
|
2. `git rebase upstream/master` — rebase nexus/main onto upstream
|
|
3. Resolve conflicts: merge upstream content into Nexus vocabulary (don't just delete upstream additions)
|
|
4. `pnpm dev` — verify build still works after rebase
|
|
5. `git push origin nexus/main --force-with-lease` — push to Forgejo (git.georgsen.dk)
|
|
6. Log rebase result in STATE.md: commits behind before, conflicts resolved count, build status
|
|
|
|
**Why:** Waiting too long means compound conflicts. Each milestone boundary is a natural sync point — code is tested, tagged, and stable.
|
|
|
|
**Autonomous mode:** The autonomous workflow MUST check for this section and run the rebase after `complete-milestone` returns, before starting the next milestone.
|
|
|
|
## Current Milestone: v1.5 Smart Onboarding + Personal AI Assistant
|
|
|
|
**Goal:** The definitive onboarding experience — hardware detection, tiered provider setup (local/free cloud/paid), and a Personal AI Assistant mode that coexists with the Project Builder.
|
|
|
|
**Target features:**
|
|
- Mode selection (Personal AI Assistant / Project Builder / Both)
|
|
- Hardware detection with pre-built model database (GPU, Apple Silicon, CPU-only)
|
|
- Local AI setup via Ollama with RAM-aware model recommendations + voice (Whisper + Piper)
|
|
- Zero-config cloud via Puter.js (500+ models, no API keys)
|
|
- OAuth cloud tier (Google Gemini, OpenAI free tiers)
|
|
- Subscription/API key auto-detection (Hermes, Claude Code, OpenClaw)
|
|
- Personal AI Assistant with persistent memory, MCP, voice, project handoff
|
|
- Summary screen → straight into chat
|
|
- `npx buildthis` CLI entry point
|
|
- Every step skippable, local-first framed as privacy premium
|
|
|
|
---
|
|
*Last updated: 2026-04-02 after v1.5 milestone started*
|