From 7d1427aaec49cd3c74e81fa71ee129b42feb0e30 Mon Sep 17 00:00:00 2001 From: Forgotten Date: Mon, 16 Feb 2026 13:31:42 -0600 Subject: [PATCH] Add product documentation GOAL.md defines Paperclip as a control plane for AI agent companies. PRODUCT.md details core concepts: companies, agents with SOUL.md/HEARTBEAT.md, hierarchical task management, and agent execution modes. Co-Authored-By: Claude Opus 4.6 --- GOAL.md | 47 ++++++++++++++++++++++++++++ PRODUCT.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 GOAL.md create mode 100644 PRODUCT.md diff --git a/GOAL.md b/GOAL.md new file mode 100644 index 00000000..02776d72 --- /dev/null +++ b/GOAL.md @@ -0,0 +1,47 @@ +# Paperclip + +Build software to manage a zero-human company where all employees are AI agents. + +## The Problem + +Task management software doesn't go far enough. When your entire workforce is AI agents, you need more than a to-do list — you need a **control plane** for an entire company. + +## What This Is + +Paperclip is the command, communication, and control plane for a company of AI agents. It is the single place where you: + +- **Manage agents as employees** — hire, organize, and track who does what +- **Define org structure** — org charts that agents themselves operate within +- **Track work in real time** — see at any moment what every agent is working on +- **Control costs** — token salary budgets per agent, spend tracking, burn rate +- **Align to goals** — agents see how their work serves the bigger mission +- **Store company knowledge** — a shared brain for the organization + +## Architecture + +Two layers: + +### 1. Control Plane (this software) + +The central nervous system. Manages: + +- Agent registry and org chart +- Task assignment and status +- Budget and token spend tracking +- Company knowledge base +- Goal hierarchy (company → team → agent → task) +- Heartbeat monitoring — know when agents are alive, idle, or stuck + +### 2. Execution Services (adapters) + +Agents run externally and report into the control plane. An agent is just Python code that gets kicked off and does work. Adapters connect different execution environments: + +- **OpenClaw** — initial adapter target +- **Heartbeat loop** — simple custom Python that loops, checks in, does work +- **Others** — any runtime that can call an API + +The control plane doesn't run agents. It orchestrates them. Agents run wherever they run and phone home. + +## Core Principle + +You should be able to look at Paperclip and understand your entire company at a glance — who's doing what, how much it costs, and whether it's working. diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 00000000..0c6189a9 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,89 @@ +# 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: +- **SOUL.md** — who they are, their ultimate objective, their personality, their operating principles. This is the agent's identity and mission. +- **HEARTBEAT.md** — what they do on their main loop. Every time the agent "wakes up," this defines what they review, what they check, what actions they take. +- **Agent configuration** — how this specific agent runs (see Agent Execution below) +- **Role & reporting** — their title, who they report to, who reports to them + +Example: A CEO's SOUL.md says "achieve $1M MRR with an AI note-taking app in 3 months." Their HEARTBEAT.md says "every loop: review what your executives are doing, check company metrics, reprioritize if needed, assign new strategic initiatives." + +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 SOUL.md and HEARTBEAT.md. + +### Agent Execution + +There are two fundamental modes for running an agent's heartbeat: + +1. **Run a command** — Paperclip kicks off a process (shell command, Python script, etc.) and tracks it. The heartbeat is "execute this and monitor it." +2. **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 hooks work this way.) + +We provide sensible defaults — a default agent that shells out to Claude Code or Codex with your configuration, remembers session IDs, runs basic scripts. But you can plug in anything. + +### 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?" + +More detailed task structure TBD. + +## 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. **Soul + Heartbeat define an agent.** Every agent has an identity (SOUL.md) and a loop (HEARTBEAT.md). This is the minimum contract. + +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 + - Write their SOUL.md (objective, personality, operating style) + - Write their HEARTBEAT.md (the loop — review executives, check metrics, reprioritize) + - Configure agent execution (e.g., Claude Code session, OpenClaw bot, custom script) +4. Define the CEO's reports: CTO, CMO, CFO, etc. + - Each gets their own SOUL.md, HEARTBEAT.md, and agent config +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 + +## Open Questions + +- Agent configuration interface — what exactly is the schema? What are the levels of integration (basic script vs. fully integrated with cost tracking)? +- Task management detail — what fields does a task have? Assignment, status workflow, dependencies beyond parentage? +- Communication protocol — how do agents talk to each other? Through tasks only, or direct messaging? +- Revenue/expense tracking — how does this integrate? Manual entry, API connections, agent-reported?