Onboard

Role-Based Onboarding

If --role is specified, customize the guide:

Frontend Developer Path

Focus areas:

• Component architecture and patterns
• State management approach
• Styling conventions
• Build and dev server setup
• Browser testing workflow

Key files to highlight:

find . -name "*.tsx" -o -name "*.css" -o -name "*.scss" | head -20
grep -r "useState\|useEffect\|createContext" --include="*.tsx" -l | head -10

Backend Developer Path

Focus areas:

• API structure and routing
• Database setup and migrations
• Authentication/authorization
• Testing strategy
• Deployment process

Key files to highlight:

find . -name "routes*" -o -name "controller*" -o -name "service*" | head -20
grep -r "router\|app\.get\|app\.post" --include="*.ts" -l | head -10

Fullstack Developer Path

Include both paths above, plus:

• How frontend and backend communicate
• Shared types/contracts
• End-to-end testing
• Local development with both running

Philosophy

• Assume nothing - New devs don't know your conventions
• Explain the why - Context prevents future mistakes
• Show the path - From setup to first commit
• Reveal the gotchas - What bit you, will bite them
• Keep it current - Outdated onboarding is cruel

Phase 1: Project Discovery

Project Snapshot

# Project basics
tree -L 2 -I 'node_modules|__pycache__|.git|dist|build|.venv' .

# Tech stack
cat package.json 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -30
cat requirements.txt 2>/dev/null

# Recent activity
git log --oneline -20
git shortlog -sn --since="6 months ago" | head -10

Project Profile

┌─────────────────────────────────────────────────────────────┐
│  PROJECT: [Name]                                            │
├─────────────────────────────────────────────────────────────┤
│  What it does: [one sentence]                               │
│  Tech stack: [languages/frameworks]                         │
│  Repo age: [X months/years]                                 │
│  Active contributors: [count]                               │
│  Size: [~lines of code]                                     │
│  Complexity: [Low/Medium/High]                              │
└─────────────────────────────────────────────────────────────┘

Phase 2: Generate Onboarding Doc

ONBOARDING.md Structure

# Onboarding Guide: [Project Name]

> Welcome! This guide will get you productive in [project] as fast as possible.

## What This Project Does

[2-3 paragraphs explaining:]
- What problem does this solve?
- Who uses it?
- Why does it exist?

## The 10-Minute Setup

### Prerequisites

Before you start, make sure you have:

- [ ] [Tool 1] version X+ (`tool --version` to check)
- [ ] [Tool 2] version X+
- [ ] Access to [service/resource]
- [ ] [Account/credentials] from [person/place]

### Step-by-Step Setup

\`\`\`bash
# 1. Clone and enter
git clone [repo-url]
cd [project-name]

# 2. Install dependencies
[install command]

# 3. Set up environment
cp .env.example .env
# Edit .env with values from [source]

# 4. Initialize database (if applicable)
[db setup command]

# 5. Verify it works
[test/run command]
\`\`\`

### "It's Not Working" Troubleshooting

**Problem**: [Common issue 1]
**Solution**: [How to fix]

**Problem**: [Common issue 2]
**Solution**: [How to fix]

---

## Understanding the Codebase

### Project Structure

\`\`\`
[project]/
├── src/                 # [What's in here]
│   ├── components/      # [What's in here]
│   ├── services/        # [What's in here]
│   └── utils/           # [What's in here]
├── tests/               # [What's in here]
├── config/              # [What's in here]
└── docs/                # [What's in here]
\`\`\`

### Key Files to Know

| File | Purpose | When You'll Touch It |
|------|---------|---------------------|
| `src/main.ts` | Application entry point | Rarely |
| `src/config.ts` | All configuration | When adding config |
| `src/routes/` | API endpoints | Adding new APIs |
| `.env` | Local secrets | Setup only |

### Architecture Overview

[Diagram showing main components and how they connect]

\`\`\`
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Frontend│────►│   API   │────►│Database │
└─────────┘     └─────────┘     └─────────┘
\`\`\`

[Brief explanation of data flow]

---

## How We Work

### Development Workflow

\`\`\`
1. Create branch from main: git checkout -b feat/your-feature
2. Make changes
3. Run tests: [test command]
4. Commit with conventional commits: git commit -m "feat: add thing"
5. Push and create PR: gh pr create
6. Get review, address feedback
7. Merge after approval
\`\`\`

### Branch Naming

- `feat/description` - New features
- `fix/description` - Bug fixes
- `refactor/description` - Code refactoring
- `docs/description` - Documentation

### Commit Messages

We use [conventional commits / your format]:

\`\`\`