Codebase Onboarding

This is an OMH codebase-onboarding workflow skill, projected for Agent Skills hosts (Claude Code, Codex, Cursor, opencode, OpenClaw, pi).

Why This Exists

codebase-onboarding adapts ECC's code-tour and onboarding surfaces into an OMH-native first-read workflow so unfamiliar repos become navigable before implementation pressure starts.

Do Not Use When

• The user already named a concrete implementation task and acceptance criteria; use ultrawork or idea-to-deploy.
• The user needs a whole-workspace capability inventory; use workspace-audit.
• The user wants a code diff review; use code-review.

Examples

Good example:

• Prompt: codebase-onboarding 처음 보는 레포라서 구조, 주요 모듈, 테스트, 첫 작업 후보를 잡아줘.
• Expected behavior: Prepare repo_map/v1, reading_path/v1, domain_glossary/v1, risk map, and first_task_runway/v1 from observed files.
• Why: The request is repo orientation before implementation.

Bad example:

• Prompt: codebase-onboarding 파일 안 읽고 이 레포 아키텍처를 확정해줘.
• Expected behavior: Mark architecture as unobserved and inspect source evidence before making claims.
• Why: Onboarding is only useful when grounded in current repo evidence.

Completion Checklist

• The plan names goals, non-goals, assumptions, acceptance criteria, and verification shape.
• Draft recommendations, accepted decisions, and executor handoffs are separate states.
• Rejected options or unresolved tradeoffs are recorded before handoff.

Recovery Notes

• If acceptance criteria or verification are missing, route back to clarification before handoff.
• If assumptions materially affect the plan, keep them visible and avoid treating the plan as accepted.

Use When

Use when Hermes should help an operator or coding executor understand an unfamiliar repository before planning implementation.

Strong routing signals: `codebase-onboarding`, `codebase onboarding`, `repo onboarding`, `repository onboarding`, `codebase tour`, `code tour`, `new repo orientation`, `understand this repo`, `how this repo works`, `first task runway`, `개발자 온보딩`, `레포 온보딩`, `코드베이스 온보딩`, `처음 보는 레포`, `레포 구조 설명`

Catalog Metadata

Category: planning Phase: codebase-onboarding Quality tier: onboarding-gated Reasoning demand: standard

Quality bar:

• Name the audience, depth, repo root, read-only boundary, and stop condition.
• Separate observed files and commands from inferred architecture and unknowns.
• Produce a practical reading path and first-task runway rather than a flat file tour.
• Route follow-up implementation to plan, ultrawork, verification-gate, or workspace-audit as needed.

Required inputs:

• repo root or supplied source context
• target audience: operator, new contributor, maintainer, or executor
• desired depth: quick map, architecture tour, first issue, or handoff pack
• known constraints such as no network, no secrets, or read-only mode

Expected outputs:

• codebase_onboarding_plan/v1
• repo_map/v1
• reading_path/v1
• domain_glossary/v1
• risk_and_unknowns_map/v1
• first_task_runway/v1
• not-evidence boundary

Artifact expectations:

• repo_map/v1 with observed directories, entrypoints, generated surfaces, tests, docs, scripts, and runtime artifacts
• reading_path/v1 ordered from product direction to architecture, core modules, tests, and operational docs
• domain_glossary/v1 with repo-specific terms, owners, artifacts, and evidence references
• first_task_runway/v1 with low-risk starter tasks, verification commands, and handoff readiness

Safety rules:

• Do not invent architecture, ownership, maturity, or runtime behavior without observed repo evidence.
• Do not mutate files, run setup, install dependencies, or dispatch an executor from onboarding alone.
• Keep onboarding findings, inferred risks, first-task suggestions, and implementation handoffs separate.
• Never expose secrets from config or environment files; record only redacted paths and risk categories.

Runtime Evidence

Use the current host's own tools and subagent/task mechanism when available; otherwise run the same lanes sequentially or name the unavailable capability. A prepared plan, handoff, checklist, or skill installation is not execution, review, CI, merge-readiness, or merge evidence. Record actual tool results, or not_observed / not_available, in the record; never invent dispatch or host accounting. Treat supplied context as advisory, not proof of hidden memory reads or writes. State scope, constraints, verification, and the stop condition before work. Reply in the user's own words and the host's own voice: OMH's record terms (surface, lane, wrapper, handoff, evidence boundary, not_observed) stay in records and tool calls, never in the sentence the user reads unless they ask about one; and when a stop condition or a decision the user owns ends the turn, offer the next action as a question rather than declaring what will not be done. Supporting paths are relative to this skill directory; sibling skill paths are relative to its parent. Resolve them from the host-provided skill base directory ({baseDir} on hosts that provide it), never a hardcoded install location. A named workflow not installed here is unavailable, not permission to emulate its host-specific capabilities. Verify through the real surface before done.