Codebase Onboarding

This is a Hermes-native codebase-onboarding workflow skill.

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.

Workflow Lane

• Current lane: Intent -> plan (oh-my-hermes, meta-router, deep-interview, context, plan, ralplan, adversarial-consensus, codebase-onboarding, +8 more) - clarify, plan, ship, or loop goals.
• If intent belongs to another lane, hand back to oh-my-hermes or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: omh-routing/references/skill-common-rail.md.

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 Hermes role: planner 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.

Handoff policy:

Keep codebase orientation in Hermes as prepared local context. File reads, generated maps, and first-task recommendations need observed repo evidence; code edits and executor handoffs happen only after onboarding identifies a concrete task.

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.

Structural Code Search

When the target is a syntactic shape rather than a string, load omh-routing/references/structural-code-search.md before searching. If ast-grep is not on PATH, use grep/ripgrep exactly as today. Cap exploration to a few bounded, targeted queries before reading a full file, escalate to a wider query only when a bounded pass finds nothing or stays ambiguous, and stop once the target is found.

Runtime Evidence

Preferred harness for this skill: codebase-onboarding.

omh runtime record --skill codebase-onboarding --harness codebase-onboarding --status started

Record observed delegation results; otherwise return not_available or not_observed. Prepared OMH routing is not execution, review, CI, merge-readiness, or merge evidence.

• Treat wrapper memory/context summaries as advisory local context, not proof of opaque Hermes memory reads or changes. Preserve workflow intent and stop conditions; verify before claiming completion. Reply in the user's own words and the host's own voice: its SOUL.md persona owns reply language, tone, speech level, and sentence endings, progress updates included (where it sets no language, use the one the user wrote in), and OMH shapes structure and content only; 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.

Use Hermes-native subagent/delegation features when available: native subagents -> Hermes delegation when available, otherwise sequential lanes.

Shared product, compatibility, topology, memory, harness, and execution rules: omh-routing/references/skill-common-rail.md. Load it when applicable; otherwise name an unavailable capability.