mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/.planning/research/FEATURES.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

13 KiB
Raw Blame History

Feature Landscape

Domain: Personal AI Agent Orchestration Platform (solo-developer fork of Paperclip) Researched: 2026-03-30 Confidence: HIGH for Paperclip base features (read from codebase); MEDIUM for ecosystem positioning (web research); LOW for subjective UX judgments

Context

This analysis is scoped to the Nexus fork of Paperclip. The upstream already ships a comprehensive engine — heartbeats, task lifecycle, multi-adapter support, cost budgets, approval gates, plugin system. The fork question is not "what to build" but "what to rename, what to surface, and what to hide." Features are evaluated against that lens.

Two distinct tracks:

  1. Engine features — what the orchestration runtime does (mostly inherited from upstream, not to be changed)
  2. Display-layer features — what the UI and CLI communicate to the human operator (primary fork scope)

Table Stakes

Features the fork must get right for Nexus to feel complete and usable. Missing or broken = product feels unfinished.

Feature Why Expected Complexity Notes
Dashboard with live agent status Users need to see what agents are doing at a glance Low Upstream has SSE-backed live updates; display rename only (Company → Workspace)
Real-time run logs / heartbeat transcript "Is my agent running or stuck?" is the first question every time Low Upstream streams stdout/stderr per heartbeat; UI already exists; display polish needed
Cost visibility per agent Without it users have no feedback loop on spend Low Upstream tracks cost_events; display rename + cleanup
Task (issue) list with status Core work item visibility Low Upstream has full issue model; display rename only
Agent status indicators (idle/running/paused) Know agent state without opening logs Low Upstream has agent status field; surface in sidebar/card
One-command startup nexus run → working dashboard Low CLI command exists as paperclipai run; display rename only
Human approval workflow Agents can request approval before acting; critical for trust Low Upstream has approvals table and routes; display rename only
Agent configuration page View and edit adapter type, model, instructions file Medium Upstream has config revisions and rollback; display cleanup needed
Sub-task / issue hierarchy Agents create sub-issues; user needs to see nesting Low Upstream has parentId and requestDepth; display only
Project grouping Issues are grouped under Projects; navigation must reflect this Low Upstream has projects entity; display rename only (no collision — Workspace > Project > Issue)
Scheduled task creation (routines) Recurring tasks without manual triggering Low Upstream has routines model with cron; display rename only
CLI help text that uses Nexus vocabulary Every --help output that says "Paperclip" or "company" breaks the mental model Medium All CLI display strings need [nexus] overrides

Assessment: Every table-stakes feature already exists in the upstream engine. The work is entirely display-layer: surface the right label, hide corporate metaphor, keep the behavior. Estimated risk: LOW — no functional code changes required.

Differentiators

Features that make Nexus feel personal and purpose-built for a solo developer, versus Paperclip's "zero-human company" framing.

D1: Zero-Question Onboarding

Value: Paperclip's onboarding asks for company name, mission, CEO name, adapter config, and then creates a task to "hire a founding engineer." None of this maps to a solo developer with a root directory of projects. Nexus asks for ONE thing (root directory), auto-creates PM + Engineer agents with sane templates, and drops the user in the dashboard.

Why it matters: Paperclip's own product notes flag "getting from install to first task in under 5 minutes" as a stated goal, not yet achieved consistently. This is the single highest-impact UX change.

Complexity: Medium (requires rewriting OnboardingWizard.tsx step sequence and onboard.ts CLI wizard; no schema changes)

Dependencies: Predefined agent templates (D2) must exist before onboarding can auto-create them.

D2: Predefined Agent Templates (PM + Engineer)

Value: Instead of asking "what should I name my CEO and what adapter should it use?", Nexus ships two templates that are immediately useful: a Project Manager agent wired to delegate and coordinate, and an Engineer agent wired to execute code tasks.

Why it matters: The upstream's default first task ("hire a founding engineer, write a hiring plan") is designed for a multi-agent org-building flow. Solo developers do not want to bootstrap an org — they want to point agents at work. Opinionated defaults remove the blank-canvas paralysis.

Complexity: Low (template content in AGENTS.md / HEARTBEAT.md / SOUL.md / TOOLS.md files; no schema changes; one new UI dropdown in "Add Agent" dialog)

Dependencies: None — these are static files bundled with the fork.

D3: Workspace-First Mental Model

Value: Replacing the Company/CEO metaphor with Workspace/Project Manager throughout every user-facing surface creates a consistent mental model. When every button, heading, and CLI response uses the same vocabulary, the user stops translating and starts working.

Why it matters: Every time a user sees "CEO" or "Company" in the Nexus UI, it costs cognitive load. Multiplied across hundreds of daily interactions, this friction accumulates. The rename is not cosmetic — it removes a persistent mismatch between the user's world model and the tool's communication.

Complexity: Medium (systematic string audit across ui/src/, cli/src/, agent template files; the work is large in surface area but each change is trivial)

Dependencies: None — display-only. Each component can be renamed independently.

D4: Human-Readable Agent Directories Under User Root

Value: Instead of ~/.paperclip/ opaque config, Nexus stores everything under the user-chosen root directory with human-readable names. An agent called "Engineer" lives at ~/RaglanWork/agents/engineer/. The user can ls their agent setup.

Why it matters: Solo developers inspect their file system. Opaque hidden directories make tooling feel like a black box. Transparent directory layout builds trust and makes debugging obvious.

Complexity: Medium (requires updating config resolution in CLI and server to respect ~/.nexus pointer file; no DB changes)

Dependencies: Zero-question onboarding (D1) — the root directory picker sets the base path.

D5: Nexus Branding Throughout

Value: Consistent logo, color, app name, tab title, CLI program name (nexus not paperclipai), and absence of any upstream branding.

Why it matters: Every occurrence of "Paperclip" in a tool you use daily is a reminder that you are using someone else's thing. Branding the fork removes that friction.

Complexity: Low (HTML <title>, favicon, logo asset swap, CLI binary name in package.json, help text strings)

Dependencies: None — purely presentational.

D6: "Add Agent" Dialog with Template Dropdown

Value: The current upstream flow says "hire" an agent. Nexus replaces this with "Add Agent" with a dropdown of predefined templates (PM, Engineer, custom). Users pick a template and get a pre-configured agent immediately.

Why it matters: The hiring metaphor forces users through a corporate onboarding flow. The template dropdown reduces the mental model to "pick what kind of agent you want."

Complexity: Low (UI-only change to the dialog component; templates are static config)

Dependencies: Predefined agent templates (D2) must be defined.

Anti-Features

Things to deliberately NOT change in v1. Each has a reason.

Anti-Feature Why Avoid What to Do Instead
Rename DB columns (company_id, companies table) Breaks upstream rebase permanently; any git rebase upstream/master creates hundreds of conflicts with zero benefit Accept the mismatch; translate at the display layer
Rename API routes (/api/companies) UI already translates; server staying upstream-compatible means zero merge conflicts on route changes Keep routes; update only the client-side labels
Rename TypeScript identifiers (companyService, boardAuthService) Mechanical but enormous merge conflict surface; thousands of import statements Leave unchanged; the identifier is not user-visible
Rename environment variables (PAPERCLIP_*) Would break every existing deployment config and upstream docs Keep env vars; update only the user-facing config documentation
Rename plugin API contracts (company.created events) Would break any existing plugins silently Leave event names unchanged; document the mismatch for plugin authors
Rename .paperclip.yaml export format Would break import compatibility with upstream instances Keep format; rename only the CLI command description, not the file format
Full Catppuccin Mocha theme High visual complexity for v1; risk of breaking responsive layout Treat as stretch goal; focus on vocabulary rename first
Multi-workspace support UI overhaul The upstream multi-company feature already works; it's just renamed Rename "Companies" → "Workspaces" in the switcher; don't rebuild the underlying logic
Telegram Channels integration Separate project scope Defer entirely
Recipe Registry plugin Separate project scope Defer entirely
MCP connector layer Upstream adapter system already handles this via the adapter registry and process/http adapters Do not add a new abstraction layer on top
Agent observability / tracing / OTEL Enterprise-grade monitoring is overkill for a single-developer Mac Mini deployment The upstream heartbeat logs + SSE updates are sufficient

Feature Dependencies

D2 (Agent Templates)
  → D1 (Zero-Question Onboarding)     [onboarding auto-creates templates; templates must exist first]
  → D6 (Add Agent Dialog w/ templates) [dropdown requires templates to be defined]

D1 (Zero-Question Onboarding)
  → D4 (Human-Readable Directories)   [root directory picker sets the base; directory layout flows from it]

D5 (Branding)                         [no dependencies; can ship independently]
D3 (Workspace Mental Model)           [no dependencies; can ship incrementally per surface]

Critical path: D2 → D1 → D4. Templates first, then onboarding wizard, then directory structure. D3, D5, D6 can ship in any order alongside or after.

MVP Recommendation

Prioritize in this order:

  1. D2 — Predefined agent templates (AGENTS.md, HEARTBEAT.md, SOUL.md, TOOLS.md for PM + Engineer)
  2. D1 — Zero-question onboarding (rewrite wizard to use root dir + auto-create from templates)
  3. D3 — Workspace mental model rename (systematic string pass across UI + CLI)
  4. D5 — Nexus branding (logo, title, CLI binary name)
  5. D6 — Add Agent dialog (template dropdown)
  6. D4 — Human-readable directories (.nexus pointer file + root-relative paths)

Defer to v2:

  • Full Catppuccin Mocha theme (stretch, high visual risk)
  • Telegram integration (separate project)
  • Recipe Registry (separate project)
  • Any plugin API renames (breaks plugins)

Confidence Assessment

Area Confidence Notes
Table stakes features HIGH Derived directly from codebase analysis; features exist and are verified
Differentiator prioritization MEDIUM Based on Paperclip's own stated onboarding goals (product docs) + ecosystem research
Anti-feature list HIGH Based on explicit PROJECT.md constraints and merge-conflict risk analysis
UX claims (cognitive load, blank-canvas friction) LOW Reasonable inference from UX research but not validated against actual users
Complexity estimates MEDIUM Based on reading the codebase; no actual implementation attempted

Sources