meatbag/business/sprint_specifications.md

# WhetForge: Detailed Sprint Specifications

This document outlines the objectives, tasks, and acceptance criteria for all sprints in the WhetForge Lite-Client & Marketplace development timeline.

---

## Sprint 0: Naming & Branding (Data-Driven UX Design)

### Objectives
Select a highly compelling, developer-friendly brand name and visual identity for the generic Lite-Client Platform and Marketplace. Use data-driven research to evaluate name options based on brand recall, developer trust, and clarity of purpose.

### Task List
1. **Run the Naming UX Research**: Execute the Deep Research prompt (found below) to analyze name categories and semantic viability.
2. **Shortlist and Domain Search**: Narrow down to 3 final name candidates and verify domain availability (.dev, .app, .com) and App Store search conflicts.
3. **Design System Tokens**: Define the core color palette (cyberpunk/modern contrast), custom Google Font pairing (Inter/Outfit), and rounded corner token rules.
4. **Product Branding Copy**: Write the marketplace landing page header, tagline, and value proposition statement.

### Acceptance Criteria
* A final, trademark-clear name is selected.
* Domain names and social handles are acquired or reserved.
* A core visual style guide (palette, typography, logo guidelines) is established.

---

### Gemini Deep Research Prompt: Naming & Branding UX Report
Copy and paste this prompt into Gemini Deep Research to generate a data-driven naming and branding analysis:

```text
Please perform a comprehensive UX Research and Branding Assessment to determine the optimal brand name and visual identity for a new developer platform.

### 1. Product Description
- The product is a generic, developer-facing Server-Driven UI (SDUI) "Lite-Client" platform and marketplace.
- It allows developers to build native smartwatch (Wear OS/watchOS), mobile, and TV dashboard widgets using a drag-and-drop builder which exports to serialized JSON configs.
- The parent business is called "WhetForge". The first reference application built on it is called "Meatbag" (satirical haptic AI agent approval manager).
- The marketplace and platform need a standalone name that is clean, professional, developer-focused, and less edgy than "Meatbag".

### 2. Naming Research Tasks
- **Semantic Mapping**: Analyze name candidates in three distinct semantic categories:
  1. *Action/Utility-focused* (e.g., DashCast, ShellPress, Viewport, Panelist).
  2. *Metaphorical/Technical* (e.g., Canvas, Blueprint, Outline, GridForge, Castway).
  3. *Short/Abstract* (e.g., Velo, Koda, Shell, Outlay).
- **Competitor Analysis**: Evaluate naming strategies of adjacent platforms (e.g., Raycast, Retool, Expo, FlutterFlow, Home Assistant, n8n). What linguistic patterns (e.g., suffix, compound word, portmanteau) command the highest trust among developers?
- **Developer Psychological Sentiment**: Research what types of names rank highest for developer trust, open-source alignment, and ease of pronunciation.
- **Search Engine Optimization (SEO)**: Highlight potential keyword conflicts, search term dilution, and target domain acquisition strategies.

### 3. Visual & UX Branding Tasks
- Analyze color psychology trends in modern developer tooling (e.g., the rise of dark modes, high-contrast neon accents like teal/purple, glassmorphism). Recommend 3 distinct color palettes with hex codes.
- Recommend modern font pairings (headers and body) that optimize readability on tiny smartwatch screens and large TV screens.

### 4. Required Deliverables
1. **Top 5 Name Recommendations**: With semantic explanations, developer-trust ratings, and trademark feasibility.
2. **Linguistic Competitor Map**: Visualization of adjacent developer tools' naming structures.
3. **3 Visual Identity Palettes**: Complete with colors, fonts, and layout recommendations.
4. **Tagline Generation**: 5 potential taglines for the developer-facing marketplace homepage.
```

---
    
## Sprint 1: Native Wearable & Mobile Polish

### Objectives
Optimize the stateless client shells on physical Android S23 Ultra and Wear OS Watch7 devices for battery efficiency, haptic response, and connection reliability.

### Task List
1. **Background Connection Handler**: Implement persistent background heartbeat sockets to prevent connection drops when screens turn off.
2. **Haptic Profile Configurations**: Calibrate physical vibration patterns on the Galaxy Watch7 for the four attention tiers (Silent, Low, Medium, High).
3. **Smartwatch Always-On Display (AOD)**: Implement ambient mode callbacks to auto-convert active layouts to low-power desaturated views.
4. **Physical Touch Targets**: Adjust button heights and margins in `MeatbagComponentHost` specifically for round watch screens to prevent layout clipping.

### Acceptance Criteria
* The app successfully maintains connection for 1+ hour in background mode on S23 Ultra.
* Smartwatch haptics trigger unique, distinct vibration patterns for different alert tiers.
* The client shell automatically changes themes when the watch enter AOD/ambient mode.

---

## Sprint 1.5: Dynamic Shortcuts & Dynamic Branding (Mobile Launcher Routing)

### Objectives
Enable the single pre-compiled client shell to behave like separate, standalone apps for different marketplace profiles by dynamically pinning launcher shortcuts and routing intent payloads.

### Task List
1. **ShortcutManager Integration**: Implement native Android `ShortcutManager` calls in `MainActivity` to request pinning shortcuts with custom names and icons.
2. **Intent Launch Routing**: Update `MainActivity` entry point to intercept `LAUNCH_PROFILE_ID` extra, skipping the manager settings dashboard.
3. **Dynamic Theme Styling**: Map loaded profile IDs to dynamic theme color palettes (e.g. Purple for LM Studio, Teal for Meatbag).
4. **Local Dashboard Tiles**: Build a tile selector in the disconnected manager interface listing installed profiles with options to "Launch" or "Pin Tile".

### Acceptance Criteria
* Clicking "Pin Tile" displays the Android system shortcut confirmation dialog.
* Launching the app via pinned shortcut bypasses settings and connects automatically.
* Toggling between profiles dynamically changes the application primary/secondary theme colors.

---

## Sprint 2: Builder Porting & Responsive Design

### Objectives
Port the visual editor layout screen from the desktop simulator to the shared code module and design the mobile-responsive phone view.

### Task List
1. **Common Code Migration**: Move `UIBuilderScreen` from `:client/desktopMain` to `:client/commonMain`.
2. **Responsive Screen Detection**: Use `BoxWithConstraints` to detect viewport width and branch layouts between Mobile and Desktop.
3. **Mobile Layout Builder**: Implement `MobileUIBuilderLayout` utilizing a split-pane layout: Watch Preview on top, Editor card on the bottom.
4. **Developer Mode (Tabs)**: Expose the tabbed properties forms inside the mobile editor card.
5. **Easy Mode (Wizard)**: Build a guided step-by-step assistant for quick layout generation.
6. **Layout Mode Toggle**: Add a header switch in the builder UI to transition between Developer and Easy modes.

### Acceptance Criteria
* The visual builder renders and operates correctly on both desktop and mobile screen sizes.
* Toggling between Developer (Tabs) and Easy (Wizard) modes instantly restructures the property configuration controls.
* Output JSON matches the shared serialization schema.

---

## Sprint 3: Local Sync API & Database Caching

### Objectives
Connect the local Ktor server to support local profile caching, enabling layouts to load dynamically from the local database.

### Task List
1. **SQLite Database Update**: Add a `profiles` table to the local `meatbag.db` storing layout ID, layout JSON, and sync timestamp.
2. **Ktor Sync API**: Build the `/api/profiles/sync` POST endpoint to ingest visual configurations from the builder and write them to SQLite.
3. **Local Layout Loader**: Implement lookup logic in the shell client to dynamically resolve and render profiles cached in the local database.
4. **CLI Integration**: Update `meatbag.py ask` to support requesting a layout by ID (e.g. `python meatbag.py ask --profile git_commit`).

### Acceptance Criteria
* Syncing from the visual builder correctly saves the JSON config to the local SQLite database.
* The client shell can load and draw cached layouts on the fly without web browser execution.
* The CLI tool can trigger complex layouts via profile IDs instead of raw text prompts.

---

## Sprint 4: Marketplace Backend & Authentication

### Objectives
Launch the centralized global marketplace server using Ktor and Postgres to handle developer registrations and profile uploads.

### Task List
1. **Marketplace Module Setup**: Initialize the `:marketplace` module in the Gradle configuration.
2. **Postgres Database Schema**: Define database tables using Kotlin Exposed ORM (Users, Developer Profiles, Marketplace Layouts, Purchases).
3. **JWT Authentication**: Integrate `ktor-auth-jwt` to handle user signups, logins, and API token generation.
4. **Upload Endpoint**: Implement `POST /api/v1/marketplace/publish` allowing developers to upload JSON layouts directly from the visual builder.
5. **Search API**: Implement `GET /api/v1/marketplace/profiles` enabling clients to browse available templates.

### Acceptance Criteria
* Users can sign up, log in, and receive secure JWT tokens.
* Developers can publish layouts from the builder directly to the global marketplace database.
* Layout schemas are validated on the server side prior to saving.

---

## Sprint 5: Billing & Stripe Integration

### Objectives
Integrate Stripe Checkout and webhooks to monetize layout profiles on the web store.

### Task List
1. **Stripe SDK Configuration**: Configure the Stripe Java SDK on the marketplace server.
2. **Stripe Checkout API**: Implement `/api/v1/checkout/session` to generate payment links for premium layouts.
3. **Stripe Webhook Listener**: Build `/api/v1/webhooks/stripe` to handle asynchronous charge events and record successful purchases.
4. **Purchase Model**: Implement the purchases verification table in PostgreSQL mapping user accounts to purchased profile IDs.

### Acceptance Criteria
* Tapping purchase on the web store successfully redirects to a secure Stripe Checkout session.
* Completing payment triggers the Stripe Webhook, writing the transaction to Postgres.
* User account instantly gains access to the purchased profile.

---

## Sprint 6: In-App Purchases & Beta Release

### Objectives
Integrate native mobile billing libraries, submit the shells to the public app stores, and launch the platform.

### Task List
1. **Google Play Billing**: Integrate Google Play In-App Purchases into the Android and Wear OS shells.
2. **Apple StoreKit**: Integrate Apple In-App Purchases into the iOS and watchOS shells.
3. **Store Submissions**: Prepare assets, privacy policies, and submit the Lite-Client Shells to the App Store and Google Play.
4. **Beta Launch**: Initiate the marketing campaign for "Meatbag" (the AI-agent confirmation reference app) to drive developer signups.

### Acceptance Criteria
* Purchases made inside the mobile app successfully process via Apple/Google billing.
* Client shells are live and downloadable from the public App Store and Google Play.
* AI agents can successfully route haptic prompts to active smartwatch users globally.