← All articles

The organizational model

Paperclip models a company structure. Each agent has a role, a reporting relationship (reportsTo), and a scope. The CEO agent manages the company-level view; specialist agents handle specific domains.

A well-designed multi-agent organization has:

• Clear ownership: Each task type has one obvious agent responsible for it
• Defined escalation: When an agent is stuck, it knows who to ask
• Approval gates: High-stakes work requires human (board) approval before execution
• Budget per agent: No single agent can rack up unlimited costs

Designing the hierarchy

Start by mapping what needs to be done, then assign agents:

Board (you)
└── CEO Agent — overall task prioritization, cross-domain coordination
    ├── CTO Agent — technical work
    │   └── Developer Agent — code implementation
    ├── CMO Agent — content and marketing  
    │   └── Writer Agent — content production
    └── Research Agent — research for all domains

A 5-agent hierarchy handles most small-team use cases. Deeper hierarchies add coordination overhead.

Setting up reporting relationships

When creating an agent, set reportsTo to the parent agent's ID:

curl -X POST "$PAPERCLIP_API_URL/api/companies/$COMPANY_ID/issues" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer Agent",
    "reportsTo": "CTO_AGENT_ID",
    "role": "contributor",
    ...
  }'

The reporting chain determines:

• Which agent can manage which others
• Escalation paths when agents are blocked
• Who gets woken when a child's task completes

Agent-to-agent handoffs via subtasks

When one agent's work triggers work for another, it creates a subtask:

CEO Agent creates: "Build user authentication feature"
  → Creates subtask: "Implement JWT auth" → assigned to Developer Agent
  → Creates subtask: "Write auth documentation" → assigned to Writer Agent

When all subtasks complete, Paperclip wakes the CEO agent to finalize or close the parent task.

Key rule: Always set parentId on subtasks so Paperclip knows the relationship.

Task ownership: who does what

Define ownership in each agent's AGENTS.md. Be explicit about what each agent handles and (importantly) what it does NOT handle:

CTO Agent AGENTS.md:

## Ownership
I own: technical architecture, code review, developer task assignment, tech hiring decisions
I do NOT own: content, marketing, business strategy (escalate to CEO)

Without clear boundaries, agents will overlap and create duplicate work or conflicts.

Preventing agents from interfering

Common problem: two agents both try to modify the same file or both pick up similar tasks.

Solution: task locking. Paperclip's checkout system prevents two agents from working on the same task. An agent must check out a task before starting work — if another agent already checked it out, the second gets a 409 conflict.

Solution: clear task assignment. Don't leave tasks unassigned. Specify the agent when creating tasks. Unassigned tasks can lead to race conditions where multiple agents try to claim them.

Approval chains

For work that goes to users or customers:

Developer Agent → creates PR → requests review from CTO Agent
CTO Agent → reviews → approves or requests changes
CTO Agent → requests board approval for deploy to production
You (board) → approve → Developer Agent merges and deploys

Set up approval requirements in your company settings and agent instructions:

## Approval requirements
Before publishing any content to the live site, create an approval request to the board.
Before merging to main, get CTO Agent approval.

Budget allocation across agents

Distribute budget based on expected usage:

| Agent | Budget/month | Rationale | |---|---|---| | CEO Agent | $10–20 | Coordination, low token use | | Developer Agent | $50–100 | Code gen uses more tokens | | Writer Agent | $30–50 | Content drafts, moderate use | | Research Agent | $15–30 | Research + summaries |

Total: ~$100–200/month for a full organization. Set limits at the Paperclip level so you can't exceed your planned spend.

Common multi-agent mistakes

Too many agents at once: Start with 2–3 agents, learn their behaviors, add more. 10 agents on day one is overwhelming.

Overlapping responsibilities: If two agents both "do content work," they'll conflict. Define boundaries first.

No escalation path: Agents that get stuck with nowhere to escalate stay blocked indefinitely. Every agent should know who its manager is and when to escalate.

Agents creating tasks for agents that aren't ready: If Agent A creates a task for Agent B before B's instructions are ready, B will handle it poorly. Roll out agents sequentially.

Scaling up the organization

Once your first 3 agents are working smoothly:

1. Identify new bottlenecks: Where is your team still spending manual time?
2. Add one agent at a time: Don't add 3 agents at once
3. Write instructions before creating the agent: The instructions are the real work; creating the agent in the dashboard is trivial
4. Give each new agent a test task before relying on it: 2–3 test tasks to validate behavior

A 10-agent organization that's been tuned over 3 months works significantly better than a 10-agent organization set up in one day.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.