/onboarding

name: onboarding
description: Guide new users through macrodata setup. Creates identity, human profile, and workspace files. Use when get_context returns isFirstRun true, or user asks to set up their profile.

Onboarding Skill

Guide new users through initial macrodata setup.

When to Use

• `get_context` returns `isFirstRun: true`
• User explicitly asks to set up or reset their profile
• State files are empty or missing

Guidelines

Use `AskUserQuestion` for any choice with multiple options (location, permissions, etc.). This provides a better UX than asking in plain text.

Onboarding Flow

Phase 0: Prerequisites

Check that Bun is installed (required for the MCP server):

command -v bun

If not found, offer to install it:

**Ask:** "Macrodata needs Bun to run. Would you like me to install it?"

If yes, run:

curl -fsSL https://bun.sh/install | bash

After installation, verify it worked:

# Source the updated PATH
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
command -v bun && bun --version

If they decline, explain that macrodata won't work without Bun and ask if they'd like to install it manually later.

Phase 1: User Info

User info has been pre-detected and is available in the context above as "Detected User Info". This JSON contains:

• `username`, `fullName`, `timezone`
• `git.name`, `git.email`
• `github.login`, `github.name`, `github.blog`, `github.bio`
• `codeDirs` - array of existing code directories

Use this data throughout onboarding - no need to run detection scripts.

Phase 2: Location

Use `AskUserQuestion` to offer location options. Always include:

• `~/Documents/macrodata` - easy to find
• `~/.config/macrodata` - hidden, default

Only include a code directory option if `codeDirs` from the detection was non-empty.

If they choose a non-default location, write it to `~/.config/macrodata/config.json`:

{
  "root": "/path/to/chosen/location"
}

After writing the config, signal the daemon to reload:

kill -HUP $(cat ~/.config/macrodata/.daemon.pid) 2>/dev/null || true

Then create the directory structure:

• `<root>/`
• `<root>/state/`
• `<root>/journal/`
• `<root>/entities/`
• `<root>/entities/people/`
• `<root>/entities/projects/`
• `<root>/topics/`

Phase 3: Human Profile

Use the info from the detection script to pre-populate.

**Ask the basics:**

• What should I call you? (confirm or correct auto-detected name)
• What's your GitHub username? (if not detected from gh cli)
• Do you have a website or blog?
• Any social profiles you'd like me to know about?

**Research their online presence:** If they provide a website, socials, or GitHub, fetch and analyze them for:

• Bio and self-description
• What they write about (interests, expertise)
• Tone and voice in their writing
• Projects and work they highlight

This gives context beyond what they explicitly state – understanding who they are publicly helps the agent communicate appropriately.

**Communication style:** If they consent, analyze their Claude Code session history (`~/.claude/projects/`):

# Extract human messages from session history
find ~/.claude/projects -name "*.jsonl" -exec cat {} \; 2>/dev/null | \
  jq -r 'select(.type == "human") | .message.content' 2>/dev/null | \
  head -200

Look for patterns:

• Message length (short/direct vs detailed)
• Tone (casual, formal, technical)
• How they give feedback (direct corrections, suggestions, questions)
• Language preferences (spelling variants, idioms)

**Current work context:** Analyze recent session history to understand what they're working on:

# Get recent project directories from Claude Code history
ls -lt ~/.claude/projects/ | head -10

# Sample recent conversations for context
find ~/.claude/projects -name "*.jsonl" -mtime -7 -exec cat {} \; 2>/dev/null | \
  jq -r 'select(.type == "human") | .message.content' 2>/dev/null | \
  head -100

**Working patterns:**

• Ask about current focus areas (or confirm what you detected)
• Any preferences for how the agent should work?

Write findings to `state/human.md`:

# Human Profile

## Basics
- **Name:** [name]
- **GitHub:** [username]
- **Website:** [url if provided]
- **Socials:** [any provided]
- **Timezone:** [detected]

## Communication Style
- [observed patterns from analysis]
- [stated preferences]

## Working Patterns
- [current focus areas]
- [preferences]

## Current Projects
- [detected from recent sessions]

## Pending Items
- [empty initially]

Phase 4: Agent Identity

Help define who the agent should be:

**Name and persona:**

• What should the agent be called?
• What's its role? (assistant, partner, specialist)
• Any personality traits?

**Values and patterns:**

• What behaviors should it prioritize?
• How proactive should it be?

Write to `state/identity.md`:

# [Agent Name] Identity

## Persona
[Description of who the agent is, its role, personality]

## Values
- [core value 1]
- [core value 2]

## Patterns
- [behavioral pattern 1]
- [behavioral pattern 2]

Phase 5: Initial Workspace

Set up working context:

1. Ask what they're currently working on 2. Create initial project files in `entities/projects/` 3. Write `state/today.md` with current context 4. Write `state/workspace.md` with active projects

# Today

## Now
[Current context from conversation]

## Context
[Background information]

# Workspace

## Active Projects
- [project 1] - [brief description]

## Open Threads
- [things in progress]

Phase 6: Permissions

Ask if they'd like to pre-grant permissions for macrodata paths. This avoids permission prompts every session.

**Ask:** "Would you like me to update your Claude Code settings to pre-grant permissions for macrodata? This means you won't be prompted each time macrodata reads or writes to its memory folder."

If yes, update `~/.claude/settings.json` to add:

{
  "permis