---
roadcrew_template_name: "onboard.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
execution_mode: "auto-execute"
roadcrew_last_updated: "2025-11-02"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# Onboard

Complete onboarding workflow for customers getting started with Roadcrew. Analyzes your repository and updates all project-specific configuration files.

## What This Command Does

1. **Analyzes your repository** - Tech stack, project structure, git configuration
2. **Updates memory-bank/techContext.md** - Comprehensive tech stack documentation
3. **Updates memory-bank/productContext.md** - Project identity and deployment info
4. **Updates .cursor/rules/00-project-context.mdc** - Detected values in frontmatter
5. **Validates all configurations** - Ensures everything is properly set up
6. **Generates onboarding report** - Shows what was updated and next steps

## Files Updated

This command updates exactly these files:

```
memory-bank/techContext.md              (language, runtime, frameworks, dependencies)
memory-bank/productContext.md           (project identity, repositories, deployment mode)
.cursor/rules/00-project-context.mdc    (auto-detected values in YAML frontmatter)
docs/reports/onboarding-TIMESTAMP.md    (onboarding report and summary)
```

## When to Use

Run this command:
- **First time** - Right after Roadcrew installation
- **New team member** - When adding a new developer to the team
- **Project changes** - When you upgrade major dependencies or architecture changes
- **Tech stack updates** - When you add/remove frameworks or tools

## Prerequisites

✅ Roadcrew installed (automatically done during installation)
✅ Node.js 18+ (required)
✅ Git repository initialized
✅ `package.json` exists in project root

## Quick Start

```bash
# Basic onboarding (current project)
/onboard

# Analyze external repository
/onboard --repo=/path/to/other/project

# Verbose mode (see all changes)
/onboard --verbose
```

## Usage

### Option 1: Current Project (Default)

```bash
/onboard
```

Analyzes your current project and updates:
- `memory-bank/techContext.md`
- `memory-bank/productContext.md`
- `.cursor/rules/00-project-context.mdc`

### Option 2: External Repository

```bash
/onboard --repo=/path/to/repo
```

Useful when:
- Analyzing a submodule customer's repository
- Setting up Roadcrew for multiple projects
- Migrating to Roadcrew from another tool

### Option 3: Verbose Output

```bash
/onboard --verbose
```

Shows all changes made line-by-line for review.

## Process

### Step 1: Repository Analysis

The command automatically detects:

**Tech Stack:**
- Language: TypeScript, JavaScript, Python, Go, etc.
- Runtime: Node.js, Python, Deno, Bun, etc.
- Package Manager: npm, yarn, pnpm, pip, etc.
- Framework: Next.js, Express, FastAPI, React, Vue, etc.
- Key dependencies: Top 5-10 dependencies from package.json

**Project Structure:**
- Monorepo vs. single project
- Frontend/backend separation
- Testing setup (Jest, Vitest, Pytest, etc.)
- Build tools (Webpack, Vite, tsc, etc.)

**Architecture:**
- API style (REST, GraphQL, RPC, etc.)
- Database type (if detected)
- CI/CD setup (GitHub Actions, GitLab CI, etc.)

### Step 2: File Updates

**memory-bank/techContext.md** gets populated with:
```markdown
# Technical Context

## Technology Stack
- Language & Version: TypeScript 5.x
- Runtime & Version: Node.js 18.x
- Package Manager: npm 9.x
- Key Frameworks: Next.js 14, React 18, Tailwind CSS
- Testing: Jest, Vitest
- Deployment: Vercel, Docker
- Architecture: Monorepo with Nx
```

**memory-bank/productContext.md** gets:
```markdown
## Project Identity
- Project Name: roadcrew-internal
- Description: Spec-driven development system for building software products at scale
- Internal Repository: https://github.com/tailwind-ai/roadcrew-internal
- Public Repository: https://github.com/tailwind-ai/roadcrew
- Deployment Mode: Submodule
```

**.cursor/rules/00-project-context.mdc** frontmatter gets:
```yaml
---
description: "{{PROJECT_NAME}} Project Context - Quick Reference"
globs: ["**/*"]
alwaysApply: true
# ONBOARD-DETECTED VALUES:
project_name: "roadcrew-internal"
internal_repo: "https://github.com/tailwind-ai/roadcrew-internal"
public_repo: "https://github.com/tailwind-ai/roadcrew"
deployment_mode: "submodule"
detected_at: "2025-11-03T12:00:00Z"
---
```

### Step 3: Validation

The command validates that:
- ✅ All three output files are readable
- ✅ YAML/Markdown syntax is valid
- ✅ Git repository can be detected
- ✅ Project.json exists and is parseable
- ✅ Detected values replace placeholders correctly
- ✅ Files have correct permissions

### Step 4: Onboarding Report

Generates `docs/reports/onboarding-YYYY-MM-DD-HHMMSS.md` with:

**Summary:**
- ✓ Files updated
- ✓ Detection accuracy
- ⚠️ Any issues or manual fixes needed

**What Was Updated:**
- memory-bank/techContext.md tech stack sections
- memory-bank/productContext.md project identity sections
- .cursor/rules/00-project-context.mdc frontmatter values

**Next Steps:**
- [ ] Review `memory-bank/techContext.md` for completeness
- [ ] Review `memory-bank/productContext.md` for accuracy
- [ ] Review `.cursor/rules/00-project-context.mdc` frontmatter values
- [ ] Customize project descriptions if needed
- [ ] Run `/analyze-repo` for deeper tech stack analysis
- [ ] Run `/analyze-frontend` if web application
- [ ] Run `/analyze-backend` if server application

## Output

The command creates/updates:

1. **memory-bank/projectbrief.md** — Core project scope and requirements
   - Auto-filled with detected project type, languages, frameworks
   - Manual editing: Add description, personas, success metrics, constraints

2. **memory-bank/techContext.md** — Technical stack and setup
   - Auto-generated from package.json, lock files, and framework detection
   - Manual editing: Add development setup details, CI/CD info, deployment constraints

3. **.cursor/rules/00-project-context.mdc** — Cursor AI configuration
   - Auto-filled frontmatter with detected values
   - Manual editing: Update project_name, organization, internal_repo, public_repo (optional)

## Understanding the Output

### Detection Accuracy

The command shows detection confidence:
- ✅ High confidence - Detected directly from package.json or config files
- ⚠️ Medium confidence - Inferred from context clues
- ❓ Low confidence - Manual review recommended

### Manual Adjustments Needed

Some items may need manual adjustment:
- **Project description** - If too generic, edit in `memory-bank/productContext.md`
- **Architecture pattern** - May need clarification based on your specific setup
- **Custom framework versions** - If you use beta/canary versions
- **Internal tools** - If you have custom build tools or frameworks

### Team Customization

After onboarding, review these files with your team:

**memory-bank/techContext.md:**
- Add performance requirements
- Document any version pinning
- Add infrastructure details
- Note any custom tooling

**memory-bank/productContext.md:**
- Add team/org information
- Document stakeholders
- Note deployment constraints
- Add links to related docs

**.cursor/rules/00-project-context.mdc:**
- Review detected values in frontmatter
- Correct any auto-detection errors
- Keep template variables for distribution
- Update detection_date if re-running

## Troubleshooting

### "package.json not found"
Your project doesn't have a package.json file. Create one or use `--repo` to specify a different path.

### "Unsupported language detected"
The command primarily supports JavaScript/TypeScript/Python projects. Manual setup may be needed for other languages.

### "No tech stack detected"
This usually means package.json or requirements.txt is malformed. Check syntax and try again.

### "Files are read-only"
Check file permissions:
```bash
# macOS/Linux
chmod 644 memory-bank/techContext.md memory-bank/projectbrief.md .cursor/rules/00-project-context.mdc

# Windows
# Right-click → Properties → Uncheck "Read-only"
```

### "Some placeholders not replaced"
This indicates a detection issue. Check the verbose output:
```bash
/onboard --verbose
```

### "Git config not accessible"
Can't read git remote. Manually set `internal_repo` and `public_repo` in:
- `memory-bank/productContext.md`
- `.cursor/rules/00-project-context.mdc` frontmatter

### "Memory Bank files missing"
Ensure Memory Bank structure exists:
```bash
mkdir -p memory-bank
# Files should have been created during Roadcrew installation
```

## Integration with Other Commands

Use this command with:

- **`/analyze-repo`** - After onboarding, get detailed tech stack analysis
- **`/analyze-frontend`** - Understand your frontend architecture
- **`/analyze-backend`** - Understand your backend architecture
- **`/create-brd`** - Create documentation using detected context

## Best Practices

✅ **Do:**
- Run onboarding soon after installation
- Review all three output files
- Update memory-bank files with team context
- Re-run when major tech stack changes occur
- Use detected values in `.cursor/rules/00-project-context.mdc` to inform rule behavior

❌ **Don't:**
- Edit the .cursor/rules file structure (only review frontmatter)
- Hardcode values (keep {{VARIABLES}} in rule content)
- Skip the review step
- Run too frequently (only when significant changes occur)
- Keep deprecated files like `ai-context.yml` or `.cursor/my-memories.md`

## Examples

### Example 1: New React Project
```bash
/onboard
```
Result:
- Detects React, Next.js, TypeScript
- Sets up memory for React best practices
- Configures Tailwind CSS if detected
- Prepares for component library analysis

### Example 2: Python Backend
```bash
/onboard
```
Result:
- Detects Python, FastAPI, PostgreSQL
- Sets up memory for async patterns
- Configures for API documentation
- Prepares for testing with pytest

### Example 3: Monorepo Project
```bash
/onboard
```
Result:
- Detects Nx or Yarn workspaces
- Identifies sub-projects
- Configures for multi-project analysis
- Sets up appropriate architecture pattern

## Parameters Reference

| Parameter | Usage | Example |
|---|---|---|
| `--repo` | External repository path | `--repo=/path/to/repo` |
| `--verbose` | Show all changes | `--verbose` |
| `--dry-run` | Show what would change (don't modify files) | `--dry-run` |
| `--force` | Overwrite existing configurations | `--force` |

## Notes

- Analysis is non-destructive - existing Memory Bank files are enhanced, not replaced
- Auto-detected values can be manually edited after onboarding
- Re-running onboarding updates detected values but preserves manual edits (additive)
- `.cursor/rules/00-project-context.mdc` frontmatter is auto-updated, rule content is preserved
- Template variables {{VARIABLES}} remain in rule content for customer distribution
- All changes are logged in the onboarding report
- Safe to run multiple times

---

**Related Guides:**
- [Installation Guide](../../docs/INSTALLATION.md)
- [AI Context Guide](../../docs/AI-INTEGRATION-GUIDE.md)
- [Quick Start](../../docs/QUICK-START-VALIDATION.md)