ai-brain-starter

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.

Use when an AI Brain vault needs a health check or something feels off: Claude ignores CLAUDE.md, journal entries missing from /weekly, hooks not firing, something broke after a git pull, a friend's install misbehaves, Obsidian crashes or pegs the CPU, a .claude/worktrees folder appeared, Granola/WhatsApp/Slack/Gmail notes stopped arriving, or Windows .ps1 scripts error. Also after major /setup-brain upgrades. Not for debugging code; audits the vault install only.

Use when many related hardened instincts (high-confidence feedback_*/discovery_* memories) have piled up in one domain, when the user runs /evolve or asks to promote, cluster, graduate, or consolidate accumulated instincts into a Command, Skill, or Agent, or when files in Instinct Proposals need review. Part of the Instinct Engine. Not for one-off pattern capture (use patterns), daily journaling, or sharing instinct packs (use instinct-export / instinct-import).

Use when a user wants the team or company version of ai-brain-starter — any variant of 'how do I add my team to this,' 'can my team use this,' 'optimize this for my company,' 'what does the team version look like,' 'install this for my whole company,' 'how does this work with multiple people,' or worries about mixing personal notes into a shared team vault. Also triggers on /for-my-team.

Use when the user invokes /graphify or asks to build, update, or query a knowledge graph from a folder of files (code, docs, papers, notes, images). Triggers: 'map this codebase', 'graph my notes', 'what is connected across these files', 'community detection', 'GraphRAG', incremental graph update, Neo4j/SVG/GraphML export, graph lookups (query, shortest path, explain a node). Not for simple file reads, vault edits, or plain text search.

Use when the user says /ingest-github <owner/repo> [--days N], or asks to ingest, capture, sync, pull, mirror, or import a GitHub repo's recent activity (merged PRs, issues, commits) into the vault, second brain, or knowledge graph, or wants repo history queryable by graphify or External Inputs refreshed. Not for opening PRs, creating issues, one-off PR diff reads, or non-GitHub sources (Slack, Notion, email have their own ingest-* connectors).

Use when the user says /ingest-youtube <url-or-channel> [--days N], pastes a YouTube URL (youtube.com or youtu.be) wanting a transcript or summary in the vault, asks to ingest, capture, sync, transcribe, or pull a YouTube video, channel, talk, podcast, or keynote into the vault, or wants a video's captions or content available to the knowledge graph. Not for downloading video files, live streams, or non-YouTube sources (Vimeo, Twitch).

Use when the user runs /instinct-export or wants to share, back up, hand off, or publish learned instincts to another machine, harness, or teammate — 'export my instincts', 'make an instinct pack', 'build a house/team instinct library', 'send my rules to a teammate', 'move instincts to my new laptop'. Part of the Instinct Engine. NOT for reading or reviewing memories (use /patterns) and NOT for importing a pack (use /instinct-import).

Use when bringing a teammate's, another machine's, or another harness's instincts into this vault: the user runs /instinct-import, shares a portable YAML instinct pack (PACK.yaml), or asks to merge, adopt, sync, or inherit shared instincts. Confidence-gated so local instincts are never clobbered. Part of the Instinct Engine; pairs with instinct-export. Do NOT use to author memories by hand (just write the file).

Use when the user says /patterns or mentions the Instinct Engine, says "I keep noticing" or "this keeps coming up", after a weekly review, when a pattern is hardening, or at session end after repeated corrections, 5+ tool-call friction on a routine task, dead-end backtracking, or an undocumented discovery. Also as a silent pre-flight before fix/debug/build/refactor on a named surface. Not for weekly/monthly journal reviews, daily journaling, or one-off decisions.

Use when the user wants to map or remap their second brain, refresh the vault's queryable metadata index, extract structured frontmatter from typed notes (books, meetings, people, journals, goals), fill wikilink gaps, or surface cross-type insights and patterns no single file shows. Triggers: /second-brain-mapping, "map my second brain", "make my vault queryable", "refresh vault metadata", stale or sparse Dataview fields. Not for single-file reads or querying an existing graph (use graphify).

Use when the user says /security-snapshot, /snapshot <domain>, "run a security check on X", "generate a security report for [company]", or wants a security hygiene snapshot or free lead-magnet report on a prospect's public domain: SSL/TLS grade, HTTP security headers, SPF/DMARC email authentication, server fingerprint leaks. Passive, unauthenticated scans only. NOT for penetration testing, internal infrastructure audits, or application-layer vulnerability assessment.

Use when configuring which document types a vault tracks: after installing ai-brain-starter, when a new kind of note appears (journals, books, meetings, clients, podcasts, travel, WhatsApp/Slack/iMessage exports), when extraction skips files because no extractor matches their type, or to add, list, or remove a custom type. Triggers: /setup-vault-types, "set up vault types", "add a note type", "enable an extractor". NOT for running extraction (use /second-brain-mapping).

Use when the user asks for the weekly meta-review or Sunday wrap-up of their week and vault: says /sunday, /sunday-review, 'let's do the weekly review,' 'Sunday review,' 'review my week,' 'weekly retro,' 'week in review,' 'end-of-week review,' or wants journals, patterns, vault health, and stale decisions reviewed together at week's end. Not for a journal-pattern read alone (use /weekly) or mid-week single checks.

Use when the user wants to journal, do a daily or end-of-day check-in, reflect on or vent about their day, brain-dump feelings, log what happened today, or says /journal. Also fires for quick one-line captures and a second session the same day (resumes that day's entry). Not for meeting notes (use meeting-todos), morning priorities (use rise), weekly/monthly reviews (use insights), or cross-entry pattern analysis (use patterns).

Use when the user types /weekly or /monthly, asks for a weekly or monthly journal review or retrospective, asks 'how was my week' or 'how was my month', or wants trends, anomalies, or patterns across recent journal entries. Also fires when regenerating an insight report for a past week or month. NOT for writing today's entry (use daily-journal), cross-session pattern extraction (use patterns), or operational/team reviews.

Use when the user says /backfill-journal-body-context, wants existing daily journal entries enriched with body data retroactively (HRV, sleep, recovery, cycle phase, labs), says 'backfill my journals with health', wants Apple Health / Oura / Fitbit / Whoop history paired with past journals, or just ran /health-setup with a historical import. Not for brand-new entries (daily-journal covers those) or for editing journal text.

Use when the user says /coach (today, week, month, profile, log), asks what to do today for training, asks for a workout, weekly training plan, or longevity plan, wants to log a finished workout or check lift progression (PR, plateau, deload), or a scheduled morning task fires to drop today's workout into the calendar. NOT for importing health data (use ingest-health/health-setup), raw biometric queries without a prescription, or emotional/life coaching (use coaching).

Use when the user wants to process a hard conversation, a decision they're second-guessing, or accumulated friction with a person (too big for a daily journal), wants panel takes that update with their corrections, or wants growth on a theme tracked over weeks. Triggers: /coaching, "coach me through this", "help me process this". NOT fitness coaching (/coach), daily entries (/journal), weekly/monthly reviews (/weekly, /monthly), or cross-session pattern detection (/patterns).

Use when a decision or strategy rests on unexamined convention: the user says 'that's how it's done', 'best practice', or 'everyone does it this way', copies a competitor, or feels stuck in a pricing model, business model, roadmap, hiring process, or career path they can't justify from scratch. Also use on any high-stakes decision (stakes: high) before commit, or when the user types /deconstruct or asks to question assumptions or reason from first principles.

Use when correctness matters more than speed: about to commit non-trivial code, make an architectural call under uncertainty, work in unfamiliar code, or assert what the compiler cannot check ('this is safe', 'thread-safe', 'this scales', 'matches the spec'). Strongest on high-stakes surfaces (production deploys, security-sensitive logic, data migrations, irreversible operations) and when the user asks to sanity-check, red-team, double-check, or get a second opinion on a decision.

Use when a host skill that benefits from biometric context runs: daily-journal (/journal), coaching, advisory-panel (/panel), patterns, or insights (/weekly, /monthly). Also use when the user asks how HRV, sleep, recovery, resting heart rate, steps, or workouts relate to a journal entry, coaching window, decision, pattern, or weekly review. Companion layer, never standalone. Setup: health-setup. Data import: ingest-health. Sync diagnostics: health-doctor.

Use when the user runs /health doctor or /health status, asks whether the health auto-chain is working, when the last Oura, Fitbit, Apple Health, or labs sync happened, whether the coach prescribed today, why a workout or prescription didn't appear in the calendar, why wearable data looks stale or missing, whether an out-of-range lab marker needs a re-test, or wants to confirm health-mcp hook wiring after first-time setup.

Use when the user says /health-setup or /setup-health, asks to set up or connect a wearable (Apple Watch, Apple Health, Oura Ring, Fitbit, Garmin, Whoop), asks how to import Oura / Fitbit / Apple Health data, asks which wearable to use, hits a failing health_vendor_healthcheck, a 429 rate limit, or an expired Fitbit token during setup, or has health-mcp installed with an empty body track. Not for querying already-imported data or building new connectors.

Use when the user says /ingest-health, asks to import, sync, ingest, or load Apple Health / Apple Watch / HealthKit data, has a fresh export.zip from the iPhone Health app, a Simple Health Export CSV folder, or a Health Auto Export TCP live feed, or when health-mcp queries return empty because no data was ever imported. Not for querying existing health data (health-mcp tools do that) or non-Apple wearables (Garmin, Whoop, Oura).

Use when an ask is underspecified ("build me X" without who it's for, why now, or what success looks like), when a request is conventional rather than specific ("a dashboard", "make it faster" with no number), when Claude catches itself silently filling in ambiguous requirements before any plan, spec, or code exists, or when the user says "interview me", "grill me", "are we sure?", or "stress-test my thinking". Needs a live user; not for CI, scheduled runs, or autonomous loops.

Use when the user wants multi-year health patterns from HealthKit + journal data: "patterns in my health data," "what does my body tell me," "correlations between mood and HRV," "Floor x body fingerprint," long-term trends in sleep, HRV, VO2max, cycle, or symptoms, "how has my body changed over the years," or /longitudinal. NOT for single-day analysis (use /health-doctor), this-week patterns (use /weekly), or journal-only pattern extraction (use /patterns).

Use when the user says /meeting-todos, "the meeting is done", "I just had a meeting", "pull the action items", "what did I commit to", or otherwise wants action items from a recent meeting note captured on their to-do list. Also when a meeting note or transcript needs its tasks pulled out. NOT for general task management, journaling, non-meeting notes (use note-todos), or pulling full meeting transcripts.

Use when the user asks to create or generate an image, visual, logo, thumbnail, infographic, product shot, hero image, OG image, blog/Substack header, sticker, portrait, or any text-to-image or image-generation task; edit a photo; compose multiple images; refine an image iteratively; set aspect ratio/resolution; or visualize real-time data (weather, stocks, news) with Gemini's Nano Banana Pro. Not for text generation, design feedback (design:design-critique), or template designs (Canva MCP).

Use when the user says /note-todos, asks to pull, extract, or file action items or to-dos from a non-meeting note (class notes, book notes, podcast notes, transcripts, panel writeups, strategy docs, action plans), or mentions tasks buried in a note that never reached a to-do list: unfiled checkboxes, orphan action items, 'what tasks are hiding in my notes'. For meeting notes prefer meeting-todos, which carries the full meeting workflow cascade.

Use when the user just gave a talk, panel, fireside chat, keynote, workshop, podcast, or webinar and wants content made from it — triggers like "I just gave a talk", "the panel is done", "just finished speaking", "turn my talk into LinkedIn posts", "repurpose this recording/transcript into posts, notes, or clips", or /repurpose-talk. Works from a recording, transcript, slides, or a from-memory brain-dump.

Use when an operator asks which rule or policy governs a question — pricing exceptions, deploys, refunds, hiring — or wants to look up the matching rule in Meta/RESOLVER.md without reading the whole index by hand. Triggers: /resolver-query <question>, "which rule applies", "what's our policy on X", "does a rule cover this". Not for writing or editing rules (read-only) and not for rebuilding RESOLVER.md (use resolver-build.py).

Use when the user says /rise, "good morning", "buenos días", "let's start the day", "morning routine", "morning check-in", wants their morning consciousness routine, or asks to set the day's priorities or intention first thing after waking. Pairs with /journal at night. NOT for evening reflection (use /journal), pattern detection (use /patterns), or workout prescription (use /coach; /rise covers only the post-wake body wake-up flow).

Use when adding or tuning edit-time secret and code-injection guardrails or security hooks in Claude Code, or on mentions of secret detection, API key safety, hardcoded or leaked keys (AWS, Stripe, GCP, OpenAI, Anthropic, GitHub, Slack, JWT, PEM, .env), gitleaks-style or pre-commit secret scanning, false positives or allowlists, unsafe pipe-to-shell or MCP server installs, or prompt injection in audited third-party content (README, AGENTS.md). Not for full security audits, pen testing, or DLP.

Use when a recurring bug, support question, client incident, or manual task surfaces 2+ times, when a codified rule keeps getting violated despite being written down, when a teammate or client hits an issue anyone could hit, or when delivery/setup friction repeats. Triggers: "skillify this", "this keeps happening", "we hit this last week too", "make a skill for X", "automate this", "every client hits this", "I keep doing X manually", "turn this into a skill".

Use when maintaining the vault ITSELF as a system, not its content: knowledge-graph build/rebuild/query (graphify), second-brain mapping, vault diagnose/audit/hygiene, drift detection, extract rules from vault, backfill journals, setup vault types, consolidate memory (index over cap), Obsidian tooling (CLI/Bases/Markdown/JSON Canvas), vault bloat or Obsidian slow. Answering questions FROM the graph, use graph-query tools; daily journal/coaching/pattern detection, use those skills.

Extract action items from a meeting note and add them to your to-do list. Separates your tasks from others' tasks. Shows a preview before writing anything. Trigger: /meeting-todos