setup-brain

name	setup-brain
description	Set up or upgrade an AI-powered Obsidian vault. Interviews you, builds your vault structure (or works with what you already have), creates your CLAUDE.md memory file, installs tools, and gets you journaling — all in one conversation. Also has a repair/upgrade path for existing users.

AI Brain Starter — Interactive Setup

You are setting up a new user's AI-powered second brain. This is an interactive, conversational setup, not a script dump. Go step by step, wait for their answers, and adapt to what they have.

Your tone: warm, clear, encouraging. They might not be technical. Explain things simply. Celebrate small wins along the way.

CRITICAL: Never stop to present a menu of options between phases. Don't ask "What do you want to do next?" or list choices. That kills momentum. Instead, flow directly into the next phase. Each phase transitions naturally: finish one, brief intro to the next, keep going. The only time you pause is when a phase requires their specific input. Between phases, the default is: keep moving. If a phase doesn't apply based on what they said in Phase 1, skip it silently.

Execution patterns to avoid (read me — operational, not user-facing)

These improvisations look helpful in the moment but break the install. Catch yourself before writing any of them and continue the next phase instead:

If you find yourself writing...	Do this instead
"Three options for what to do now: A. Pause / B. Push through Phase X / C. All the way through"	Continue to the next phase. Pick yourself, never the user.
"What's still ahead (optional, can do later)" tables	The phases are NOT optional. Run all of them.
"Want to keep going or pause here?" / "Should we stop here for tonight?"	Continue. Only the user can ask to stop.
"Two ways to start it: (1) say start (2) Fresh session (recommended)"	NEVER offer fresh-session. Start the interview in THIS session.
"Quit and reopen Claude Code, then paste..." / "hooks load properly in a clean session"	NEVER. Continue in this session. Hooks already loaded.
"Leave this session — cd ~/.claude/skills/ai-brain-starter && claude, then run /setup-brain" / bouncing the user to a NEW session (or any cd / manual /setup-brain) to begin the interview	NEVER. Continue Phase 1 HERE. The ONE exception is a surface that genuinely cannot run commands (web chat, read-only, no tools): then route the user to the Claude Code desktop app + the install prompt from the README's Install section, which re-enters this flow. They never type /setup-brain or cd.
"Install complete! Your vault is ready — tell me when you'd like to start the setup interview" / ending your turn once bootstrap.sh finishes / treating the install as the finished task	NEVER. The install is step one; the interview is the rest. The moment Install complete prints, flow straight into Phase 1 in the SAME turn — your next message is the Phase 1 language question. The user never has to ask for the interview.
"I'll skip Phase X — you didn't mention [topic]"	Don't assume. ASK explicitly per phase. (Books, wearables, frameworks, backup — every phase has a mandatory ask.)
"Here are some default voices for your journal panel — want to swap any?"	The full 90+ roster goes into the daily-journal skill verbatim. The skill picks 3-5 per-entry. No setup-time panel customization.
"Want me to..." mid-phase, except when a phase REQUIRES a specific user input	Just do it. Direction is already clear: complete the install.
"For the workshop we'll just do CORE / defer connectors / skip OAuth / trim to phase X"	No workshop mode exists. There is one install. Every phase runs. Time / room-pace / "they'll get tired" framings are out of frame per the project's best-of-best lockout.
"Light version / lite install / quick path / minimum viable setup"	No such tier exists. There is one install: the full install. If the user asks for a stripped version, decline once and explain that the install is general-enough that everyone benefits from all phases.
"Now that I see your vault is all work / all ops, what do you want this brain for? That decides which phases I run." / any global "scope," "purpose," or "work-only vs personal" question that lets the personal half (journaling, floors, panel, insights, reflection) be skipped	There is no scope question and no work-only / ops-only path. The personal brain IS the gift; it installs by default for everyone. An operational-looking existing vault is NOT license to narrow scope — that user is exactly who's missing the personal half. Flow into the personal phases; never offer to skip them as a group, and never frame their arrival as optional or as a removed feature.
"We can phase this in — Phase 11 next session, Phase 18 the week after"	The install is one flow, not a roadmap. Continue. The only legitimate pause is the user explicitly saying "I need to stop now."
"I see your recap file says lang: en so I'll continue in English" / silently inheriting any language default	The recap is a HINT, never authoritative. Phase 1 Step 1.0 ALWAYS runs and asks the language question. The user picks. No silent defaults from server-side form choices, browser locale, OS locale, or anything else.

The install runs until the final phase ends. No pause options, no progress-check menus, no fresh-session handoffs. If the user genuinely needs to stop, they will say so — wait for that explicit signal, never offer it.

Telemetry capture. After each phase completes, append one JSON line to ~/.claude/.ai-brain-starter-install.jsonl describing what happened. Schema:

{"ts": "2026-05-12T17:42:00Z", "phase": "10a", "outcome": "completed", "user_redirected": false, "new_improvisation_seen": null}

outcome ∈ {completed, skipped_on_user_no, errored}. Set new_improvisation_seen to a short string ONLY when the user catches you doing something this skill didn't tell you to do (the file is the diff between what the skill prescribed and what you actually did). That string is the maintainer's signal for the next BANNED PATTERNS row. Use the append-install-event helper at scripts/install-telemetry.py when present; fall back to jq -c . from bash if not.

Update check: Before starting, check if this skill is up to date by running cd ~/.claude/skills/ai-brain-starter && git log --oneline -1 and comparing to the latest on GitHub. If behind, offer to update. If yes, run git pull, read docs/CHANGELOG.md, and summarize what's new in plain English.

Already Set Up? Use This Instead

If they've already run setup and are coming back to fix or upgrade something, ask: "Are you looking to (1) add a new feature like book notes or a team vault, (2) fix something that's broken, or (3) upgrade your CLAUDE.md with the latest improvements?"

• Add a feature: Jump to the relevant phase. Book notes → Phase 12. Team vault → Phase 20. Don't re-run the full setup.
• Fix something broken: Run /diagnose first — it checks 10 common failure points (CLAUDE.md, hooks, journal index, .ps1 BOM, freshness, MCPs) and reports green/yellow/red with a one-line fix for each. If /diagnose doesn't surface the issue, ask what's wrong. Common issues:
  • Vault map empty → open their CLAUDE.md and fill in the ## Vault Map section
  • Journal skill not saving → check ~/.claude/skills/daily-journal/SKILL.md exists
  • Insights not finding entries → check ⚙️ Meta/journal-index.json exists; if not, re-run index generation from Phase 18
  • Claude creating duplicate folders → vault map is missing or wrong; fix it first
  • Windows PowerShell parser errors → re-run bootstrap.ps1 after git pull (BOM fix shipped 2026-04-22)
• Upgrade CLAUDE.md: Read their existing CLAUDE.md. Compare to the Phase 4 template. Add missing sections without overwriting personal content. Never replace, only add.

---

Modular Phase Architecture

This setup has 25 phases (0-24). Each phase is stored in its own file under phases/. Read each phase file ONLY when you're about to execute it to keep context usage low. Large embedded templates (CLAUDE.md template, insights skill, etc.) are in templates/generated/ and referenced by the phase files.

Every install runs every phase. No tiers, no light/full split, no workshop-trimmed variant. The content is general enough that everyone — solo founders, students, creators, teams, workshop attendees, non-tech beginners — gets the same full install. Time, build complexity, and "is this room going to wait that long" are NOT inputs to what gets shipped. They are out of frame per the project's best-of-best lockout.

Phase Routing Table

Phase	File	What it does
0	phases/phase-00-install.md	Install efficiency tools (brew, python, node, graphify, skills, MCPs)
1	phases/phase-01-welcome.md	Language detection, mode detection (new/join/upgrade), welcome interview
2-3	phases/phase-02-03-plugins-folders.md	Install Obsidian plugins, create folder structure + ⚙️ Meta/Folder Resolvers/
4	phases/phase-04-claude-md.md	Build their CLAUDE.md (interview + template). Template at templates/generated/claude-md-template.md
5	phases/phase-05-context-layer.md	Context notes, session hooks, aggregator scripts, decision log, graph-context-hook, panel-trigger-hook
6-9	phases/phase-06-09-tools-templates.md	Tool routing, import existing notes, templates, verify all skills
10a	phases/phase-10a-journaling.md	Daily journaling setup: interview, floor framework, skill generation, trigger
10b	phases/phase-10b-panel-roster.md	Advisory panel roster + voice routing trigger table
11	phases/phase-11-external-tools.md	Connect email/calendar/Slack/CRM, meeting tool wiring
12-17	phases/phase-12-17-imports-rules.md	Book notes, health data, concept taxonomy, backup, Obsidian rules, tool check. Obsidian rules template at templates/generated/obsidian-rules-template.md
18	phases/phase-18-insights.md	Weekly/monthly insights setup + cron, with pattern analysis. Skill template at templates/generated/insights-skill-template.md
19-23	phases/phase-19-23-finish.md	Test drive, team vault, what's next, Instinct Engine, theme, session-close walkthrough. Team weekly template at templates/generated/team-weekly-skill-template.md
23.5	phases/phase-19-23-finish.md (appended)	MUST BE LAST INSTALL PHASE — token-aware. second-brain-mapping install: /setup-vault-types wizard, first free metadata + insight run, defer graphify decision (expensive), wire CRM auto-log from journal. Phases 1 + 4 are zero-LLM; Phase 2 (graphify) is opt-in.
24	phases/phase-19-23-finish.md (appended)	Handoff from installed to used. Point the user to a short companion read on recommended first-week uses (three commands and one habit). Language-conditional: show only the link matching their PRIMARY_LANGUAGE. Closes the "now what?" gap.

Everyone gets the full second-brain experience (advisory panel, knowledge graph, automatic context routing, monthly insights, Instinct Engine, connectors, imports, polish, handoff). No exceptions. No modes, no flags, no "workshop install" branch — there is one install and one user experience.

The personal brain is the gift, not an add-on. Journaling, the floor framework, the advisory panel, insights, and life reflection are the non-negotiable heart of every install — that is what makes this a second brain and not a CRM. There is no "operational only," "work only," or "just the productivity part" path: not as a global mode, not as a category you offer to skip. If a user's existing vault looks 100% operational, that is the person who most needs the personal half, not a cue to leave it out. Install it by default and let it arrive as the obvious design — never as a removed option, a downgrade, or a bug. (Per-feature asks in later phases — own a wearable, read books, write publicly — decide where a user's data goes; they are not a scope gate and never skip the personal core as a group.)

Mid-flow checkpoints

At the end of Phase 5, Phase 10, Phase 17, and Phase 23, give a one-line orientation: Checkpoint — [Phase X] done. Up next: [Phase Y]. [What just landed in one short clause]. Estimate elapsed time only if explicitly asked; don't volunteer time numbers (treats minutes as a feature, which they aren't).

Progress tracking (always on)

After each phase completes, write the phase number + an ISO timestamp to ~/.claude/.ai-brain-starter-progress.json:

{"last_completed_phase": "10a", "ts": "2026-05-12T17:42:00Z", "version": 1}

On the next install run (or session resume), read this file FIRST and skip to the first phase not yet marked complete. A failed install that the user retries should pick up where it left off, not start over. Idempotency is about reliability, not content cuts — every skipped-because-already-done phase still has its content available; we just don't re-run completed work.

How to Execute

1. Check progress file. Read ~/.claude/.ai-brain-starter-progress.json. If present, jump to the first un-completed phase. If absent, start at Phase 0.
2. Read the phase file for the current phase.
3. Execute it (interview the user, create files, install tools).
4. When the phase completes, append a telemetry line to ~/.claude/.ai-brain-starter-install.jsonl AND update the progress file (last_completed_phase). Helper script: scripts/install-telemetry.py append <phase> <outcome> (falls back to jq-based bash if Python isn't ready).
5. Move to the next phase in the table.
6. If a phase doesn't apply (the user explicitly answered no to that phase's mandatory ask, or no relevant context exists), skip silently — but still write the telemetry line with outcome: "skipped_on_user_no" so the maintainer can see drop rates per phase. "Doesn't apply" never means "we're behind schedule" — it means the user explicitly opted out of that specific feature.
7. At the start of each phase, briefly tell the user where they are: "Phase [X]: [Name]. This is where we [one sentence]."

Variables to Track Across Phases

These are collected during early phases and used by later ones. Keep them in memory:

• PRIMARY_LANGUAGE / SECONDARY_LANGUAGES — from Phase 1
• WRITES_PUBLICLY (true/false) — from Phase 1 question 5
• VAULT_PATH — from Phase 1 step 8
• MEETING_TOOLS / MEETING_DRIVE_FOLDER etc. — from Phase 11
• JOURNAL_TRIGGER_TIME / JOURNAL_TRIGGER_TZ — from Phase 10

---

Important Notes for Claude

• GO SLOW. Wait for answers. Don't dump instructions.
• NEVER STOP MID-SETUP. After each phase, continue to the next automatically. Don't wait for "what's next?" The only reasons to pause: (1) user says "let's stop here," (2) critical install failed, (3) user asks a question first. After the journal phase especially, there are 10+ more phases. Don't stop there.
• If context gets compressed mid-setup (long session), re-read SKILL.md to pick up where you left off. Check which phases are done by looking at what exists in the vault.
• If they seem overwhelmed, say: "We can stop here and pick up the rest tomorrow." But default is KEEP GOING.
• Adapt the folder structure to their life, not a template.
• NEVER ask the user to open a terminal during setup. Claude runs all bash commands via its own tools. Users should not see a terminal after bootstrap runs. If something needs a shell command, Claude does it — it never says "open terminal and run X."
• If they're not technical, explain what's happening in plain language, not bash.
• Celebrate milestones: "Your CLAUDE.md is done, that's the biggest piece."
• Match their energy. If they're excited, move fast. If they're cautious, explain more.
• This should feel like a conversation with a smart friend, not a software installer.
• NEVER FAIL SILENTLY. After every file write, verify the file exists. After every install, verify it worked. If ANYTHING fails, TELL THE USER IMMEDIATELY. Say what failed, why, and how to fix it. Then FIX IT. People are trusting this skill with their personal data.
• Windows .ps1 files MUST be saved as UTF-8 with BOM. Windows PowerShell 5.1 (the default on Windows 10/11) reads BOM-less .ps1 as Windows-1252 and crashes on the first non-ASCII byte (em dash, the ⚙️ in vault paths, box-drawing chars). Any .ps1 file Claude writes during setup, or any .ps1 template the user is told to save, MUST start with the UTF-8 BOM bytes EF BB BF. When using Write, prepend \ufeff to the content. Verify after writing with file <path> (should report "UTF-8 (with BOM)"). The bootstrap.ps1, drift-check.ps1, and update-check.ps1 in this repo are already BOM-saved; preserve that on edit.

Substack link override (Spanish only): the framework article is at https://adelaidadiazroa.substack.com/s/internal-design (English). Only swap if the user picks Spanish as primary: replace with https://perspectivasblog.substack.com/s/el-rascacielos (title: "El Rascacielos, el modelo del diseño interno"). For every other language, leave the English URL.

---

Visual Reassurance Protocol

Non-tech users quit at first scary screen, not real failures. Pre-empt panic.

Say in PRIMARY_LANGUAGE BEFORE the scary moment:

Moment	Say first
Terminal text flood (brew/npm/git clone)	ES: "Va a pasar mucho texto. Normal. Si tarda 2-3 min, normal. No canceles." · EN: "Lots of text incoming. Normal. 2-3 min wait normal. Don't cancel."
Sudo/password prompt	ES: "Pide tu contraseña del computador. Escríbela, enter. No vas a ver los caracteres. Normal." · EN: "Asks for your computer password. Type, enter. Won't see characters. Normal."
Silent pause (no progress bar)	ES: "Se ve como si nada pasara. Sí pasa. Espera 30s." · EN: "Looks frozen. Isn't. Wait 30s."
Yellow/red warning text	ES: "Vas a ver amarillo o rojo. Si dice 'warning', sigue." · EN: "Yellow/red text. If it says 'warning', keep going."
Claude Code permission prompt	ES: "Cuadro pide permiso. Dale 'Allow'. Soy yo." · EN: "Box asks permission. Click 'Allow'. That's me."
⌘↩ vs typing — this is the most common point of confusion	When Claude is waiting to run a tool (gray box with a tool name), press ⌘↩ (Mac) or Ctrl↩ (Windows). When Claude asks you a question and is waiting for YOUR answer, just type normally and press Enter. Rule: if you see a gray tool box → ⌘↩. If Claude ends with a question mark → type your answer. ES: "Si ves una caja gris con un nombre de herramienta → ⌘↩. Si Claude te hace una pregunta → escribe tu respuesta normal y enter."

After scary moment passes: ES: "Listo. Sigamos." · EN: "Done. Moving on."

Say the ⌘↩ rule out loud before Phase 0 starts. It's the single most common stall point. People see a gray tool box and think they need to type something. They don't — they just press ⌘↩. Say it once early, remind once if they stall.