Onboarding

onboarding

Announce at start: "I'm using the onboarding skill."

Contract-driven progressive onboarding for new users and employees.

Two execution paths, chosen from the policy's policy_type:

• DAG policies (8 of the 9 built-ins) resolve to a minimal set of steps via the onboarding graph, execute each step's verification, and render a markdown progress report.
• The interactive policy (interactive_onboarding) drives a branching prompt flow through a transition table and writes an overlay YAML (plus a legacy .env) describing the chosen deployment.

Built-in Policies

All 9 policies below ship in omnibase_infra/onboarding/policies/. Step counts are the steps the resolver selects out of the 17-step canonical graph.

Environment Setup (DAG)

Full Platform / Development (DAG)

Guided Install (interactive)

Usage

/onex:onboarding
/onex:onboarding --policy standalone_quickstart
/onex:onboarding --policy new_employee --dry-run
/onex:onboarding --policy contributor_local --skip start_docker_infra
/onex:onboarding --policy full_platform --continue-on-failure
/onex:onboarding --policy interactive_onboarding --dry-run
/onex:onboarding --policy interactive_onboarding --env-output-path ./onex.env

Execution

Parse args into a JSON payload, then dispatch node_onboarding on the local runtime. Do not import or call the handler yourself — the node owns the logic.

• omnimarket and omnibase_infra ship in the plugin venv ($CLAUDE_PLUGIN_DATA/.venv, built by ensure-plugin-venv.sh), which also provides the onex entrypoint. No source checkout and no cd are required — run from wherever the session already is. If that venv is missing, rebuild it with bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/ensure-plugin-venv.sh" (the same script the SessionStart hook runs).
• env -u PYTHONPATH is required: the ONEX hooks export PYTHONPATH into the session, and a leaked value shadows the venv's packages.
• onex node runs the node on the local in-memory bus, so onboarding works before any broker exists — which is the point.

Write the payload to a file, then dispatch:

cat > "${TMPDIR:-/tmp}/onboarding-input.json" <<'JSON'
{
  "policy_name": "<policy_name>",
  "skip_steps": [<skip_steps>],
  "continue_on_failure": <continue_on_failure>,
  "dry_run": <dry_run>,
  "env_output_path": <env_output_path>,
  "overlay_output_path": <overlay_output_path>
}
JSON

env -u PYTHONPATH "${CLAUDE_PLUGIN_DATA:?CLAUDE_PLUGIN_DATA is injected by Claude Code}/.venv/bin/onex" \
  node node_onboarding --input "${TMPDIR:-/tmp}/onboarding-input.json"

Substitutions (all JSON, so true/false/null, not Python literals):

The dispatch writes .onex_state/workflow_result.json under the state root and exits 0 on COMPLETED, 1 on FAILED/TIMEOUT, 2 on PARTIAL. Read terminal_payload from that file and render rendered_output directly to the user.

For dry-run mode on a DAG policy, also display resolved_steps so the user can see what would execute. For the interactive policy, terminal_payload carries policy_type, visited_steps, terminal_step, and — outside dry-run — overlay_output_path_written / env_output_path_written.

If dispatch refuses with an omnimarket-drift error, the co-installed omnimarket build is behind the canonical clone; repair the install rather than setting ONEX_ALLOW_OMNIMARKET_DRIFT (results produced under that override are not evidence).

Architecture

SKILL.md              -> thin UX wrapper (this file)
node_onboarding       -> omnimarket/nodes/node_onboarding/ (policy resolution + path selection)
handle_onboarding     -> omnibase_infra/.../handlers/handler_onboarding.py (async orchestration)
canonical.yaml        -> omnibase_infra/.../onboarding/graphs/canonical.yaml (17-step DAG)
policies/*.yaml       -> omnibase_infra/.../onboarding/policies/ (9 builtin policies)