Scenario 01: Onboard to an unfamiliar codebase

Use this workflow when you need a reliable first map of a repository before answering questions or changing code. It identifies the detected workspace, languages, available graph and documentation evidence, important unknowns, and the next files worth reading. Use focused follow-up workflows for the remaining repository areas.

Quick start

In an installed OpenCode client, open the repository and run:

/onboard

The command is workspace-neutral and discovers the language, build system, directory layout, operating system, and shell from the current workspace.

What the workflow checks

The current command performs a bounded sequence:

codegraph_project_context_status reports whether project context is usable.
codegraph_project_context_sync_status reports pending or stale synchronization.
codegraph_context_session_open opens or reuses an explicit context session.
codegraph://project/context supplies detected project metadata and languages.
codegraph_context_retrieval_evidence_fetch and codegraph_context_retrieval_fused_search retrieve architecture and documentation evidence.
codegraph_context_retrieval_file_read reads only the source slices needed to confirm a claim.

codegraph_digital_employee_skill_search may add one bounded onboarding hint. The repository and current runtime remain the source evidence.

Interpret readiness before trusting the answer

Interpret readiness before trusting the answer
Mode	What it means	Safe next action
`ready`	Project context and the required evidence surfaces are available.	Continue with targeted questions and source reads.
`sync-pending`	Context projection has not caught up with the workspace.	Record the pending state and wait for or run the documented synchronization action.
`graph-only`	Structural graph evidence is available, but semantic or memory context is unavailable.	Use bounded graph facts and label missing semantic context explicitly.
stale or locked	The server reports that the context requires refresh or recovery.	Return the server-provided blocker and next action; use the named recovery surface.

A useful onboarding result

The result should let another engineer answer these questions:

What directory and project boundary did CodeGraph detect?
Which languages and major subsystems are supported by evidence?
Which startup paths or entry points were actually inspected?
What is the readiness mode, and which limitations follow from it?
Which claims are source-backed, and which remain unknown?
What is the smallest next investigation that would reduce uncertainty?

Treat generated summaries as navigation aids. Before using a statement in a design, review, or change, follow its evidence reference to current source.

When to stop

Narrow the request when the repository contains several products, the target subsystem is ambiguous, or the response has only graph-wide matches. A good follow-up names one user journey, component, function, or change area. Security, architecture, and release owners use their accountable workflows and evidence for those decisions.

Maintained source contracts

OpenCode workflow: .opencode/commands/onboard.md
Role-bound scenario routing: src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py
Employee/scenario policy: src/digital_employees/runtime/scenarios/employee_scenario_invocation.py

See also Security Audit for a bounded audit after onboarding, and Feature Development after the implementation scope is accepted.