@yesterday-ai/paperclipper

v0.3.5

Published

an hour ago

Bootstrap a Paperclip company workspace from modular templates. Company as code.

0High
0Medium
0Low

lx0

paperclip ai-agents company-as-code bootstrap templates cli

Clipper is a CLI and template system for Paperclip — the control plane for AI-agent companies. It assembles ready-to-run company workspaces by combining a base org (CEO + Engineer) with composable modules and optional specialist roles.

Gracefully optimistic: capabilities extend, they don't require. The system works with just two roles and gets better as you add more. Adding a Product Owner shifts backlog management away from the CEO automatically. Adding a UX Researcher makes them the primary market analyst. No config changes needed.

Quick Start

npx @yesterday-ai/paperclipper

That's it. The interactive wizard handles the rest. Add --api to auto-provision in your local Paperclip instance.

Install

npx @yesterday-ai/paperclipper           # run directly (no install)
npm i -g @yesterday-ai/paperclipper      # or install globally → clipper

Requires Node.js 20+.

Usage

The interactive wizard walks through these steps:

$ clipper --api

  ╭──────────────╮
  │   Clipper    │
  ╰──────────────╯

  Company name: Acme Corp
  Company goal: Build the best widgets in the world
  Description:  Ship v1 with core features and onboard first 10 customers

  Project name: Acme Corp
  GitHub repo URL: https://github.com/acme/widgets

  Select a preset:
  ❯ fast — Speed-optimized for solo engineer...
    quality — Quality-optimized with PR review...
    rad — Rapid development with tech evaluation...
    startup — Strategy-first bootstrapping...
    research — Research and planning only...
    full — Full company setup with everything...
    custom — Pick modules manually

  ✓ Company "Acme Corp" created
  ✓ Goal created
  ✓ Project created (workspace: companies/AcmeCorp/projects/AcmeCorp)
  ✓ CEO agent created
  ✓ Engineer agent created
  ✓ 4 issues created
  ✓ CEO heartbeat started

Options

Company options

Infrastructure options

Company directories use PascalCase: "Black Mesa" becomes companies/BlackMesa/

Non-interactive mode

Pass --name and --preset to skip the wizard entirely. No TTY required.

# Minimal — assemble files only
clipper --name "Acme" --preset fast

# Full provisioning
clipper --name "Acme" --goal "Build widgets" --preset startup --api --start

# Custom composition
clipper --name "Acme" --preset fast --roles product-owner --modules pr-review

# Preset with overrides
clipper --name "Acme" --preset custom --modules github-repo,auto-assign,stall-detection

# In a CI/CD pipeline or script
clipper --name "$COMPANY" --preset "$PRESET" --api --api-url "$API_URL" --start

--modules and --roles are additive — they merge with whatever the preset includes.

AI wizard mode

Let Claude figure out the best setup. Two sub-modes — interview (3 guided questions) and single-shot (one description).

Requires ANTHROPIC_API_KEY — pass it inline or export it:

# Inline
ANTHROPIC_API_KEY=sk-ant-... clipper --ai

# Or export once
export ANTHROPIC_API_KEY=sk-ant-...

# Interview — AI asks 3 questions, each building on previous answers
clipper --ai

# Single-shot — describe everything upfront
clipper --ai "A fintech startup building a payment processing API, focus on security"

# Override AI choices with explicit flags
clipper --ai --name "PixelForge" --api
clipper --ai "Enterprise SaaS with CI/CD" --preset quality

The AI selects the best preset, modules, and roles based on your input. Explicit flags (--name, --preset, --modules, --roles) always override AI choices.

One-liner: description to running company

Combine single-shot with --api and --start for full programmatic integration — describe a company in natural language, assemble files, provision via API, and start the CEO heartbeat in one command:

ANTHROPIC_API_KEY=sk-ant-... clipper --ai "A dev agency that builds React apps" --api --start

No prompts, no interaction, no TTY required — fully scriptable.

AI wizard prompts are stored in templates/ai-wizard/ and can be edited to customize the wizard's behavior.

What You Get

companies/AcmeCorp/
├── BOOTSTRAP.md              # Setup guide (goal, project, agents, tasks)
├── agents/
│   ├── ceo/
│   │   ├── AGENTS.md         # Identity + skill references
│   │   ├── SOUL.md           # Persona and voice
│   │   ├── HEARTBEAT.md      # Execution checklist
│   │   ├── TOOLS.md          # Tool inventory
│   │   └── skills/           # Assigned by capability resolution
│   ├── engineer/
│   │   └── ...
│   ├── product-owner/        # ← if role selected
│   ├── code-reviewer/        # ← if role selected
│   ├── ui-designer/          # ← if role selected
│   └── ux-researcher/        # ← if role selected
├── projects/
│   └── AcmeCorp/             # Agent workspace (cwd)
└── docs/                     # Shared workflows from modules

With --api, everything is provisioned automatically. Without it, BOOTSTRAP.md has step-by-step instructions for manual setup.

Files are read live by Paperclip agents — edit anything on disk and it takes effect on the next heartbeat.

Gracefully Optimistic Architecture

Start with CEO + Engineer. Everything works. Add specialists and responsibilities shift automatically:

How it works: Primary owners get the full skill. Fallback owners get a safety-net variant that only activates when the primary is absent or stalled.

Example: CEO + Engineer only? The CEO handles market analysis, hiring review, and backlog management alongside strategy. Add a Product Owner and those responsibilities shift automatically — the CEO keeps a fallback safety net but steps back from day-to-day.

Presets

fast is for a single engineer — multiple engineers without review will cause conflicts.
research has no code workflow. Add github-repo and backlog when ready to build.

fast — Solo engineer, direct-to-main, automated backlog. No review, no planning phase.

quality — Full review pipeline. Product Owner manages backlog and product alignment, Code Reviewer gates code quality. Feature branches with PR workflow.

rad — Rapid Application Development. Pick a tech stack, start building, hire when you hit bottlenecks. No upfront market research or architecture formalization — prototype first, learn from what you build, formalize later.

startup — Strategy-first. Starts with vision, market analysis, tech evaluation, and hiring review before any code. CEO and Engineer grow the team through board approvals.

research — Planning only. Vision, market research, tech evaluation, and team assessment. No repo, no code workflow. Upgrade to startup or full when ready to build.

full — Everything. Full strategic planning, quality engineering with PR review, team growth via hiring review. Product Owner and Code Reviewer included. Best for serious projects that need both strategy and engineering rigor.

Modules

Strategy & Planning

Engineering Workflow

vision-workshop

Defines the strategic foundation. The CEO runs a vision workshop to refine the company goal into a vision statement, success metrics, and milestones.

Capability: none (CEO-only strategic task)
Doc: docs/vision-template.md
With UX Researcher: contributes user-centered metrics and journey mapping

market-analysis

Researches the target market, competitors, and positioning.

Capability: market-analysis — owners: ux-researcher → cmo → product-owner → ceo
Fallback: CMO focuses on positioning and competitive landscape; CEO creates a brief overview only
Doc: docs/market-analysis-template.md

hiring-review

Evaluates team composition against the goal and proposes hires through board approval.

Capability: hiring-review — owners: product-owner → ceo
Fallback: CEO proposes one urgent hire only

tech-stack

Evaluates technology options and documents decisions with rationale and trade-offs.

Capability: tech-stack — owners: engineer → ceo
Fallback: CEO makes pragmatic defaults, marks them provisional
Doc: docs/tech-stack-template.md

architecture-plan

Designs the system architecture. Requires tech-stack. Includes a design-system capability for UI Designers.

Capability: architecture-plan — owners: engineer → ceo
Capability: design-system — owners: ui-designer → engineer
Docs: docs/architecture-template.md, docs/design-system-template.md

github-repo

Git workflow and commit conventions.

Task: Engineer initializes repo
Doc: docs/git-workflow.md

pr-review

PR-based review workflow. Requires github-repo. Activates with code-reviewer, product-owner, ui-designer, ux-researcher, qa, or devops.

Task: Engineer sets up branch protection
Doc: docs/pr-conventions.md

backlog

Owns the product backlog lifecycle — from goal decomposition to a steady pipeline of actionable issues.

Capability: backlog-health — owners: product-owner → ceo
Fallback: CEO creates 1-2 issues only when backlog is critically empty
Doc: docs/backlog-process.md

auto-assign

Assigns unassigned issues to idle agents.

Capability: auto-assign — owners: product-owner → ceo
Fallback: CEO assigns only when agents are critically idle

brand-identity

Creates brand guidelines: logo usage, color palette, typography, iconography, and tone of voice.

Capability: brand-identity — owners: ui-designer → cmo → ceo
Fallback: CMO focuses on brand strategy and messaging; CEO creates minimal provisional placeholder
Doc: docs/brand-identity-template.md

user-testing

Designs and executes usability evaluations, documents findings with severity ratings.

Capability: user-testing — owners: qa → ux-researcher → product-owner → ceo
Fallback: QA adds test automation and edge case coverage; CEO creates a basic heuristic checklist
Doc: docs/user-testing-template.md

ci-cd

Continuous integration and deployment pipeline. Requires github-repo.

Capability: ci-cd — owners: devops → engineer
Fallback: Engineer sets up basic CI (lint, test, build); DevOps owns full pipeline lifecycle including CD
Doc: docs/ci-cd-template.md

monitoring

Observability, error tracking, logging, alerting, and health checks. Requires github-repo.

Capability: monitoring — owners: devops → engineer
Fallback: Engineer sets up basic health checks and structured logging; DevOps owns full observability stack
Doc: docs/monitoring-template.md

stall-detection

Detects issues stuck in in_progress or in_review with no recent activity. Nudges the assigned agent, escalates to the board if nudging doesn't help.

Capability: CEO-only

Roles

Every company starts with CEO and Engineer (base roles). These optional roles extend the team:

| Role | Paperclip role | Reports to | Enhances | | :--- | :------------- | :--------- | :------- | | Product Owner | pm | CEO | Takes over roadmap, auto-assign, hiring-review from CEO | | Code Reviewer | general | CEO | Enables pr-review activation | | UI & Brand Designer | designer | CEO | Takes over design-system and brand-identity | | UX Researcher | researcher | CEO | Takes over market-analysis and user-testing | | CTO | cto | CEO | Technical leadership, architecture oversight | | CMO | cmo | CEO | Marketing strategy, go-to-market, growth metrics | | CFO | cfo | CEO | Financial planning, budget tracking, cost analysis | | DevOps Engineer | devops | CEO | Takes over ci-cd and monitoring from Engineer | | QA Engineer | qa | CEO | Takes over user-testing, quality gates |

Product Owner

The voice of the user. Owns the backlog pipeline, validates engineering output against goals, manages scope discipline. Adds product-alignment review pass with pr-review module.

Code Reviewer

Owns code quality. Reviews PRs for correctness, style, security, and test coverage. Never writes code — only reviews it.

UI & Brand Designer

Owns visual identity, design systems, and brand consistency. Creates design specs that engineers implement. Outputs are design documents, not code. Adds design review pass with pr-review module.

UX Researcher

Owns user experience research, usability analysis, and journey mapping. Grounds design and product decisions in evidence-based user insights. Adds UX review pass with pr-review module.

CTO

Technical leadership and architecture oversight. Guides technology decisions, reviews system design, and ensures engineering quality at scale.

CMO

Owns marketing strategy, brand positioning, go-to-market planning, and growth metrics. Data-driven, measures everything.

CFO

Owns financial planning, budget tracking, cost analysis, and resource allocation. Monitors agent cost events and budget utilization.

DevOps Engineer

Owns infrastructure, CI/CD pipelines, deployment, monitoring, and platform reliability. Automation over manual work, infrastructure as code.

QA Engineer

Owns test strategy, test automation, quality gates, and regression prevention. Prevention over detection.

After Clipper

With `--api` (recommended)

Clipper provisions everything in the local Paperclip instance automatically:

Company — created with the name you entered
Goal — company-level goal, set to active
Project — workspace pointing to companies/<Name>/projects/<ProjectName>/
Agents — one per role, with cwd, instructionsFilePath, model, and adapter config
Issues — initial tasks from modules, linked to goal and project
CEO heartbeat — optionally started with --start

Without `--api`

Follow the BOOTSTRAP.md file generated in the company directory. It lists every resource to create manually in the Paperclip UI.

Extending

Add a module

templates/modules/<name>/
├── module.json                  # Name, capabilities, tasks, dependencies
├── skills/                      # Shared skills (used by any primary owner)
│   └── <skill>.md
├── agents/<role>/
│   ├── skills/                  # Role-specific overrides and fallbacks
│   │   ├── <skill>.md           # Override (replaces shared for this role)
│   │   └── <skill>.fallback.md  # Fallback (safety-net for non-primary)
│   └── heartbeat-section.md     # Optional: injected into role's HEARTBEAT.md
└── docs/                        # Shared docs (→ docs/)

Two kinds of docs end up in {company}/docs/:

Templates (lowercase-kebab.md) — Shipped by modules, copied at assembly time. Guaranteed to exist if the module is active.
Agent output (UPPERCASE.md) — Created by agents during execution. May or may not exist yet.

The naming convention is the contract: UPPERCASE.md from another module → always wrap in "if exists". lowercase.md from own module → safe to reference directly.

{
  "name": "my-module",
  "requires": ["other-module"],
  "activatesWithRoles": ["my-role"],
  "capabilities": [
    {
      "skill": "my-skill",
      "owners": ["my-role", "ceo"],
      "fallbackSkill": "my-skill.fallback"
    }
  ],
  "tasks": [
    {
      "title": "Initial task",
      "assignTo": "capability:my-skill",
      "description": "Task description"
    }
  ]
}

When assembling a capability's primary skill, the system checks in order:

Role-specific override: agents/<role>/skills/<skill>.md
Shared skill: skills/<skill>.md

First match wins. Most capabilities only need a shared skill. Role-specific overrides exist only when a role brings a genuinely different approach. Fallback variants are always role-specific.

Example: market-analysis module
├── skills/
│   └── market-analysis.md                    # Shared: any primary owner
├── agents/
│   ├── ux-researcher/skills/
│   │   └── market-analysis.md                # Override: user-focused
│   └── ceo/skills/
│       └── market-analysis.fallback.md       # Fallback: brief overview

UX Researcher present → gets role-specific override (user-focused)
Product Owner primary → gets shared skill
CEO primary → gets shared skill
CEO as fallback → gets fallback variant

Add a role

templates/roles/<name>/
├── role.json        # Name, title, paperclipRole, reportsTo, adapter
├── AGENTS.md
├── SOUL.md
├── HEARTBEAT.md
└── TOOLS.md

{
  "name": "my-role",
  "title": "My Role",
  "paperclipRole": "general",
  "description": "What this role does",
  "reportsTo": "ceo",
  "enhances": ["Takes over X from CEO"],
  "adapter": {
    "model": "claude-sonnet-4-6"
  }
}

Add a preset

{
  "name": "my-preset",
  "description": "What this preset is for",
  "constraints": [],
  "base": "base",
  "roles": ["product-owner"],
  "modules": ["github-repo", "backlog"]
}

How It Works

┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Wizard    │────▶│   Assembly   │────▶│   Provisioning   │
│  (prompts)  │     │  (files)     │     │   (API, --api)   │
└─────────────┘     └──────────────┘     └──────────────────┘

Assembly (always runs):

Copies base role files (CEO, Engineer) into agents/
Copies selected extra roles into agents/
For each module: resolves capability ownership, installs skills, copies docs
Injects module heartbeat sections into each role's HEARTBEAT.md
Generates BOOTSTRAP.md with goal, project, agent paths, and initial tasks

Provisioning (with --api):

Creates company → goal → project (with workspace) → agents → issues
Wires reportsTo hierarchy (CEO first, then other agents)
Optionally starts CEO heartbeat (--start)

Changelog

See CHANGELOG.md for version history.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — Yesterday