AI Onboarding
Automated setup with AI guidance from environment detection to MVP deployment.
The AI onboarding flow automates the entire installation process through the /initialize command. The assistant detects the operating system, installs required tools, configures environment variables, and generates an MVP based on the product brief.
Prerequisites
AI agent with file system access (Claude Code, Cursor, Windsurf, or similar) and internet connectivity for package downloads. The agent reads llms/commands/initialize.md and executes each step interactively.
Starting the Onboarding
Instruct the AI agent to execute the initialization command:
Read and execute llms/commands/initialize.mdThe agent reads llms/CORE.md for context, then begins the setup workflow.
Onboarding Workflow
The initialization process follows a structured sequence:
Environment Detection - Identifies macOS, Linux, or WSL2. Native Windows users are directed to install WSL2 + Ubuntu before proceeding.
Toolchain Verification - Checks for Git, Node.js 20.18.1+, and pnpm. Missing tools are installed via Homebrew, nvm, or corepack. The agent initializes git and creates a setup branch.
Dependency Installation - Runs pnpm install. Failures trigger automatic recovery: store pruning, node_modules cleanup, and reinstall.
Environment Configuration - Copies .env.example to .env.local and prompts for credentials. The process pauses until environment variables are confirmed complete.
First Boot - Executes pnpm dev:auto and monitors for READY signal. Errors are diagnosed and resolved interactively.
Product Brief - Reads features/INITIAL_APP_FEATURE.md and features/INITIAL_REBRAND.md, then collects app details: name, description, audience, and value proposition. Requires user approval before proceeding.
Core Features - Identifies must-have features for MVP v0. Backend infrastructure (auth, billing, database) remains unchanged. Features are written to INITIAL_APP_FEATURE.md and require approval.
Visual Rebrand - Captures visual direction (clean SaaS, bold gradients, muted serif, primary color). Writes to INITIAL_REBRAND.md and requires approval.
PRP Generation - Re-runs /prime context, then generates two PRPs: /generate-prp features/INITIAL_APP_FEATURE.md for features and /generate-prp features/INITIAL_REBRAND.md for design. Both require approval before execution.
PRP Execution (Rebrand) - Asks permission to execute rebranding PRP via /execute-prp. Monitors progress and validates with pnpm validate.
PRP Execution (Features) - Asks permission to execute feature PRP. Ensures all validations pass.
Summary - Reports installation status, confirms app is running, and lists completed MVP tasks.
Stop Points
The initialization process includes deliberate pause points requiring user confirmation:
Generated Artifacts
The onboarding process creates structured documentation:
features/INITIAL_APP_FEATURE.md- Product brief, target audience, value proposition, and core MVP features agreed upon during setupfeatures/INITIAL_REBRAND.md- Visual direction, styling preferences, color scheme, and typography decisions for the rebrand- Generated PRPs - Project Requirement Plans for feature implementation and design rebrand with task breakdowns and validation steps
Platform-Specific Behavior
WSL2 Required for Windows
Native Windows environments are not supported. The agent stops and provides WSL2 installation instructions before proceeding with setup.
Safety and Idempotency
The initialization process includes safety mechanisms:
- Secrets are never printed to stdout or logs
- File overwrites require explicit user confirmation
- Each step detects completion status and skips if already done
- Failed steps provide diagnostic information and recovery options
- Version checks ensure Node.js ≥20.18.1 before proceeding
Development Commands
After onboarding completes, the standard development workflow:
# Applications run automatically after first boot
# Marketing: http://localhost:3000
# Dashboard: http://localhost:3001
# Restart development servers
pnpm dev
# Run validation checks
pnpm validate
# Execute tests
pnpm testManual Setup Alternative
For developers preferring manual installation: