onboard

Codebase onboarding orchestrator that scans, documents, summarizes, and teaches a codebase to new developers or to the AI agent itself.

SKILL.md

GitHub

Onboard

Purpose

Onboard is the codebase learning and teaching orchestrator. It systematically explores a codebase and produces a comprehensive understanding that it can either present to a human developer or internalize for its own future use. Onboard answers the question every new team member asks: "How does this all fit together?"

Onboard goes beyond just listing files and directories. It traces data flows, identifies architectural patterns, maps dependencies, finds the critical paths, and explains the "why" behind design decisions when evidence is available. It produces both high-level summaries for quick orientation and deep-dive documentation for reference.

Workflow

Phase 1: Scan

  1. Invoke scout -- Perform a comprehensive codebase scan:
    • Directory structure and organization pattern
    • File types and language composition
    • Entry points (main files, route files, index files)
    • Configuration files and their purposes
    • Dependency manifest (package.json, Cargo.toml, etc.)
    • Test file locations and patterns
    • Build and deployment configuration
  2. Identify the tech stack -- Catalog all technologies:
    • Languages and versions
    • Frameworks and libraries (with versions)
    • Database and storage technologies
    • Infrastructure and deployment tools
    • Development tools (linters, formatters, test runners)
  3. Invoke research (if needed) -- For unfamiliar frameworks or libraries, look up their purpose and patterns via Context7 to understand what role they play.

Phase 2: Map Architecture

  1. Identify architectural pattern -- Determine the overall architecture:
    • Monolith vs microservices vs monorepo
    • MVC, layered, hexagonal, event-driven, etc.
    • Client-server, serverless, edge, etc.
  2. Map module boundaries -- Identify logical modules and their responsibilities:
    • What each top-level directory represents
    • How modules communicate (imports, APIs, events, shared state)
    • Module ownership and dependency direction
  3. Invoke mermaid -- Generate architecture diagrams:
    • High-level system architecture
    • Module dependency graph
    • Data flow diagrams for key operations
    • Database entity relationship diagram (if schema is accessible)
  4. Trace critical paths -- Identify and document the most important code paths:
    • User authentication flow
    • Primary data creation/update flow
    • Request lifecycle (from entry to response)
    • Error handling flow
    • Background job processing (if applicable)

Phase 3: Analyze Patterns & Conventions

  1. Extract coding conventions -- Document the patterns the codebase follows:
    • Naming conventions (files, functions, variables, components)
    • File organization patterns (co-location, feature-based, layer-based)
    • Import patterns (absolute vs relative, barrel files)
    • Component patterns (composition, render props, hooks)
    • State management approach
    • Error handling patterns
    • Logging conventions
  2. Identify key abstractions -- Find and explain the core abstractions:
    • Base classes or shared interfaces
    • Custom hooks or utilities used everywhere
    • Middleware or decorator patterns
    • Configuration and environment handling
  3. Invoke sequential-thinking -- For complex architectural decisions, reason through why they were made based on evidence in the code.

Phase 4: Document

  1. Generate the onboarding guide -- Structure the knowledge into a consumable format:

    Section 1: Quick Start

    • What this project does (one paragraph)
    • How to set it up locally
    • How to run it
    • How to run tests

    Section 2: Architecture Overview

    • System architecture diagram
    • Tech stack table
    • Module map with one-line descriptions

    Section 3: Key Concepts

    • Core domain concepts and terminology
    • Key abstractions and where they live
    • Patterns and conventions to follow

    Section 4: Code Map

    • Directory-by-directory breakdown
    • Key files and what they do
    • Entry points for each major feature

    Section 5: Data Flow

    • How data moves through the system
    • Critical path walkthroughs
    • Database schema overview

    Section 6: Development Guide

    • How to add a new feature (where to put what)
    • How to add a new test
    • How to deploy
    • Common gotchas and tribal knowledge
  2. Invoke docs-writer (if writing to file) -- Format and write the onboarding guide as a document.

Phase 5: Teach

  1. Present the summary -- Deliver the onboarding to the user in the requested format:
    • Interactive: Walk through the codebase conversationally, answering questions as they arise
    • Written guide: Deliver the full document
    • Diagram-heavy: Lead with visual architecture diagrams, supplement with text
  2. Answer questions -- Be prepared to go deeper on any area the user asks about.
  3. Write to memory -- Store the codebase knowledge for future sessions so subsequent interactions don't need a full re-scan.

Output Formats

Quick Summary (for experienced developers)

Project: [name] - [one-line description]
Stack: [language] + [framework] + [database] + [deployment]
Architecture: [pattern] with [key characteristic]
Entry: [main entry file] -> [routing] -> [handlers] -> [data layer]
Tests: [test runner] in [test directory], run with [command]
Key dirs: [dir1] (purpose), [dir2] (purpose), [dir3] (purpose)

Full Onboarding (for new team members)

Complete multi-section document as described in Phase 4.

Architecture Deep Dive (for architects)

Focused on architectural decisions, trade-offs, and technical debt with supporting diagrams.

Decision Points

Condition Action
Small project (< 50 files) Quick summary format, skip deep architecture
Large project (> 500 files) Full onboarding with all sections
Monorepo Document each package/app separately, then integration
User asks about specific area Focus onboard on that area, brief overview of rest
Unfamiliar technology detected Invoke research via Context7 before documenting
Complex architecture Invoke sequential-thinking to explain design rationale
Codebase already scanned in memory Skip Phase 1, update only changed areas

Usage

Use Onboard when encountering a new codebase for the first time, when a new team member joins, or when you need to refresh understanding of a project you haven't worked on recently.

Best for:

  • First encounter with a new codebase
  • Onboarding new team members
  • Documenting an undocumented project
  • Refreshing context after time away from a project
  • Understanding a project before an audit
  • Preparing to contribute to an open-source project

Not ideal for:

  • Building features (use cook after onboarding)
  • Code review (use code-review)
  • Auditing for issues (use audit)

Examples

Example 1: Full codebase onboarding

User: /onboard Walk me through this codebase

Onboard workflow:
1. scout -> Scan: Next.js app, 234 files, TypeScript, Prisma, Tailwind
2. Architecture -> App Router pattern, API routes, Prisma data layer
3. mermaid -> System diagram, module deps, auth flow, data creation flow
4. Patterns -> Feature-based directories, custom hooks pattern, Zod validation
5. Document -> Full 6-section onboarding guide
6. Present -> Deliver guide, offer to deep-dive on any section

Example 2: Focused module onboarding

User: /onboard Explain the payment system in this codebase

Onboard workflow:
1. scout -> Focus scan on payment-related files and dependencies
2. Architecture -> Payment module boundaries, Stripe integration points
3. mermaid -> Payment flow diagram (checkout -> webhook -> fulfillment)
4. Patterns -> Payment-specific error handling, retry logic, idempotency
5. Document -> Payment system deep-dive document
6. Present -> Walkthrough of the payment flow with key files

Example 3: Self-onboarding (AI learning)

User: /onboard Learn this codebase so you can help me effectively

Onboard workflow:
1. scout -> Full codebase scan
2. Architecture -> Map all modules and patterns
3. Key abstractions -> Identify core utilities, shared types, conventions
4. Memory write -> Store complete codebase map, conventions, and patterns
5. Present -> Brief summary to user, deep knowledge stored for future use
6. Ready -> "I've learned the codebase. Here's a quick overview..."

Example 4: Open-source contribution prep

User: /onboard I want to contribute to this open-source project, help me understand it

Onboard workflow:
1. scout -> Scan codebase + look for CONTRIBUTING.md, CODE_OF_CONDUCT.md
2. Architecture -> Map the project structure and key modules
3. research -> Check project docs, issue tracker patterns, PR conventions
4. Document -> Contributor-focused guide: where to add code, test patterns,
              PR expectations, coding style
5. Present -> "Here's how this project works and how to contribute..."

Guardrails

  • Read-only. Onboard never modifies source code. It only reads and analyzes.
  • Start broad, go deep. Always provide the high-level overview before diving into details.
  • Show, don't just tell. Use diagrams for architecture, code snippets for patterns, examples for conventions.
  • Admit uncertainty. If the "why" behind a design decision is unclear, say so rather than guessing.
  • Respect scope. If asked about one module, don't dump the entire codebase analysis.
  • Update, don't rebuild. If the codebase was previously onboarded and stored in memory, only re-scan changed areas.
  • Tailor to the audience. Junior developers need more explanation; architects need more diagrams and trade-off analysis.
  • Always include "how to get started." The most important outcome is that the reader can set up and run the project.