Add ClipHub company template registry spec

ClipHub is a public registry for sharing and discovering Paperclip company configurations. Defines template publishing, semantic search, forking, versioning, moderation, and agent/team sub-packages. Includes data model sketch, user flows, architecture, and V1 scope. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-16 20:58:21 -06:00
parent 5e9b61541d
commit 9722bd7106
1 changed files with 336 additions and 0 deletions
--- a/doc/CLIPHUB.md
+++ b/doc/CLIPHUB.md
@@ -0,0 +1,336 @@
+# ClipHub — The Company Registry
+
+**Download a company.**
+
+ClipHub is the public registry where people share, discover, and download Paperclip company configurations. A company template is a portable artifact containing an entire org — agents, reporting structure, adapter configs, role definitions, seed tasks — ready to spin up with one command.
+
+---
+
+## What It Is
+
+ClipHub is to Paperclip what a package registry is to a programming language. Paperclip already supports exportable org configs (see SPEC.md §2). ClipHub is the public directory where those exports live.
+
+A user builds a working company in Paperclip — a dev shop, a marketing agency, a research lab, a content studio — exports the template, and publishes it to ClipHub. Anyone can browse, search, download, and spin up that company on their own Paperclip instance.
+
+The tagline: **you can literally download a company.**
+
+---
+
+## What Gets Published
+
+A ClipHub package is a **company template export** — the portable artifact format defined in the Paperclip spec. It contains:
+
+| Component | Description |
+|---|---|
+| **Company metadata** | Name, description, intended use case, category |
+| **Org chart** | Full reporting hierarchy — who reports to whom |
+| **Agent definitions** | Every agent: name, role, title, capabilities description |
+| **Adapter configs** | Per-agent adapter type and configuration (SOUL.md, HEARTBEAT.md, CLAUDE.md, process commands, webhook URLs — whatever the adapter needs) |
+| **Seed tasks** | Optional starter tasks and initiatives to bootstrap the company's first run |
+| **Budget defaults** | Suggested token/cost budgets per agent and per company |
+
+Templates are **structure, not state.** No in-progress tasks, no historical cost data, no runtime artifacts. Just the blueprint.
+
+### Sub-packages
+
+Not every use case needs a whole company. ClipHub also supports publishing individual components:
+
+- **Agent templates** — a single agent config (e.g. "Senior TypeScript Engineer", "SEO Content Writer", "DevOps Agent")
+- **Team templates** — a subtree of the org chart (e.g. "Marketing Team: CMO + 3 reports", "Engineering Pod: Tech Lead + 4 Engineers")
+- **Adapter configs** — reusable adapter configurations independent of any specific agent role
+
+These can be mixed into existing companies. Download an agent, slot it into your org, assign a manager, go.
+
+---
+
+## Core Features
+
+### Browse & Discover
+
+The homepage surfaces companies across several dimensions:
+
+- **Featured** — editorially curated, high-quality templates
+- **Popular** — ranked by downloads, stars, and forks
+- **Recent** — latest published or updated
+- **Categories** — browseable by use case (see Categories below)
+
+Each listing shows: name, short description, org size (agent count), category, adapter types used, star count, download count, and a mini org chart preview.
+
+### Search
+
+Search is **semantic, not keyword-only.** Powered by vector embeddings so you can search by intent:
+
+- "marketing agency that runs facebook ads" → finds relevant company templates even if those exact words aren't in the title
+- "small dev team for building APIs" → finds lean engineering orgs
+- "content pipeline with writers and editors" → finds content studio templates
+
+Also supports filtering by: category, agent count range, adapter types, star count, recency.
+
+### Company Detail Page
+
+Clicking into a company template shows:
+
+- **Full description** — what this company does, how it operates, what to expect
+- **Interactive org chart** — visual tree of every agent with role, title, and capabilities
+- **Agent list** — expandable details for each agent (adapter type, config summary, role description)
+- **Seed tasks** — the starter initiatives and tasks included
+- **Budget overview** — suggested cost structure
+- **Install command** — one-line CLI command to download and create
+- **Version history** — changelog, semver, previous versions available
+- **Community** — stars, comments, forks count
+
+### Install & Fork
+
+Two ways to use a template:
+
+**Install (fresh start):**
+```
+paperclip install cliphub:<publisher>/<company-slug>
+```
+Downloads the template and creates a new company in your local Paperclip instance. You add your own API keys, set budgets, customize agents, and hit go.
+
+**Fork:**
+Forking creates a copy of the template under your own ClipHub account. You can modify it, republish it as your own variant, and the fork lineage is tracked. This enables evolutionary improvement — someone publishes a marketing agency, you fork it, add a social media team, republish.
+
+### Stars & Comments
+
+- **Stars** — bookmark and signal quality. Star count is a primary ranking signal.
+- **Comments** — threaded discussion on each listing. Ask questions, share results, suggest improvements.
+
+### Download Counts & Signals
+
+Every install is counted. The registry tracks:
+
+- Total downloads (all time)
+- Downloads per version
+- Fork count
+- Star count
+
+These signals feed into search ranking and discovery.
+
+---
+
+## Publishing
+
+### Who Can Publish
+
+Anyone with a GitHub account can publish to ClipHub. Authentication is via GitHub OAuth.
+
+### How to Publish
+
+From within Paperclip, export your company as a template, then publish:
+
+```
+paperclip export --template my-company
+paperclip publish cliphub my-company
+```
+
+Or use the web UI to upload a template export directly.
+
+### What You Provide
+
+When publishing, you specify:
+
+| Field | Required | Description |
+|---|---|---|
+| `slug` | yes | URL-safe identifier (e.g. `lean-dev-shop`) |
+| `name` | yes | Display name |
+| `description` | yes | What this company does and who it's for |
+| `category` | yes | Primary category (see below) |
+| `tags` | no | Additional tags for discovery |
+| `version` | yes | Semver (e.g. `1.0.0`) |
+| `changelog` | no | What changed in this version |
+| `readme` | no | Extended documentation (markdown) |
+| `license` | no | Usage terms |
+
+### Versioning
+
+Templates use semantic versioning. Each publish creates an immutable version. Users can install any version or default to `latest`. Version history and changelogs are visible on the detail page.
+
+### The `sync` Command
+
+For power users who maintain multiple templates:
+
+```
+paperclip cliphub sync
+```
+
+Scans your local exported templates and publishes any that are new or updated. Useful for maintaining a portfolio of company templates from a single repo.
+
+---
+
+## Categories
+
+Company templates are organized by use case:
+
+| Category | Examples |
+|---|---|
+| **Software Development** | Full-stack dev shop, API development team, mobile app studio |
+| **Marketing & Growth** | Performance marketing agency, content marketing team, SEO shop |
+| **Content & Media** | Content studio, podcast production, newsletter operation |
+| **Research & Analysis** | Market research firm, competitive intelligence, data analysis team |
+| **Operations** | Customer support org, internal ops team, QA/testing shop |
+| **Sales** | Outbound sales team, lead generation, account management |
+| **Finance & Legal** | Bookkeeping service, compliance monitoring, financial analysis |
+| **Creative** | Design agency, copywriting studio, brand development |
+| **General Purpose** | Starter templates, minimal orgs, single-agent setups |
+
+Categories are not exclusive — a template can have one primary category plus tags for cross-cutting concerns.
+
+---
+
+## Moderation & Trust
+
+### Verified Publishers
+
+Publishers who meet certain thresholds (account age, published templates with good signals) earn a verified badge. Verified templates rank higher in search.
+
+### Security Review
+
+Company templates contain adapter configurations, which may include executable commands (process adapter) or webhook URLs (HTTP adapter). The moderation system:
+
+1. **Automated scanning** — checks adapter configs for suspicious patterns (arbitrary code execution, exfiltration URLs, credential harvesting)
+2. **Community reporting** — any signed-in user can flag a template. Auto-hidden after multiple reports pending review.
+3. **Manual review** — moderators can approve, reject, or request changes
+
+### Account Gating
+
+New accounts have a waiting period before they can publish. This prevents drive-by spam.
+
+---
+
+## Architecture
+
+ClipHub is a **separate service** from Paperclip itself. Paperclip is self-hosted; ClipHub is a hosted registry that Paperclip instances talk to.
+
+### Integration Points
+
+| Layer | Role |
+|---|---|
+| **ClipHub Web** | Browse, search, discover, comment, star — the website |
+| **ClipHub API** | Registry API for publishing, downloading, searching programmatically |
+| **Paperclip CLI** | `paperclip install`, `paperclip publish`, `paperclip cliphub sync` — built into Paperclip |
+| **Paperclip UI** | "Browse ClipHub" panel in the Paperclip web UI for discovering templates without leaving the app |
+
+### Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend | React + Vite (consistent with Paperclip) |
+| Backend | TypeScript + Hono (consistent with Paperclip) |
+| Database | PostgreSQL |
+| Search | Vector embeddings for semantic search |
+| Auth | GitHub OAuth |
+| Storage | Template zips stored in object storage (S3 or equivalent) |
+
+### Data Model (Sketch)
+
+```
+Publisher
+  id, github_id, username, display_name, verified, created_at
+
+Template
+  id, publisher_id, slug, name, description, category,
+  tags[], readme, license, created_at, updated_at,
+  star_count, download_count, fork_count,
+  forked_from_id (nullable)
+
+Version
+  id, template_id, version (semver), changelog,
+  artifact_url (zip), agent_count, adapter_types[],
+  created_at
+
+Star
+  id, publisher_id, template_id, created_at
+
+Comment
+  id, publisher_id, template_id, body, parent_id (nullable),
+  created_at, updated_at
+
+Report
+  id, reporter_id, template_id, reason, created_at
+```
+
+---
+
+## User Flows
+
+### "I want to start a company"
+
+1. Open ClipHub, browse by category or search "dev shop for building SaaS"
+2. Find a template that fits — "Lean SaaS Dev Shop (CEO + CTO + 3 Engineers)"
+3. Read the description, inspect the org chart, check the comments
+4. Run `paperclip install cliphub:acme/lean-saas-shop`
+5. Paperclip creates the company locally with all agents pre-configured
+6. Set your API keys, adjust budgets, add your initial tasks
+7. Hit go
+
+### "I built something great and want to share it"
+
+1. Build and iterate on a company in Paperclip until it works well
+2. Export: `paperclip export --template my-agency`
+3. Publish: `paperclip publish cliphub my-agency`
+4. Fill in description, category, tags on the web UI
+5. Template is live — others can find and install it
+
+### "I want to improve someone else's company"
+
+1. Find a template on ClipHub that's close to what you need
+2. Fork it to your account
+3. Install your fork locally, modify the org (add agents, change configs, restructure teams)
+4. Export and re-publish as your own variant
+5. Fork lineage visible on both the original and your version
+
+### "I just need one great agent, not a whole company"
+
+1. Search ClipHub for agent templates: "senior python engineer"
+2. Find a well-starred agent config
+3. Install just that agent: `paperclip install cliphub:acme/senior-python-eng --agent`
+4. Assign it to a manager in your existing company
+5. Done
+
+---
+
+## Relationship to Paperclip
+
+ClipHub is **not required** to use Paperclip. You can build companies entirely from scratch without ever touching ClipHub. But ClipHub dramatically lowers the barrier to entry:
+
+- **New users** get a working company in minutes instead of hours
+- **Experienced users** share proven configurations with the community
+- **The ecosystem** compounds — every good template makes the next company easier to build
+
+ClipHub is to Paperclip what a package registry is to a language runtime: optional, but transformative.
+
+---
+
+## V1 Scope
+
+### Must Have
+
+- [ ] Template publishing (upload via CLI or web)
+- [ ] Template browsing (list, filter by category)
+- [ ] Template detail page (description, org chart, agent list, install command)
+- [ ] Semantic search (vector embeddings)
+- [ ] `paperclip install cliphub:<publisher>/<slug>` CLI command
+- [ ] GitHub OAuth authentication
+- [ ] Stars
+- [ ] Download counts
+- [ ] Versioning (semver, version history)
+- [ ] Basic moderation (community reporting, auto-hide)
+
+### V2
+
+- [ ] Comments / threaded discussion
+- [ ] Forking with lineage tracking
+- [ ] Agent and team sub-packages
+- [ ] Verified publisher badges
+- [ ] Automated security scanning of adapter configs
+- [ ] "Browse ClipHub" panel in Paperclip web UI
+- [ ] `paperclip cliphub sync` for bulk publishing
+- [ ] Publisher profiles and portfolios
+
+### Not in Scope
+
+- Paid / premium templates (everything is free and public, at least initially)
+- Private registries (may be a future enterprise feature)
+- Running companies on ClipHub (it's a registry, not a runtime — consistent with Paperclip's own philosophy)