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:

cafeteria-pro

AAlvAAro

AAlvAAro

private

public

private

/Users/aalvaaro/Projects

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

! gh auth login

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

upstream

# 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:

pg

brew install postgresql@17

brew install postgresql

node

node --version

brew services start postgresql

ruby

.ruby-version

rbenv

asdf

vite

npm install

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

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.