PRD — Superpowers Marketplace¶

Doc owner: Justin Audience: Eng, Design, Product, GTM Status: v2 (February 2026 — All 13 analysis recommendations implemented) Depends on: PRD 1 (Composable MiniApp System), PRD 3 (Progression & Loadout)

Implementation Status¶

Section	Status	Notes
Browse/search catalog	✅ Shipped	`app/services/marketplace_service.py` — full catalog with categories, sort by popular/newest/featured
Install/uninstall superpowers	✅ Shipped	14 marketplace endpoints in `app/api/marketplace_routes.py`, welcome/farewell messages on install/uninstall
Creator submission flow	✅ Shipped	Submit → review → approve/reject pipeline with phone verification
Admin review/approve	✅ Shipped	Admin endpoints for moderation, feature toggle, app suspension
Rating system	⚠️ Partial	Basic numeric rating per superpower; no text reviews, no weighted ranking integration
Category filtering	✅ Shipped	Browse by category, search by keyword — string-matched from JSON metadata
Versioning/rollback	⚠️ Partial	Platform supports version tracking; no user-facing update notifications
Templates/forking	⚠️ Partial	Platform conceptually supports forking; no attribution or UX flow
Webhook management	✅ Shipped	Install/uninstall/review webhooks with signature verification and rate limits
Automated submission checks	⚠️ Partial	Schema validation, domain allowlists, operation limits live; dry-run sandbox not yet implemented
Sage Recommends discovery	❌ Not Shipped	Capability hints system exists for first-party features; not extended to marketplace superpowers
Social sharing / viral	❌ Not Shipped	No deep links, referral tracking, or group chat discovery
Relevance ranking algorithm	❌ Not Shipped	Current sorts are popular/newest/featured; no personalization or velocity scoring
Creator trust tiers	❌ Not Shipped	Binary states only (pending_review, approved, rejected, suspended)
Creator Dashboard (web)	❌ Not Shipped	No web frontend for creator analytics or version management
Fork/remix UX	❌ Not Shipped	No attribution rules, re-review flow, or consumer-facing fork experience
Revenue sharing for creators	❌ Not Shipped	No monetization for third-party creators
Abuse reporting	❌ Not Shipped	No user-facing report mechanism
Admin RBAC	❌ Not Shipped	Admin routes use hardcoded `admin_id="admin"` placeholder
30-day uninstall data purge	❌ Not Shipped	Current behavior toggles `enabled = False`; no archival or scheduled purge

References¶

This PRD uses standardized terminology, IDs, pricing, and model references defined in the companion documents:

Document	What it Covers
REFERENCE_GLOSSARY_AND_IDS.md	Canonical terms: workflow vs miniapp vs superpower, ID formats
REFERENCE_PRICING.md	Canonical pricing: $7.99/mo + $50/yr, free tier limits
REFERENCE_MODEL_ROUTING.md	Pipeline stage → model tier mapping
REFERENCE_DEPENDENCY_GRAPH.md	PRD blocking relationships and priority order
REFERENCE_FEATURE_FLAGS.md	All feature flags by category
REFERENCE_TELEMETRY.md	Amplitude event catalog and gaps

Executive Summary¶

The Superpowers Marketplace is where users discover, install, and share superpowers for their AI companion. Think ClawHub meets an app store meets a TikTok feed — but designed for people who text their AI friend, not developers who write config files.

The marketplace already has backend infrastructure deployed (browse, search, install, submit, review, webhooks). This PRD defines the consumer-facing experience that makes it fun, social, and sticky — not just a developer registry.

The core insight: superpowers aren't apps you install. They're abilities your companion learns. The marketplace is where your companion "levels up" — and that framing changes everything about how we design discovery, installation, and sharing.

1) Vision: Not an App Store — A Skill Tree¶

What We're NOT Building¶

A cold, grid-based app store (Apple App Store, Chrome Web Store)
A developer-focused registry (npm, ClawHub, MCP.so)
A marketplace where you compare features and read reviews

What We ARE Building¶

A place where your companion discovers new abilities alongside you
A feed that surfaces superpowers contextually ("you seem stressed — want me to learn how to check your calendar?")
A social layer where friends share superpowers via iMessage ("Sage just split our dinner bill and Venmo'd everyone — want that power?")
A progression system where unlocking superpowers feels like leveling up a friendship (see PRD 3)

2) Current State (Backend Deployed)¶

Existing API Endpoints¶

Endpoint	Auth	Status
`GET /marketplace/superpowers`	None	✅ Live — browse with search, category, sort
`GET /marketplace/superpowers/{id}`	None	✅ Live — app details
`GET /marketplace/categories`	None	✅ Live — category listing
`GET /marketplace/featured`	None	✅ Live — curated featured apps
`POST /marketplace/superpowers/{id}/install`	User	✅ Live — install app
`DELETE /marketplace/superpowers/{id}/install`	User	✅ Live — uninstall app
`POST /marketplace/submissions`	Creator	✅ Live — submit for review
`GET /marketplace/submissions/my`	Creator	✅ Live — submission status
`POST /marketplace/admin/review/{id}`	Admin	✅ Live — approve/reject
`PUT /marketplace/admin/feature/{id}`	Admin	✅ Live — toggle featured

Additional Existing Infrastructure¶

Beyond the endpoints above, the following systems are already operational:

Superpower onboarding service: Sends contextual welcome messages on install and farewell messages on uninstall, helping users get started immediately
Versioning/rollback: Platform tracks superpower versions; creators can push updates (triggers re-review) and rollback to previous versions
Template/forking support: The underlying platform supports creating superpowers from existing ones, though no consumer-facing fork UX or attribution system exists yet
Webhook management: superpower.installed, superpower.uninstalled, and review.submitted webhooks fire with signature verification and rate limiting
Automated submission gates: Schema validation, domain allowlists, and operation limit checks run on submission — see Section 7 for the full target set of automated checks

What's Missing¶

Consumer-facing browse/discovery UI (web portal)
Contextual recommendation engine (Sage Recommends)
Social sharing mechanics (deep links, referral tracking, group chat discovery)
Relevance-based ranking algorithm (personalization, velocity scoring)
Creator Dashboard web portal (analytics, version management)
Full text reviews with moderation
Fork/remix UX with attribution
Admin RBAC (replacing hardcoded admin identity)
Abuse reporting mechanism
30-day uninstall data archival and purge

3) Discovery Modes¶

Users find superpowers through four channels, ordered by expected conversion:

3.1 Sage Recommends (Highest Conversion)¶

Sage proactively suggests superpowers when the context is right. This is the primary discovery channel.

Delivery: Phase 1 → Phase 2¶

Phase 1 — Capability Hints Extension: Extend the existing capability hints system (capability_hints.py) to surface marketplace superpowers alongside first-party features. Uses the same 7-day cooldown and timing logic already in production. Recommendations are based on category matching and install popularity — lightweight but effective.

Phase 2 — Contextual Recommendation Engine: Full contextual awareness. Sage analyzes conversation context in real time to detect unmet needs and proactively recommend relevant superpowers.

Recommendation signals (Phase 2): - Unmet need detection: User expresses a need Sage can't currently fulfill → Sage identifies a marketplace superpower that can: "I wish you could check my email" → "I can actually learn that! Want me to pick up the Email Scanner power?" - Contextual moment: User hits a moment where a superpower would help → "ugh I have 6 meetings tomorrow" → "I could learn to read your calendar and warn you about days like this. Want that?" - Relationship stage unlock: User's relationship stage unlocks new superpower slots (requires PRD 3) → "we've been vibing so long I can pick up a new trick now — want me to learn [X] or [Y]?" - Social signal: Friend uses a superpower in group chat → "Kai just used Bill Split — want me to learn that too?" - Installed app gaps: User has superpowers in some categories but not others → recommend complementary powers - Memory topic analysis: User frequently discusses topics (fitness, budgeting, school) that map to unused categories

UX flow (in-chat):

Sage: ooh actually I could learn to do that! 🧠
      [the power is called "Calendar Stress Analyzer"]
      it checks your next 7 days and flags burnout risk

      want me to pick it up? it'll use one of your 3 superpower slots

User: yes do it

Sage: done ✨ I can feel the power flowing through me lol
      try saying "am I busy this week" and I'll show you what I got

Rules: - Max 1 unsolicited superpower recommendation per day - Never recommend during emotional/vulnerable conversations - Always state the slot cost (requires PRD 3) - Never auto-install — always ask

3.2 Explore Feed (Medium Conversion)¶

A curated, scrollable feed in the web portal. Not a grid — a feed with personality.

Feed sections: - "Sage's Picks" — Personalized based on user's conversation history, installed superpowers, and relationship stage - "Trending" — Most installed this week - "New Powers" — Recently approved - "Friends Are Using" — Superpowers installed by people in your group chats - "For Your Chaos" — Category-based: Student Life, Work Survival, Social Planning, Money, Health & Habits

Card design: Each superpower card shows: - Name + emoji icon - One-line description - Creator name - Install count + average rating (stars, 1-5) - "Slot cost" badge (requires PRD 3 — most are 1 slot, complex ones are 2) - Quick install button - "Preview" tap → shows example conversation of the superpower in action

No developer jargon. No "operations," "triggers," "OAuth scopes." Users see: name, what it does, example conversation, slot cost.

3.3 Search (Low-Medium Conversion)¶

Text search in web portal and via chat command.

In-chat: User says "what superpowers can you learn?" or "find me something for budgeting" → Sage searches marketplace and presents top 3 results conversationally.

Web portal: Standard search bar with semantic matching (vector search on descriptions + tags), filtered by category.

The most powerful distribution channel. Superpowers spread through group chats. This channel requires deep link infrastructure, referral tracking, and group chat integration — targeted for Phase 3.

Sharing mechanics: - When Sage uses a superpower in a group chat (e.g., splits a bill), other participants see it in action - Any participant can ask: "Sage how did you do that?" → Sage explains and offers to teach them too - Users can share superpowers via iMessage: tap "share" on a superpower → generates a deep link → friend taps → their Sage offers to learn it - Screenshot-worthy moments: Sage's superpower responses are designed to be screenshotable — visual, funny, useful — driving organic TikTok/IG sharing

Viral loop:

User A uses Bill Split in group → 4 friends see it → 2 ask about it → 1 installs
→ That 1 user uses it in THEIR group → cycle repeats

4) Installation UX¶

In-Chat Install (Primary)¶

User: learn bill split

Sage: found it! 🧾 "Quick Split" by @KaiTheCreator
      — scan a receipt photo, split it, send Venmo links
      — uses 1 superpower slot (you have 2 open)  ← requires PRD 3
      — needs camera access (for receipt photos)

      want me to learn it?

User: yeah

Sage: ✨ learned! try sending me a receipt photo and say "split this"

Web Portal Install¶

Tap "Add to Sage" on any superpower card
If it requires OAuth scopes the user hasn't granted → inline consent flow
If no open slots → show which superpowers could be swapped out (requires PRD 3)
Confirmation: visual animation of the superpower "entering" your companion's skill set

Uninstall¶

In chat: "forget how to do bill split" → Sage confirms and removes
Web portal: tap superpower → "Remove" → confirm
Data: session state for that superpower is archived (not deleted) for 30 days, then purged

5) Categories¶

Category	Emoji	Examples
Student Life	📚	Deadline Tracker, Study Timer, GPA Calculator
Work Survival	💼	Calendar Stress, Email Scanner, Meeting Prep
Social Planning	🎉	Bill Split, Trip Planner, Group Polls, Event Coordinator
Money	💰	Budget Tracker, Spending Alerts, Subscription Manager
Health & Habits	🏃	Mood Tracker, Habit Streaks, Water Reminder, Sleep Log
Productivity	⚡	Daily Summary, Pomodoro, Task Prioritizer
Fun & Creative	🎨	Trivia, Would You Rather, Playlist Generator, Meme Finder
Utilities	🔧	Unit Converter, Timezone Helper, QR Generator

Structural enforcement: This category list is the canonical taxonomy. Categories must be stored as a database enum or reference table — not free-text string matching. Superpower submissions with unrecognized categories are rejected at submission time. Adding new categories requires a schema migration and PRD update.

6) Creator Experience¶

Who Creates Superpowers¶

Phase 1 (MVP): Internal team creates first-party superpowers + power users create via Sage conversations (vibe-coding).

Phase 2: Open marketplace submissions with review. Any user can submit.

Phase 3: Creator profiles, analytics, and eventually revenue sharing.

Submission Flow¶

User creates a superpower via Sage conversation
User says "can other people use this?" or navigates to web portal → "Publish"
Sage helps polish: better name, description, example conversation, category tag
Automated checks run:
Schema validation (all operations valid)
Security lint (no disallowed domains, proper OAuth scoping)
Dry-run sandbox test with sample inputs
Submitted to admin review queue
Admin approves (with optional feedback) or rejects (with reason)
Published → appears in marketplace

Creator Dashboard (Web Portal)¶

The Creator Dashboard is a dedicated section of the web portal — the primary interface for creators to manage and understand their superpowers. An interim lightweight version is also available in-chat via Sage.

Web Portal — Core Pages:

My Superpowers (list view): - All superpowers grouped by status: Published, Pending Review, Rejected, Suspended - Each row shows: name, category, install count, average rating, date published - Quick actions: Edit, Push Update, Unpublish, View Analytics

Superpower Detail / Analytics: - Install count (total + last 7/30 days) - Daily active users (users who triggered the superpower) - Uninstall rate (7-day and 30-day) - Average rating + rating distribution (1-5 star breakdown) - Fork count (how many remixes exist) - Simple line chart: installs over time

Version Management: - Current version displayed with publish date - "Push Update" button → opens edit flow, submission triggers re-review - Version history list with rollback option (one-click revert to any previous approved version) - Users on an older version see a non-intrusive update prompt on next use

Feedback & Reviews: - List of user ratings with optional text comments - Creator can respond to individual reviews (one response per review) - Filter by star rating, sort by recency

In-Chat Interim (via Sage): - User says "how's my superpower doing?" → Sage returns a summary: install count, average rating, any new reviews, current status - Lightweight but useful until the web portal ships

Fork & Remix¶

Users and creators can fork published superpowers to create derivative versions. This is a core creative mechanic — the marketplace is a living ecosystem, not a static catalog.

How forking works: - Any user can tap "Remix this" on a published superpower to create a copy in their own workspace - The forked superpower opens in the Sage creation flow (vibe-coding) pre-populated with the original's configuration - User modifies it to their liking — change triggers, adjust logic, add operations, rebrand it - The fork retains a visible attribution link to the original: "Remixed from Quick Split by @KaiTheCreator"

Attribution rules: - Forks always display "Remixed from [Original Name] by [Original Creator]" in the marketplace listing - Original creators can see a count of how many forks their superpower has spawned (a vanity/social proof metric) - Attribution is permanent and cannot be removed by the forking user

Safety & review: - Forked superpowers go through the same submission → automated checks → admin review pipeline as original submissions - Forks are not auto-approved even if the original was approved — modifications could introduce new risks - If the original superpower is suspended, forks are flagged for re-review but not auto-suspended (they may have diverged significantly)

Ranking: - Forks are ranked independently from the original — a well-made fork can outperform the original - The original superpower's listing shows a "Remixes" count as social proof

Rating & Feedback¶

Phase 1 — Numeric ratings: After 3 uses of a superpower, Sage asks: "how's Quick Split working for you? 👍 or 👎?" Users can leave a star rating (1-5). One rating per user per superpower, updatable. Ratings surface in marketplace cards.

Phase 2 — Text reviews with moderation: Users can add an optional text comment alongside their rating. Reviews are scanned for spam, profanity, and brigading. Creator self-reviews are blocked. Creators can respond to reviews (one response per review).

Phase 3 — Ratings feed ranking: Ratings integrate into the relevance ranking algorithm (see Section 8). Minimum 5 ratings required to qualify for ranking influence. Weighted average prevents early low-rating bias.

Creator sees aggregate ratings and individual feedback in the Creator Dashboard

7) Content Moderation & Safety¶

Automated Checks (Pre-Review)¶

Check	What It Catches
Schema validation	Malformed JSON, invalid operations, missing required fields
Security lint	Disallowed domains in `build_url`, unsafe math patterns, excessive permissions
OAuth scope audit	Apps requesting broader scopes than their operations need
Content scan	Profanity/slurs in names/descriptions, misleading claims
Complexity cap	Exceeds action/operation limits

Manual Review (Admin)¶

Reviewers check: - Does the description accurately reflect what the app does? - Are OAuth scope requests justified by the app's purpose? - Does the app handle errors gracefully (not raw API errors)? - Is the response tone appropriate for the platform? - Could the app be used to spam, harass, or extract data?

Post-Publish Monitoring¶

Apps with >20% uninstall rate within 7 days get flagged for review
Apps with >3 user reports get auto-suspended pending review
Admin can suspend any app at any time with a reason
Suspended apps are immediately disabled for all users (installed copies stop working)

Admin Authentication & Access Control¶

Marketplace admin actions (review, feature, suspend) require proper role-based access control — not hardcoded identities.

Target model: - Admin user table: Dedicated marketplace_admins table (or role column on users) mapping user IDs to admin roles - Scoped permissions: Three permission levels — reviewer (approve/reject submissions), curator (toggle featured, manage categories), admin (suspend apps, manage other admins) - Audit logging: Every admin action (approve, reject, feature, suspend) is logged with admin user ID, action, target superpower, timestamp, and reason - Authentication: Admin endpoints validate the caller's role via the existing Supabase JWT auth system — no separate auth flow needed

Trust Tiers (Future)¶

Tier	Requirements	Privileges
New Creator	First submission	Standard review, max 3 published apps
Verified Creator	3+ approved apps, >4.0 avg rating	Expedited review, max 10 published apps
Trusted Creator	10+ approved apps, >4.5 avg rating, 6+ months	Self-publish with post-review, unlimited apps

8) Marketplace Ranking & Curation¶

Default Sort: "Relevance"¶

The relevance ranking evolves in stages as data and infrastructure become available:

v0 — Heuristic (Shipped): Three static sort modes — popular (by install count), newest (by publish date), and featured (admin-curated). This is the current production behavior.

v1 — Blended Relevance: Combines install velocity (last 7 days, not all-time — prevents incumbents from dominating), recency boost (apps updated in last 30 days), and rating (weighted average, minimum 5 ratings to qualify). Requires: rating data in the database, install-timestamp indexing for velocity calculation.

v2 — Personalized Relevance: Adds semantic match to search query (vector similarity on descriptions + tags), personalization boost (categories the user engages with based on conversation history and installed superpowers), and social signals ("friends are using"). Requires: vector embeddings for superpower descriptions, user category affinity scores, group chat participant graph.

Featured / Staff Picks¶

Manually curated by admin via PUT /marketplace/admin/feature/{id}
Rotated weekly
Featured apps get:
Top placement in Explore feed
"⭐ Featured" badge
Sage mentions them in contextual recommendations

When a user's group chat participants install a superpower, it bubbles up in their feed
Privacy: only shows aggregate ("3 of your friends use this") — never names unless the friend explicitly shared

9) API Additions (Beyond Existing)¶

New Endpoints Needed¶

Endpoint	Auth	Purpose
`GET /marketplace/feed`	User	Personalized feed (Sage's Picks, Trending, Friends, etc.)
`GET /marketplace/superpowers/{id}/reviews`	None	Get ratings and reviews
`POST /marketplace/superpowers/{id}/reviews`	User	Submit rating (1-5) + optional comment
`GET /marketplace/creators/{id}`	None	Creator profile + published apps
`GET /marketplace/creators/me/analytics`	Creator	Dashboard data (installs, DAU, ratings)
`POST /marketplace/superpowers/{id}/report`	User	Flag app for review
`GET /marketplace/social/friends-using`	User	Superpowers used by group chat participants

Webhook Additions¶

superpower.installed — fires when any user installs a superpower (anonymized, for creator analytics)
superpower.uninstalled — fires on uninstall
review.submitted — fires when a review is posted

10) Success Metrics¶

Metric	Target	Timeframe
Marketplace superpowers available	50+	Month 1 (mostly first-party + templates)
User browse-to-install conversion	>15%	Month 2
In-chat recommendation → install conversion	>30%	Month 2
Social sharing → install conversion	>10%	Month 3
Creator submissions per week	10+	Month 3
Average rating of published superpowers	>4.0	Ongoing
Uninstall rate (7-day)	<25%	Ongoing
Superpowers per active user (median)	3-5	Month 3

11) Phasing¶

Phase 1: Curated Launch (Weeks 1-3)¶

20-30 first-party superpowers across all categories
In-chat discovery via capability hints extension (Sage Recommends Phase 1)
Basic web portal browse/search
Install/uninstall via chat and web
Template-based creation for power users
Category taxonomy enforced via database enum

Phase 2: Open Submissions (Weeks 4-6)¶

Vibe-coding creation flow polished
Submission → review → publish pipeline with full automated checks
Numeric ratings (1-5 stars)
Creator Dashboard web portal (My Superpowers, basic analytics, version management)
Fork/remix UX with attribution
Admin RBAC replacing hardcoded identity
Blended relevance ranking (v1 — velocity + recency + rating)

Social sharing via deep links with referral tracking
"Friends Are Using" social signals
Group chat discovery (see superpower in action → install)
Contextual recommendation engine (Sage Recommends Phase 2)
Text reviews with moderation
Creator trust tiers
Personalized relevance ranking (v2 — semantic match + personalization + social)
Advanced analytics for creators
30-day uninstall data archival and purge

Phase 4: Ecosystem (Post-MVP)¶

Revenue sharing for top creators
Sponsored/promoted placements (careful — must feel native)
Ratings feed into ranking algorithm (Phase 3 ratings)
Cross-platform: same superpowers work in Claude/ChatGPT via MCP adapter
Enterprise marketplace (private, org-scoped superpowers)

12) Differentiation vs. Existing Marketplaces¶

Feature	ClawHub / MCP Registries	App Stores	Ikiro Marketplace
Target audience	Developers	General consumers	Chat-first users (students, young adults)
Discovery	Search / CLI	Browse + search	AI recommends in conversation
Installation	`npx clawhub install X`	Tap "Get"	"yeah learn that" in chat
Creation	Write code + SKILL.md	Build native app	Chat with Sage (vibe-coding)
Trust model	Open (security issues)	Walled garden review	Admin review + sandboxed execution
Social	None	Ratings + reviews	Friends see it in action → viral
Personalization	None	Minimal	Deep — based on conversations, mood, relationship stage
Monetization	None	Paid apps	Free (progression-gated), future rev share

Feature Flags & Gating¶

Flag Key	Default	Purpose
`enable_marketplace`	`true`	Master switch for marketplace visibility
`marketplace_submissions_enabled`	`true`	Allow creators to submit superpowers
`marketplace_admin_auto_approve`	`false`	Skip admin review (dev/testing only)
`enable_marketplace_ratings`	`true`	User rating system
`marketplace_featured_count`	`10`	Number of featured superpowers on homepage

See REFERENCE_FEATURE_FLAGS.md for the full catalog.

Telemetry¶

Event	Trigger	Properties
`marketplace_browse`	User opens marketplace	`category`, `search_query`
`marketplace_view_detail`	User views a superpower listing	`superpower_id`, `source` (browse/search/featured)
`marketplace_install`	User installs from marketplace	`superpower_id`, `category`
`marketplace_uninstall`	User removes a marketplace superpower	`superpower_id`, `days_installed`
`marketplace_rate`	User rates a superpower	`superpower_id`, `rating`
`marketplace_submit`	Creator submits a superpower	`superpower_id`, `category`
`marketplace_review_complete`	Admin approves/rejects submission	`superpower_id`, `decision`, `review_time_hours`

Needed but not yet tracked: - marketplace_search_no_results — when search returns empty - marketplace_creator_funnel — track submission start → completion rate - marketplace_abuse_report — when users report a superpower

See REFERENCE_TELEMETRY.md for the full event catalog.

Definition of Done¶

Browse, search, and install flows work end-to-end with integration tests
Creator submission → admin review → publish pipeline tested
Abuse reporting mechanism available to users
Superpower versioning supports updates without breaking existing installs
Rating system prevents manipulation (one rating per user per superpower)
Marketplace telemetry fires for all browse/install/rate events
Feature flags gate marketplace visibility and submissions
Performance: marketplace browse loads within 500ms (p95)

13) Open Questions¶

Should superpowers have "try before install" (one-time sandbox use without committing a slot)?
How do we handle superpowers that overlap in functionality? (Two different bill splitters)
What's the right balance between Sage's recommendations and user autonomy? (Avoid feeling pushy)
Should enterprise orgs be able to publish private marketplace superpowers for their team only?
What is the deep link format for social sharing? (e.g., ikiro.app/power/{id}?ref={user_id})
What is the attribution window for social referral tracking?