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 ```bash # 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 AGENTS.md Project instructions live in `AGENTS.md`, read by every coding agent; `CLAUDE.md` imports it. `ai-toolkit install --local` creates both, or moves an existing `CLAUDE.md` with `ai-toolkit adopt-agents-md`. By hand: ```bash cp /path/to/ai-toolkit/app/AGENTS.md.template ./AGENTS.md printf '@AGENTS.md\n' > CLAUDE.md ``` Keep `AGENTS.md` under 24,000 bytes: Antigravity truncates larger files. 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 ```bash /path/to/ai-toolkit/validate.sh ``` ### Step 6: Quick Start Guide | Command | Purpose | |---------|---------| | `/explore` | Understand the codebase | | `/plan` | Plan a new feature | | `/test` | Run tests | | `/review` | Code review | | `/commit` | Create a structured commit | ## 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