Files

Dotta 29b70e0c36 Add company import export v2 plan

2026-03-13 21:10:45 -05:00

17 KiB

Raw Blame History

ClipHub: Marketplace for Paperclip Team Configurations

Supersession note: this marketplace plan predates the markdown-first company package direction. For the current package-format and import/export rollout plan, see doc/plans/2026-03-13-company-import-export-v2.md and docs/companies/companies-spec.md.

The "app store" for whole-company AI teams — pre-built Paperclip configurations, agent blueprints, skills, and governance templates that ship real work from day one.

1. Vision & Positioning

ClipHub sells entire team configurations — org charts, agent roles, inter-agent workflows, governance rules, and project templates — for Paperclip-managed companies.

Dimension	ClipHub
Unit of sale	Team blueprint (multi-agent org)
Buyer	Founder / team lead spinning up an AI company
Install target	Paperclip company (agents, projects, governance)
Value prop	"Skip org design — get a shipping team in minutes"
Price range	$0–$499 per blueprint (+ individual add-ons)

2. Product Taxonomy

2.1 Team Blueprints (primary product)

A complete Paperclip company configuration:

Org chart: Agents with roles, titles, reporting chains, capabilities
Agent configs: Adapter type, model, prompt templates, instructions paths
Governance rules: Approval flows, budget limits, escalation chains
Project templates: Pre-configured projects with workspace settings
Skills & instructions: AGENTS.md / skill files bundled per agent

Examples:

"SaaS Startup Team" — CEO, CTO, Engineer, CMO, Designer ($199)
"Content Agency" — Editor-in-Chief, 3 Writers, SEO Analyst, Social Manager ($149)
"Dev Shop" — CTO, 2 Engineers, QA, DevOps ($99)
"Solo Founder + Crew" — CEO agent + 3 ICs across eng/marketing/ops ($79)

2.2 Agent Blueprints (individual agents within a team context)

Single-agent configurations designed to plug into a Paperclip org:

Role definition, prompt template, adapter config
Reporting chain expectations (who they report to)
Skill bundles included
Governance defaults (budget, permissions)

Examples:

"Staff Engineer" — ships production code, manages PRs ($29)
"Growth Marketer" — content pipeline, SEO, social ($39)
"DevOps Agent" — CI/CD, deployment, monitoring ($29)

2.3 Skills (modular capabilities)

Portable skill files that any Paperclip agent can use:

Markdown skill files with instructions
Tool configurations and shell scripts
Compatible with Paperclip's skill loading system

Examples:

"Git PR Workflow" — standardized PR creation and review (Free)
"Deployment Pipeline" — Cloudflare/Vercel deploy skill ($9)
"Customer Support Triage" — ticket classification and routing ($19)

2.4 Governance Templates

Pre-built approval flows and policies:

Budget thresholds and approval chains
Cross-team delegation rules
Escalation procedures
Billing code structures

Examples:

"Startup Governance" — lightweight, CEO approves > $50 (Free)
"Enterprise Governance" — multi-tier approval, audit trail ($49)

3. Data Schemas

3.1 Listing

interface Listing {
  id: string;
  slug: string;                    // URL-friendly identifier
  type: 'team_blueprint' | 'agent_blueprint' | 'skill' | 'governance_template';
  title: string;
  tagline: string;                 // Short pitch (≤120 chars)
  description: string;             // Markdown, full details

  // Pricing
  price: number;                   // Cents (0 = free)
  currency: 'usd';

  // Creator
  creatorId: string;
  creatorName: string;
  creatorAvatar: string | null;

  // Categorization
  categories: string[];            // e.g. ['saas', 'engineering', 'marketing']
  tags: string[];                  // e.g. ['claude', 'startup', '5-agent']
  agentCount: number | null;       // For team blueprints

  // Content
  previewImages: string[];         // Screenshots / org chart visuals
  readmeMarkdown: string;          // Full README shown on detail page
  includedFiles: string[];         // List of files in the bundle

  // Compatibility
  compatibleAdapters: string[];    // ['claude_local', 'codex_local', ...]
  requiredModels: string[];        // ['claude-opus-4-6', 'claude-sonnet-4-6']
  paperclipVersionMin: string;     // Minimum Paperclip version

  // Social proof
  installCount: number;
  rating: number | null;           // 1.0–5.0
  reviewCount: number;

  // Metadata
  version: string;                 // Semver
  publishedAt: string;
  updatedAt: string;
  status: 'draft' | 'published' | 'archived';
}

3.2 Team Blueprint Bundle

interface TeamBlueprint {
  listingId: string;

  // Org structure
  agents: AgentBlueprint[];
  reportingChain: { agentSlug: string; reportsTo: string | null }[];

  // Governance
  governance: {
    approvalRules: ApprovalRule[];
    budgetDefaults: { role: string; monthlyCents: number }[];
    escalationChain: string[];     // Agent slugs in escalation order
  };

  // Projects
  projects: ProjectTemplate[];

  // Company-level config
  companyDefaults: {
    name: string;
    defaultModel: string;
    defaultAdapter: string;
  };
}

interface AgentBlueprint {
  slug: string;                     // e.g. 'cto', 'engineer-1'
  name: string;
  role: string;
  title: string;
  icon: string;
  capabilities: string;
  promptTemplate: string;
  adapterType: string;
  adapterConfig: Record<string, any>;
  instructionsPath: string | null;  // Path to AGENTS.md or similar
  skills: SkillBundle[];
  budgetMonthlyCents: number;
  permissions: {
    canCreateAgents: boolean;
    canApproveHires: boolean;
  };
}

interface ProjectTemplate {
  name: string;
  description: string;
  workspace: {
    cwd: string | null;
    repoUrl: string | null;
  } | null;
}

interface ApprovalRule {
  trigger: string;                  // e.g. 'hire_agent', 'budget_exceed'
  threshold: number | null;
  approverRole: string;
}

3.3 Creator / Seller

interface Creator {
  id: string;
  userId: string;                   // Auth provider ID
  displayName: string;
  bio: string;
  avatarUrl: string | null;
  website: string | null;
  listings: string[];               // Listing IDs
  totalInstalls: number;
  totalRevenue: number;             // Cents earned
  joinedAt: string;
  verified: boolean;
  payoutMethod: 'stripe_connect';
  stripeAccountId: string | null;
}

3.4 Purchase / Install

interface Purchase {
  id: string;
  listingId: string;
  buyerUserId: string;
  buyerCompanyId: string | null;    // Target Paperclip company
  pricePaidCents: number;
  paymentIntentId: string | null;   // Stripe
  installedAt: string | null;       // When deployed to company
  status: 'pending' | 'completed' | 'refunded';
  createdAt: string;
}

3.5 Review

interface Review {
  id: string;
  listingId: string;
  authorUserId: string;
  authorDisplayName: string;
  rating: number;                   // 1–5
  title: string;
  body: string;                     // Markdown
  verifiedPurchase: boolean;
  createdAt: string;
  updatedAt: string;
}

4. Pages & Routes

4.1 Public Pages

Route	Page	Description
`/`	Homepage	Hero, featured blueprints, popular skills, how it works
`/browse`	Marketplace browse	Filterable grid of all listings
`/browse?type=team_blueprint`	Team blueprints	Filtered to team configs
`/browse?type=agent_blueprint`	Agent blueprints	Single-agent configs
`/browse?type=skill`	Skills	Skill listings
`/browse?type=governance_template`	Governance	Policy templates
`/listings/:slug`	Listing detail	Full product page
`/creators/:slug`	Creator profile	Bio, all listings, stats
`/about`	About ClipHub	Mission, how it works
`/pricing`	Pricing & fees	Creator revenue share, buyer info

4.2 Authenticated Pages

Route	Page	Description
`/dashboard`	Buyer dashboard	Purchased items, installed blueprints
`/dashboard/purchases`	Purchase history	All transactions
`/dashboard/installs`	Installations	Deployed blueprints with status
`/creator`	Creator dashboard	Listing management, analytics
`/creator/listings/new`	Create listing	Multi-step listing wizard
`/creator/listings/:id/edit`	Edit listing	Modify existing listing
`/creator/analytics`	Analytics	Revenue, installs, views
`/creator/payouts`	Payouts	Stripe Connect payout history

4.3 API Routes

Method	Endpoint	Description
`GET`	`/api/listings`	Browse listings (filters: type, category, price range, sort)
`GET`	`/api/listings/:slug`	Get listing detail
`POST`	`/api/listings`	Create listing (creator auth)
`PATCH`	`/api/listings/:id`	Update listing
`DELETE`	`/api/listings/:id`	Archive listing
`POST`	`/api/listings/:id/purchase`	Purchase listing (Stripe checkout)
`POST`	`/api/listings/:id/install`	Install to Paperclip company
`GET`	`/api/listings/:id/reviews`	Get reviews
`POST`	`/api/listings/:id/reviews`	Submit review
`GET`	`/api/creators/:slug`	Creator profile
`GET`	`/api/creators/me`	Current creator profile
`POST`	`/api/creators`	Register as creator
`GET`	`/api/purchases`	Buyer's purchase history
`GET`	`/api/analytics`	Creator analytics

5. User Flows

5.1 Buyer: Browse → Purchase → Install

Homepage → Browse marketplace → Filter by type/category
  → Click listing → Read details, reviews, preview org chart
  → Click "Buy" → Stripe checkout (or free install)
  → Post-purchase: "Install to Company" button
  → Select target Paperclip company (or create new)
  → ClipHub API calls Paperclip API to:
      1. Create agents with configs from blueprint
      2. Set up reporting chains
      3. Create projects with workspace configs
      4. Apply governance rules
      5. Deploy skill files to agent instruction paths
  → Redirect to Paperclip dashboard with new team running

5.2 Creator: Build → Publish → Earn

Sign up as creator → Connect Stripe
  → "New Listing" wizard:
      Step 1: Type (team/agent/skill/governance)
      Step 2: Basic info (title, tagline, description, categories)
      Step 3: Upload bundle (JSON config + skill files + README)
      Step 4: Preview & org chart visualization
      Step 5: Pricing ($0–$499)
      Step 6: Publish
  → Live on marketplace immediately
  → Track installs, revenue, reviews on creator dashboard

5.3 Creator: Export from Paperclip → Publish

Running Paperclip company → "Export as Blueprint" (CLI or UI)
  → Paperclip exports:
      - Agent configs (sanitized — no secrets)
      - Org chart / reporting chains
      - Governance rules
      - Project templates
      - Skill files
  → Upload to ClipHub as new listing
  → Edit details, set price, publish

6. UI Design Direction

6.1 Visual Language

Color palette: Dark ink primary, warm sand backgrounds, accent color for CTAs (Paperclip brand blue/purple)
Typography: Clean sans-serif, strong hierarchy, monospace for technical details
Cards: Rounded corners, subtle shadows, clear pricing badges
Org chart visuals: Interactive tree/graph showing agent relationships in team blueprints

6.2 Key Design Elements

Element	ClipHub
Product card	Org chart mini-preview + agent count badge
Detail page	Interactive org chart + per-agent breakdown
Install flow	One-click deploy to Paperclip company
Social proof	"X companies running this blueprint"
Preview	Live demo sandbox (stretch goal)

6.3 Listing Card Design

┌─────────────────────────────────────┐
│  [Org Chart Mini-Preview]           │
│  ┌─CEO─┐                            │
│  ├─CTO─┤                            │
│  └─ENG──┘                           │
│                                     │
│  SaaS Startup Team                  │
│  "Ship your MVP with a 5-agent      │
│   engineering + marketing team"      │
│                                     │
│  👥 5 agents  ⬇ 234 installs       │
│  ★ 4.7 (12 reviews)                │
│                                     │
│  By @masinov          $199  [Buy]   │
└─────────────────────────────────────┘

6.4 Detail Page Sections

Hero: Title, tagline, price, install button, creator info
Org Chart: Interactive visualization of agent hierarchy
Agent Breakdown: Expandable cards for each agent — role, capabilities, model, skills
Governance: Approval flows, budget structure, escalation chain
Included Projects: Project templates with workspace configs
README: Full markdown documentation
Reviews: Star ratings + written reviews
Related Blueprints: Cross-sell similar team configs
Creator Profile: Mini bio, other listings

7. Installation Mechanics

7.1 Install API Flow

When a buyer clicks "Install to Company":

POST /api/listings/:id/install
{
  "targetCompanyId": "uuid",         // Existing Paperclip company
  "overrides": {                      // Optional customization
    "agentModel": "claude-sonnet-4-6", // Override default model
    "budgetScale": 0.5,               // Scale budgets
    "skipProjects": false
  }
}

The install handler:

Validates buyer owns the purchase
Validates target company access
For each agent in blueprint:
- POST /api/companies/:id/agents (if paperclip-create-agent supports it, or via approval flow)
- Sets adapter config, prompt template, instructions path
Sets reporting chains
Creates projects and workspaces
Applies governance rules
Deploys skill files to configured paths
Returns summary of created resources

7.2 Conflict Resolution

Agent name collision: Append -2, -3 suffix
Project name collision: Prompt buyer to rename or skip
Adapter mismatch: Warn if blueprint requires adapter not available locally
Model availability: Warn if required model not configured

8. Revenue Model

Fee	Amount	Notes
Creator revenue share	90% of sale price	Minus Stripe processing (~2.9% + $0.30)
Platform fee	10% of sale price	ClipHub's cut
Free listings	$0	No fees for free listings
Stripe Connect	Standard rates	Handled by Stripe

9. Technical Architecture

9.1 Stack

Frontend: Next.js (React), Tailwind CSS, same UI framework as Paperclip
Backend: Node.js API (or extend Paperclip server)
Database: Postgres (can share Paperclip's DB or separate)
Payments: Stripe Connect (marketplace mode)
Storage: S3/R2 for listing bundles and images
Auth: Shared with Paperclip auth (or OAuth2)

9.2 Integration with Paperclip

ClipHub can be:

Option A: A separate app that calls Paperclip's API to install blueprints
Option B: A built-in section of the Paperclip UI (/marketplace route)

Option B is simpler for MVP — adds routes to the existing Paperclip UI and API.

9.3 Bundle Format

Listing bundles are ZIP/tar archives containing:

blueprint/
├── manifest.json          # Listing metadata + agent configs
├── README.md              # Documentation
├── org-chart.json         # Agent hierarchy
├── governance.json        # Approval rules, budgets
├── agents/
│   ├── ceo/
│   │   ├── prompt.md      # Prompt template
│   │   ├── AGENTS.md      # Instructions
│   │   └── skills/        # Skill files
│   ├── cto/
│   │   ├── prompt.md
│   │   ├── AGENTS.md
│   │   └── skills/
│   └── engineer/
│       ├── prompt.md
│       ├── AGENTS.md
│       └── skills/
└── projects/
    └── default/
        └── workspace.json  # Project workspace config

10. MVP Scope

Phase 1: Foundation

Listing schema and CRUD API
Browse page with filters (type, category, price)
Listing detail page with org chart visualization
Creator registration and listing creation wizard
Free installs only (no payments yet)
Install flow: blueprint → Paperclip company

Stripe Connect integration
Purchase flow
Review system
Creator analytics dashboard
"Export from Paperclip" CLI command

Phase 3: Growth

Search with relevance ranking
Featured/trending listings
Creator verification program
Blueprint versioning and update notifications
Live demo sandbox
API for programmatic publishing

17 KiB Raw Blame History Unescape Escape

ClipHub: Marketplace for Paperclip Team Configurations

1. Vision & Positioning

2. Product Taxonomy

2.1 Team Blueprints (primary product)

2.2 Agent Blueprints (individual agents within a team context)

2.3 Skills (modular capabilities)

2.4 Governance Templates

3. Data Schemas

3.1 Listing

3.2 Team Blueprint Bundle

3.3 Creator / Seller

3.4 Purchase / Install

3.5 Review

4. Pages & Routes

4.1 Public Pages

4.2 Authenticated Pages

4.3 API Routes

5. User Flows

5.1 Buyer: Browse → Purchase → Install

5.2 Creator: Build → Publish → Earn

5.3 Creator: Export from Paperclip → Publish

6. UI Design Direction

6.1 Visual Language

6.2 Key Design Elements

6.3 Listing Card Design

6.4 Detail Page Sections

7. Installation Mechanics

7.1 Install API Flow

7.2 Conflict Resolution

8. Revenue Model

9. Technical Architecture

9.1 Stack

9.2 Integration with Paperclip

9.3 Bundle Format

10. MVP Scope

Phase 1: Foundation

Phase 2: Payments & Social

Phase 3: Growth

17 KiB

Raw Blame History