paperclip/doc/PRODUCT.md

Paperclip — Product Definition

What It Is

Paperclip is the control plane for autonomous AI companies. One instance of Paperclip can run multiple companies. A company is a first-order object.

Core Concepts

Company

A company has:

• A goal — the reason it exists ("Create the #1 AI note-taking app that does $1M MRR within 3 months")
• Employees — every employee is an AI agent
• Org structure — who reports to whom
• Revenue & expenses — tracked at the company level
• Task hierarchy — all work traces back to the company goal

Employees & Agents

Every employee is an agent. When you create a company, you start by defining the CEO, then build out from there.

Each employee has:

• Adapter type + config — how this agent runs and what defines its identity/behavior. This is adapter-specific (e.g., an OpenClaw agent might use SOUL.md and HEARTBEAT.md files; a Claude Code agent might use CLAUDE.md; a bare script might use CLI args). Paperclip doesn't prescribe the format — the adapter does.
• Role & reporting — their title, who they report to, who reports to them
• Capabilities description — a short paragraph on what this agent does and when they're relevant (helps other agents discover who can help with what)

Example: A CEO agent's adapter config tells it to "review what your executives are doing, check company metrics, reprioritize if needed, assign new strategic initiatives" on each heartbeat. An engineer's config tells it to "check assigned tasks, pick the highest priority, and work it."

Then you define who reports to the CEO: a CTO managing programmers, a CMO managing the marketing team, and so on. Every agent in the tree gets their own adapter configuration.

Agent Execution

Paperclip supports several ways to run an agent's heartbeat:

1. Local CLI/session adapters — Paperclip starts or resumes local coding-tool sessions such as Claude Code, Codex, Gemini, OpenCode, Pi, and Cursor, then tracks the run.
2. Run a command — Paperclip kicks off a process (shell command, Python script, etc.) and tracks it. The heartbeat is "execute this and monitor it."
3. Fire and forget a request — Paperclip sends a webhook/API call to an externally running agent. The heartbeat is "notify this agent to wake up." OpenClaw-style hooks work this way.
4. External adapter plugins — Paperclip loads adapter packages through the plugin/adapter flow so self-hosted installs can add runtimes without hardcoding them in core.

Agent runs can use project and execution workspaces, managed runtime services such as preview/dev servers, adapter-specific session state, and HTTP/webhook-style execution. We provide sensible defaults, but the adapter is still the boundary: if a runtime can be invoked, observed, and authorized, Paperclip can coordinate it.

Task Management

Task management is hierarchical. At any moment, every piece of work must trace back to the company's top-level goal through a chain of parent tasks:

I am researching the Facebook ads Granola uses (current task)
  because → I need to create Facebook ads for our software (parent)
    because → I need to grow new signups by 100 users (parent)
      because → I need to get revenue to $2,000 this week (parent)
        because → ...
          because → We're building the #1 AI note-taking app to $1M MRR in 3 months

Tasks have parentage. Every task exists in service of a parent task, all the way up to the company goal. This is what keeps autonomous agents aligned — they can always answer "why am I doing this?"

The current issue model includes stable issue identifiers, parent/sub-issues, blockers, a single assignee, comments, issue documents, attachments and work products, and review/approval handoffs. That structure keeps work inspectable by both the board and agents while still allowing agents to decompose work into smaller tasks.

Principles

1. Unopinionated about how you run your agents. Your agents could be OpenClaw bots, Python scripts, Node scripts, Claude Code sessions, Codex instances — we don't care. Paperclip defines the control plane for communication and provides utility infrastructure for heartbeats. It does not mandate an agent runtime.

2. Company is the unit of organization. Everything lives under a company. One Paperclip instance, many companies.

3. Adapter config defines the agent. Every agent has an adapter type and configuration that controls its identity and behavior. The minimum contract is just "be callable."

4. All work traces to the goal. Hierarchical task management means nothing exists in isolation. If you can't explain why a task matters to the company goal, it shouldn't exist.

5. Control plane, not execution plane. Paperclip orchestrates. Agents run wherever they run and phone home.

User Flow (Dream Scenario)

1. Open Paperclip, create a new company
2. Define the company's goal: "Create the #1 AI note-taking app, $1M MRR in 3 months"
3. Create the CEO
   • Choose an adapter (e.g., process adapter for Claude Code, HTTP adapter for OpenClaw)
   • Configure the adapter (agent identity, loop behavior, execution settings)
   • CEO proposes strategic breakdown → board approves
4. Define the CEO's reports: CTO, CMO, CFO, etc.
   • Each gets their own adapter config and role definition
5. Define their reports: engineers under CTO, marketers under CMO, etc.
6. Set budgets, define initial strategic tasks
7. Hit go — agents start their heartbeats and the company runs

Guidelines

There are two runtime modes Paperclip must support:

• local_trusted (default): single-user local trusted deployment with no login friction
• authenticated: login-required mode that supports both private-network and public deployment exposure policies

Canonical mode design and command expectations live in doc/DEPLOYMENT-MODES.md.

Further Detail

See SPEC.md for the full technical specification and TASKS.md for the task management data model.

---

Paperclip’s core identity is a control plane for autonomous AI companies, centered on companies, org charts, goals, issues/comments, heartbeats, budgets, approvals, and board governance. The public docs are also explicit about the current boundaries: tasks/comments are the built-in communication model, Paperclip is not a chatbot, and it is not a code review tool. The roadmap already points toward easier onboarding, cloud agents, easier agent configuration, plugins, better docs, and ClipMart/ClipHub-style reusable companies/templates.

What Paperclip should do vs. not do

Do

• Stay board-level and company-level. Users should manage goals, orgs, budgets, approvals, and outputs.
• Make the first five minutes feel magical: install, answer a few questions, see a CEO do something real.
• Keep work anchored to issues/comments/projects/goals, even if the surface feels conversational.
• Treat agency / internal team / startup as the same underlying abstraction with different templates and labels.
• Make outputs first-class: files, docs, reports, previews, links, screenshots.
• Provide hooks into engineering workflows: worktrees, preview servers, PR links, external review tools.
• Use plugins for edge cases like rich chat, knowledge bases, doc editors, custom tracing.

Do not

• Do not make the core product a general chat app. The current product definition is explicitly task/comment-centric and “not a chatbot,” and that boundary is valuable.
• Do not build a complete Jira/GitHub replacement. The repo/docs already position Paperclip as organization orchestration, not focused on pull-request review.
• Do not build enterprise-grade RBAC first. Paperclip now has authenticated mode, company memberships, instance roles, and permission grants, but fine-grained enterprise governance should remain secondary to the core company control plane.
• Do not interpret agent-level privacy flags as a project/issue privacy feature in V1; work visibility stays company-scoped.
• Do not lead with raw bash logs and transcripts. Default view should be human-readable intent/progress, with raw detail beneath.
• Do not force users to understand provider/API-key plumbing unless absolutely necessary. There are active onboarding/auth issues already; friction here is clearly real.

Specific design goals

1. Time-to-first-success under 5 minutes A fresh user should go from install to “my CEO completed a first task” in one sitting.

2. Board-level abstraction always wins The default UI should answer: what is the company doing, who is doing it, why does it matter, what did it cost, and what needs my approval.

3. Conversation stays attached to work objects “Chat with CEO” should still resolve to strategy threads, decisions, tasks, or approvals.

4. Progressive disclosure Top layer: human-readable summary. Middle layer: checklist/steps/artifacts. Bottom layer: raw logs/tool calls/transcript.

5. Output-first Work is not done until the user can see the result: file, document, preview link, screenshot, plan, or PR.

6. Execution visibility without log worship Active runs, recovery issues, productivity review states, blockers, and work products should be first-class surfaces. Raw transcripts are available when needed, but they are not the primary product surface.

7. Local-first, cloud-ready The mental model should not change between local solo use and shared/private or public/cloud deployment.

8. Safe autonomy Auto mode is allowed; hidden token burn is not.

9. Thin core, rich edges Put optional chat, knowledge, and special surfaces into plugins/extensions rather than bloating the control plane.