doc/PRODUCT.md
Paperclip is the control plane for autonomous AI companies. One instance of Paperclip can run multiple companies. A company is a first-order object.
A company has:
Every employee is an agent. When you create a company, you start by defining the CEO, then build out from there.
Each employee has:
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.
Paperclip supports several ways to run an agent's heartbeat:
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 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.
Company skills are shared operating capabilities, not privileged objects by default. Every authenticated agent in a company can create, import, install, edit, update, test, reset, and remove that company's skills unless the company has configured an explicit restriction.
The governing rule is: skill permissions are opt-in restrictions, not opt-in capabilities. Missing skill grants never create a denial in an otherwise unconfigured company, and ordinary skill work does not require board confirmation, a draft-only workflow, or an activation approval.
Core Paperclip owns the skill runtime, company-boundary enforcement, policy evaluation contract, API denials, validation, path containment, secret redaction, and activity logging. Those safety invariants cannot be disabled by policy. Open-by-default skill work never authorizes arbitrary host-path reads, unsafe executable content, or policy edits: local imports and scans must stay within Paperclip-known workspace or managed-skill roots, remote sources must resolve to validated immutable content, and platform safety denials must stay distinct from optional administrative restrictions. Paperclip EE may provide detailed administration for per-agent, per-role, per-action, per-source, and protected-skill rules, but EE is not required to use skills and is not an enforcement boundary. Without EE, companies remain open by default and any already-configured restrictions continue to be enforced by core.
An explicit restricted policy may deny selected operations or switch to a default-deny preset with explicit allow rules. Core exposes a stable versioned policy API so EE and other administrative clients configure and simulate the same evaluator used by skill mutation routes. Core Skill Studio only needs to perform normal skill work, explain an explicit denial, and point administrators to EE when its richer policy UI is available; it must not recreate a partial enterprise permission editor.
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.
Company is the unit of organization. Everything lives under a company. One Paperclip instance, many companies.
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."
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.
Control plane, not execution plane. Paperclip orchestrates. Agents run wherever they run and phone home.
There are two runtime modes Paperclip must support:
local_trusted (default): single-user local trusted deployment with no login frictionauthenticated: login-required mode that supports both private-network and public deployment exposure policiesCanonical mode design and command expectations live in doc/DEPLOYMENT-MODES.md.
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.
Do
Do not
Time-to-first-success under 5 minutes A fresh user should go from install to “my CEO completed a first task” in one sitting.
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.
Conversation stays attached to work objects “Chat with CEO” should still resolve to strategy threads, decisions, tasks, or approvals.
Progressive disclosure Top layer: human-readable summary. Middle layer: checklist/steps/artifacts. Bottom layer: raw logs/tool calls/transcript.
Output-first Work is not done until the user can see the result: file, document, preview link, screenshot, plan, or PR.
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.
Local-first, cloud-ready The mental model should not change between local solo use and shared/private or public/cloud deployment.
Safe autonomy Auto mode is allowed; hidden token burn is not.
Thin core, rich edges Put optional chat, knowledge, and special surfaces into plugins/extensions rather than bloating the control plane.