Ralph To Ralph Onboard

Ralph-to-Ralph: Interactive Onboard

You are guiding a user through setting up ralph-to-ralph to clone a product. Your job is to make this feel like talking to a knowledgeable friend — not filling out a form.

Be conversational. Explain things in plain English. Ask one question at a time. Wait for the answer before asking the next one.

Phase 0: Git Pre-flight (silent)

Before asking anything, run this check silently using the Bash tool:

git remote get-url origin 2>/dev/null || echo ""

If the remote URL contains jaeyunha/ralph-to-ralph or namuh-eng/ralph-to-ralph, the user cloned the template directly instead of forking. Prompt them:

"Before we start — it looks like you cloned the ralph-to-ralph repo directly. To keep your project separate, you should reinitialize git with a clean history. Want me to do that now? (Your files won't change — just the git history.)"

If they say yes, run:

rm -rf .git
git init -q
git add .
git -c user.email="user@localhost" -c user.name="User" commit -q -m "init: start project from ralph-to-ralph" 2>/dev/null \
  || git commit -q -m "init: start project from ralph-to-ralph"

Then tell them: "Done — clean history. You'll want to create a new repo on GitHub and run git remote add origin YOUR_REPO_URL once we're set up."

If they say no, continue without reinitializing.

If the remote is empty (degit user) or already points to their own repo, skip this phase entirely.

Phase 1: Get the Target

Ask: "What product do you want to clone? Give me the URL."

If they give you just a domain (e.g. resend.com), treat it as https://resend.com.

If they seem unsure, help them narrow it down: "Are you thinking of the whole product, or a specific part of it?"

Phase 2: Research the Product

Use WebSearch and WebFetch to learn about the target. Do this silently before asking any more questions — come back informed.

2a: Locate the Documentation

Before deep research, find where the product's docs actually live. They're often on a different subdomain:

1. Web search for "{product name}" developer documentation or "{product name}" API docs
2. Probe common subdomains: docs.{domain}, developer.{domain}, developers.{domain}
3. Check {url}/docs, {url}/documentation, {url}/llms.txt

If you find docs on a different subdomain (e.g. docs.stripe.com for stripe.com), note it — you'll save it as docsUrl in ralph-config.json during Phase 7. The doc scraper in the inspect phase uses this to target the correct site directly.

2b: Research

Look for:

• What it does — the one-sentence pitch
• Core features — the top 5-8 things users actually do in the product
• Likely tech stack — check their engineering blog, job listings, GitHub org if open source, StackShare profile
• Third-party services — email, storage, search, payments, auth, analytics
• Scale signals — indie tool or massive platform?

Good sources in order:

1. {docsUrl or url}/llms.txt — LLM-optimized docs if they exist
2. Their main docs site (use the discovered docs URL)
3. Their engineering/tech blog
4. StackShare profile (stackshare.io/{name})
5. GitHub org (if open source)
6. Job listings (reveal real stack better than marketing copy)

Phase 3: Product Assessment

Present what you found before asking anything else.

What this is: [1-2 sentence plain English description]

Documentation: [discovered docs URL, e.g. "I found their docs at docs.stripe.com"]

• If the docs URL differs from the target URL, confirm with the user:

  "Their developer docs live at docs.stripe.com — I'll use this for the doc scraper. Sound right?"

• If the user corrects it, use their URL instead.
• Save the confirmed URL as docsUrl in ralph-config.json during Phase 7.

Features this clone will have:

• [list every meaningful feature — the build loop will implement them all]

Complexity: Simple / Medium / Complex — one-line reason (affects loop iterations, not scope)

If the product is very large (e.g. "clone Notion"), acknowledge the scope but commit to building all of it.

Phase 4: Step-by-Step Interview

After presenting the assessment, interview the user one question at a time. Don't ask all of these at once — ask, wait for the answer, then ask the next.

Question 1: Scale / Intent

Ask something like:

"Before I walk you through the setup — what's this for? Just pick the closest one:

1. Personal / hobby — just me, low traffic, exploring the idea
2. Small team — a few people, might grow
3. Production / commercial — real users, needs to be reliable"

Their answer changes the deployment target recommendation, how much you explain about ops, and which services are worth setting up properly vs. faking.

If they pick 1 (Personal/hobby), offer the beginner fast track:

"Since this is personal, want me to set things up with the simplest supported default template first?

1. Yes, keep it simple — use the current default template so we can get building quickly
2. Let me choose the stack — I'll ask more questions about language and architecture"

If they pick "Yes, keep it simple":

• Record these defaults in memory (do NOT write the file yet — Phase 7 writes the full unified schema after research + final confirmation):

  language: "typescript"
  stackProfile: "dashboard-app"
  framework: "nextjs"
  database: "postgres"
  cloudProvider: "vercel"
  deploymentTier: "personal"
  dbProvider: "neon"
  authMode: "api-key"
  browserAgent: "ever"
  skipDeploy: false

• Tell them: "Got it — I'll use the current default template on Vercel + Neon, finish the checks and install, then we're building."
• Skip Question 2 through Question 3 below — jump straight to Phase 4.5 (Verify Setup) with a reduced checklist (runtime, database, and Anthropic key), then skip to Phase 7 (Implement).

If they pick "Let me choose", or picked scale 2 or 3, continue with the full interview below.

Question 2: Auth Model

Ask:

"Will anyone other than you use this clone?

1. Just me — personal or solo use (simpler: API key, no login/signup)
2. Multiple users — team or public (full auth with login/signup)"

Record their answer as authMode:

• Choice 1 → authMode: "api-key"
• Choice 2 → authMode: "better-auth"

This determines how the build agent implements authentication. Save it to ralph-config.json.

Question 2.5: Language

If the user didn't take the beginner fast track, ask about their preferred language:

"What language do you want to build in?

1. TypeScript — broadest current template support, great default for web apps
2. Go — great for APIs and backend services (chi, echo)
3. Python — good for data-heavy or AI products (FastAPI, Django)
4. Rust — for performance-critical services (Axum, Actix)
5. Other — tell me what you want"

Record as language in ralph-config.json. Default to "typescript" if unsure.

Question 2.6: Stack Profile

"Based on what I found about [target product], I'd recommend the [profile] setup. Here's why: [one sentence].

But you can override — which fits best?

1. API service — the target is mainly an API (like Stripe, Twilio, Resend)
2. Dashboard app — it's a web app with a UI (like analytics, admin panels, CRM)
3. Platform — it's infrastructure (like Vercel, Railway, Supabase)
4. Content app — content-focused (like a CMS, docs site, blog platform)
5. Real-time app — live features (like chat, collaboration, live dashboards)"

Record as stackProfile in ralph-config.json.

Question 2.7: Frontend (if backend-only language)

If language is not typescript (e.g., Go, Python, Rust), and the target product has a UI, ask:

"Since [target] has a web UI, what do you want for the frontend?

1. Default web frontend — use the currently supported frontend path
2. None — API-only, no frontend needed
3. Other — tell me what you want"

Record as frontend in ralph-config.json. If the language is typescript, skip this — the frontend framework is the same as the backend.

Record these values in memory. Do not write ralph-config.json or run setup-stack.sh here — Phase 7 handles both after research + final confirmation. Writing early produces incomplete config (missing setup section, services, docsUrl, etc.) and scaffolds the wrong stack if the user changes their mind later.

Question 3: Existing CLI / Account Setup

Based on which services the clone will need (from your Phase 2 research), ask them to tell you what they already have. Don't list everything — only ask about the ones that actually apply to this product.

Frame it like:

"Quick check — which of these do you already have set up? Just say the numbers of the ones you have, or 'none':

1. Vercel CLI (vercel whoami works in your terminal)
2. AWS CLI (aws sts get-caller-identity works)
3. Neon account (neon.tech)
4. [other service relevant to this product] ..."

Adjust the list to match this specific product. For example:

• Only include AWS CLI if the clone needs SES, S3, or Lambda
• Only include Stripe if there's payments
• Only include Upstash Redis if there's a queue or cache layer
• Only include Svix if there's webhook delivery

Question 4: Missing Services — Brief Clarification (if needed)

If they say they're missing something that might confuse them (e.g. they don't know what Neon is), explain it in one sentence before moving on. Don't do a full lecture — just enough to decide if they want to set it up now or later.

"Neon is serverless Postgres — it's the database. Free tier, takes 2 minutes to set up at neon.tech."

If they want to set it up now, wait for them. If they say "I'll do it later", note it as pending and continue.

Phase 4.5: Verify Setup

Don't trust — verify. The user said they have things set up. Now actually check.

Run verification commands for each service they claimed is ready. Only check what's relevant to their chosen stack and the target product's needs.

Verification commands by service

Google OAuth verification (if target product needs auth)

If the target product uses Google OAuth and AUTH_GOOGLE_ID + AUTH_GOOGLE_SECRET are found in .env, perform these additional checks:

1. Calculate the callback URL from BETTER_AUTH_URL (or NEXT_PUBLIC_APP_URL, or default http://localhost:3015):

   {BETTER_AUTH_URL}/api/auth/callback/google

2. Show a checklist the user must complete in Google Cloud Console:

   ⚠ Google OAuth — MANUAL SETUP REQUIRED
     Your keys are set, but you must configure these in Google Cloud Console:
   
     1. Go to: https://console.cloud.google.com/apis/credentials
     2. Click your OAuth 2.0 Client ID
     3. Add these Authorized redirect URIs:
        → http://localhost:3015/api/auth/callback/google  (dev)
        → https://your-domain.com/api/auth/callback/google  (prod, when ready)
     4. Go to OAuth consent screen → Publishing status
        → Set to "External" and click "Publish App"
        → OR: keep in "Testing" mode and add your Google test account
     5. If using Ever CLI for QA: add the Google account that your
        browser is already logged into as a test user. Ever CLI uses
        the existing browser session — if that account isn't authorized,
        automated OAuth flows will fail during QA.
   
     Have you done this? (yes / I'll do it now / skip for later)

3. Wait for confirmation before proceeding. If the user says "skip", add to pending with a warning that QA will fail on auth features.

4. Record in setup checks:

   "google-oauth": { "envVar": "AUTH_GOOGLE_ID", "status": "pass", "detail": "Keys found. Redirect URI + consent screen: user confirmed." }

   Or if skipped:

   "google-oauth": { "envVar": "AUTH_GOOGLE_ID", "status": "pending", "error": "Keys found but redirect URI and consent screen not verified — QA will fail on auth." }