Rails AI Kit — Project Initializer

Automates the full setup of a new project from the rails-ai-kit starter kit. Handles git remote configuration, GitHub repo creation, dependency installation, database preparation, and boot verification — so the project is ready to build features immediately.

This is NOT just a clone. It produces a properly configured project with:

• origin pointing to the new project repo (ready for git push)
• upstream pointing to AAlvAAro/rails-ai-kit (ready for git fetch upstream && git merge upstream/main)
• All dependencies installed, database migrated, and dev server verified

Workflow Overview

Input (project name, optional org)
  → Clone rails-ai-kit
    → Create new GitHub repo
      → Remap git remotes
        → Clean git history (optional)
          → Run bin/setup
            → Verify boot
              → Present result + next steps

---

Step 0: Gather Inputs

Determine these values from the user's message or ask if missing:

Input	Example	Required?
Project name	cafeteria-pro	Yes
GitHub owner/org	AAlvAAro	Default: AAlvAAro
Repo visibility	private or public	Default: private
Fresh history?	yes/no	Default: no (keep rails-ai-kit history)
Parent directory	/Users/aalvaaro/Projects	Default: current working directory

Project name rules:

• Must be lowercase kebab-case (e.g., my-saas-app, not MySaasApp)
• Will be used as: directory name, GitHub repo name, Kamal service name, and database name

If the user says something like "start a new project called Cafeteria Pro", infer:

• Project name: cafeteria-pro
• Repo: AAlvAAro/cafeteria-pro
• Confirm before proceeding

---

Step 1: Clone rails-ai-kit

Clone the starter kit into the target directory with the new project name:

git clone https://github.com/AAlvAAro/rails-ai-kit.git <parent-dir>/<project-name>
cd <parent-dir>/<project-name>

Verify the clone succeeded by checking for key files:

• Gemfile exists
• package.json exists
• CLAUDE.md exists
• bin/setup exists
• app/frontend/pages/ directory exists

If any are missing, abort and report the error.

---

Step 2: Create GitHub Repository

Create the new repo on GitHub using gh:

gh repo create <owner>/<project-name> --<visibility> --source=. --remote=new-origin

If gh is not authenticated, instruct the user to run ! gh auth login and retry.

If the repo already exists, ask the user whether to:

• Use the existing repo (skip creation)
• Choose a different name
• Abort

---

Step 3: Remap Git Remotes

Configure remotes so origin is the new project and upstream tracks rails-ai-kit:

# Rename the original origin to upstream
git remote rename origin upstream

# Rename the remote created by gh to origin
git remote rename new-origin origin

Verify the remote setup:

git remote -v

Expected output:

origin    git@github.com:<owner>/<project-name>.git (fetch)
origin    git@github.com:<owner>/<project-name>.git (push)
upstream  https://github.com/AAlvAAro/rails-ai-kit.git (fetch)
upstream  https://github.com/AAlvAAro/rails-ai-kit.git (push)

If remotes don't match, fix them before proceeding.

---

Step 4: Initialize Git History

If the user chose fresh history:

# Remove existing git history
rm -rf .git
git init
git add -A
git commit -m "Initial commit from rails-ai-kit

Scaffolded from https://github.com/AAlvAAro/rails-ai-kit

Co-Authored-By: Claude <noreply@anthropic.com>"

# Re-add remotes
git remote add origin git@github.com:<owner>/<project-name>.git
git remote add upstream https://github.com/AAlvAAro/rails-ai-kit.git

Note: Fresh history means git merge upstream/main won't work for future updates — warn the user about this tradeoff.

If keeping history (default):

Create an initial project commit to mark the fork point:

git commit --allow-empty -m "Initialize <project-name> from rails-ai-kit

Forked from https://github.com/AAlvAAro/rails-ai-kit
upstream remote tracks the starter kit for future updates.

Co-Authored-By: Claude <noreply@anthropic.com>"

---

Step 5: Push to Origin

Push the initial state to the new repo:

git push -u origin main

Verify with:

gh repo view <owner>/<project-name> --json url --jq '.url'

---

Step 6: Run bin/setup

Install all dependencies and prepare the database:

bin/setup --skip-server

This runs:

1. bundle install — Ruby gems
2. npm install — Node packages
3. bin/rails db:prepare — Database creation and migration

If bin/setup fails, diagnose the error:

Error	Fix
pg gem install fails	Check PostgreSQL is installed: brew install postgresql@17 or brew install postgresql
node not found	Check Node.js is installed: node --version
Database connection refused	Check PostgreSQL is running: brew services start postgresql
ruby version mismatch	Check .ruby-version and install the required version via rbenv or asdf
vite not found	Run npm install manually, then retry

If the error is not in the table, read the full error output and attempt to fix it. Ask the user only if the fix requires system-level changes (installing Homebrew packages, changing system config).

---

Step 7: Verify Boot

Start the dev server and verify it responds:

# Start in background
bin/dev &
DEV_PID=$!

# Wait for server to boot
sleep 8

# Check if it responds
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

# Kill the background server
kill $DEV_PID 2>/dev/null

Success: HTTP 200 (or 302 redirect to login page).

If boot fails:

1. Check log/development.log for errors
2. Check Vite is running (port 5173)
3. Check Rails is running (port 3000)
4. Report the specific error to the user

---

Step 8: Project-Specific Configuration

After successful boot, apply these customizations:

8A: Update Application Name

Search and replace the default app name in key files:

# Find references to the default app name in configuration
grep -r "rails-ai-kit\|RailsAiKit\|rails_ai_kit" --include="*.rb" --include="*.yml" --include="*.json" --include="*.ts" --include="*.tsx" -l

Update these files with the new project name:

• config/application.rb — module name
• package.json — name field
• app/frontend/components/app-logo.tsx — displayed app name

Do NOT rename the CLAUDE.md references to rails-ai-kit — those are documentation about the kit's conventions and should stay as-is.

8B: Generate deploy.yml (if not already configured)

If the user mentions a deployment domain, update config/deploy.yml:

service: <project-name>
image: ghcr.io/<owner>/<project-name>

proxy:
  ssl: true
  host: <project-name>.alvarodelgado.dev

---

Step 9: Present Result

Display a summary:

✅ Project <project-name> is ready!

📁 Location: <parent-dir>/<project-name>
🔗 GitHub:   https://github.com/<owner>/<project-name>
🔀 Remotes:
   origin   → <owner>/<project-name> (your project)
   upstream → AAlvAAro/rails-ai-kit (starter kit)

🛠️ Status:
   Dependencies: ✅ installed
   Database:     ✅ migrated
   Dev server:   ✅ boots successfully

📋 Next steps:
   1. cd <parent-dir>/<project-name>
   2. bin/dev                          # Start development
   3. Open http://localhost:3000
   4. Use /feature-planner to spec your first feature

🔄 To pull starter kit updates later:
   git fetch upstream
   git merge upstream/main

---

Behavior Notes

• Never push to rails-ai-kit. The entire point of this skill is to prevent that. Always verify remotes before any push.
• Keep it fast. The user wants to start building, not wait through a long setup. Skip unnecessary confirmations — confirm once at Step 0, then execute.
• Diagnose, don't bail. If bin/setup fails, read the error and attempt a fix before asking the user. Common issues (missing Postgres, wrong Ruby version) have known solutions.
• Default to keeping history. Fresh history is a destructive choice that breaks upstream merging. Only do it if explicitly requested.
• The --skip-server flag matters. bin/setup without it will start the dev server and block the script. Always use --skip-server for automated setup, then verify boot separately.