paperclip-orchestrator

name: paperclip-orchestrator description: PaperClip Orchestrator v2.0 — AI agent orchestration platform with 6 native sub-agents, automated hooks, heartbeat scheduling, task queues, and budget governance. Use when the user wants to orchestrate AI agents as a structured team, set up recurring agent check-ins, manage multi-agent projects, or create agent workflows. Triggers on /paperclip, "agent company", "orchestrate agents", "agent team".

PaperClip Orchestrator v2.0

Orchestrate multiple AI agents as a structured "company" — define org charts, assign roles, schedule heartbeats, manage task queues, enforce budgets, and govern autonomous workflows.

All state stored as JSON files under .paperclip/. No database required.

Full documentation: See README.md for quickstart guide, complete walkthrough, and FAQ.

v2.0 New: Native Sub-Agents & Hooks

PaperClip v2.0 ships with 6 native Claude Code sub-agents and 3 automation hooks. /agents to discover, hooks run automatically.

How it works:

1. User creates a task → auto-dispatched to matching agent role
2. Heartbeat fires → Claude invokes the native sub-agent (e.g., paperclip-architect) with independent context
3. Sub-agent reads its state from .paperclip/, executes the task, updates status
4. Hooks auto-append audit logs and update heartbeat timestamps — no manual bookkeeping

Two Operating Modes

Mode A: Dialogue (primary, no dependencies)

All operations happen in Claude Code conversation. Use natural language or slash commands:

Mode B: Terminal CLI

# Quick init
./bin/paperclip-init my-project --budget 500000

# Budget report
/paperclip-status --company-dir ./my-project

# Fetch design brand
（design-fetcher agent 自动获取）

No pip install required. Zero Python dependencies (PyYAML removed in v2.1).

Command Mapping

Natural language triggers:

• "启动心跳" → start heartbeats
• "开始" / "继续" → invoke paperclip sub-agent with pending tasks
• "测试" → invoke paperclip-tester
• "查看状态" → show dashboard
• /agents → discover all 6 paperclip sub-agents

Six Native Sub-Agents

Sub-agents are defined in agents/*.md. Each has independent context, model selection, and tool permissions. The Developer cannot create Cron jobs; the Architect uses opus for deeper reasoning.

Three Automation Hooks

Hooks are defined in hooks/hooks.json. They eliminate manual bookkeeping — no more manually typing audit entries or updating timestamps after every task.

Core Concepts

Runtime State Structure

my-project/
├── company.json           # Company config (JSON, user-editable)
└── .paperclip/            # Runtime state (auto-managed, no database)
    ├── company.json       # Company info + schema_version + heartbeat IDs
    ├── budget.json        # Budget tracking
    ├── audits.jsonl       # Append-only audit log (auto-managed by hooks)
    ├── agents/            # One JSON file per agent (no write conflicts)
    │   ├── architect.json
    │   ├── developer.json
    │   ├── reviewer.json
    │   ├── tester.json
    │   └── operator.json
    ├── tasks/             # One JSON file per task
    │   ├── task_001.json
    │   └── task_002.json
    └── design/            # DESIGN.md cache (optional, fetched by design-fetcher agent)

Plugin Structure (v2.0)

paperclip-orchestrator/
├── .claude-plugin/plugin.json   # v2.0.0 — registers skills, agents, hooks
├── SKILL.md                     # This file
├── README.md                    # Full documentation
├── agents/                      # 🆕 6 native sub-agents
│   ├── architect.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── operator.md
│   └── design-fetcher.md
├── hooks/                       # 🆕 Automation hooks
│   └── hooks.json
├── assets/company_template/     # Templates for company init
├── scripts/                     # Python CLI helpers
└── references/                  # Detailed reference docs

Workflow

1. Initialize a Company

./bin/paperclip-init my-project --budget 500000

Creates company.json and .paperclip/ with file-based state. See references/company-structure.md for full configuration reference.

2. Define Agent Roles

Agent roles defined in each agents/*.md file under the paperclip: frontmatter. Six default roles: architect (opus), developer, reviewer, tester, operator (sonnet), design-fetcher (haiku). Each sub-agent carries its own capabilities, budget share, and role definition.

The legacy agents.yaml is no longer generated for new companies, but existing companies with the file continue to work.

3. Schedule Heartbeats

"启动心跳"（在对话中对 Claude 说）

Registers CronCreate jobs. At each heartbeat, Claude invokes the corresponding paperclip-* sub-agent.

Protocol: CronCreate fires → Claude invokes sub-agent → Sub-agent reads state → Executes → Reports → Hook updates timestamps See references/heartbeat-system.md for scheduling patterns.

4. Manage Tasks

Lifecycle: todo → in_progress → in_review → done

"创建任务 'Implement JWT login' --type feature"（在对话中对 Claude 说）

See references/task-lifecycle.md for complete lifecycle.

5. Track Budget

/paperclip-status --company-dir ./my-project --format summary

Enforces per-task caps, daily limits, auto-throttling at 80%. See references/budget-governance.md for governance rules.

6. Multi-Agent Workflows

With native sub-agents in v2.0, use Workflow.pipeline or Workflow.parallel for concurrent agent execution:

• Architect designs → Developer implements → Reviewer verifies (pipeline)
• Developer + Tester run in parallel on independent tasks See references/workflow-patterns.md for detailed patterns.

Pro Mode (4-Layer Integration)

PaperClip Pro integrates four skill layers for production-grade agent teams:

Quick Setup (Pro)

# Init with a design brand — v2.2: design-fetcher agent auto-fetches DESIGN.md
./bin/paperclip-init my-app --budget 500000
（design-fetcher agent 自动获取）

# Browse and select a brand
（design-fetcher agent 自动获取）
（design-fetcher agent 自动获取）

Role → Skill Mapping

See references/skill-matrix.md for the complete cross-reference.