project-onboarding

When to Use

• Starting work on an unfamiliar codebase
• After context is lost (new session)
• When

  check_onboarding_performed

  indicates no memories exist
• When user asks to "learn about this project" or "understand this codebase"

Onboarding Workflow

Step 1: Check Existing Knowledge

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

Step 2: Project Discovery

Greenfield vs Brownfield Detection

.git

package.json

requirements.txt

src/

app/

lib/

1. Respect Ignore Files: Check

   .gitignore

   and

   .claudeignore

   BEFORE scanning
2. Efficient File Triage:
   • Use

     git ls-files

     to list tracked files (respects .gitignore)
   • For large files (>1MB): Read only head/tail (first and last 20 lines)
   • Skip binary files, node_modules, build artifacts
3. Infer Tech Stack: Analyze manifests before asking questions
4. Context-Aware Questions: Base questions on discovered patterns

# Efficient file listing (respects .gitignore)
git ls-files --exclude-standard -co | head -100

# For non-git projects with manual ignores
find . -type f \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -100

• Create fresh context artifacts
• Use interactive-requirements-gathering skill for setup

1. Package Manager & Language:

   • package.json

     - Node.js/JavaScript/TypeScript

   • pyproject.toml

     ,

     requirements.txt

     - Python

   • Cargo.toml

     - Rust

   • go.mod

     - Go

   • pom.xml

     ,

     build.gradle

     - Java

   • composer.json

     - PHP
2. Project Type:
   • Frontend, Backend, Fullstack, Library, CLI, Mobile, Monorepo
3. Framework Detection:
   • Parse dependencies for frameworks (React, Next.js, FastAPI, etc.)

Step 3: Build System Analysis

1. Check package.json scripts (Node.js):
   json

   {
     "scripts": {
       "dev": "...",
       "build": "...",
       "start": "...",
       "test": "..."
     }
   }

2. Check Makefiles (Python, Go, Rust):
   makefile

   build:
   test:
   lint:

3. Check pyproject.toml (Python):
   toml

   [tool.poetry.scripts]
   [tool.poe.tasks]

4. Document discovered commands:
   • Development:

     npm run dev

     ,

     uv run dev

   • Build:

     npm run build

     ,

     cargo build

   • Test:

     npm test

     ,

     pytest

   • Lint:

     npm run lint

     ,

     ruff check

Step 4: Directory Structure Mapping

src/

lib/

test/

tests/

__tests__/

docs/

scripts/

config/

• Entry points (

  index.ts

  ,

  main.py

  ,

  app.py

  )
• Component directories
• API routes
• Database models

Step 5: Create Onboarding Memories

# Project Structure

## Overview

- Project Type: [fullstack/backend/frontend/library]
- Primary Language: [TypeScript/Python/Go/Rust]
- Framework: [Next.js/FastAPI/Express/etc.]

## Key Directories

- Source: `src/`
- Tests: `test/`
- Config: `.claude/`

## Entry Points

- Main: `src/index.ts`
- API: `src/api/`

## Important Files

- Configuration: `package.json`, `tsconfig.json`
- Environment: `.env.example`

# Build Commands

## Development

- Start dev server: `npm run dev`
- Watch mode: `npm run watch`

## Build

- Production build: `npm run build`
- Type check: `npm run typecheck`

## Clean

- Clean build: `npm run clean`

# Test Commands

## Unit Tests

- Run all: `npm test`
- Watch mode: `npm test -- --watch`
- Coverage: `npm test -- --coverage`

## E2E Tests

- Run: `npm run test:e2e`

## Linting

- Lint: `npm run lint`
- Fix: `npm run lint:fix`

Step 6: Validation

1. Test Commands (if safe):
   • Run

     npm --version

     or equivalent to verify package manager
   • Run

     npm run --silent

     to list available scripts
   • Do NOT run build or test without user permission
2. Verify Paths:
   • Confirm key directories exist
   • Verify entry points are correct

Step 7: Report Summary

## Onboarding Complete

**Project**: [name]
**Type**: [fullstack/backend/etc.]
**Framework**: [Next.js/FastAPI/etc.]

**Quick Commands**:
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

**Key Locations**:
- Source: `src/`
- Tests: `test/`
- API: `src/api/`

**Memories Created**:
- .claude/context/memory/project-structure.md
- .claude/context/memory/build-commands.md
- .claude/context/memory/test-commands.md

1. Check for existing memories in

   .claude/context/memory/

2. If no memories, run project discovery
3. Analyze package.json, directory structure
4. Create memory files
5. Report summary

## Onboarding Complete

**Project**: agent-studio
**Type**: Multi-agent orchestration framework
**Framework**: Claude Code + Custom agents

**Quick Commands**:
- Validate: `node .claude/tools/validate-agents.mjs`
- Test hooks: `node .claude/hooks/routing/router-enforcer.cjs` (uses `.claude/lib/routing/routing-table.cjs`)

**Key Locations**:
- Agents: `.claude/agents/`
- Skills: `.claude/skills/`
- Memory: `.claude/context/memory/`

**Memories Created**: 3 files

Memory Protocol (MANDATORY)

.claude/context/memory/learnings.md

• New pattern discovered ->

  .claude/context/memory/learnings.md

• Issue encountered ->

  .claude/context/memory/issues.md

• Decision made ->

  .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.