Hugging Face's logo

Spaces:
AUXteam
/
Plandex
Paused

App Files Community
3
Plandex / docs /specs /cliphub-plan.md
AUXteam's picture
AUXteam
Upload folder using huggingface_hub
cf9339a verified
preview code
|
raw
history blame
16.9 kB

ClipHub: Marketplace for Paperclip Team Configurations

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

  1. Hero: Title, tagline, price, install button, creator info
  2. Org Chart: Interactive visualization of agent hierarchy
  3. Agent Breakdown: Expandable cards for each agent — role, capabilities, model, skills
  4. Governance: Approval flows, budget structure, escalation chain
  5. Included Projects: Project templates with workspace configs
  6. README: Full markdown documentation
  7. Reviews: Star ratings + written reviews
  8. Related Blueprints: Cross-sell similar team configs
  9. 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:

  1. Validates buyer owns the purchase
  2. Validates target company access
  3. 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
  4. Sets reporting chains
  5. Creates projects and workspaces
  6. Applies governance rules
  7. Deploys skill files to configured paths
  8. 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

Phase 2: Payments & Social

  • 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