> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairn.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# HR Onboarding

> A personal onboarding guide for every new hire — personalised, proactive, and checklist-aware.

## The problem

New employee onboarding is the same 40 questions every time. HR teams answer them manually, new hires wait hours, and nothing is personalised to the person's role, team, or start date.

**What Kairn enables:** A personal onboarding agent for every new hire — knows their role, team, and start context, answers instantly, tracks checklist progress, and nudges them daily.

***

## Setup

**1. Define the soul**

```ts theme={null}
await kairn.souls.create({
  name: 'onboarding',
  label: 'Onboarding Guide',
  soulMd: `
    You are an onboarding guide for new employees joining the company.

    Your job:
    - Answer questions about company policies, tools, and processes
    - Guide the new hire through their first-week checklist
    - Help them understand their role, team structure, and who to contact
    - Make them feel welcomed and supported

    Behaviour rules:
    - Use the employee's name (from memory) when greeting them
    - Reference their specific role and team when relevant
    - Track checklist progress in memory — update keys when tasks are completed
    - If you don't know something specific, direct them to their manager or HR contact
    - Keep a friendly, encouraging tone — starting a new job is stressful

    First-week checklist items (track completion in memory):
    - it_setup: laptop, accounts, email configured
    - team_intro: met their immediate team
    - tools_setup: Slack, Notion, GitHub/Jira access confirmed
    - first_1on1: first 1:1 with manager scheduled
    - culture_docs: read company handbook and values doc
    - payroll: banking details submitted to HR
  `,
  defaultModel: 'anthropic/claude-sonnet-4-6',
})
```

**2. Seed employee context on day one**

Trigger this when the employee record is created in your HR system.

```ts theme={null}
async function onboardEmployee(employeeId: string) {
  const employee = await hrSystem.getEmployee(employeeId)
  const team     = await hrSystem.getTeam(employee.teamId)
  const manager  = await hrSystem.getUser(employee.managerId)

  await kairn.memory.set(employeeId, 'default', {
    name:         employee.firstName,
    full_name:    employee.fullName,
    role:         employee.jobTitle,
    department:   employee.department,
    start_date:   employee.startDate,
    team_name:    team.name,
    team_size:    String(team.memberCount),
    manager_name: manager.name,
    manager_email: manager.email,
    hr_contact:   'hr@company.com',

    // Checklist — all pending at start
    it_setup:     'pending',
    team_intro:   'pending',
    tools_setup:  'pending',
    first_1on1:   'pending',
    culture_docs: 'pending',
    payroll:      'pending',
  })

  // Daily nudge — runs 9am Mon-Fri
  await kairn.mandates.create({
    userId: employeeId,
    soul: 'onboarding',
    label: 'Daily onboarding check-in',
    taskPrompt: `
      Check the employee's onboarding checklist progress in memory.
      Identify which items are still pending.
      Write a brief encouraging note to memory under "daily_nudge"
      reminding them of the next pending item to complete.
      If all items are done, write "onboarding_complete: true" to memory.
    `,
    trigger: {
      type: 'cron',
      cron: '0 9 * * 1-5',
    },
  })
}
```

**3. Surface checklist status in your HR portal**

```ts theme={null}
// GET /api/onboarding/status
export async function getOnboardingStatus(employeeId: string) {
  const memory = await kairn.memory.get(employeeId, 'default')

  const checklist = [
    { key: 'it_setup',     label: 'IT setup (laptop, accounts, email)' },
    { key: 'team_intro',   label: 'Meet your team' },
    { key: 'tools_setup',  label: 'Tools access (Slack, Notion, etc.)' },
    { key: 'first_1on1',   label: 'Schedule first 1:1 with manager' },
    { key: 'culture_docs', label: 'Read company handbook' },
    { key: 'payroll',      label: 'Submit payroll details' },
  ]

  return {
    employeeName:  memory.name,
    role:          memory.role,
    startDate:     memory.start_date,
    managerName:   memory.manager_name,
    checklist:     checklist.map(item => ({
      ...item,
      status: memory[item.key] ?? 'pending',
    })),
    completionPct: Math.round(
      checklist.filter(i => memory[i.key] === 'done').length / checklist.length * 100
    ),
    todaysNudge: memory.daily_nudge ?? null,
  }
}
```

**4. Add the onboarding chat**

```tsx theme={null}
export function OnboardingAssistant({ employeeId }: { employeeId: string }) {
  return (
    <div className="onboarding-assistant">
      <div className="assistant-header">
        <h3>Your Onboarding Guide</h3>
        <p>Ask me anything about your first week, the company, or your team.</p>
      </div>
      <AgentChat
        employeeId={employeeId}
        agentName="onboarding"
        sessionId={`onboarding_${employeeId}`}
        placeholder="What's on the agenda for today?"
      />
    </div>
  )
}
```

***

## Example conversation

```
New hire: Hi! I just got my laptop set up. What should I do next?

Agent:    Great news, Alex — IT setup done! I've marked that off
          your checklist (5 items to go).

          Next up: getting your tools access sorted.
          You'll need:
          - Slack (your manager Sarah can add you to the workspace)
          - Notion (IT can provision this — reply to your welcome email)
          - GitHub (your team lead handles this — ask in #eng-team)

          Once those are done, let me know and I'll mark it complete.
          You're making great progress for day 1!

New hire: Done! All tools are set up.

Agent:    Excellent — tools access complete ✓

          You're 3/6 through your first-week checklist.
          Next: schedule your first 1:1 with Sarah (sarah@company.com).
          She usually does these on Tuesdays or Thursdays — shoot her
          a calendar invite for whenever works for you this week.
```

The agent updated the checklist in memory automatically. The HR dashboard shows 3/6 complete in real time — no manual tracking.

***

## What this replaces

> [card] Manual HR Q\&A
>
> 50+ common first-week questions answered instantly, personalised to the employee's role and team.

> [card] Checklist spreadsheets
>
> Progress tracked in memory, surfaced in your portal, updated by the employee through conversation.

> [card] Manager follow-up calls
>
> Daily nudges via mandate ensure nothing falls through the cracks — without manager overhead.

> [card] Generic onboarding docs
>
> Responses are tailored to the employee's specific role, team, manager, and start context.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.