onboard-codebase

Onboard Codebase

Generate a comprehensive onboarding guide for a new developer joining the project, identifying key code, architecture, and people to talk to.

Prerequisites

Omen CLI must be installed and available in PATH.

Workflow

Step 1: Get a Quick Code Map

Run the outline command for a token-cheap overview of every file's structure:

omen -f json outline --compact --top 50

This returns imports, classes with methods, and top-level functions — much cheaper than reading full source files.

Step 2: Identify Key Symbols

Run the repomap analysis to find the most important code:

omen -f json repomap --compact --top 25

PageRank-ranked symbols show what's central to the codebase.

Step 3: Map the Architecture

Run the dependency graph analysis to understand structure:

omen -f json graph

This reveals how the codebase is organized and how modules relate.

Step 4: Identify Subject Matter Experts

Run the ownership analysis to find who knows what:

omen -f json ownership

This shows who has expertise in each area of the code.

Step 5: Find Complexity Hotspots

Run the complexity analysis to identify tricky areas:

omen -f json complexity

New developers should be warned about complex areas.

Output Format

Generate an onboarding guide:

# Onboarding Guide: <Project Name>

## Quick Start
1. Clone the repo: `git clone ...`
2. Install dependencies: `...`
3. Run tests: `...`
4. Start dev server: `...`

## Architecture Overview

### Module Structure

src/ ├── core/ # Core business logic ├── api/ # HTTP handlers ├── storage/ # Database layer └── utils/ # Shared utilities

### Key Dependencies
- `core/` depends on `storage/`
- `api/` depends on `core/`
- `utils/` is shared by all

## Important Code to Understand

### Core Symbols (by importance)
1. `core.Engine` - Main processing engine, heart of the system
2. `api.Router` - HTTP routing and middleware
3. `storage.Repository` - Database abstraction
4. ...

### Entry Points
- `cmd/server/main.go` - Main server entry point
- `cmd/worker/main.go` - Background job processor

## Subject Matter Experts

| Area | Expert | Notes |
|------|--------|-------|
| Core engine | [email protected] | Original author |
| API layer | [email protected] | Recent maintainer |
| Storage | [email protected] | Database specialist |

## Areas to Be Careful With

### High Complexity
- `core/processor.go` - Cognitive complexity: 45
  - Talk to alice before modifying
  - Has many edge cases

- `api/middleware.go` - Cyclomatic complexity: 28
  - Authentication logic is tricky
  - Well-tested but fragile

### Knowledge Silos
- `legacy/importer.go` - Only one contributor
  - Documentation is sparse
  - Ask alice for context

## First Tasks Suggestions

Good starter tasks to learn the codebase:
1. Add a new API endpoint (learn api/ patterns)
2. Write tests for an untested function (learn testing patterns)
3. Fix a documentation issue (explore while reading)
4. Address a simple TODO/FIXME (learn code style)

## Resources

- Design docs: `docs/design/`
- API docs: `docs/api/`
- Team wiki: <link>