Clipper

Bootstrap AI agent teams from modular templates.

Development Preview: A Paperclip plugin version of Clipper with a web UI is in active development. See web/README.md for details.

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

Flag	Description	Default
`--name <name>`	Company name	(wizard prompt)
`--goal <title>`	Company goal title	(wizard prompt)
`--goal-description <desc>`	Goal description	(wizard prompt)
`--project <name>`	Project name	company name
`--project-description <desc>`	Project description	(wizard prompt)
`--repo <url>`	GitHub repository URL	(wizard prompt)
`--preset <name>`	Preset: `fast`, `quality`, `rad`, `startup`, `research`, `full`, `secure`, `gtm`, `content`, `repo-maintenance`, `build-game`	(wizard prompt)
`--modules <a,b,c>`	Comma-separated module names (merged with preset)	(wizard prompt)
`--roles <a,b>`	Comma-separated extra role names (merged with preset)	(wizard prompt)

Infrastructure options

Flag	Description	Default
`--output <dir>`	Output directory for company workspaces	`./companies/`
`--dry-run`	Show summary and exit without writing files	off
`--api`	Provision via Paperclip API after file assembly	off
`--api-url <url>`	Paperclip API URL (implies `--api`)	`http://localhost:3100`
`--api-email <email>`	Board login email (for authenticated instances)	`PAPERCLIP_EMAIL` env var
`--api-password <pass>`	Board login password	`PAPERCLIP_PASSWORD` env var
`--api-workspace-root <path>`	Workspace root as seen by the API server (for Docker)	local path
`--model <model>`	Default LLM model for all agents	adapter default
`--start`	Start CEO heartbeat after provisioning (implies `--api`)	off
`--ai`	AI interview: 3 guided questions, then auto-config	—
`--ai <desc>`	AI single-shot: describe company, auto-config	—
`--ai-model <model>`	Model for AI wizard	`claude-opus-4-6`

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.

Goal generation: Paperize distills notes, ideas, research, or Obsidian vaults into actionable goals via AI. Use it to generate goals for Clipper programmatically: npx paperize --source ~/notes.

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:

Capability	Primary Owner	Fallback	Module
`market-analysis`	UX Researcher → CMO → Product Owner	CEO	market-analysis
`hiring-review`	Product Owner	CEO	hiring-review
`backlog-health`	Product Owner	CEO	backlog
`auto-assign`	Product Owner	CEO	auto-assign
`user-testing`	QA → UX Researcher → Product Owner	CEO	user-testing
`brand-identity`	UI Designer → CMO	CEO	brand-identity
`ci-cd`	DevOps	Engineer	ci-cd
`monitoring`	DevOps	Engineer	monitoring
`tech-stack`	Engineer	CEO	tech-stack
`architecture-plan`	Engineer	CEO	architecture-plan
`design-system`	UI Designer	Engineer	architecture-plan
`pr-review`	Code Reviewer / Product Owner / UI Designer / UX Researcher / QA / DevOps	—	pr-review
`threat-model`	Security Engineer → DevOps	Engineer	security-audit
`security-review`	Security Engineer → DevOps	Engineer	security-audit
`project-docs`	Technical Writer → Engineer	CEO	documentation
`competitive-tracking`	Customer Success → CMO → Product Owner	CEO	competitive-intel
`accessibility-audit`	QA → UI Designer	Engineer	accessibility
`codebase-audit`	Engineer	CEO	codebase-onboarding
`issue-triage`	Product Owner → Engineer	CEO	triage
`dependency-audit`	DevOps → Security Engineer	Engineer	dependency-management
`release-process`	DevOps → Engineer	CEO	release-management
`game-design`	Game Designer → Engineer	CEO	game-design
`stall-detection`	CEO (always)	—	stall-detection
`vision-workshop`	CEO (always)	—	vision-workshop

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

Preset	Modules	Best for
`fast`	github-repo, backlog, auto-assign, stall-detection	Solo engineer, prototypes, MVPs
`quality`	+ pr-review, + Product Owner, + Code Reviewer	Teams, production systems
`rad`	+ tech-stack, + hiring-review	Rapid prototyping, formalize later
`startup`	+ vision, market, hiring, tech, architecture	Strategy-first, grow organically
`research`	vision, market, tech, hiring (no repo/code)	Planning phase only
`full`	All modules + Product Owner + Code Reviewer	Full planning + quality engineering
`secure`	+ security-audit, + Security Engineer + Code Reviewer + PO	Regulated industries, fintech, healthtech
`gtm`	+ competitive-intel, brand-identity, + CMO + Customer Success + PO	Market-facing products, competitive positioning
`content`	+ documentation, accessibility, + Technical Writer + PO	Dev tools, documentation-heavy projects
`launch-mvp`	launch-mvp, github-repo, backlog, auto-assign, stall-detection	Ship a first version end-to-end
`build-api`	build-api, github-repo, backlog, auto-assign, ci-cd, stall-detection	Build a REST/GraphQL API from scratch
`website-relaunch`	website-relaunch, github-repo, pr-review, backlog, auto-assign, stall-detection + UI Designer + PO	Relaunch a website with external design assets
`repo-maintenance`	triage, codebase-onboarding, dependency-management, release-management, github-repo, pr-review, backlog, auto-assign, stall-detection + Code Reviewer + PO	Maintain an existing repository
`build-game`	game-design, tech-stack, github-repo, backlog, auto-assign, stall-detection + Game Designer + Game Artist	Build a game from idea to release

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.

Preset details

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.

secure — Security-first. Threat modeling, security reviews, and quality gates on top of full planning and PR review. Security Engineer, Code Reviewer, and Product Owner included. Best for regulated industries, fintech, healthtech, or any project where security is a hard requirement.

gtm — Go-to-market focused. Competitive intelligence, market analysis, and brand identity. CMO for marketing strategy, Customer Success for competitive tracking, Product Owner for backlog. Best for products entering or competing in established markets.

content — Content and documentation focused. Technical Writer for developer docs and guides, accessibility for inclusive design, market analysis for positioning. Best for developer tools, documentation-heavy projects, or content-driven products.

website-relaunch — Relaunch an existing website with external design assets. Site audit, design ingestion, implementation, content migration, QA, and go-live. UI Designer for design analysis, Product Owner for backlog management. Includes a user-assigned "Provide design assets" issue as the entry point — upload your agency's designs, the team handles the rest.

repo-maintenance — Custodial maintenance for existing repositories. Agents review and merge open PRs, triage inbound GitHub issues, audit codebase health, manage dependencies, and handle releases. Code Reviewer for PR quality gates, Product Owner for issue triage and backlog. Inline goal bootstraps the team through repo onboarding, process setup, initial sweep, and steady-state maintenance.

build-game — Game development from idea to playable release. Game Designer owns the GDD, mechanics, and balancing. Game Artist generates sprites, textures, and tilesets via AI image generation and code-based approaches. Inline goal with 5 milestones: concept (GDD + engine + art style), prototype (core loop + placeholder art + first playtest), vertical slice (one polished level), production (all content), polish & ship (balancing + distribution). Works for any genre.

Modules

Strategy & Planning

Module	What it does	Kickoff task
`vision-workshop`	Define vision, success metrics, strategic milestones	CEO defines vision
`market-analysis`	Research market, competitors, positioning	Primary owner conducts analysis
`hiring-review`	Evaluate team gaps, propose hires via board approval	Primary owner reviews team
`tech-stack`	Evaluate and document technology choices	Primary owner evaluates stack
`architecture-plan`	Design system architecture + design system	Engineer + Designer (if present)
`brand-identity`	Brand book, visual identity, design guidelines	Primary owner defines brand
`user-testing`	Usability evaluations and findings	Primary owner runs evaluations
`competitive-intel`	Competitive landscape analysis and tracking	Primary owner builds landscape
`documentation`	Project docs, API refs, onboarding guides	Primary owner creates docs
`security-audit`	Threat modeling and security code review	Primary owner conducts audit
`accessibility`	WCAG 2.2 compliance audit and remediation	Primary owner runs audit
`website-relaunch`	Website relaunch: audit, design ingestion, implementation, migration	Engineer audits + analyzes designs
`launch-mvp`	MVP lifecycle: scope, build core feature, deploy, iterate from feedback	CEO scopes, Engineer builds
`game-design`	Game Design Document, core mechanics, progression, balancing	Primary owner creates GDD

Maintenance & Operations

Module	What it does	Kickoff task
`codebase-onboarding`	Audit existing codebase, map architecture, track tech debt, ongoing cleanup	Primary owner audits codebase
`triage`	Classify, prioritize, and respond to inbound GitHub issues	Primary owner triages open issues
`dependency-management`	Dependency audits, CVE scanning, safe patching, upgrade planning	Primary owner audits dependencies
`release-management`	Semver, changelogs, git tagging, GitHub Releases, rollback procedures	Primary owner documents release process

Engineering Workflow

Module	What it does	Kickoff task
`github-repo`	Git workflow and commit conventions	Engineer initializes repo
`pr-review`	PR-based review workflow	Engineer sets up branch protection
`backlog`	Auto-generate issues from goals when backlog runs low	Primary owner creates initial backlog
`auto-assign`	Assign unassigned issues to idle agents	—
`stall-detection`	Detect stuck handovers, nudge or escalate	—
`build-api`	REST API: schema design, endpoints, auth, documentation	Engineer designs and implements
`ci-cd`	Continuous integration and deployment pipeline	Primary owner sets up CI/CD
`monitoring`	Observability, alerting, health checks	Primary owner sets up monitoring

Module details

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

security-audit

Threat modeling and security code review. Identifies attack surfaces, OWASP Top 10 vulnerabilities, and dependency CVEs.

Capability: threat-model — owners: security-engineer → devops → engineer
Capability: security-review — owners: security-engineer → devops → engineer
Fallback: DevOps focuses on infrastructure security; Engineer runs basic checks only

documentation

Project documentation: READMEs, API references, architecture overviews, onboarding guides.

Capability: project-docs — owners: technical-writer → engineer → ceo
Fallback: Engineer writes minimal README; CEO creates bare-bones project overview

competitive-intel

Living competitive landscape — competitor profiles that evolve over time with positioning, strengths, and differentiation insights.

Capability: competitive-tracking — owners: customer-success → cmo → product-owner → ceo
Fallback: CMO focuses on positioning angles; CEO creates brief overview only

accessibility

WCAG 2.2 compliance auditing: semantic HTML, keyboard navigation, color contrast, ARIA, screen reader compatibility.

Capability: accessibility-audit — owners: qa → ui-designer → engineer
Fallback: UI Designer focuses on visual accessibility; Engineer runs automated checks

website-relaunch

Full website relaunch lifecycle: audit the current site, ingest design assets from an external agency, implement the new design, migrate content, and go live. Includes an inline goal with 5 milestones (discovery, design handoff, implementation, content migration, QA & launch) and 10 issues.

Capability: design-ingestion — owners: ui-designer → engineer → ceo
Capability: site-audit — owners: ui-designer → engineer → ceo (designer brings design/content lens; engineer fallback focuses on technical audit)
Goal: Website Relaunch (with dedicated project, 5 milestones, 10 issues)

build-api

REST API development from schema to documentation. Includes an api-design skill covering resource-oriented URL design, HTTP conventions, input validation, pagination, authentication, and OpenAPI documentation. Inline goal with 4 milestones and 8 issues.

Capability: api-design — owners: engineer → ceo
Requires: github-repo
Goal: Build a REST API (with dedicated project, 4 milestones, 8 issues)

launch-mvp

MVP project lifecycle: define scope tightly, build the core feature, deploy, and iterate from user feedback. No capabilities or skills — this module is a structured goal with milestones and issues that guide the team through the MVP process.

Goal: Launch MVP (with dedicated project, 4 milestones, 8 issues)

codebase-onboarding

Audit an existing codebase and maintain its health over time. Initial pass maps architecture, identifies tech debt hotspots, and assesses test coverage. Ongoing heartbeat-driven health checks find refactoring opportunities, remove dead code, and create focused cleanup PRs. Requires github-repo.

Capability: codebase-audit — owners: engineer → ceo
Fallback: CEO writes high-level architecture overview only
Output: docs/CODEBASE-AUDIT.md

triage

Processes inbound GitHub issues: classify by type (bug, feature, enhancement, question, duplicate, invalid) and priority (P0–P3), respond to reporters, close duplicates, and convert actionable items into Paperclip tasks. Requires github-repo.

Capability: issue-triage — owners: product-owner → engineer → ceo
Fallback: CEO triages P0/P1 only, skips product decisions on feature requests

dependency-management

Dependency lifecycle: vulnerability scanning, outdated package detection, safe patch-level updates, and major version migration planning. Requires github-repo.

Capability: dependency-audit — owners: devops → security-engineer → engineer
Fallback: Engineer runs audit and applies safe patches only
Output: docs/DEPENDENCY-AUDIT.md

release-management

Release lifecycle: semantic versioning, changelog generation, git tagging, GitHub Releases, and rollback documentation. Requires github-repo.

Capability: release-process — owners: devops → engineer → ceo
Fallback: Engineer documents current process and sets up basic semver
Output: docs/RELEASE-PROCESS.md

game-design

Game Design Document creation and ongoing mechanic design, progression, and balancing. Ships a GDD template covering concept, core mechanic, three-layer game loop, progression, win/lose, controls, art/audio direction, and tuning parameters. Game Designer gets a deep role-specific skill with balancing workflows and design experiments.

Capability: game-design — owners: game-designer → engineer → ceo
Fallback: CEO writes minimal GDD with concept and core mechanic only
Doc: docs/gdd-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
Technical Writer	`general`	CEO	Takes over documentation, adds doc review pass
Security Engineer	`general`	CEO	Takes over security-audit, adds security review pass
Customer Success	`general`	CEO	Takes over competitive-intel customer analysis
Game Designer	`pm`	CEO	Takes over game-design from Engineer, playtesting focus
Level Designer	`pm`	CEO	Takes over level-specific design from Game Designer
Game Artist	`designer`	CEO	Takes over art asset creation from Engineer

Role details

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.

Technical Writer

Owns developer documentation, API references, READMEs, and onboarding guides. Keeps docs accurate as the codebase evolves. Accuracy over completeness.

Security Engineer

Owns threat modeling, security code reviews, OWASP compliance, and secure coding standards. Finds vulnerabilities before attackers do. Security issues are always blocking.

Customer Success Manager

Owns customer health monitoring, feedback synthesis, churn prevention, and competitive intelligence from the customer perspective. Empathy-driven, data-backed.

Game Designer

Owns the Game Design Document, core mechanics, game loop, progression systems, difficulty curves, and balancing. Defines what the game is and how it plays. Runs design experiments and iterates based on playtest data.

Level Designer

Owns level layout, pacing, difficulty curves, environmental storytelling, and spatial progression. Translates game design into playable spaces and encounters.

Game Artist

Owns visual art production: sprites, textures, tilesets, UI elements, and visual effects. Creates assets using AI image generation tools, code-based approaches (SVG, procedural generation, pixel art scripts), and asset pipeline tools.

After Clipper

With `--api` (recommended)

For local_trusted instances, --api works without credentials. For authenticated instances, provide board login credentials via env vars or flags:

# Env vars (set once)
export PAPERCLIP_EMAIL="you@example.com"
export PAPERCLIP_PASSWORD="yourpassword"
clipper --name "Acme" --preset fast --api

# Or inline flags
clipper --name "Acme" --preset fast --api \
  --api-email you@example.com --api-password yourpassword

Clipper auto-detects whether authentication is needed — no configuration change required for local_trusted instances.

For Docker deployments where the workspace is mounted at a different path, use --api-workspace-root to remap paths:

# Local: companies/ is mounted into Docker at /data/companies/
clipper --name "Acme" --preset fast --api \
  --api-workspace-root /data/companies

Clipper provisions everything in the 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.meta.json             # Name, capabilities, tasks, dependencies, permissions
├── 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/)

Doc references in skills

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.

Reference	Rule	Example
Define own output	Name the path directly	"Document in `docs/TECH-STACK.md`"
Read own template	Reference directly (assembly guarantees it)	"Follow conventions in `docs/pr-conventions.md`"
Read cross-module output	Always conditional with graceful fallback	"If `docs/TECH-STACK.md` exists, review it. Otherwise, proceed based on project context."

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.

module.meta.json schema

{
  "name": "my-module",
  "requires": ["other-module"],
  "activatesWithRoles": ["my-role"],
  "permissions": ["tasks:assign"],
  "adapterOverrides": { "chrome": true },
  "capabilities": [
    {
      "skill": "my-skill",
      "owners": ["my-role", "ceo"],
      "fallbackSkill": "my-skill.fallback"
    }
  ],
  "tasks": [
    {
      "title": "Initial task",
      "assignTo": "capability:my-skill",
      "description": "Task description"
    }
  ],
  "goal": {
    "title": "My Goal",
    "description": "What this goal achieves",
    "project": true,
    "milestones": [
      { "id": "phase-1", "title": "Phase 1", "project": false }
    ],
    "issues": [
      { "title": "First task", "milestone": "phase-1", "assignTo": "engineer", "priority": "high" }
    ]
  }
}

Field	Description
`requires`	Other modules that must be selected
`activatesWithRoles`	Module only applies if one of these roles is present
`capabilities[].owners`	Priority order — first present role gets the primary skill
`capabilities[].fallbackSkill`	Filename (without `.md`) of the fallback variant
`tasks[].assignTo`	A role name or `"capability:<skill>"` to auto-resolve
`adapterOverrides`	Adapter config keys merged into all capability owner agents during provisioning (e.g., `{ "chrome": true }`)
`goal`	Optional inline goal with milestones and issues. When active, `tasks` are skipped.
`goal.project`	If `true` (default), creates a dedicated Paperclip project for this goal
`goal.issues[].assignTo`	Role name, `"capability:<skill>"`, or `"user"` (unassigned for human pickup)

Skill resolution

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.meta.json   # Name, title, base, paperclipRole, reportsTo, adapter
├── AGENTS.md
├── SOUL.md
├── HEARTBEAT.md
└── TOOLS.md

role.meta.json schema

{
  "name": "my-role",
  "title": "My Role",
  "base": false,
  "division": "engineering",
  "tagline": "One-liner for wizard display and AI selection",
  "paperclipRole": "general",
  "description": "What this role does",
  "reportsTo": "ceo",
  "enhances": ["Takes over X from CEO"],
  "adapter": {
    "model": "claude-sonnet-4-6"
  }
}

Field	Description
`base`	`true` for always-present roles (ceo, engineer). Omit or `false` for optional roles.
`division`	Functional grouping: `leadership`, `engineering`, `design`, `product`. Used for wizard display and AI selection.
`tagline`	One-liner personality summary for wizard UX and AI wizard selection.
`paperclipRole`	Paperclip enum: `ceo`, `engineer`, `pm`, `qa`, `designer`, `cto`, `cmo`, `cfo`, `devops`, `researcher`, `general`
`adapter`	Passed to `adapterConfig` during provisioning. `--model` CLI flag is fallback.

Add a preset

Create templates/presets/<name>/preset.meta.json:

{
  "name": "my-preset",
  "description": "What this preset is for",
  "constraints": [],
  "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):

Connects to Paperclip API (auto-detects local_trusted vs authenticated, resolves board user ID)
Creates company → goal → project (with workspace) → agents (with adapter config from role + module adapterOverrides) → module task issues
For each inline goal (from preset/modules): sub-goal → optional project → milestones → issues
Issues with assignTo: "user" are assigned to the board user; agent issues are assigned to the matching agent
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

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.claude/commands		.claude/commands
.github		.github
.husky		.husky
dist		dist
src		src
templates		templates
web		web
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.tool-versions		.tool-versions
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
esbuild.config.mjs		esbuild.config.mjs
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Clipper

Table of Contents

Quick Start

Install

Usage

Options

Company options

Infrastructure options

Non-interactive mode

AI wizard mode

One-liner: description to running company

What You Get

Gracefully Optimistic Architecture

Presets

Modules

Strategy & Planning

Maintenance & Operations

Engineering Workflow

vision-workshop

market-analysis

hiring-review

tech-stack

architecture-plan

github-repo

pr-review

backlog

auto-assign

brand-identity

user-testing

ci-cd

monitoring

security-audit

documentation

competitive-intel

accessibility

website-relaunch

build-api

launch-mvp

codebase-onboarding

triage

dependency-management

release-management

game-design

stall-detection

Roles

Product Owner

Code Reviewer

UI & Brand Designer

UX Researcher

CTO

CMO

CFO

DevOps Engineer

QA Engineer

Technical Writer

Security Engineer

Customer Success Manager

Game Designer

Level Designer

Game Artist

After Clipper

With --api (recommended)

Without --api

Extending

Add a module

Add a role

Add a preset

How It Works

Changelog

Contributing

License

About

Topics

Resources

License

Contributing

With `--api` (recommended)

Without `--api`

Packages