/onboard

name: onboard
description: "Sets up ai-toolkit in a project: symlinks, CLAUDE.md, intent interview. Triggers: onboard, setup project, install ai-toolkit, migrate project."
effort: medium
disable-model-invocation: true
argument-hint: "[project-path]"
allowed-tools: Bash, Read, Write, Glob

/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

| 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