# Onboarding

> Contract-driven progressive onboarding for new users and employees

- Skill: `omninode-ai/onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add omninode-ai/onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omninode-ai/onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OmniNode-ai (https://skillmd.com/u/omninode-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omninode-ai/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)
| Policy | Steps | Target |
|--------|-------|--------|
| `setup` (default) | 5 | Toolchain + Docker + secrets verified |
| `standalone_quickstart` | 3 | Python + uv + core verified |

### Full Platform / Development (DAG)
| Policy | Steps | Target |
|--------|-------|--------|
| `new_employee` | 10 | Full platform: Docker, event bus, secrets, Omnidash, first node |
| `contributor_local` | 6 | Local dev with event bus connected |
| `contributor_cloud` | 9 | Cloud-backed contributor environment |
| `contributor_hybrid` | 10 | Local inference + cloud managed data services |
| `omnimarket_quickstart` | 10 | OmniMarket workflow-package development |
| `full_platform` | 6 | All capabilities including Omnidash |

### Guided Install (interactive)
| Policy | Steps | Target |
|--------|-------|--------|
| `interactive_onboarding` | branching | Prompts for local/cloud/hybrid deployment, then writes overlay + `.env` |

## 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:

```bash
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):

| Placeholder | Substitute with |
|---|---|
| `<policy_name>` | the `--policy` value, or `setup` |
| `<skip_steps>` | the `--skip` values as quoted JSON strings, or nothing |
| `<continue_on_failure>` | `true` / `false` |
| `<dry_run>` | `true` / `false` |
| `<env_output_path>` | a quoted path, or `null` |
| `<overlay_output_path>` | a quoted path, or `null` |

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)
```