Onboard

/onboard - Project Setup Guide

$ARGUMENTS

What This Command Does

Guide the user through setting up the ai-toolkit in their project, including configuration and customization.

Setup Steps

Step 0: Intent Capture Interview

Before setting up tooling, understand the project's undocumented context. Ask the developer these questions (adapt based on what the codebase scan reveals):

1. What's the one thing a new contributor always gets wrong? — This reveals the biggest documentation gap
2. Are there files or directories that should NOT be modified? — Identifies protected areas (legacy, generated, vendor)
3. What's the deployment model? — Monolith, microservices, serverless, edge — shapes which agents and skills are most relevant
4. Are there non-obvious constraints? — Compliance requirements, performance budgets, browser support matrix
5. What's the team's review culture? — Strict PR reviews, trunk-based, pair programming — configures /review behavior

Use answers to:

• Customize the generated CLAUDE.md with project-specific warnings and conventions
• Select the right --profile (minimal/standard/strict) automatically
• Pre-configure relevant language rules

Step 1: Prerequisites Check

• Claude Code CLI installed
• ai-toolkit repository cloned
• Current directory is the target project

Step 2: Install Toolkit

# Run the installer from the toolkit directory
/path/to/ai-toolkit/install.sh

This creates symlinks in .claude/:

• agents/ -> toolkit agents
• skills/ -> toolkit skills (slash commands + knowledge skills)
• hooks.json -> quality gates
• constitution.md -> safety rules

Step 3: Configure CLAUDE.md

Create a project-specific CLAUDE.md from the template:

cp /path/to/ai-toolkit/CLAUDE.md.template ./CLAUDE.md

Customize with:

• Project description and tech stack
• Coding standards specific to this project
• Common development commands
• Architecture notes

Step 4: Configure Settings

Edit .claude/settings.local.json for project-specific settings:

• MCP server connections
• Permission overrides
• Environment variables

Step 5: Verify Installation

/path/to/ai-toolkit/validate.sh

Step 6: Quick Start Guide

Usage Examples

/onboard              # Full guided setup
/onboard verify       # Just verify existing installation
/onboard update       # Update toolkit symlinks

Rules

• MUST run the intent-capture interview before creating any files — skip only if the user provides answers up front
• NEVER overwrite an existing CLAUDE.md without confirming
• CRITICAL: prefer project-local installation (--local) unless the user asks for global
• MANDATORY: verify installation at the end with the toolkit's validate script

Gotchas

• On Windows without WSL, symlink creation requires either Developer Mode or admin privileges. The installer silently skips agents and skills that cannot be linked — verify with ai-toolkit doctor after install on Windows hosts.
• If .claude/ already exists as a real directory (not a symlink), ai-toolkit install will not replace it. Old files linger. Check ls -la .claude/ for mixed symlink + real-file state before onboarding.
• settings.local.json is per-user and gitignored, but settings.json is shared. Users who edit the wrong file lose their overrides on git pull.
• When the target project is a git submodule, the toolkit's notion of "project root" (outermost .git) differs from the developer's — symlinks may land in the parent repo instead of the submodule. Confirm git rev-parse --show-toplevel before installing.

When NOT to Use

• To update an already-onboarded project — use /onboard update
• To scaffold a new app from scratch — use /app-builder
• For plugin development inside ai-toolkit — use /plugin-creator
• When the project already has its own CLAUDE.md conventions — discuss migration before overwriting