Initialize Your Project

After create-red-app scaffolds the codebase, run /red-init once to turn the starter into your project. It is an interactive setup skill: it asks questions, shows a summary, waits for your confirmation, then applies the changes.

Prerequisites

• Open Claude Code in the RED project root.
• The project was scaffolded with bun create red-app my-project --license <key>.
• .red-version exists and is committed.
• .red-license exists and is git-ignored.

If .red-version or .red-license is missing, the skill stops and asks you to scaffold with create-red-app first.

Run the Skill

/red-init

The skill follows a fixed sequence so setup stays reviewable.

Phase 0: Preflight

The skill verifies:

• .red-license exists.
• .red-version exists.
• .gitignore ignores .red-license.
• .red-version remains tracked because future updates use it as the RED base version.

Phase 0b: Convex Backend

RED uses Convex for backend functions, storage, scheduling, and reactive data. The skill asks how you want to configure it:

• Existing project — provide a deployment name like my-app-123. The skill writes .env.local with CONVEX_DEPLOYMENT, VITE_CONVEX_URL, and VITE_CONVEX_SITE_URL.
• Create a new project — run bunx convex dev --once in a separate terminal. The Convex CLI needs browser login and project selection, so the skill waits for you to confirm when it completes.
• Skip for now — continue setup and configure Convex later.

After Convex setup, the skill checks .env.local. If the Convex CLI wrote CONVEX_URL or CONVEX_SITE_URL, the skill renames them to VITE_CONVEX_URL and VITE_CONVEX_SITE_URL because Vite only exposes VITE_ variables to the frontend.

Phase 1: Project Name

Choose the name shown in the app, emails, and admin UI.

Phase 2: Domain Model

RED ships with a Books demo domain. Choose one:

• Keep Books — best if you want a working reference while learning.
• Remove Books — best if you want a clean codebase.
• Replace with custom — scaffold your own entity, then remove Books.

For a replacement, the skill asks for:

• Entity name and purpose.
• Key fields beyond defaults like userId, organizationId, and creatorName.
• Optional child entity, such as comments, line items, or sections.

New entities follow RED’s org-scoped pattern: organizationId, a by_org index, and permission entries for owner, admin, and member roles.

Phase 3: Auth and Access

Choose:

• Signup mode — open signup, waitlist first, or invite only.
• Organization creation — users can create organizations, or only admins can create them.

These choices update the default configuration used by the app and admin settings.

Phase 4: Optional Modules

Choose which optional modules to keep:

• AI Chat — threads, boundaries, tool calling, agent runs, and task-backed AI workflows.
• Billing — Autumn plans, entitlements, metered usage, and Stripe checkout.
• API Keys — org-scoped API keys with JWT token exchange and rate limiting.

Modules you remove are deleted from code and integration points are cleaned up.

Phase 4b: Documentation Site

RED includes apps/docs/, which documents RED itself. Most product teams remove it during initialization. Keep it only if you want to repurpose it as your own docs site.

Phase 5: Summary and Confirmation

The skill shows a summary of every choice. No files are changed until you confirm.

Phase 6: Apply Changes

After confirmation, the skill applies changes in order:

1. Updates the project name in configuration.
2. Keeps, removes, or replaces the demo domain.
3. Applies auth and organization defaults.
4. Removes unselected optional modules.
5. Removes apps/docs/ if requested.
6. Runs verification.
7. Runs bun run seed if Convex is configured.

If Convex was configured, verification includes bunx convex dev --once and bun run lint. If Convex was skipped, the skill skips backend verification and tells you what to run later.

After Initialization

Run the app:

bun dev

If Convex was skipped, configure it first:

bunx convex dev --once
bun run seed

Then open http://localhost:5173, sign in with the seeded admin credentials, and verify the app loads with no console errors.

Important Notes

• Treat /red-init as first-time setup for a freshly scaffolded project.
• Do not delete core modules: auth, admin, audit, config, email, users, and organizations.
• If you keep the AI module, read Core Mental Model before adding custom agents.
• Set RESEND_API_KEY in Convex environment variables before relying on real email delivery.
• Set the Site URL in Admin > Configure > General so email links and CORS use the correct origin.