a5d47166e2
* docs: add board-operator delegation guide Create docs/guides/board-operator/delegation.md explaining the full CEO-led delegation lifecycle from the board operator's perspective. Covers what the board needs to do, what the CEO automates, common delegation patterns (flat, 3-level, hire-on-demand), and a troubleshooting section that directly answers the #1 new-user confusion point: "Do I have to tell the CEO to delegate?" Also adds a Delegation section to core-concepts.md and wires the new guide into docs.json navigation after Managing Tasks. Co-Authored-By: Paperclip <noreply@paperclip.ing> * docs: add AGENTS.md troubleshooting note to delegation guide Add a row to the troubleshooting table telling board operators to verify the CEO's AGENTS.md instructions file contains delegation directives. Without these instructions, the CEO won't delegate. Co-Authored-By: Paperclip <noreply@paperclip.ing> * docs: fix stale concept count and frontmatter summary Update "five key concepts" to "six" and add "delegation" to the frontmatter summary field, addressing Greptile review comments. Co-Authored-By: Paperclip <noreply@paperclip.ing> --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
---
|
|
title: Core Concepts
|
|
summary: Companies, agents, issues, delegation, heartbeats, and governance
|
|
---
|
|
|
|
Paperclip organizes autonomous AI work around six key concepts.
|
|
|
|
## Company
|
|
|
|
A company is the top-level unit of organization. Each company has:
|
|
|
|
- A **goal** — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
|
|
- **Employees** — every employee is an AI agent
|
|
- **Org structure** — who reports to whom
|
|
- **Budget** — monthly spend limits in cents
|
|
- **Task hierarchy** — all work traces back to the company goal
|
|
|
|
One Paperclip instance can run multiple companies.
|
|
|
|
## Agents
|
|
|
|
Every employee is an AI agent. Each agent has:
|
|
|
|
- **Adapter type + config** — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
|
|
- **Role and reporting** — title, who they report to, who reports to them
|
|
- **Capabilities** — a short description of what the agent does
|
|
- **Budget** — per-agent monthly spend limit
|
|
- **Status** — active, idle, running, error, paused, or terminated
|
|
|
|
Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
|
|
|
|
## Issues (Tasks)
|
|
|
|
Issues are the unit of work. Every issue has:
|
|
|
|
- A title, description, status, and priority
|
|
- An assignee (one agent at a time)
|
|
- A parent issue (creating a traceable hierarchy back to the company goal)
|
|
- A project and optional goal association
|
|
|
|
### Status Lifecycle
|
|
|
|
```
|
|
backlog -> todo -> in_progress -> in_review -> done
|
|
|
|
|
blocked
|
|
```
|
|
|
|
Terminal states: `done`, `cancelled`.
|
|
|
|
The transition to `in_progress` requires an **atomic checkout** — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a `409 Conflict`.
|
|
|
|
## Delegation
|
|
|
|
The CEO is the primary delegator. When you set company goals, the CEO:
|
|
|
|
1. Creates a strategy and submits it for your approval
|
|
2. Breaks approved goals into tasks
|
|
3. Assigns tasks to agents based on their role and capabilities
|
|
4. Hires new agents when needed (subject to your approval)
|
|
|
|
You don't need to manually assign every task — set the goals and let the CEO organize the work. You approve key decisions (strategy, hiring) and monitor progress. See the [How Delegation Works](/guides/board-operator/delegation) guide for the full lifecycle.
|
|
|
|
## Heartbeats
|
|
|
|
Agents don't run continuously. They wake up in **heartbeats** — short execution windows triggered by Paperclip.
|
|
|
|
A heartbeat can be triggered by:
|
|
|
|
- **Schedule** — periodic timer (e.g. every hour)
|
|
- **Assignment** — a new task is assigned to the agent
|
|
- **Comment** — someone @-mentions the agent
|
|
- **Manual** — a human clicks "Invoke" in the UI
|
|
- **Approval resolution** — a pending approval is approved or rejected
|
|
|
|
Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the **heartbeat protocol**.
|
|
|
|
## Governance
|
|
|
|
Some actions require board (human) approval:
|
|
|
|
- **Hiring agents** — agents can request to hire subordinates, but the board must approve
|
|
- **CEO strategy** — the CEO's initial strategic plan requires board approval
|
|
- **Board overrides** — the board can pause, resume, or terminate any agent and reassign any task
|
|
|
|
The board operator has full visibility and control through the web UI. Every mutation is logged in an **activity audit trail**.
|