OnboardingAI

OnboardingAI is a guided engineering onboarding agent. A new hire picks their team, manager, and OS; the app reads the matching Confluence onboarding guide, builds a short setup plan, and walks them through each step — with human approval before running terminal commands, and a Slack draft (never auto-sent) when access is required.

How it works

The flow is interactive and checkpointed. A Next.js app hosts the UI; shared logic lives in @onboarding/agent-core.

Discover → plan → approve → execute → validate → report

1. Start — hire selects name, eng manager, team, role, and OS.
2. Discover — detect tools already installed so the plan can skip them.
3. Plan — fetch the Confluence guide, parse steps, condense to ~10–15 readable items, synthesize install/download commands when the page has none, and normalize access items to real systems (GitHub, VPN, GitHub PAT, …).
4. Run — for each step:
   • access — pause, draft a Slack message to the manager, wait until access is confirmed.
   • install / command / config — ask for approval, run the shell command, validate, checkpoint.
5. Dashboard — managers see In Progress / Blocked on Access / Completed sessions.

Each step halts for user input (approve, skip, or access granted). Session state is persisted so refresh and the manager dashboard stay in sync.

How to run locally

Prerequisites

Dependency	Install	Notes
Node.js 20+	nodejs.org or nvm install 20	Required
Yarn or npm	comes with Node	Workspaces via root package.json
Confluence Cloud access	Atlassian API token	Space with onboarding pages
OpenAI API key (optional)	platform.openai.com	Help chatbot; falls back to Confluence snippets without it

1. Configure your environment

cp apps/web/.env.local.example apps/web/.env.local

Fill in the required values in apps/web/.env.local (see Configuration).

2. Install dependencies

From the repo root (onboarding-platform/):

npm install
# or: yarn

3. Start the web app

npm run dev:web
# or: npm run dev -w @onboarding/web

Open http://localhost:3000/onboard.

Manager view: http://localhost:3000/dashboard.

4. Run tests

# Unit tests (agent-core + web)
npm test

# Playwright e2e (web app; starts against mocked APIs in CI-style runs)
npm run test:e2e -w @onboarding/web

Configuration

See apps/web/.env.local.example. Key variables:

Variable	Description
CONFLUENCE_BASE_URL	Confluence site URL (e.g. https://your-org.atlassian.net)
CONFLUENCE_EMAIL	Atlassian account email (Cloud Basic auth)
CONFLUENCE_TOKEN	Atlassian API token
CONFLUENCE_SPACE_KEY	Space that holds onboarding guides
OPENAI_API_KEY	Optional — enables the Confluence-grounded help chatbot
OPENAI_HELP_MODEL	Optional — model override for help chat
SLACK_CLIENT_ID / SLACK_CLIENT_SECRET / SLACK_REDIRECT_URI	Optional — Slack OAuth for draft-to-DM helpers
SLACK_MANAGER_USER_ID / SLACK_MANAGER_EMAIL	Optional — default manager lookup for Slack drafts
ONBOARDING_MANAGER	Optional — fallback manager name in drafts
SLACK_WEBHOOK_URL	Optional — webhook posting (not used for the hire’s access draft)
CRON_SECRET	Shared secret for /api/cron/freshness-report

Team + eng manager dropdowns come from packages/agent-core/src/data/org-chart.json (not live Confluence Teams scrape). Refresh that file when the org chart changes.

Architecture

apps/web/                      Next.js App Router UI + API routes
  src/app/onboard/             Hire setup chat + terminal stream
  src/app/dashboard/           Manager sessions + doc freshness
  src/app/api/onboard/         start, stream, access, options, report
  src/app/api/dashboard/       sessions, freshness
  src/app/api/help-chat/       Confluence-grounded help assistant
  src/app/api/cron/            Weekly freshness report
  reports/                     Persisted sessions (gitignored)

packages/agent-core/           Shared onboarding agent logic
  src/agents/
    discovery.ts               Detect installed tools
    planner.ts                 Order + condense Confluence steps
    install-commands.ts        Synthesize brew/curl/open installs
    approval.ts                Prompt + parse yes / skip / why
    executor.ts                Run approved shell commands
    validator.ts               Post-step checks + retry
    reporter.ts                Hire / manager reports
  src/integrations/
    confluence.ts              Guides, page parse, managers
    org-chart.ts               Teams + eng managers
    slack.ts                   Access request drafts (no auto-send)
    freshness.ts               Doc drift + broken-link checks
    keychain.ts                Credential storage helpers
  src/utils/
    access-labels.ts           Normalize access → GitHub, VPN, PAT, …
  src/state/                   In-memory sessions + checkpoints
  src/data/org-chart.json      Source of truth for team/manager UI

Trust boundaries

• Shell commands run only after explicit approval.
• Access requests are Slack drafts the hire pastes — the bot does not auto-send.
• Homebrew / sudo installs need a real Terminal (no TTY password prompt in the agent runner).

About

OnboardingAI turns messy Confluence onboarding docs into an interactive, approval-gated setup path for new engineers, with manager visibility when someone is blocked on access.