project-onboarding

When to Use

Invoke this skill when:

• 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

First, check if onboarding was already performed:

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

If memories exist, read them and skip to Step 6 (Validation).

Step 2: Project Discovery

First, classify the project:

Greenfield vs Brownfield Detection

Indicator	Present?	Classification
.git directory with history	Yes	Brownfield
Package manifest (package.json, requirements.txt, etc.)	Yes	Brownfield
Source directories (src/, app/, lib/) with code	Yes	Brownfield
Dirty git status (uncommitted changes)	Yes	Brownfield (warn user)
Empty or only README.md	None of above	Greenfield

For Brownfield Projects:

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

For Greenfield Projects:

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

Analyze the project root to identify:

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

Identify how to build/run the project:

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

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

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

   build:
   test:
   lint:
   

3. Check pyproject.toml (Python):

   [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

Map key directories:

Directory	Purpose
src/	Source code
lib/	Library code
test/, tests/, __tests__/	Test files
docs/	Documentation
scripts/	Utility scripts
config/	Configuration files

Identify:

• Entry points (index.ts, main.py, app.py)
• Component directories
• API routes
• Database models

Step 5: Create Onboarding Memories

Save discovered information to persistent memories:

Memory: project-structure.md

# 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`

Memory: build-commands.md

# 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`

Memory: test-commands.md

# 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

Validate discovered information:

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

Output a concise 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

Agent Actions:

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

Output:

## Onboarding Complete

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

**Quick Commands**:
- Validate: `node .claude/tools/cli/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

</usage_example>

Iron Laws

1. ALWAYS check for existing onboarding memories before running discovery — duplicate onboarding creates contradictory knowledge entries that mislead future agents.
2. NEVER assume standard conventions without verification — run commands to confirm what actually works in this specific project environment.
3. ALWAYS write discovered commands and paths to persistent memory files — session context resets, but named memory files survive indefinitely.
4. ALWAYS verify discovered commands with a safe test step before documenting — incorrect commands in onboarding memories mislead every agent that reads them.
5. NEVER complete onboarding without revisiting memories when the project evolves — stale onboarding artifacts are more dangerous than no onboarding.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Assuming standard conventions without checking	Every project has unique build/test/lint commands; wrong assumptions cause silent failures	Read package.json, Makefile, or pyproject.toml and run --version to confirm
Skipping verification of discovered commands	Documented-but-wrong commands mislead every future agent session	Run each command with a safe no-op or --help flag to confirm it works
Storing onboarding only in session context	Context resets on every new conversation; discoveries are permanently lost	Write all findings to named memory files in .claude/context/memory/named/
Treating onboarding as a one-time event	Projects evolve; stale commands fail silently and waste agent time	Update onboarding memories after any significant project structure change
Over-documenting without prioritizing key commands	Long files with low-priority info bury the critical build/test commands	Structure memories with Quick Start commands at the top, details below

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• 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.