Vibes is for people who use Claude Code, but don't know how to code.

version
0.2.151
GitHub stars
135

Install

/plugin install vibes@VibesOS

Run it inside Claude Code after adding the marketplace with /plugin marketplace add popmechanic/VibesOS.

Contents

Discovered from source

Skills 8

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:cloudflare". Do not decompose the steps below into separate plan tasks.

  ╔═══════════════════════════════════════════════╗
  ║   ☁️  CLOUDFLARE WORKERS DEPLOY               ║
  ║   Deploy API · Pocket ID · Edge Functions      ║
  ╚═══════════════════════════════════════════════╝

Deploy to Cloudflare

Deploy your Vibes app to Cloudflare Workers via the Deploy API.

Prerequisites

  1. Assembled HTML file (from /vibes:vibes or /vibes:factory)
  2. Vibes account (browser login on first deploy)

No Cloudflare account or wrangler CLI needed — the Deploy API handles infrastructure.

Quick Deploy

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/deploy-cloudflare.js" --name myapp --file index.html

On first run, a browser window opens for Pocket ID authentication. Tokens are cached for subsequent deploys.

Static Assets: Place images, fonts, or other static files in an assets/ directory next to the app file. The deploy script auto-discovers and includes them (binary files are base64-encoded). Reference in code with absolute paths like /assets/logo.png.

Deploy with AI enabled

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/deploy-cloudflare.js" --name myapp --file index.html --ai-key "sk-or-v1-your-key"

The --ai-key flag configures the OpenRouter API key for the useAI() hook. Without it, /api/ai/chat returns {"error": "AI not configured"}.

Endpoints

EndpointMethodDescription
/registry.jsonGETPublic registry read
/check/:subdomainGETCheck subdomain availability
/claimPOSTClaim a subdomain (auth required)
/api/ai/chatPOSTAI proxy to OpenRouter (requires AI key)

Important: Custom Domain Required for Subdomains

Workers.dev domains only support one subdomain level for SSL. For multi-tenant apps with subdomains (tenant.myapp.workers.dev), you MUST use a custom domain.

Won't work: tenant.myapp.username.workers.dev (SSL error) Will work: tenant.myapp.com (with custom domain)

On workers.dev, use the ?subdomain= query parameter for testing:

  • myapp.username.workers.dev → landing page
  • myapp.username.workers.dev?subdomain=tenant → tenant app
  • myapp.username.workers.dev?subdomain=admin → admin dashboard

Custom Domain Setup

  1. Add domain to Cloudflare (get nameservers from Cloudflare DNS dashboard)
  2. Point registrar nameservers to Cloudflare's assigned nameservers
  3. Delete conflicting DNS records for the apex domain (A, AAAA, CNAME)
  4. Add Custom Domain in Workers & Pages → your worker → Settings → Domains & Routes → Add → Custom Domain (apex: yourdomain.com)
  5. Add wildcard CNAME in DNS: Name: *, Target: <worker-name>.<username>.workers.dev (Proxied: ON)
  6. Add Route in Workers & Pages → your worker → Settings → Domains & Routes → Add → Route: *.yourdomain.com/*

After setup:

  • yourdomain.com → landing page
  • tenant.yourdomain.com → tenant app
  • admin.yourdomain.com → admin dashboard

Troubleshooting

ProblemCauseFix
Browser doesn't open for authHeadless environmentCopy the printed URL and open manually
Deploy API returns 401Expired or invalid tokenDelete ~/.vibes/auth.json and retry
404 on subdomain URLWorkers.dev doesn't support nested subdomainsSet up a custom domain (see Custom Domain Setup above)
/api/ai/chat returns "AI not configured"Missing OpenRouter keyRedeploy with --ai-key
Stale content after redeployBrowser cacheHard refresh (Cmd+Shift+R) or clear cache

What's Next?

After successful deployment, present these options:

AskUserQuestion: question: "Your app is deployed! What would you like to do next?" header: "Next steps" options: - label: "Set up custom domain" description: "Configure DNS for subdomain routing (required for multi-tenant)" - label: "Enable AI features" description: "Add OpenRouter API key for the useAI() hook" - label: "Add auth & SaaS features" description: "Transform into SaaS with /vibes:factory, then redeploy" - label: "Open in browser" description: "Visit the deployed URL to verify everything works"

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:design". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓███████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░▒▓█▓▒░░▒▓██████▓▒░░▒▓███████▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓██████▓▒░  ░▒▓██████▓▒░░▒▓█▓▒░▒▓█▓▒▒▓███▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓███████▓▒░░▒▓████████▓▒░▒▓███████▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░

Design Reference Transformer

Transform a complete design reference HTML file into a working Vibes app with TinyBase reactive data.


Core Principle

Preserve and adapt, don't interpret and recreate.

The design reference is source code to transform, not inspiration to interpret. When given a complete HTML file with styles, your job is to make minimal surgical changes to connect it to React/TinyBase—not to recreate it from your understanding of its aesthetic.


When to Use This Skill

Use this skill when:

  • User provides a design.html, mockup, or static prototype file
  • User says "match this design exactly" or "use this as a reference"
  • User wants their existing HTML converted to a Vibes app
  • A previous implementation didn't match the design reference

The Transformation is Mechanical

The conversion from design HTML to React/TinyBase is deterministic, not creative:

TransformationRuleExample
Attributesclass → classNameclass="btn" → className="btn"
Attributesfor → htmlForfor="email" → htmlFor="email"
Attributeskebab-case → camelCasestroke-width → strokeWidth
Self-closingAdd explicit close<input> → <input />
CommentsHTML → JSX<!-- x --> → {/* x */}
Inline stylesString → Objectstyle="color: red" → style={{ color: 'red' }}
Event handlersLowercase → camelCaseonclick → onClick

CSS requires NO changes. Copy the entire <style> block verbatim.


Workflow

Step 1: Read the Design Reference

# Read the design file completely
Read design.html

Note the structure:

  • <style> block (copy verbatim)
  • HTML structure (preserve exactly)
  • Any vanilla JavaScript (will be replaced with React)

Step 2: Identify Dynamic Content

Ask: "What content comes from the database?"

Typical dynamic elements:

  • List items that repeat (.map())
  • Text that users enter (controlled inputs)
  • Counts, totals, timestamps
  • User-specific content

Everything else stays static.

Step 3: Create the React Component

function App() {
  // TinyBase hooks are globals — no imports, no initialization call needed
  const rowIds = useRowIds('items');
  const handleAdd = useAddRowCallback('items', (e) => ({
    text: '', type: 'item', created: Date.now()
  }));

  return (
    <>
      {/* CSS copied VERBATIM from design.html */}
      <style>{`
        /* Paste entire <style> block here unchanged */
      `}</style>

      {/* HTML structure preserved, only syntax converted */}
      {/* Dynamic content replaced with {expressions} */}
    </>
  );
}

Step 4: Handle Dark Mode Override (If Needed)

The Vibes template has dark mode support. If your design is light-only, add this CSS override:

/* Force light theme regardless of system preference */
html, body, #container, #container > div {
    background-color: var(--your-bg-color) !important;
}

Note: Avoid targeting [style*="position: fixed"] as this will style the VibesSwitch toggle button.

Step 4b: Scope CSS to Avoid VibesSwitch/VibesPanel Conflicts

The template includes a VibesSwitch toggle button and VibesPanel admin menu that sit outside your app container. Broad CSS selectors can accidentally style these components.

Watch for these problematic patterns:

ProblematicWhySafe Alternative
button { ... }Styles VibesSwitch toggle.app button { ... } or #container button { ... }
* { ... } (with colors/backgrounds)Cascades everywhereScope to specific containers
[style*="position: fixed"]Targets VibesSwitchTarget by class/ID instead
body > divMay match menu wrapperUse #container > div

If your design has global button/element styles:

  1. Wrap your app content in a container with a class: <div className="app">...</div>
  2. Scope broad rules: button { } → .app button { }
  3. Or use #container which is the template's app root

The template already protects components with:

button[aria-controls="hidden-menu"] { background: transparent !important; }
#hidden-menu { /* menu-specific variable resets */ }

But defense-in-depth is better—scope your CSS to avoid conflicts.

Step 5: Assemble and Test

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/assemble.js" app.jsx index.html

Open in browser and visually diff against the design reference. They should be pixel-identical except for dynamic content.


Anti-Patterns (DO NOT DO THESE)

Anti-PatternWhy It's WrongCorrect Approach
Translate colors to OKLCHChanges the designUse exact hex values from reference
Restructure HTML "for React"Breaks layoutPreserve structure, only change syntax
"Improve" the CSSNot your jobCopy verbatim
Add your own classesIntroduces driftUse exact classes from reference
Interpret the "vibe"Creates divergenceBe literal, not interpretive
Skip vanilla JS analysisMiss functionalityUnderstand what it does, then React-ify

Transformation Checklist

Before writing code, verify:

  • Read the entire design.html file
  • Identified all <style> blocks (will copy verbatim)
  • Identified dynamic content (lists, inputs, user data)
  • Identified vanilla JS functionality (will convert to React)
  • Noted any custom fonts (add to imports if needed)
  • Checked for dark/light theme assumptions

During transformation:

  • CSS pasted unchanged (no "improvements")
  • HTML structure preserved exactly
  • Only syntax converted (class→className, etc.)
  • Dynamic content uses {expressions} and .map()
  • Vanilla JS replaced with React hooks and handlers
  • Dark mode override added if design is light-only

After assembly:

  • Visual comparison with design reference
  • All interactive elements work
  • Data persists on refresh
  • No console errors
  • VibesSwitch toggle (bottom-right) displays correctly with no background box
  • VibesPanel menu opens when toggle is clicked
  • Menu buttons are correctly styled (not inheriting app button styles)

Example: Static List → Dynamic List

Design HTML:

<ul class="item-list">
  <li class="item">First item</li>
  <li class="item">Second item</li>
</ul>

React with TinyBase:

const rowIds = useRowIds('items');

<ul className="item-list">
  {rowIds.map(id => (
    <ItemRow key={id} id={id} />
  ))}
</ul>

// Child component uses useCell for reactive per-row data
function ItemRow({ id }) {
  const text = useCell('items', id, 'text');
  return <li className="item">{text}</li>;
}

Note: Only the content changed. The classes, structure, and styling are identical.


Example: Static Form → Controlled Form

Design HTML:

<form>
  <input type="text" class="input" placeholder="Enter text...">
  <button class="btn">Submit</button>
</form>

React with TinyBase:

const [text, setText] = useState('');
const handleAdd = useAddRowCallback('items', () => ({
  text, type: 'item', created: Date.now()
}));

<form onSubmit={(e) => { e.preventDefault(); handleAdd(); setText(''); }}>
  <input
    type="text"
    className="input"
    placeholder="Enter text..."
    value={text}
    onChange={(e) => setText(e.target.value)}
  />
  <button type="submit" className="btn">Submit</button>
</form>

Note: Same structure, same classes, same placeholder. Only added React bindings.


Integration with Vibes Assembly

This skill produces an app.jsx that works with the standard Vibes assembly:

# In the working directory
VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/assemble.js" app.jsx index.html

The assembly script:

  • Inserts your JSX into the Vibes template
  • Handles OIDC authentication wrapper (via Pocket ID)
  • Sets up import maps for React and TinyBase
  • Configures sync URLs if present (auth is automatic via Pocket ID)

What's Next?

After transforming a design reference, present these options using AskUserQuestion:

Question: "Design reference transformed! What's next?"
Header: "Next"
Options:
- Label: "Test locally"
  Description: "Open index.html in browser to verify it matches the design exactly"

- Label: "Deploy to Cloudflare (/cloudflare)"
  Description: "Push the app live to Cloudflare Workers"

- Label: "Make adjustments"
  Description: "Fine-tune specific elements while preserving the design"

- Label: "I'm done"
  Description: "Wrap up - files are saved locally"

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:factory". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓████████▓▒░░▒▓██████▓▒░ ░▒▓██████▓▒░▒▓████████▓▒░░▒▓██████▓▒░░▒▓███████▓▒░░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ ░▒▓█▓▒░  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░         ░▒▓█▓▒░  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
░▒▓██████▓▒░ ░▒▓████████▓▒░▒▓█▓▒░         ░▒▓█▓▒░  ░▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░  ░▒▓██████▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░         ░▒▓█▓▒░  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░  ░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░  ░▒▓█▓▒░  ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░  ░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░   ░▒▓█▓▒░  ░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░   ░▒▓█▓▒░

Quick Navigation


CRITICAL RULES - READ FIRST

DO NOT generate code manually. This skill uses pre-built scripts and API calls:

StepToolWhat it does
Assemblyassemble-factory.jsGenerates unified index.html
Deploydeploy-cloudflare.jsDeploys to Cloudflare Workers
ConfigurePOST /app/configureStores billing config in KV
InitializePOST /token/:appName/initializeSets up Vibe Token economics
GrantPOST /token/:appName/grantGrants tokens to partners

Script location:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"

Factory API base: https://factory.vibesos.com


Factory - App Monetization Pipeline

Transform your Vibes app into a revenue-generating SaaS with token-backed contributor rewards.

Architecture

The factory skill sets up:

  • Stripe Subscriptions — flat monthly price + metered AI token billing
  • Vibe Token Economics — revenue-sharing tokens for distribution partners
  • Factory Dashboard — manage tokens, view revenue, process payouts

All configuration is stored in the factory worker. Token state lives in a Durable Object per app.


Terminal or Editor UI?

Detect whether you're running in a terminal (Claude Code CLI) or an editor. Terminal agents use AskUserQuestion for all input. Editor agents present requirements as a checklist comment, wait for user edits, then proceed. See the vibes skill for the full detection and interaction pattern.

Step 1: Pre-Flight

Before starting, verify these prerequisites. STOP if any check fails.

1.1 Auth Check

Auth is automatic — on first deploy, a browser window opens for Pocket ID login. Tokens are cached at ~/.vibes/auth.json for subsequent deploys.

1.2 Detect Existing App

ls -la app.jsx 2>/dev/null || echo "NOT_FOUND"

Decision tree:

  • Found app.jsx -> Proceed to Step 2
  • Found multiple riff-*/app.jsx -> Ask user to select one
  • Found nothing -> Tell user to run /vibes:vibes first

1.3 Check Existing Config

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
APP_NAME="${1:-}"
if [ -n "$APP_NAME" ]; then
  curl -s "https://factory.vibesos.com/connect/status/$APP_NAME" \
    -H "Authorization: Bearer $(cat ~/.vibes/auth.json | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")" 2>/dev/null
fi

If the app already has billing configured, offer to update or show current config.

1.4 Pre-Flight Summary

"Pre-flight checks passed:

  • App found (app.jsx)
  • Auth is automatic via Pocket ID

Ready to configure your app factory."


Step 2: Subscription Pricing

Use AskUserQuestion:

Question 1: "What should your app cost per month?"
Header: "Monthly Price"
Options:
- "$5/month"
- "$10/month"
- "$25/month"
- Other (enter custom amount)
Description: "This is the flat monthly subscription price. AI token usage is billed separately."

Question 2: "Offer a free trial?"
Header: "Free Trial"
Options:
- "No trial"
- "7-day trial"
- "14-day trial"
Description: "Trial lets users try before paying. Stripe handles the trial period automatically."

Store: price (number, dollars), trialDays (number, 0/7/14)


Step 3: AI Token Billing

Use AskUserQuestion:

Question: "Does your app use AI features?"
Header: "AI Billing"
Options:
- Label: "No AI features"
  Description: "Skip AI billing setup"
- Label: "Yes, 2x margin (recommended)"
  Description: "Customers pay 2x the model cost. You keep the difference."
- Label: "Yes, 3x margin"
  Description: "Higher margin, customers pay 3x model cost."
- Label: "Yes, custom margin"
  Description: "Enter your own multiplier."

If AI is enabled, explain:

"OpenRouter routes to the underlying provider; the factory worker meters token usage per customer and posts events to a shared Stripe Billing Meter. Your customers will see AI usage as a line item on their monthly invoice alongside the flat subscription fee."

Store: aiMarginPercent (number: 0 for no AI, 200 for 2x, 300 for 3x, etc.)


Step 4: Vibe Token Configuration

Use AskUserQuestion:

Question: "What percentage of revenue should flow to token holders? This is locked forever."
Header: "Revenue Share (Alpha)"
Options:
- "10% — Conservative"
- "15% — Balanced"
- "20% — Generous (recommended)"
- "25% — Very generous"
- Other (enter custom %)
Description: "Alpha determines how much of each invoice goes to Vibe Token holders. Higher alpha = more attractive to partners, but less developer take-home. This cannot be changed after launch."

Store: alpha (number, 0.10-0.50)

Auto-calculate remaining parameters:

const k = Math.max((price * 12) / 10_000_000, 0.005);
const preMint = Math.round(100 * price * 12);
const initialPrice = k * Math.sqrt(1000); // price at s_min

Show summary and confirm:

Use AskUserQuestion:

Question: "Confirm these token economics? (This is permanent)"
Header: "Token Summary"
Options:
- "Confirm and proceed"
- "Go back and adjust"
Description: |
  Revenue Share: {alpha*100}%
  Pricing Constant (k): {k}
  Treasury Size: {preMint} tokens
  Initial Token Price: ${initialPrice.toFixed(4)}
  Formula: P = {k} * sqrt(supply)

  At 100 subscribers ($X/mo each):
  - Monthly revenue: ${price * 100}
  - Token holder pool: ${Math.floor(alpha * price * 100 * 100)/100}
  - Token price: ${(k * Math.sqrt(1000 + preMint * 0.1)).toFixed(4)}

Step 5: Stripe Connect Onboarding

Get the auth token:

TOKEN=$(cat ~/.vibes/auth.json | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])" 2>/dev/null || echo "")

Create Stripe Connect account:

curl -s -X POST "https://factory.vibesos.com/connect/onboard" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"appName\": \"$APP_NAME\"}"

Expected response: { "ok": true, "url": "https://connect.stripe.com/...", "accountId": "acct_..." }

Open the onboarding URL in the user's browser:

open "$ONBOARD_URL"  # macOS

Poll for completion:

while true; do
  STATUS=$(curl -s "https://factory.vibesos.com/connect/status/$APP_NAME" \
    -H "Authorization: Bearer $TOKEN")
  COMPLETE=$(echo "$STATUS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('complete', False))")
  if [ "$COMPLETE" = "True" ]; then
    echo "Stripe Connect onboarding complete!"
    break
  fi
  sleep 5
done

Store: stripeConnectAccountId from the response


Step 6: Deploy

6.1 Store Billing Configuration

curl -s -X POST "https://factory.vibesos.com/app/configure" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"appName\": \"$APP_NAME\",
    \"stripeConnectAccountId\": \"$ACCOUNT_ID\",
    \"price\": $PRICE,
    \"aiMarginPercent\": $AI_MARGIN,
    \"vibeToken\": {
      \"alpha\": $ALPHA,
      \"k\": $K,
      \"preMint\": $PREMINT
    }
  }"

6.2 Assemble Factory App

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/assemble-factory.js" app.jsx index.html \
  --app-name "$APP_NAME" \
  --app-title "$APP_TITLE" \
  --domain "$APP_NAME.vibesos.com" \
  --tagline "$TAGLINE" \
  --subtitle "$SUBTITLE" \
  --billing-mode "required" \
  --features "$FEATURES_JSON" \
  --admin-ids '[]'

6.3 Deploy to Cloudflare

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/deploy-cloudflare.js" \
  --name "$APP_NAME" \
  --file index.html

6.4 Initialize Vibe Token Engine

curl -s -X POST "https://factory.vibesos.com/token/$APP_NAME/initialize" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

The initialize endpoint reads the billing config from KV and creates the VibeTokenDO with the correct alpha, k, and preMint values.

6.5 Verify Deployment

curl -s -o /dev/null -w "%{http_code}" "https://$APP_NAME.vibesos.com"

Expected: 200


Step 7: Generate Invite Codes (Optional)

Use AskUserQuestion:

Question: "Would you like to generate invite codes for distribution partners now?"
Header: "Distribution Partners"
Options:
- Label: "Yes, generate invites"
  Description: "Create shareable codes that grant Vibe Tokens to whoever claims them."
- Label: "Skip for now"
  Description: "You can generate codes later from the dashboard."

If generating invites:

Use AskUserQuestion (repeatable):

Question: "How many tokens should this invite grant?"
Header: "Invite tokens"
Options:
- "500 tokens"
- "1000 tokens"
- "2500 tokens"
- Other (enter amount)

For each invite, call the API:

RESULT=$(curl -s -X POST "https://factory.vibesos.com/invite/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"appName\": \"$APP_NAME\", \"tokens\": $TOKEN_AMOUNT}")

CODE=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['code'])")
URL=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
echo "Share this URL: $URL"

Output:

Invite 1: {CODE} — {TOKENS} tokens
  Claim URL: {URL}

Completion Summary

Present the final summary:

Your app factory is live!

App URL: https://{appName}.vibesos.com Dashboard: https://factory.vibesos.com/dashboard/apps/{appName}

Configuration:

  • Monthly price: ${price}/mo
  • AI margin: {aiMarginPercent}%
  • Revenue share (alpha): {alpha*100}%
  • Treasury: {preMint} tokens
  • Token price: ${initialPrice.toFixed(4)}

What happens next:

  • Customers subscribe at your landing page
  • Revenue auto-distributes to token holders
  • Referrers earn new tokens from customers they bring
  • Monthly payouts transfer earnings to Stripe Connect accounts
  • Manage everything at the dashboard

What's Next?

Question: "Your factory is deployed! What would you like to do?"
Header: "Next"
Options:
- Label: "Open dashboard"
  Description: "View your app at factory.vibesos.com/dashboard"
- Label: "Grant more tokens"
  Description: "Invite additional distribution partners"
- Label: "Customize landing page"
  Description: "Adjust colors, tagline, and features"
- Label: "I'm done for now"
  Description: "Your factory is live and accepting customers"

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:launch". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓█▓▒░      ░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░░▒▓██████▓▒ ░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░     ░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░     ░▒▓████████▓▒░
░▒▓█▓▒░      ░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░     ░▒▓█▓▒░░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░     ░▒▓█▓▒░░▒▓█▓▒░
░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░▒▓█▓▒░░▒▓█▓▒░

Notation

Ask [Header]: "question" means call AskUserQuestion with that header and question. Options listed as bullets. User can always type custom via "Other".

For architecture context, see LAUNCH-REFERENCE.md in this directory.


FIRST: Terminal or Editor UI?

This is the very first question — ask before anything else. DO NOT check .env, credentials, or project state before asking this question. DO NOT invoke any other skill before asking this question. If Editor is chosen, skip ALL remaining steps — the editor handles everything.

Ask the user:

"How do you want to build? Editor (opens a browser UI with live preview, chat, and deploy button) or Terminal (I'll generate and deploy from here)?"

Present Editor as the first/recommended option.

  • If Editor: Start the editor server and END YOUR TURN. Do not ask any more questions. Do not continue to Phase 0 or any phase below. The editor UI handles the entire workflow — setup, generation, preview, deploy.

    Launch the editor server:

    VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
    bun "$VIBES_ROOT/scripts/server.ts" --mode=editor --prompt "USER_PROMPT_HERE"
    

    If no prompt was given, omit --prompt:

    VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
    bun "$VIBES_ROOT/scripts/server.ts" --mode=editor
    

    Tell the user: "Open http://localhost:3333 — the editor handles everything from here." Your job is done. Stop. Do not read further. Do not proceed to any phase below.

  • If Terminal: Continue with the workflow below.


⛔ EVERYTHING BELOW IS TERMINAL MODE ONLY

If the user chose Editor above, STOP. Do not read or execute anything below this line. The editor UI handles setup, generation, preview, and deployment.


Auth Check (Terminal mode only — silent unless needed)

Check for cached auth. Editor mode handles auth in the browser, so this only runs for Terminal:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun --input-type=module -e "
import { readCachedTokens, isTokenExpired } from '$VIBES_ROOT/scripts/lib/cli-auth.js';
const tokens = readCachedTokens();
if (tokens && !isTokenExpired(tokens.expiresAt)) {
  console.log('AUTH_OK');
} else {
  console.log('AUTH_NEEDED');
}
"
  • If AUTH_OK → proceed silently (do not mention auth)
  • If AUTH_NEEDED → ask: "To deploy apps, you'll need a Vibes account. Sign in now? (A browser window will open for Pocket ID — takes about 10 seconds.)"
    • If yes:
      VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
      bun --input-type=module -e "
      import { getAccessToken } from '$VIBES_ROOT/scripts/lib/cli-auth.js';
      import { OIDC_AUTHORITY, OIDC_CLIENT_ID } from '$VIBES_ROOT/scripts/lib/auth-constants.js';
      const tokens = await getAccessToken({ authority: OIDC_AUTHORITY, clientId: OIDC_CLIENT_ID });
      if (tokens) console.log('Signed in successfully!');
      "
      
      Confirm success, then continue.
    • If no → proceed anyway (auth will be needed at deploy time)

Pre-Flight Check

Only one check before collecting input:

#CheckCommandIf True
1app.jsx existstest -f app.jsxAsk [Reuse]: "app.jsx exists. Reuse it or regenerate?" If reuse: skip T1.

Auth and deploy credentials are handled automatically — no user setup needed. On first deploy, a browser window opens for Pocket ID login. Tokens are cached at ~/.vibes/auth.json.

Phase 0: Collect Inputs

0.1 App Prompt

Ask [App prompt]: "What do you want to build? Describe the app you have in mind."

  • "Todo list" — A simple task manager with categories and due dates
  • "Photo gallery" — A shareable photo gallery with albums and captions
  • "Team dashboard" — A metrics and status dashboard for small teams

Store as appPrompt.

0.2 App Name

Ask [App name]: "What's the app name? (used for subdomain + database)"

  • "Derive from prompt" — Generate a URL-safe slug automatically
  • "Let me specify" — I'll type my own name

If "Derive from prompt": generate URL-safe slug (lowercase, hyphens, max 30 chars). Store as appName.

0.3 AI Features (conditional)

Scan appPrompt for AI keywords: "chatbot", "chat with AI", "summarize", "generate", "analyze", "AI-powered", "intelligent".

If detected: Ask [AI features]: "Does this app need AI features?"

  • "Yes — I have an OpenRouter key" — I'll paste my API key
  • "Yes — I need to get one" — I'll sign up at openrouter.ai
  • "No AI needed" — Skip AI capabilities

If yes: check grep OPENROUTER_API_KEY ~/.vibes/.env. If found, offer reuse (mask key). Otherwise collect via Ask and offer to cache to ~/.vibes/.env. Store as openRouterKey (or null if no AI).

0.4 SaaS Config

Factory config is collected here but applied later by the assembly script. Do NOT hand-implement SaaS logic — the factory assembly handles tenant routing, auth gating, and billing.

Choose billing mode based on monetization intent:

  • "off" (free) — all authenticated users get full access. Good for MVPs and internal tools.
  • "required" (subscription) — users must subscribe. Stripe billing integration is phase 2.

Always ask the user — do not assume a default.

Ask [Billing]: "What billing mode for your SaaS?" AND [Title]: "App display title?"

  • Billing: "Free (no billing)" or "Subscription required"
  • Title: "Derive from app name" or "Let me specify"

Ask [Tagline]: "Describe your app's tagline (short punchy phrase)"

  • "Generate one" — Create from app description
  • "Let me write it" — I'll provide it

When billing is "required": These fields appear on a pricing section visible to potential customers before signup. Optimize for marketing copy quality — benefit-driven language, not technical descriptions. Tagline = sales headline. Subtitle = value proposition ("why should I pay?"). Features = compelling benefit statements (3-5 items).

Repeat pattern for subtitle and features list (3-5 bullet points).

Store: billingMode ("off"/"required"), appTitle, tagline, subtitle, features (JSON array).

0.5 Theme Selection

Theme switching is handled by the live preview wrapper, not inside the app. The builder generates a single-theme layout. Set themeCount = 1.


Phase 1: Build

1.1 Setup

  1. Resolve plugin root — use this in all bash blocks:
    VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
    
  2. Create team: TeamCreate("launch-{appName}", "Full SaaS pipeline for {appName}")
  3. Create tasks: T1 (generate app.jsx), T3 (assembly), T4 (deploy), T5 (verify).

1.2 Spawn Builder (T1)

  1. Read ${CLAUDE_SKILL_DIR}/prompts/builder.md
  2. Substitute: {appPrompt}, {appName}, {pluginRoot}
  3. Set {aiInstructions}: if openRouterKey is set, add rule about useAI hook (see vibes SKILL.md "AI Features"). If null, leave empty.
  4. Spawn: Task tool, team_name="launch-{appName}", name="builder", subagent_type="general-purpose"

While the builder generates, SaaS config was already collected in Phase 0. Nothing else needs to happen in parallel — no credential collection, no manual setup.


Phase 2: Assembly & Deploy

Blocked by T1. Check TaskList until builder completes.

2.1 Verify Inputs

Confirm: app.jsx exists with valid JSX. All factory config values collected.

Scan app.jsx for builder mistakes (see LAUNCH-REFERENCE.md "Common Builder Mistakes"). Fix any found before proceeding.

2.2 Preview Before Deploy

Ask [Preview]: "Want to preview the app before deploying?"

  • "Yes — open live preview" — Start the preview server and iterate on the design
  • "No — deploy now" — Skip preview, go straight to deploy

If yes: run bun "$VIBES_ROOT/scripts/server.ts" and tell the user to open http://localhost:3333. They can chat to iterate on the design and switch themes. When satisfied, stop the server and continue to 2.3.

2.3 Assemble & Deploy

Step A — Assemble:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/assemble-factory.js" app.jsx index.html \
  --app-name "{appName}" \
  --app-title "{appTitle}" \
  --domain "{appName}.vibes.diy" \
  --billing-mode "{billingMode}" \
  --tagline "{tagline}" \
  --subtitle "{subtitle}" \
  --features '{featuresJSON}' \
  --admin-ids '[]'

Step B — Validate: grep -c '__VITE_\|__OIDC_\|__APP_' index.html — must be 0.

Step C — Deploy:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/deploy-cloudflare.js" \
  --name "{appName}" \
  --file index.html \
  {aiKeyFlag}

Where {aiKeyFlag} = --ai-key "{openRouterKey}" if set, omitted if null.

On first deploy, the CLI opens a browser for Pocket ID login. The user signs in once and tokens are cached for future deploys.


Phase 3: Verify & Cleanup

3.1 Verify

Ask [Verify]: "Your app is live! Open each URL and verify:\n\n- Landing: https://{appName}.vibes.diy\n- Tenant: https://{appName}.vibes.diy?subdomain=test\n\nDoes everything look right?"

  • "All working" — Everything loads correctly
  • "Something's broken" — Need to troubleshoot

If broken, ask what's wrong and troubleshoot.

3.2 Shutdown

Send shutdown_request to "builder" (if spawned). Wait for response. Clean up team.

3.3 Summary

## Launch Complete

**App**: {appTitle}
**URL**: https://{appName}.vibes.diy
**Billing**: {billingMode}

### What's deployed:
- Cloudflare Worker via Deploy API
- TinyBase sync via WebSocket + Durable Object (auto-provisioned)
- Pocket ID authentication with passkeys
- Subdomain-based multi-tenancy

### Next steps:
- Sign in at your app URL to become the first user
- Configure admin access via the app settings
- Set up Stripe billing if using subscription mode

Error Handling

FailureRecovery
Builder generates invalid JSXRead app.jsx, fix TS syntax / wrong hooks, re-save
Assembly has placeholdersRe-run assembly — auth constants are hardcoded, no .env needed
Deploy fails (auth)Delete ~/.vibes/auth.json and retry — browser login will re-open
Deploy fails (other)Check error output from deploy-cloudflare.js
Teammate silent 3+ minSendMessage status check. If no response, take over task
Builder hardcodes DB nameEdit app.jsx: replace with useTenant() pattern before assembly

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:riff". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓███████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░
 ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░
 ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░░▒▓██████▓▒░  ░▒▓██████▓▒░
  ░▒▓█▓▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░
  ░▒▓█▓▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░
   ░▒▓██▓▒░  ░▒▓█▓▒░▒▓███████▓▒░░▒▓████████▓▒░▒▓███████▓▒░

Vibes Riff Generator

Generate multiple app variations in parallel. Each riff is a different INTERPRETATION - different ideas, not just styling.

Terminal or Editor UI?

Detect whether you're running in a terminal (Claude Code CLI) or an editor (Cursor, Windsurf, VS Code with Copilot). Terminal agents use AskUserQuestion for all input. Editor agents present requirements as a checklist comment, wait for user edits, then proceed. See the vibes skill for the full detection and interaction pattern.

Workflow

Step 1: Gather ALL Requirements Upfront

Use AskUserQuestion to collect all config at once.

Question 1: "What kind of app do you want to explore? (broad/loose is fine)"
Header: "Theme"
Options: User enters via "Other"

Question 2: "Describe the visual style - colors, mood, aesthetic"
Header: "Visual"
Options: ["Warm sunset tones", "Clean minimal white", "Neon cyberpunk", "Other (describe)"]

Question 3: "How many variations should I generate?"
Header: "Count"
Options: ["3 (recommended)", "5", "7", "10"]

After receiving all answers, proceed immediately to Step 2 - no more questions.

Note: If the frontend-design skill is available, use it for enhanced visual design quality.

Step 2: Create Riff Directories

mkdir -p riff-1 riff-2 riff-3 ...

Step 3: Generate Riffs in Parallel

Use the bundled script to generate riffs in parallel. Each script instance calls claude -p (uses subscription tokens) and writes directly to disk.

Generate riffs in parallel based on user's count:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
# For each N from 1 to ${count}:
bun "$VIBES_ROOT/scripts/generate-riff.js" "${prompt}" N riff-N/app.jsx "${visual}" &

# Then wait for all
wait
echo "All ${count} riffs generated!"

Example for count=3:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/generate-riff.js" "productivity apps" 1 riff-1/app.jsx "warm sunset oranges and soft creams" &
bun "$VIBES_ROOT/scripts/generate-riff.js" "productivity apps" 2 riff-2/app.jsx "warm sunset oranges and soft creams" &
bun "$VIBES_ROOT/scripts/generate-riff.js" "productivity apps" 3 riff-3/app.jsx "warm sunset oranges and soft creams" &
wait

Why this works:

  • Each script calls claude -p "..." → uses subscription tokens
  • Script writes directly to disk → no tokens flow through main agent
  • Background processes (&) run in parallel → true concurrency
  • Main agent only sees "✓ riff-N/app.jsx" output → minimal tokens

Step 4: Assemble HTML

Convert each app.jsx to a complete index.html:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun "$VIBES_ROOT/scripts/assemble-all.js" riff-1 riff-2 riff-3 ...

Step 5: Evaluate & Rank

Read the pitch.md files (NOT the full code) for fast evaluation:

# Read pitch files - contains reasoning about theme, colors, functionality
cat riff-*/pitch.md

# Also read BUSINESS comments for app names (just first 10 lines of each)
head -10 riff-*/app.jsx

pitch.md contains the model's reasoning about theme, colors, and design choices. BUSINESS comment (top of app.jsx) contains: name, pitch, customer, revenue.

Then create RANKINGS.md using this format:

# Riff Rankings: [Theme]

## Summary

| Rank | App Name | Score | Best For |
|------|----------|-------|----------|
| 1 | [Name] | XX/50 | [one-liner] |
| 2 | [Name] | XX/50 | [one-liner] |
| ... | ... | ... | ... |

## Detailed Scores

### #1: [App Name] (riff-N)
| Criterion | Score | Notes |
|-----------|-------|-------|
| Originality | X/10 | [Why unique or derivative] |
| Market Potential | X/10 | [Target audience size, demand] |
| Feasibility | X/10 | [Technical complexity, time to build] |
| Monetization | X/10 | [Revenue model viability] |
| Wow Factor | X/10 | [First impression, engagement] |
| **Total** | **XX/50** | |

[Repeat for each riff]

## Recommendations

- **Best for solo founder:** [riff-N] - [reason]
- **Fastest to ship:** [riff-N] - [reason]
- **Most innovative:** [riff-N] - [reason]
- **Best monetization:** [riff-N] - [reason]

Scoring Guidelines:

  • 1-3: Poor - significant issues
  • 4-5: Below average - notable weaknesses
  • 6-7: Average - meets expectations
  • 8-9: Good - stands out positively
  • 10: Excellent - exceptional in this criterion

Step 6: Generate Gallery

Create index.html gallery page with:

  • Dark theme (#0a0a0f background)
  • Glass-morphism cards with purple/cyan accents
  • Each card: rank badge, app name, pitch, score bar, "Launch →" link
  • Responsive grid layout
  • Self-contained with inline styles

Step 7: Present Results

Generated ${count} riffs for "${prompt}":
#1: riff-X - App Name (XX/50)
#2: riff-Y - App Name (XX/50)
...

Open index.html for gallery, or browse riff-1/, riff-2/, etc.

Plugin Directory

Scripts resolve the plugin root via VIBES_ROOT, which tries ${CLAUDE_PLUGIN_ROOT} first (set by Claude Code) and falls back to deriving the path from ${CLAUDE_SKILL_DIR} (two directories up). Set it at the top of each bash block: VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"


What's Next?

After presenting rankings, guide the user with AskUserQuestion:

Question: "You have ${count} variations ranked. What would you like to do?"
Header: "Next"
Options:
- Label: "Develop the #1 ranked app"
  Description: "Take the top-ranked variation and continue building it. I'll copy riff-1/app.jsx to your working directory so you can iterate with the full vibes feature set - add functionality, refine the design, make it yours."

- Label: "Let me pick a different one"
  Description: "The rankings are just my analysis - you might see something special in another variation. Tell me which riff number speaks to you and I'll set it up for development."

- Label: "Turn winner into SaaS (/sell)"
  Description: "Ready to monetize the best one? Sell adds authentication via Pocket ID with passkeys, subscription billing, and multi-tenant database isolation. Each customer gets their own subdomain with their own data."

- Label: "Deploy a riff as demo (/cloudflare)"
  Description: "Want to share one quickly? Deploy puts any variation live on Cloudflare Workers within minutes. Great for getting feedback before committing to further development."

- Label: "I'm done for now"
  Description: "Wrap up this session. All riffs are saved in riff-1/, riff-2/, etc. - browse them locally or come back later to continue."

After user responds:

  • "Develop #1" → Copy riff-1/app.jsx to ./app.jsx, confirm ready for vibes iteration
  • "Pick different" → Ask which riff number, then copy that one
  • "Turn into SaaS" → Copy riff-1/app.jsx, auto-invoke /vibes:factory skill
  • "Deploy demo" → Ask which riff, auto-invoke /vibes:cloudflare skill with that riff's index.html
  • "I'm done" → Confirm riffs saved, provide directory listing

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:test". Do not decompose the steps below into separate plan tasks.

Integration Test Skill

Orchestrates the full test pipeline: credentials → fixture assembly → Cloudflare deploy (with auto-provisioned Connect) → live URL → unit tests.

Working directory: test-vibes/ (gitignored, persists across runs)

Phase 1: Credentials

Check if test-vibes/.env exists and has OIDC credentials.

# From the plugin root
cat test-vibes/.env 2>/dev/null

If the file exists and contains VITE_OIDC_AUTHORITY:

AskUserQuestion:
  Question: "Reuse existing test credentials? (OIDC authority: https://...)"
  Header: "Credentials"
  Options:
  - Label: "Yes, reuse"
    Description: "Use the OIDC credentials already in test-vibes/.env"
  - Label: "No, enter new credentials"
    Description: "I want to use different OIDC credentials"

If the file doesn't exist or credentials are missing, or user wants new ones:

AskUserQuestion:
  Question: "Paste your OIDC Authority URL (e.g., https://studio.exe.xyz/auth)"
  Header: "OIDC Authority"
  Options:
  - Label: "I need to set up OIDC first"
    Description: "I'll configure Pocket ID and come back"

If they need to set up OIDC, tell them:

You need a Pocket ID instance for authentication. Connect is auto-provisioned on first deploy -- you just need the OIDC Authority URL and Client ID from your Pocket ID configuration.

Then ask for the client ID:

AskUserQuestion:
  Question: "Paste your OIDC Client ID"
  Header: "OIDC Client ID"

Write test-vibes/.env:

VITE_OIDC_AUTHORITY=<authority-url>
VITE_OIDC_CLIENT_ID=<client-id>

Phase 2: Connect (Auto-Provisioned)

Connect is automatically provisioned on first Cloudflare deploy -- no manual setup needed. The deploy-cloudflare.js script handles R2 bucket, D1 databases, and cloud backend Worker provisioning via alchemy. Subsequent deploys skip Connect setup.

Proceed directly to fixture selection.

Phase 3: Fixture Selection

AskUserQuestion:
  Question: "Which fixture to test?"
  Header: "Fixture"
  Options:
  - Label: "basic (Recommended)"
    Description: "TinyBase data operations with React singleton — the standard integration test"
  - Label: "minimal"
    Description: "Template + Babel + import map only — fastest, no data layer"
  - Label: "sell-ready"
    Description: "useTenant() + multi-tenant routing — tests factory assembly path"
  - Label: "ai-proxy"
    Description: "/api/ai/chat endpoint + CORS — requires OpenRouter key"

For sell-ready fixture: Check test-vibes/.env for a cached admin user ID from a previous run:

grep OIDC_ADMIN_USER_ID test-vibes/.env 2>/dev/null

If found, offer to reuse it (mask the middle of the value in the prompt, e.g., user_37ici...ohcY):

AskUserQuestion:
  Question: "Reuse stored admin user ID? (user_37ici...ohcY)"
  Header: "Admin ID"
  Options:
  - Label: "Yes, reuse"
    Description: "Use the cached user ID from test-vibes/.env"
  - Label: "Skip admin"
    Description: "Deploy without admin — you can set it up after deploy"

If "Yes, reuse": use the stored value in Phase 4 assembly. If "Skip admin": omit --admin-ids in Phase 4. Admin setup will be offered post-deploy in Phase 5.5.

If not found: No prompt needed. Admin will be set up post-deploy in Phase 5.5 after the user has a chance to sign up on the live app.

Phase 3.5: Factory Configuration (sell-ready only)

Condition: Only runs when the user selected sell-ready in Phase 3.

Ask billing mode:

AskUserQuestion:
  Question: "Which billing mode should this factory test use?"
  Header: "Billing"
  Options:
  - Label: "Free (billing off)"
    Description: "Claims work without payment — tests auth + tenant routing only"
  - Label: "Billing required"
    Description: "Claims require subscription — tests auth gate flow (Stripe billing is phase 2)"

If "Free": Store BILLING_MODE=off in test-vibes/.env. Skip webhook setup. Proceed to Phase 4.

If "Billing required": Store BILLING_MODE=required in test-vibes/.env. Note that Stripe billing integration is phase 2, so the paywall will be a placeholder.

Proceed to Phase 4.

Phase 4: Assembly

Copy the selected fixture and assemble:

# Copy fixture to working directory
cp scripts/__tests__/fixtures/<fixture>.jsx test-vibes/app.jsx

# Source env for assembly
set -a && source test-vibes/.env && set +a

For sell-ready fixture:

bun scripts/assemble-factory.js test-vibes/app.jsx test-vibes/index.html \
  --domain vibes-test.<account>.workers.dev \
  --admin-ids '["<admin-user-id>"]'  # read OIDC_ADMIN_USER_ID from test-vibes/.env

If admin was skipped, omit --admin-ids. The --domain flag is always required.

For all other fixtures:

bun scripts/assemble.js test-vibes/app.jsx test-vibes/index.html

Validate the output (same checks as the vitest suite):

  1. File exists and is non-empty
  2. No __PLACEHOLDER__ strings remain
  3. Import map <script type="importmap"> is present
  4. <script type="text/babel"> contains the fixture code
  5. For sell-ready: getRouteInfo function is present

If any check fails, report the error, then ask:

AskUserQuestion:
  Question: "What next?"
  Header: "Next"
  Options:
  - Label: "Test another fixture"
    Description: "Go back to Phase 3 and pick a different fixture"
  - Label: "End test session"
    Description: "Clean up artifacts and finish"

If "Test another fixture": go to Phase 3. If "End test session": go to Phase 11.

Phase 5: Deploy to Cloudflare

For ai-proxy fixture: Check ~/.vibes/.env for a cached OpenRouter key first:

grep OPENROUTER_API_KEY ~/.vibes/.env 2>/dev/null

If found, offer to reuse it (mask the key, e.g., sk-or-v1-...a3b2):

AskUserQuestion:
  Question: "Reuse stored OpenRouter API key? (sk-or-v1-...a3b2)"
  Header: "AI Key"
  Options:
  - Label: "Yes, reuse"
    Description: "Use the cached key from ~/.vibes/.env"
  - Label: "Enter new"
    Description: "I'll paste a different key"
  - Label: "Skip AI proxy"
    Description: "Deploy without AI endpoint"

If "Yes, reuse": use the stored value. If "Enter new": collect via the prompt below, then update ~/.vibes/.env.

If not found (or user chose "Enter new"):

AskUserQuestion:
  Question: "Paste your OpenRouter API key for the AI proxy"
  Header: "AI Key"
  Options:
  - Label: "Skip AI proxy"
    Description: "Deploy without AI endpoint"

After collecting a new key, offer to save it:

AskUserQuestion:
  Question: "Save this OpenRouter key to ~/.vibes/.env for future projects?"
  Header: "Cache"
  Options:
  - Label: "Yes, save"
    Description: "Cache the key so you don't have to paste it again"
  - Label: "No, skip"
    Description: "Use for this session only"

If "Yes, save":

mkdir -p ~/.vibes
grep -q OPENROUTER_API_KEY ~/.vibes/.env 2>/dev/null && \
  sed -i '' 's/^OPENROUTER_API_KEY=.*/OPENROUTER_API_KEY=<new>/' ~/.vibes/.env || \
  echo "OPENROUTER_API_KEY=<new>" >> ~/.vibes/.env

Run the deploy:

bun scripts/deploy-cloudflare.js --name vibes-test --file test-vibes/index.html

For sell-ready fixture: Pass --env-dir to auto-detect OIDC config, and pass billing mode from test-vibes/.env:

bun scripts/deploy-cloudflare.js --name vibes-test --file test-vibes/index.html \
  --env-dir test-vibes \
  --billing-mode $BILLING_MODE

Read BILLING_MODE from test-vibes/.env. The --env-dir flag auto-detects VITE_OIDC_AUTHORITY from .env (fetches OIDC discovery, gets PEM key, sets OIDC_PEM_PUBLIC_KEY and PERMITTED_ORIGINS as Worker secrets). --billing-mode patches the [vars] in wrangler.toml before deploy.

For ai-proxy with key:

bun scripts/deploy-cloudflare.js --name vibes-test --file test-vibes/index.html --ai-key <key>

Phase 5.5: Admin Setup (sell-ready only)

Condition: Only runs for the sell-ready fixture AND admin is not yet configured (no cached ID was reused in Phase 3).

After deploy, guide the user through post-deploy admin setup:

  1. Tell the user the app is live and they can now sign up:
Your app is deployed! To configure admin access, first create an account:
  Sign up here: https://vibes-test.<account>.workers.dev?subdomain=test

After signing up, we'll grab your User ID from Pocket ID.
  1. Ask if they've signed up:
AskUserQuestion:
  Question: "Have you completed signup on the deployed app?"
  Header: "Signup"
  Options:
  - Label: "Yes, signed up"
    Description: "I've created my account and I'm ready to get my User ID"
  - Label: "Skip admin setup"
    Description: "Continue without admin access"

If "Skip admin setup": proceed to Phase 6 without admin configured.

  1. Guide to finding User ID:
Now grab your User ID:
  1. Check the Pocket ID admin panel or your app's user profile
  2. Find and copy your User ID (starts with user_)
  1. Collect the User ID:
AskUserQuestion:
  Question: "Paste your User ID (starts with user_)"
  Header: "Admin ID"
  Options:
  - Label: "I need help finding it"
    Description: "Show me where to find the User ID in Pocket ID"
  - Label: "Skip admin setup"
    Description: "Continue without admin access"

Validate the input starts with user_. If not, ask again.

  1. Save to test-vibes/.env:
grep -q OIDC_ADMIN_USER_ID test-vibes/.env 2>/dev/null && \
  sed -i '' 's/^OIDC_ADMIN_USER_ID=.*/OIDC_ADMIN_USER_ID=<userId>/' test-vibes/.env || \
  echo "OIDC_ADMIN_USER_ID=<userId>" >> test-vibes/.env
  1. Re-assemble with admin configured:
set -a && source test-vibes/.env && set +a

bun scripts/assemble-factory.js test-vibes/app.jsx test-vibes/index.html \
  --domain vibes-test.<account>.workers.dev \
  --admin-ids '["<userId>"]'
  1. Re-deploy:
bun scripts/deploy-cloudflare.js --name vibes-test --file test-vibes/index.html \
  --env-dir test-vibes \
  --billing-mode $BILLING_MODE
  1. Confirm:
Admin access configured! The admin dashboard at ?subdomain=admin should now work for your account.

Proceed to Phase 6.

Phase 6: Present URL

Print the live URL and what to check:

For minimal / basic:

Deployed! Open in your browser:
  https://vibes-test.<account>.workers.dev

What to verify:
- Page loads without console errors
- (basic) TinyBase data operations work — add, edit, delete items
- Settings gear icon opens the menu

For sell-ready:

Deployed! Open these URLs:
  Landing:  https://vibes-test.<account>.workers.dev
  Tenant:   https://vibes-test.<account>.workers.dev?subdomain=test
  Admin:    https://vibes-test.<account>.workers.dev?subdomain=admin

What to verify:
- Landing page shows pricing/marketing content
- Claim a subdomain — should succeed (tests /claim + JWT auth)
- Tenant URL shows auth gate (OIDC sign-in via Pocket ID)
- Admin URL shows admin dashboard (if admin was configured in Phase 3 or 5.5)
- Admin URL shows "Admin Access Required" (if admin setup was skipped)

For ai-proxy:

Deployed! Open in your browser:
  https://vibes-test.<account>.workers.dev

What to verify:
- App loads and renders
- AI chat feature works (sends to /api/ai/chat)
- Check Network tab: requests go to OpenRouter via proxy

Then ask:

AskUserQuestion:
  Question: "How does it look?"
  Header: "Result"
  Options:
  - Label: "Working"
    Description: "Everything renders correctly"
  - Label: "Has issues"
    Description: "Something isn't right — I'll describe it"

If "Working":

Print a summary table:

| Phase       | Status |
|-------------|--------|
| Credentials | ✓      |
| Assembly    | ✓ <fixture>.jsx → index.html |
| Cloudflare  | ✓ <url> (Connect auto-provisioned) |
| Browser     | ✓ User confirmed working |
AskUserQuestion:
  Question: "What next?"
  Header: "Next"
  Options:
  - Label: "Test another fixture"
    Description: "Go back to Phase 3 and pick a different fixture"
  - Label: "End test session"
    Description: "Clean up artifacts and finish"

If "Test another fixture": go to Phase 3. If "End test session": go to Phase 11.

If "Has issues": Read ${CLAUDE_SKILL_DIR}/references/diagnostics.md for the full diagnosis flow (Phases 7-10: diagnosis tables, root cause classification, fix-and-verify loop, resolution summary). Then return here for Phase 11.


Phase 11: Unit & Integration Tests

Run the vitest suite to confirm plugin source is healthy. Especially important after any fixes applied in Phase 9.

cd scripts && npm test

If all tests pass: Print the count (e.g. "429 tests passed") and proceed to cleanup.

If any tests fail: Show the failure output and ask:

AskUserQuestion:
  Question: "Unit/integration tests failed. Fix before finishing?"
  Header: "Tests"
  Options:
  - Label: "Yes, fix them"
    Description: "Investigate and fix the failing tests"
  - Label: "Skip"
    Description: "Finish the session anyway"

If "Yes, fix them": diagnose and fix the failures, re-run npm test, loop until green.

Phase 12: Session Cleanup

Triggered after Phase 11 completes or when user selects "End test session" from any "What next?" prompt.

Clean up test artifacts while preserving reusable credentials:

# Clean test artifacts, preserve .env
cd test-vibes && find . -maxdepth 1 ! -name '.' ! -name '.env' -exec rm -rf {} +

Print:

Test session complete.
  Cleaned: test-vibes/ artifacts
  Preserved: .env (reusable next session)

Your Role

You're helping a non-technical user clarify what they want to build before code generation begins. You ask short, friendly, multiple-choice questions. You never use technical jargon — no words like "sync", "state management", "rows", "tables", "CRDT", "database", or "schema." Your questions are about features, saving, sharing, and how the app works. Keep it conversational and approachable.

How It Works

Assess the user's prompt. Identify what you can confidently infer vs what's ambiguous. Ask ONE question at a time with 2-4 concrete options (plus the user can always type something custom). Keep asking as long as each question meaningfully improves the app — there's no hard limit. Users enjoy this conversation.

Every question after the first must include an escape hatch as the last option:

▸ That's enough — let's build it!

This lets the user opt out naturally whenever they're ready, without you imposing a cap. Stop asking when:

  • The user picks the escape hatch
  • You can't think of a question that would meaningfully change the generated app
  • The prompt was so specific that 0 questions are needed

Formatting Choices

Present each option on its own line, prefixed with ▸ . This marker tells the chat UI to render clickable buttons. Example:

Who's going to use this?

▸ Just me
▸ Me and a group of people
▸ Real-time with other people (like a game or collaboration)

Always keep the question text ABOVE the options, separated by a blank line. Each ▸ option is its own line.

Question Categories

Draw from these categories. Skip what the prompt already answers. Invent answer choices fresh for each app — don't reuse canned options. The choices should feel specific to what the user described, not generic. The only exceptions are questions where the precise schema of answers matters for architecture decisions (marked with fixed options below).

  • Who uses this? — fixed options (determines auth architecture):

    ▸ Just me ▸ Shared with a group ▸ Real-time with others (like a game or collaboration)

  • What do others see? — fixed options, only if shared (determines data filtering):

    ▸ Same view ▸ Personal views ▸ Mix of both

  • What's the vibe? — What personality and tone should this have? Focus on mood, not visuals (the theme handles that). Invent options that fit the app concept.

  • Main interaction — What's the main thing you do in this app? Invent options specific to the app type.

  • What are you tracking? — What are the main things in this app and how detailed are they? Invent options that explore the depth of content structure.

  • What gets saved? — What should still be there when you come back tomorrow? Invent options specific to the app type.

  • How big is this? — How much should this do? Invent options that range from focused to ambitious, described in terms of the specific app.

  • Special features — Anything unique to the concept that would change the architecture. Invent options based on what you know about the domain (timers, scoring, voting, AI suggestions, etc.).

Translation Layer

This section is for Claude's reasoning only. Do not show this to users.

Principles for mapping user answers to data architecture:

  • "Just me" — all persistent data in TinyBase, no user attribution needed, sync gives cross-device access
  • "Shared with a group" — TinyBase with createdBy: user?.email || 'anonymous' on user-owned items
  • "Real-time with others" — shared data in TinyBase, user attribution on every item, ephemeral interaction (drag position, cursor) can stay in useState
  • "Personal views" — tag all items with createdBy, filter by current user on read
  • "Same view for everyone" — no filtering, all items visible to all clients

Principles for mapping vibe/mood to app personality:

  • "Serious and buttoned-up" — formal labels, no emoji, concise copy, structured layouts, no playful animations
  • "Casual and friendly" — conversational microcopy, gentle humor, relaxed spacing, approachable empty states
  • "Playful and a little weird" — emoji in labels, fun empty states, bouncy interactions, personality in error messages, easter eggs
  • "Calm and focused" — minimal UI chrome, generous whitespace, no distractions, zen-like empty states

Principles for mapping scope to architecture:

  • "One focused screen" — single App component, minimal state, no routing or tabs
  • "A few sections or tabs" — tab state in useState, content switches, shared data across views
  • "Full dashboard" — multiple distinct panels, possibly a sidebar, more complex layout grid

The Brief

When you have enough context, present a summary and transition straight into building in the same response. The brief is the final message before code generation — treat it as the green light.

Here's what I'll build:

[2-3 sentence description of the app]

- [key feature 1]
- [key feature 2]
- [data/sharing approach in plain language]

After the brief, immediately output the structured <vibes-brief> block and start generating. The user already gave permission to build by completing the Q&A — the brief is a statement of intent, followed by action. If the user wants changes, they iterate after seeing the result.

Example Flows

Notice how answer choices are invented fresh for each app — they feel specific to the concept, not generic.

"a board game"

  • Q: Who's going to play? (fixed — architecture decision)

    ▸ Just me ▸ Real-time with others (like a game or collaboration)

  • Q: How do players take turns?

    ▸ We go back and forth, chess-style ▸ Everyone moves at once, then we see what happened ▸ It's more of a party game — chaos is the point ▸ That's enough — let's build it!

  • Q: What kind of board are we talking about?

    ▸ A grid you place pieces on ▸ A winding path you race along ▸ Cards or tiles you collect and play ▸ That's enough — let's build it!

  • Q: What personality should this have?

    ▸ Tense and strategic — make every move count ▸ Lighthearted — trash talk encouraged ▸ Cozy — more about hanging out than winning ▸ That's enough — let's build it!

  • Q: What happens between sessions?

    ▸ Track our win streaks and rivalry stats ▸ Save the game so we can pick up later ▸ Fresh start every time ▸ That's enough — let's build it!

  • Brief: "A 2-player turn-based grid game with tense, strategic energy. Both players see the same board. Win streaks and rivalry stats are saved."

"a recipe tracker"

  • Q: Is this just for you, or will you share recipes with others? (fixed)

    ▸ Just me ▸ Shared with a group

  • Q: How detailed do you want each recipe to be?

    ▸ Just a name and a quick note or link ▸ Ingredients list and step-by-step instructions ▸ The whole deal — ingredients, steps, cook time, ratings, maybe photos ▸ That's enough — let's build it!

  • Q: What personality should this have?

    ▸ Like a worn-in notebook — handwritten feel ▸ Magazine-quality — make the food look amazing ▸ No-nonsense — just get me to the recipe fast ▸ That's enough — let's build it!

  • Q: How do you want to find things later?

    ▸ Just scroll or search — I won't have that many ▸ Sort by meal type — breakfast, lunch, dinner, dessert ▸ My own tags — "weeknight quick", "impress guests", "kid-approved" ▸ That's enough — let's build it!

  • Brief: "A personal recipe notebook with a worn-in, handwritten feel. Full ingredients and steps, organized by meal type. Saved across all your devices."

"a poll"

  • (No questions needed — clearly shared, everyone sees results)
  • Brief: "A shared poll where anyone with the link can vote and see live results."

Building

After presenting the brief, immediately output the structured block and start building. The brief itself is the confirmation:

<vibes-brief>
App: [description]
Vibe: [personality and tone — e.g., "casual and friendly", "playful and weird", "calm and focused"]
Audience: [solo / shared / real-time multiplayer]
Interaction: [main thing the user does — e.g., "drag cards between columns", "check off items"]
Content: [what's being tracked and its structure — e.g., "recipes with ingredients, steps, and categories"]
Saves: [what persists]
Sharing: [what others see, or "n/a" for solo]
Scope: [one view / a few sections / full dashboard]
Key features: [list]
</vibes-brief>

Then tell the user: "Building your app now..." — the generate flow picks up from here.

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:vibes". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓███████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░
 ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░
 ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░▒▓███████▓▒░░▒▓██████▓▒░  ░▒▓██████▓▒░
  ░▒▓█▓▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░
  ░▒▓█▓▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░             ░▒▓█▓▒░
   ░▒▓██▓▒░  ░▒▓█▓▒░▒▓███████▓▒░░▒▓████████▓▒░▒▓███████▓▒░

Quick Navigation


Vibes DIY App Generator

Generate React web applications using TinyBase for reactive data with real-time sync.

Auth Check (silent — only prompt if needed)

Before asking Terminal or Editor, check for cached auth:

VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
bun --input-type=module -e "
import { readCachedTokens, isTokenExpired } from '$VIBES_ROOT/scripts/lib/cli-auth.js';
const tokens = readCachedTokens();
if (tokens && !isTokenExpired(tokens.expiresAt)) {
  console.log('AUTH_OK');
} else {
  console.log('AUTH_NEEDED');
}
"
  • If AUTH_OK → proceed silently to "Terminal or Editor?" (do not mention auth)
  • If AUTH_NEEDED → ask: "To deploy apps, you'll need a Vibes account. Sign in now? (A browser window will open for Pocket ID — takes about 10 seconds.)"
    • If yes:
      VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
      bun --input-type=module -e "
      import { getAccessToken } from '$VIBES_ROOT/scripts/lib/cli-auth.js';
      import { OIDC_AUTHORITY, OIDC_CLIENT_ID } from '$VIBES_ROOT/scripts/lib/auth-constants.js';
      const tokens = await getAccessToken({ authority: OIDC_AUTHORITY, clientId: OIDC_CLIENT_ID });
      if (tokens) console.log('Signed in successfully!');
      "
      
      Confirm success, then proceed to "Terminal or Editor?"
    • If no → proceed anyway (auth will be needed at deploy time)

Step 0: Terminal or Editor UI?

This is the very first question — ask before anything else (after auth check above). Do not check .env, credentials, or project state before asking this question. Do not invoke any other skill before asking this question. If Editor is chosen, skip all pre-flight checks — the editor handles everything.

Ask the user:

"How do you want to build? Editor (opens a browser UI with live preview, chat, and deploy button) or Terminal (I'll generate and deploy from here)?"

Present Editor as the first/recommended option.

  • If Editor: Start the editor server and END YOUR TURN. Do not ask any more questions. Do not continue to Pre-Flight Check or any step below. The editor UI handles the entire workflow — setup, generation, preview, deploy.

    Launch the editor server:

    VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
    bun "$VIBES_ROOT/scripts/server.ts" --mode=editor --prompt "USER_PROMPT_HERE"
    

    If no prompt was given, omit --prompt:

    VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
    bun "$VIBES_ROOT/scripts/server.ts" --mode=editor
    

    Tell the user: "Open http://localhost:3333 — the editor handles everything from here." Your job is done. Stop. Do not read further. Do not proceed to any step below.

  • If Terminal: Continue with the project folder selection and normal generation workflow below.


⛔ EVERYTHING BELOW IS TERMINAL MODE ONLY

If the user chose Editor above, STOP. Do not read or execute anything below this line. The editor UI handles setup, generation, preview, and deployment.


Project Folder

Before generating, ask the user where to save the project:

"Where should this project live? Enter a path or press Enter for the default (~/VibesOS/{app-slug}/)."

  • If the user provides a path, use it as the project directory
  • If they press Enter, use ~/VibesOS/{app-slug}/ (the slug is derived from the prompt later — for now just note the preference)
  • Create the directory if it doesn't exist
VIBES_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "${CLAUDE_SKILL_DIR}")")}"
mkdir -p "$PROJECT_DIR"

After the directory is ready, initialize vibes.json:

bun -e "
  const { initVibesJson } = await import('$VIBES_ROOT/scripts/lib/vibes-json.js');
  initVibesJson('$PROJECT_DIR');
"

Use $PROJECT_DIR as the working directory (cwd) for all subsequent code generation. The generated app.jsx and assembled index.html will be written here.


Pre-Flight Check

Complete these steps before generating any app code.

  • Auth is automatic — on first deploy, a browser window opens for Pocket ID login
  • Tokens are cached at ~/.vibes/auth.json for subsequent deploys
  • Sync infrastructure deploys automatically on first app deploy — no manual setup needed

Read ${CLAUDE_SKILL_DIR}/references/generation-rules.md for platform constraints, core rules, what generated code must/must not contain, generation process, assembly workflow, and the <Markdown> component for rendering formatted text.


Read ${CLAUDE_SKILL_DIR}/references/style-guide.md for OKLCH colors, theming, design token overrides, and visual style patterns.


Read ${CLAUDE_SKILL_DIR}/references/data-api.md for the complete TinyBase hook API reference, data access patterns, user identity, game patterns, reference app, and bug prevention checklist.


When to Read Extended Docs

Read these reference files when the user's prompt matches the signals below:

NeedSignal in PromptRead This
TinyBase data patternsforms, lists, filtering, ordering, pagination, master-detail${CLAUDE_SKILL_DIR}/references/tinybase-patterns.md
Multiplayer / shared appsmultiplayer, collaborative, shared, multi-user, game with players${CLAUDE_SKILL_DIR}/references/multiplayer-guide.md
Game developmentgame, timer, countdown, turn-based, score${CLAUDE_SKILL_DIR}/references/game-patterns.md
AI-powered featuresAI, chatbot, summarize, generate, openrouter${CLAUDE_SKILL_DIR}/references/ai-integration.md
Bug prevention referencedebugging, troubleshooting, reviewing code${CLAUDE_SKILL_DIR}/references/bug-prevention.md
Design tokens & themingcolors, theme, tokens, brand colors, styling${CLAUDE_PLUGIN_ROOT}/build/design-tokens.txt
Full design system detailsdetailed design system, spacing, typography${CLAUDE_SKILL_DIR}/defaults/style-prompt.txt
Advanced visual effects"interactive", "animated", "3D", "particles", "shader", "canvas"${CLAUDE_SKILL_DIR}/defaults/advanced-effects-prompt.txt

Deployment Options

After generating your app, deploy it:

  • Cloudflare - Edge deployment with Workers. Use /vibes:cloudflare to deploy.

What's Next?

After generating and assembling the app, present these options using AskUserQuestion:

Question: "Your app is live! Want to turn it into a product? The /sell skill adds multi-tenant SaaS with auth and billing. Or pick another direction:"
Header: "Next"
Options:
- Label: "Keep improving this app"
  Description: "Continue iterating on what you've built. Add new features, refine the styling, or adjust functionality. Great when you have a clear vision and want to polish it further."

- Label: "Apply a design reference (/design)"
  Description: "Have a design.html or mockup file? This skill mechanically transforms your app to match it exactly - pixel-perfect fidelity with your TinyBase data binding preserved."

- Label: "Explore variations (/riff)"
  Description: "Not sure if this is the best approach? Riff generates 3-10 completely different interpretations of your idea in parallel. You'll get ranked variations with business model analysis to help you pick the winner."

- Label: "Make it a SaaS (/sell)"
  Description: "Ready to monetize? Sell transforms your app into a multi-tenant SaaS with Pocket ID authentication, subscription billing, and isolated databases per customer. Each user gets their own subdomain."

- Label: "Deploy to Cloudflare (/cloudflare)"
  Description: "Go live on the edge. Deploy to Cloudflare Workers with a subdomain registry, KV storage, and global CDN. Fast, scalable, and always on."

- Label: "I'm done for now"
  Description: "Wrap up this session. Your files are saved locally - come back anytime to continue."

After user responds:

  • "Keep improving" → Acknowledge and stay ready for iteration prompts. After each round of changes to app.jsx, re-run assembly and re-deploy.
  • "Apply a design reference" → Auto-invoke /vibes:design skill
  • "Explore variations" → Auto-invoke /vibes:riff skill
  • "Make it a SaaS" → Auto-invoke /vibes:factory skill
  • "Deploy" → Auto-invoke /vibes:cloudflare skill
  • "I'm done" → Confirm files saved, wish them well

Do not proceed to code generation until: Pre-flight check is complete (auth is automatic on deploy — no credentials to collect).

Sponsors

Details

Marketplace
popmechanic/VibesOS
Author
Marcus Estes
Category
Community

More from popmechanic/VibesOS

All 2