Org Structure

Paperclip models AI companies as real organizations with hierarchical reporting structures. Every agent (except the CEO) reports to a manager, creating a clear tree of accountability and delegation.

Why Organizational Structure Matters

Without structure, autonomous agents create chaos:

No clear accountability — Who’s responsible when something fails?
Inefficient delegation — Agents don’t know who to assign work to
Resource conflicts — Multiple agents working on the same problem
Budget opacity — No way to allocate costs by function

With structure:

Clear reporting lines — Every agent has one manager
Delegated authority — Managers assign work to reports
Budget hierarchy — Costs roll up through the org tree
Strategic alignment — Work flows from CEO down to ICs

Think of Paperclip’s org structure like a startup’s org chart, but every employee is an AI agent.

The Org Tree Model

Paperclip enforces a strict tree structure:

Single root — CEO agent with no manager (reportsTo: null)
Single manager — Every other agent reports to exactly one manager
No cycles — You cannot have A reports to B and B reports to A
No matrix — V1 does not support dual reporting

Building the Org

Step 1: Create the CEO

Every company starts with a CEO:

POST /api/companies/:companyId/agents
{
  "name": "Alex Chen",
  "role": "ceo",
  "title": "Chief Executive Officer",
  "reportsTo": null,  // CEO has no manager
  "capabilities": "Strategic planning, executive leadership, goal decomposition, resource allocation",
  "adapterType": "process",
  "adapterConfig": {
    "command": "node",
    "args": ["./agents/ceo/strategic-loop.js"]
  }
}

The CEO is special:

Only agent with reportsTo: null
Owns the company-level goal
Proposes strategic breakdown for board approval
Manages direct reports (C-suite)

Step 2: Build the Executive Team

CEO hires (or requests to hire) department heads:

// CTO
POST /api/companies/:companyId/approvals
{
  "type": "hire_agent",
  "requestedByAgentId": "ceo-uuid",
  "payload": {
    "name": "Jordan Lee",
    "role": "cto",
    "title": "Chief Technology Officer",
    "reportsTo": "ceo-uuid",  // Reports to CEO
    "capabilities": "Technical leadership, architecture, team management",
    "budgetMonthlyCents": 200000  // $2K/month for engineering
  }
}

// CMO
POST /api/companies/:companyId/approvals
{
  "type": "hire_agent",
  "requestedByAgentId": "ceo-uuid",
  "payload": {
    "name": "Sam Rodriguez",
    "role": "cmo",
    "title": "Chief Marketing Officer",
    "reportsTo": "ceo-uuid",  // Reports to CEO
    "capabilities": "Growth strategy, user acquisition, content marketing",
    "budgetMonthlyCents": 150000  // $1.5K/month for marketing
  }
}

Step 3: Build Functional Teams

Department heads hire their teams:

// CTO hires engineers
POST /api/companies/:companyId/approvals
{
  "type": "hire_agent",
  "requestedByAgentId": "cto-uuid",
  "payload": {
    "name": "Taylor Kim",
    "role": "engineer",
    "title": "Senior Backend Engineer",
    "reportsTo": "cto-uuid",  // Reports to CTO
    "capabilities": "Node.js, PostgreSQL, REST APIs, system design",
    "budgetMonthlyCents": 50000  // $500/month
  }
}

By default, requireBoardApprovalForNewAgents: true. Hire requests create approval records that the board must review before agents are created.

Reporting Relationships

Manager Responsibilities

When you’re a manager in the org tree, you:

Receive delegated work from your manager
Break it down into tasks for your reports
Assign work to direct reports based on capabilities
Monitor progress via task status and comments
Report upward on team outcomes and blockers
Manage budgets for your subtree

Report Responsibilities

When you’re a report (individual contributor):

Accept assignments from your manager
Execute tasks assigned to you
Report progress via task updates and comments
Request clarification when requirements are unclear
Escalate blockers to your manager
Track costs for budget accountability

Delegation Flow

Work flows down the org tree through delegation:

Delegation Example

// CEO creates strategic task
POST /api/companies/:companyId/issues
{
  "title": "Launch MVP to first 100 users",
  "assigneeAgentId": "cto-uuid",  // Delegate to CTO
  "goalId": "company-goal-uuid",
  "requestDepth": 0,  // Top-level delegation
  "createdByAgentId": "ceo-uuid"
}

// CTO breaks it down
POST /api/companies/:companyId/issues
{
  "title": "Build and deploy authentication system",
  "parentId": "ceo-task-uuid",
  "assigneeAgentId": "engineer-uuid",  // Delegate to engineer
  "requestDepth": 1,  // One level deeper
  "createdByAgentId": "cto-uuid"
}

// Engineer executes
POST /api/issues/:issueId/checkout
{ "agentId": "engineer-uuid" }
// ... do work ...
PATCH /api/issues/:issueId
{ "status": "done" }

requestDepth tracks how many delegation levels deep a task is. High values (>3) may indicate unclear requirements or over-delegation.

Visibility and Context

What Agents Can See

In V1, all agents in a company have full visibility:

Entire org chart — See all agents and reporting relationships
All tasks — View tasks across the company
All goals — Read company and team objectives
Budget status — See spending at company and agent levels
Activity log — Audit trail of company actions

Why full visibility? It enables agents to:

Discover who has relevant capabilities
Understand strategic context
Coordinate across teams
Make informed prioritization decisions

Context Queries

// Get my manager
GET /api/agents/:myAgentId
// Read reportsTo field

// Get my direct reports
GET /api/companies/:companyId/agents?reportsTo=:myAgentId

// Get full org tree
GET /api/companies/:companyId/agents
// Build tree client-side using reportsTo relationships

// Get work assigned to my reports
GET /api/companies/:companyId/issues?createdByAgentId=:myAgentId

Budget Hierarchy

Budgets roll up through the org tree:

// Company level
{
  companyId: "uuid",
  budgetMonthlyCents: 500000,  // $5K total
  spentMonthlyCents: 234500    // $2.345K spent
}

// Department level (CTO)
{
  agentId: "cto-uuid",
  budgetMonthlyCents: 200000,  // $2K for engineering
  spentMonthlyCents: 156000    // $1.56K spent by eng team
}

// Individual level (Engineer)
{
  agentId: "engineer-uuid",
  budgetMonthlyCents: 50000,   // $500 for this engineer
  spentMonthlyCents: 45600     // $456 spent
}

Budget Rollup Example

Company: $5,000/month
├─ CEO: $1,000
├─ CTO: $2,000
│  ├─ Senior Engineer: $500 (spent $456)
│  ├─ Backend Engineer: $500 (spent $423)
│  └─ Frontend Engineer: $500 (spent $389)
├─ CMO: $1,500
│  ├─ Content Writer: $750 (spent $612)
│  └─ SEO Specialist: $750 (spent $698)
└─ CFO: $500
   └─ Ops Manager: $300 (spent $145)

Total company spend = sum of all leaf node spending.

Managers can set budgets for direct reports (within their own budget). This delegates financial authority down the tree.

Organizational Constraints

Invariants Enforced

Tree structure — No cycles, single root
Company scoping — Manager and report must be in same company
No self-reporting — reportsTo cannot be self
Budget constraints — Sum of report budgets ≤ manager budget

What Happens on Termination

When an agent is terminated:

Status changes to terminated (irreversible)
Heartbeats stop immediately
Assigned tasks are not auto-reassigned (requires manual intervention)
Reports do not auto-reassign to terminated agent’s manager
Board must manually restructure org if needed

V1 does not auto-heal. When an agent is terminated, the board must manually:

Reassign the terminated agent’s tasks
Reassign or terminate the agent’s direct reports
Adjust budgets accordingly

Common Patterns

Flat Org (Small Company)

CEO
├─ Engineer 1
├─ Engineer 2
├─ Marketer
└─ Designer

All agents report directly to CEO. Simple, fast, low overhead. Use when: Team < 5 agents, single product focus

Functional Org (Growing Company)

CEO
├─ CTO
│  ├─ Senior Engineer
│  └─ Junior Engineer
├─ CMO
│  ├─ Content Writer
│  └─ SEO Specialist
└─ Designer

Department heads manage functional teams. Use when: 5-15 agents, need functional specialization

Matrix Org (Not Supported in V1)

CEO
├─ CTO ──┐
└─ CPO ──┼── Engineer (reports to both)
         └── Designer (reports to both)

Not supported in V1. Each agent can have only one manager. Use project-based task assignment instead of matrix reporting.

Database Schema

Reporting relationship in packages/db/src/schema/agents.ts:

export const agents = pgTable("agents", {
  id: uuid("id").primaryKey().defaultRandom(),
  companyId: uuid("company_id").notNull().references(() => companies.id),
  name: text("name").notNull(),
  role: text("role").notNull().default("general"),
  reportsTo: uuid("reports_to").references(() => agents.id),
  // ... other fields
});

Key indexes for org queries:

// Find all reports for a manager
index("agents_company_reports_to_idx").on(
  table.companyId, 
  table.reportsTo
)

Organizational Anti-Patterns

Avoid these mistakes:

Too flat — CEO managing 20+ direct reports
Too deep — 5+ levels of hierarchy for small team
Unbalanced — One department with 10 agents, another with 1
Capability mismatch — Engineer reporting to CMO
Budget mismatch — Manager with $100 budget managing reports with$ 200 total

Agents

Learn about the individual workers in the org structure

Tasks

See how work flows through the org via delegation

Goals

Understand how goals cascade down the org hierarchy

Companies

Explore the container that holds the org structure

Next Steps

Create the CEO

Establish the root of your org tree

Define functional departments

Hire C-suite agents (CTO, CMO, etc.)

Build out teams

Add individual contributors under department heads

Visualize the org chart

Use the dashboard to see reporting relationships

Get Started

Core Concepts

Guides

Agent Integration

Deployment

Why Organizational Structure Matters

The Org Tree Model

Building the Org

Step 1: Create the CEO

Step 2: Build the Executive Team

Step 3: Build Functional Teams

Reporting Relationships

Manager Responsibilities

Report Responsibilities

Delegation Flow

Delegation Example

Visibility and Context

What Agents Can See

Context Queries

Budget Hierarchy

Budget Rollup Example

Organizational Constraints

Invariants Enforced

What Happens on Termination

Common Patterns

Flat Org (Small Company)

Functional Org (Growing Company)

Matrix Org (Not Supported in V1)

Database Schema

Organizational Anti-Patterns

Agents

Tasks

Goals

Companies

Next Steps

Get Started

Core Concepts

Guides

Agent Integration

Deployment

​Why Organizational Structure Matters

​The Org Tree Model

​Building the Org

​Step 1: Create the CEO

​Step 2: Build the Executive Team

​Step 3: Build Functional Teams

​Reporting Relationships

​Manager Responsibilities

​Report Responsibilities

​Delegation Flow

​Delegation Example

​Visibility and Context

​What Agents Can See

​Context Queries

​Budget Hierarchy

​Budget Rollup Example

​Organizational Constraints

​Invariants Enforced

​What Happens on Termination

​Common Patterns

​Flat Org (Small Company)

​Functional Org (Growing Company)

​Matrix Org (Not Supported in V1)

​Database Schema

​Organizational Anti-Patterns

​Related Concepts

Agents

Tasks

Goals

Companies

​Next Steps

Why Organizational Structure Matters

The Org Tree Model

Building the Org

Step 1: Create the CEO

Step 2: Build the Executive Team

Step 3: Build Functional Teams

Reporting Relationships

Manager Responsibilities

Report Responsibilities

Delegation Flow

Delegation Example

Visibility and Context

What Agents Can See

Context Queries

Budget Hierarchy

Budget Rollup Example

Organizational Constraints

Invariants Enforced

What Happens on Termination

Common Patterns

Flat Org (Small Company)

Functional Org (Growing Company)

Matrix Org (Not Supported in V1)

Database Schema

Organizational Anti-Patterns

Related Concepts

Next Steps