Onboarding System Skill

A structured six-phase methodology for onboarding to new Java codebases, with templates for documentation and progress tracking.

Purpose

This skill provides a systematic approach to learning a new codebase, with clear phases, defined outputs, and progress tracking to ensure nothing is missed and learnings are preserved.

The Six Onboarding Phases

Phase Details

Phase 1: Setup

Goal: Get the project building and running locally

Activities:

• •Clone repository
• •Install prerequisites (Java version, Maven/Gradle, Docker, etc.)
• •Set up environment variables
• •Build the project
• •Run tests
• •Start the application
• •Verify it works

Output: docs/architecture/setup-notes.md with:

• •Prerequisites table
• •Quick start commands
• •Environment variables
• •Common issues & fixes
• •Useful commands
• •Local URLs

Phase 2: Cartography

Goal: Create a mental map of the architecture

Activities:

• •Run analyze-structure.sh - Get overall structure
• •Run find-entrypoints.sh - Find where execution begins
• •Run dep-graph.sh - Understand dependencies
• •Review README and any existing documentation
• •Identify modules and their purposes
• •Identify technology stack

Output: docs/architecture/overview.md with:

• •System purpose statement
• •High-level architecture diagram
• •Technology stack table
• •Module map
• •Key entry points
• •External integrations

Phase 3: Domain

Goal: Understand the business domain and vocabulary

Activities:

• •Identify core domain entities
• •Map entity relationships
• •Document business rules
• •Create glossary of terms
• •Identify status/state machines
• •Understand key workflows

Output: docs/architecture/domain-glossary.md with:

• •Core entities table
• •Entity relationship diagram
• •Status enums and transitions
• •Business rules
• •Term glossary
• •Acronyms

Phase 4: Modules

Goal: Deep understanding of key modules

Activities:

• •Prioritize modules by importance
• •For each module:
  • •Run map-vertical-slice.sh for key entities
  • •Trace request flows
  • •Document business logic
  • •Map dependencies
  • •Review tests
  • •Note configuration
  • •Document patterns used

Output: docs/architecture/modules/{module-name}.md for each module

Phase 5: Cross-cutting

Goal: Understand shared patterns and infrastructure

Activities:

• •Document authentication mechanism
• •Document authorization model
• •Understand logging patterns
• •Learn error handling patterns
• •Find configuration management approach
• •Identify caching strategy
• •Understand transaction management

Output: docs/architecture/cross-cutting.md

Phase 6: Contribute

Goal: Ship your first change

Activities:

• •Pick a small, well-defined task
• •Create a branch
• •Implement the change
• •Write tests
• •Submit PR
• •Incorporate feedback
• •Get merged

Output: Personal journal with learnings

Progress Tracking

Progress is tracked in .claude/onboarding-progress.yml:

project: project-name
started: 2025-01-15
current_phase: 2

phases:
  setup:
    status: complete
    completed: 2025-01-15
  cartography:
    status: in_progress
    started: 2025-01-16
    modules_identified: []
  domain:
    status: not_started
  modules:
    status: not_started
    explored: []
    pending: []
  cross_cutting:
    status: not_started
  contribute:
    status: not_started
    first_pr: null

questions:
  - "How does the auth token refresh work?"

contacts:
  - name: "Jane Smith"
    role: "Tech Lead"
    area: "Payments"

learnings:
  - "The 'legacy' package is deprecated"

bookmarks:
  - path: "src/main/java/com/example/Application.java"
    description: "Main entry point"

Templates

Documentation templates are in templates/:

• •progress.yml - Progress tracker template
• •setup-notes.md - Phase 1 output
• •overview.md - Phase 2 output
• •domain-glossary.md - Phase 3 output
• •module-notes.md - Phase 4 per-module template
• •cross-cutting.md - Phase 5 output
• •journal.md - Personal learning log

Project Context

Users can add project-specific context that the orchestrator reads:

Location: .claude/onboarding-context.md

# Project Context

## Business Domain
This is a [describe what the product does]

## Key Stakeholders
- Product: @person
- Architecture: @person

## Important Links
- Confluence: [url]
- Runbooks: [url]

## Known Gotchas
- The "legacy" package is deprecated, ignore it

Output Locations

Shareable documentation (commit to repo):

docs/architecture/
├── overview.md
├── setup-notes.md
├── domain-glossary.md
├── cross-cutting.md
└── modules/
    ├── auth.md
    ├── payments.md
    └── ...

Personal notes (local only):

~/.claude/onboarding/{project}/
├── journal.md
├── questions.md
└── scratch/

Progress tracking:

{repo}/.claude/onboarding-progress.yml

Integration

This skill is used by:

• •onboarding-orchestrator agent - Drives the entire process
• •codebase-cartographer agent - Phase 2
• •module-archaeologist agent - Phase 4

Best Practices

1. •Complete phases in order - Each phase builds on the previous
2. •Document as you go - Don't wait until the end
3. •Track questions - Write them down immediately
4. •Update progress - After each session
5. •Share documentation - PR the docs/architecture folder
6. •Keep personal notes - For things not appropriate to share
7. •Celebrate completions - Each phase is an achievement