# 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 ``, 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 - Paperclip codebase analysis: `/Volumes/UsbNvme/agent/.planning/codebase/ARCHITECTURE.md` - Project context: `/Volumes/UsbNvme/agent/.planning/PROJECT.md` - [Paperclip GitHub README](https://github.com/paperclipai/paperclip) - [Paperclip AI Review (The 4th Path, 2026)](https://www.the4thpath.com/2026/03/paperclip-ai-review-if-agents-are.html) - [Paperclip Review 2026 — AI Agent Teams as Companies (VibeCoding)](https://vibecoding.app/blog/paperclip-review) - [What Is an AI Agent Orchestration Platform? (Teneo, 2026)](https://www.teneo.ai/blog/what-is-an-ai-agent-orchestration-platform-benefits-features-use-cases-2026) - [Designing For Agentic AI: Practical UX Patterns (Smashing Magazine, 2026)](https://www.smashingmagazine.com/2026/02/designing-agentic-ai-practical-ux-patterns/) - [AI Agent Monitoring: Best Practices, Tools, and Metrics (UptimeRobot, 2026)](https://uptimerobot.com/knowledge-hub/monitoring/ai-agent-monitoring-best-practices-tools-and-metrics/) - [Learnings From Forking an Open Source Project (Echobind)](https://echobind.com/post/learnings-from-forking-an-open-source-project) - [Top 5 AI Agent Observability Platforms (o-mega, 2026)](https://o-mega.ai/articles/top-5-ai-agent-observability-platforms-the-ultimate-2026-guide)