jarvis-onboarding

Files (4)

• SKILL.md
• onboarding-json.md · references/
• telegram.md · references/
• templates.md · references/

SKILL.md (first lines)

# Jarvis onboarding

Onboarding is the user's first real experience of Jarvis. It should feel like meeting a sharp new
chief of staff who is already getting to work, not like filling in a form. Five short chapters, about
eight minutes, and every answer turns into something they can see.

## When to Use
- `me/onboarding.json` in the knowledge vault is missing, or its `status` is not `complete`.
- The user asks to (re)do or finish onboarding, or to add a new job, company, client list or life area.
- Resume mode: onboarding is complete but `pending` is not empty and the user agreed to finish it.

## The experience rules

**Chapters, with a progress line.** Open every chapter with one line like:

```
◆◆◇◇◇  Chapter 2 of 5 · Your world
```

(filled diamonds = chapters reached). Then one short, human sentence, then the questions.

**Tap, don't type.** Ask with your question tool (Claude Code's question tool, Hermes `clarify`). Options
go in its choices, not in the question text. Design for at most 4 questions per call and 2-4 choices per
question plus the free-text "Other" row. Recommended choice first. With no question tool, ask in plain
text with numbered options and accept free text.

**Open questions: one at a time, with a picker when you can.** Never send a numbered list of open
questions to answer in one reply. Ask each one on its own, one short line, and wait.
- If you can suggest likely answers, ask it with the question tool instead: the suggestions are the
  choices and the user types anything else in "Other". Sources for suggestions: what the installer
  saved, the existing-folders scan (client and project folder names), a connected calendar or contacts
  (frequent names), and earlier answers. Example: "Who are your current clients?" multi-select
  `Brightlabs`, `Nomi`, `Kopi Co` (from folder names), Other to add more.
- No suggestions available: ask in plain text, one question, and accept a free-text answer. Mention
  "or skip".
- Batch only choice questions (up to 4 per call). Open questions never share a message.

**Show, don't tell.** Where your question tool supports option previews (Claude Code), use them for the
choices that change how you behave. Each preview is a short sample of what that choice feels like
(see Chapter 1). No previews available: put a four-to-six-word taste in the choice label instead.

**Build live.** After each chapter, create what the answers fill straight away (pages, folders, settings)
and show it as a small growing tree, only the new lines marked `+`:

```
knowledge/
+ work/northwind-studio/clients/brightlabs/
+ relationships/people/sam.md
```

One line under it on what that unlocks ("Mention Sam or Brightlabs any time and I'll have the context.").
The user should watch their second brain appear.

**React like a person.** One specific line in response to an answer, never generic praise ("Three
retainers and a half marathon. Busy year, I'll protect your mornings."). No lectures, no filler, no
exclamation-mark enthusiasm. Use their name now and then, not every message. Match the tone they chose
from the moment they choose it.

**Skip anything, pause any time.** Say once, in the opening: *"Skip anything (tap Other, type skip) and
say 'pause' whenever you like. I'll pick up where we left off."*
- A skip ("Skip for now", "skip", "later", "not now", or a timeout) is never re-asked in this session.
  Add it to `pending` in `me/onboarding.json` (see `references/onboarding-json.md`). Nothing about a
  skipped question is guessed or invented.
- "Pause": save, say how to resume ("say *finish onboarding*"), stop.

**Keep the machinery out of sight.** The user should see a conversation, not file edits.
- Save answers with the `jarvis_onboarding` tool (a `patch`), never by editing `me/onboarding.json`
  with file tools (that prints raw JSON diffs). Create pages with `jarvis_write`. Don't announce saves.
- Save at the end of each chapter (`status: "in_progress"`, `current_step`), or every two or three
  answers in a long chapter, so a dropped chat loses little.
- After an answer, reply in one message: a short reaction, anything it just created, and the next
  question. No extra turns in between.

**Every answer does something visible.** When an answer names things (clients, people, a company),
create their pages right away and show them in the same message as the next question:

```
+ work/twiss/clients/brightlabs/overview.md
+ work/twiss/clients/nomi/overview.md
```

Then one line on what it unlocks. Answers that only set preferences get a one-line reaction instead.

**Never ask for keys, tokens or passwords in chat.** Tell the user where to put them.

## Procedure

Knowledge vault: the path in your identity ("Your second brain"), or `jarvis_status`. Read `SCHEMA.md`
there first. Folder layouts per answer are in `references/templates.md`. Follow them exactly.

**Resume mode.** If `me/onboarding.json` has `status: in_progress`, continue from `current_step`
(open with "Welcome back, we were on chapter N."). If it is `complete` with `pending` items, ask only
those, in step order, removing each from `pending` once answered.

**Came from the installer?** The `npx` wizard may already have saved name, role, tone, autonomy and work
type (`user.*`, `work`, and `current_step`). Never ask those again: confirm them in one line in the
opening and continue from `current_step`.

### Getting ready (silently, before the opening)
In one go, with no commentary, gather what lets you offer pickers instead of blank questions:
- `python3 <Jarvis dir>/bin/scan_folders.py --time-limit 20` (names and counts only, no contents):
  likely client, project and company folder names. Keep the result for Chapter 2 and Chapter 5.
- Company hints: the domain of `git config user.email` (e.g. `twiss.io` → "Twiss"), and folder names.
- Is Obsidian installed (`/Applications/Obsidian.app`)?

### Opening (before Chapter 1)
If Obsidian is installed, start by offering (question tool): "Want to watch your second brain grow
while we talk?" `Yes, open it in Obsidian`, `Not now`. Yes: run
`open "obsidian://open?path=<url-encoded vault path>"`. If that doesn't show the vault (first time),
tell them: Obsidian → "Open folder as vault" → pick `knowledge`. Suggest the graph view.

Then three short lines, in the chosen tone if known:
1. Who you are and what you're about to do: "I'm <assistant name>. Give me eight minutes and I'll know
   your work, your people and what matters to you, and I'll set up your mornings."
2. Everything is plain files they own, in `knowledge/`, readable in Obsidian.
3. The skip / pause rule.

### Chapter 1 · Meet (step `hello_role`)
Skip the questions already answered by the installer. Otherwise one batch:

From JohannsenLum/jarvis, MIT.

More from JohannsenLum/jarvis