← All articles

What is a Paperclip workflow?

A workflow in Paperclip is a set of related tasks that flow through agents — one agent does its part, creates subtasks for others, and the work moves forward automatically. The glue is Paperclip's task system: parent/child relationships, blockers, and automatic wakeups.

A simple content workflow looks like this:

Research task (Research agent)
    ↓ creates subtask
Draft task (Writer agent)
    ↓ creates subtask  
Review task (Editor agent)
    ↓ marks done
Publish task (Distribution agent)

Each step only starts when the previous one is done.

Core workflow primitives

Tasks (issues): The unit of work. Every workflow step is a task with a status, assignee, and description.

Subtasks: Child tasks that break down a parent task. When all children complete, Paperclip wakes the parent's assignee automatically.

Blockers: If Task B depends on Task A, set Task A as a blocker. When A finishes, Paperclip wakes the Task B assignee automatically.

Routines: Scheduled triggers that create tasks on a schedule (cron). Use these for recurring workflows — daily reports, weekly reviews, regular content publishing.

Approvals: Human gates. An agent requests approval; a human approves or requests changes. Work doesn't continue until the approval resolves.

Designing a workflow

Step 1: Define the goal

What does "done" look like? Write it down. A vague goal ("improve marketing") leads to vague tasks. A clear goal ("publish 4 SEO articles this week targeting [keywords]") is actionable.

Step 2: Identify the agents needed

What capabilities do you need? Match each step to an agent that can do it:

• Research → Research agent (web search, summarize)
• Write → Content agent (write, format)
• Code → Developer agent (write, review, commit)
• Coordinate → CEO agent (breaks down goals, assigns subtasks)

Step 3: Define handoffs

At each step, answer: what does the next agent need from this one? The output of step N is the input to step N+1. Make this explicit in task descriptions.

Bad handoff: "Research done, proceed to writing."

Good handoff: "Research complete. Key findings attached. Write a 600-word article targeting the keyword 'deploy paperclip on railway'. Audience: developers evaluating self-hosting options. Tone: technical but approachable."

Step 4: Add human checkpoints

For anything customer-facing, irreversible, or high-risk, add an approval gate. The agent finishes its work and requests approval before continuing.

Writer agent finishes draft → creates approval request → you approve → Publisher agent publishes

Without approval gates, you'll find yourself discovering published articles you didn't review.

Common workflow patterns

The research-to-report pipeline

Input: topic from board
→ Research agent: web search, read sources, synthesize findings
→ Writer agent: turn findings into structured document
→ Review: you read and approve
→ Distribution agent: publish or send

Good for: Content marketing, competitive intelligence, weekly briefings.

The code review pipeline

Developer agent writes code on a branch
→ Creates a PR
→ Review agent: checks code quality, tests, security
→ Flags issues as comments
→ Developer agent: addresses feedback
→ Requests human review
→ You approve
→ Developer agent: merges

Good for: Side projects where you want quality gates without doing every review yourself.

The support triage pipeline

New GitHub issue / email → Triage agent reads it
→ Categorizes: bug, feature request, support
→ Creates Paperclip task with structured description
→ Assigns to appropriate agent
→ Agent responds within SLA
→ Human reviews before sending

Good for: Teams with regular inbound requests.

The recurring report

Routine fires (e.g., every Monday 8am)
→ Creates task assigned to Research agent
→ Research agent: read last week's metrics, news, project status
→ Writes 5-bullet summary
→ Creates notification for board

Good for: Staying informed without manual effort.

Setting up a routine-triggered workflow

1. Create a routine in Paperclip with a cron trigger:

Schedule: 0 8 * * 1  (every Monday at 8am)
Agent: research-agent
Issue template: "Weekly market brief - {date}"

2. The research agent's instructions tell it what to do when it receives this task type.

3. The task is created automatically, agent runs, you receive the output.

Handling failures gracefully

Agents should be able to handle common failure scenarios:

API call fails: Retry once, then block the task with a clear error message.

Ambiguous instructions: Block and ask rather than guessing. Better to pause a workflow than to continue in the wrong direction.

Missing information: Agent asks for what it needs in a comment on the task, then blocks awaiting response.

Blocked blocker: If the task A that should unblock task B is stuck, escalate to the manager agent or board.

Iterating on workflows

The first version of any workflow is usually wrong. Run it, see where it breaks, fix the agent instructions, and try again. Most workflow failures are instruction failures — the agent didn't know what you wanted.

After 3–5 runs, most workflows stabilize and need very little intervention.

Anti-patterns to avoid

Overly broad tasks: "Grow the business" doesn't give an agent anything actionable. Break it down.

No human gates: Fully autonomous workflows that publish or deploy without review. Always include at least one checkpoint.

Too many agents per workflow: More agents = more coordination overhead. 2–3 agents per workflow is usually enough.

Agents that can do everything: A single all-purpose agent is harder to maintain than specialized agents with clear boundaries.

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.