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 <noreply@anthropic.com>

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.

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?