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 tooling, configures environment variables, and captures the MVP brief that powers the first set of Project Requirement Plans (PRPs).
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 now flows through eight streamlined phases:
Environment Detection – Identify macOS, Linux, or WSL2. Native Windows users are paused until WSL2 + Ubuntu is installed.
Toolchain Bootstrap – Verify Git, Node.js ≥ 20.18.1, and pnpm. Install missing dependencies, initialise git, and create a working branch.
Dependency Install – Run pnpm install. If it fails, apply the automated recovery path (pnpm store prune, remove node_modules, retry) and narrate the fix.
Environment Configuration – Copy .env.example → .env.local, pause for the user to fill secrets, add safe placeholders if required, then sync with pnpm convex:env.
Launch Apps – Start pnpm dev:auto, wait for the READY banner, and verify marketing (:3000) and dashboard (:3001) are online.
Capture the Brief – Gather name, one-liner, audience, value prop, MVP must-haves, and visual vibe. Persist the answers in features/INITIAL_APP_FEATURE.md and features/INITIAL_REBRAND.md.
Generate PRPs – Re-run /prime, call /generate-prp for the feature and rebrand briefs, and stop for user approval before any execution.
Execute & Wrap Up – With explicit consent, run /execute-prp for each plan, validate (pnpm validate), and deliver a closing summary.
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 MVP features captured during onboardingfeatures/INITIAL_REBRAND.md– Visual direction, styling preferences, brand tone, and palette decisions- Generated PRPs – Project Requirement Plans for feature work and rebranding, ready to execute once approved
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: