second-brain-os

Interactive first-run setup for a fresh fork of the second-brain-os — THE entry point every fork user runs once to configure their identity, name their assistant's persona (no default name — fork users always name their own), pick a design system, create the PARA workspace, and write the Configuration token block in root CLAUDE.md. A short, plain-language guided walkthrough for knowledge workers (~8-10 min) with AskUserQuestion gates and a brief why-it-matters intro on each step; nothing is installed, nothing is committed, every write asks first. When core setup finishes, it offers two OPTIONAL go-further steps — learning your writing voice from your own sent Slack/Gmail messages (with consent), and bringing your existing work in via `/migrate-work`. Detects re-runs via `setup_completed:` and refuses gracefully. Use after cloning the repo, or to reconfigure identity / persona / workspace — phrases like "/bootstrap", "I just cloned this", "first-time setup", "configure the assistant". Tiger invariants T1-T4 (n

Bring a user's EXISTING work into their second-brain-os PARA workspace by reading their past Claude Cowork sessions (local transcripts on disk) — discovering the projects they've actually been working on, then scaffolding the chosen ones as organized PARA entries (1-Projects or 4-Resources) with a CLAUDE.md + memory.md seeded from the session context. Read-only discovery + a fan-out of scout subagents (one per discovered project) + a SINGLE approval gate, then copy-never-move writes. Offered at the end of `/bootstrap` and re-invokable anytime. Use when the user says "/migrate-work", "bring in my existing work", "import my projects", "I have existing projects to bring over", "organize my past work", "migrate my cowork sessions". Hard invariants live in SKILL.md body — copy-never-move, read-only discovery, one approval gate, no fabrication, runnable code routes to the coding bucket (`<workspace.coding>`), never auto-commit.

OS reference manual — for fork users in their first 30 days AND for Claude Code self-correcting mid-session on an OS-shaped mistake. Routes the question to its canonical source file, reads at runtime, answers with file:line citations. Topics — PARA, Configuration tokens, memory model, contacts schema, tools, lifecycle, design system, locked decisions, capability index, trigger-phrase map, Operating Principles. **Claude SHOULD consult this skill** before answering questions involving OS configuration values, workspace paths, or canonical skill behavior — especially before writing file paths into responses or scaffolding new files. Read-only by default; `/os-guide --sync` is the sole mutation mode and is gated behind explicit user approval. PRECEDENCE — `/bootstrap` for first-run setup; `/find` for topic search across user content; `/contact` for people; `/os-guide` for the OS itself.

Moves a completed project from `<workspace.root>/<workspace.projects>/<slug>/` to `<workspace.root>/<workspace.archive>/<slug>/` and flips its frontmatter `status: active` → `status: done`. All paths come from the Configuration section in root CLAUDE.md — read those first. Use this whenever the user says they're done with a project, wants to wrap it up, or wants to clean up their active list — phrases like "archive the X project", "I'm done with X", "wrap up X", "move X to archive", "X is finished — clear it out", "shelve X for now". Optional one-paragraph retro gets appended to `memory.md` before the move so the decision context survives. Trigger even when the user doesn't say "archive" explicitly — finishing/wrapping/clearing language for a known project should invoke this skill rather than letting them `mv` by hand (which would skip the status flip and break `/prune-projects` later).

Upload files (screenshots, diagrams, PDFs, exported designs) as attachments to a Jira issue or a Confluence page. Works for either target — pick the subcommand. Uses Atlassian REST API directly via Python urllib + multipart — the official Atlassian MCP has no attachment-upload tools, so this skill exists to fill that hole. Auth via ATLASSIAN_BASIC_AUTH env var (classic API token only — scoped tokens cannot upload). Use whenever the user wants to add an image, screenshot, design export, or any binary file to an existing Jira ticket or Confluence page — phrases like "attach this screenshot to PROJ-450", "upload my-diagram.png to the design page", "add this PDF to the ticket", "embed this image in Confluence". Pairs naturally with `/confluence-publish-markdown` (which embeds external URLs only — no native upload) and with `/scaffold-engineering-project` (when slice descriptions need supporting images).

Deep, iterative, hypothesis-driven research that loops until confident — not a single-pass lookup. Builds on /research by spawning multiple hypothesis workers per iteration, accumulating evidence in Ouros sessions, looping until confident or the user stops. Use when the user says 'research this deeply across multiple passes', 'run iterative research on', 'hypothesis-driven investigation of', 'loop until you understand X', 'deep-dive with synthesis'. NOT for single-session exploration (use /research) or implementation (use /autonomous).

Autonomously implement a software task end-to-end — feature build, bug fix, or multi-milestone greenfield project. Orchestrates worker agents via TDD (plan, test-first, implement, validate, evolve). Use when the user says 'implement this autonomously', 'build feature X with tests', 'run the SDLC pipeline on', 'autonomous implementation of', 'scaffold and build it'. NOT for open-ended research (use /research) or one-off edits.

Get a code project agent-ready — score readiness across 27 criteria in 7 categories, auto-fix mechanical gaps, load context blocks, then route to research / autonomous / review mode. Use when the user says '/bootup', 'get this project ready for Claude agents', 'run a readiness check', 'score this codebase', 'prepare this repo for agent work', or 'set up agent tooling for this project'. Spawns Task agents to score and fix; does not edit business code directly. NOT first-run fork setup (that is /bootstrap).

Morning chief-of-staff briefing — composes available signal sources (email, calendar, messaging, issue-tracking, code-hosting) plus local sources (contacts, active projects, USER.md priorities) into one self-contained HTML brief at `<workspace.root>/<workspace.resources>/briefings/morning-briefing-YYYY-MM-DD.html`. Detects tool availability at runtime in Step 0.5 + auth-health probes each detected tool in Step 0.6, surfacing failures via AskUserQuestion BEFORE composing (so a dead Slack token doesn't get discovered after the brief is written). Fork users with zero MCPs still get a useful brief from local state. Use when <user.name> asks to start the day or surface what needs attention — phrases like "/briefing", "brief me", "what's on my plate today", "what should I work on today". Trigger broadly on day-orientation language. Filters `status: personal` contacts; never auto-sends; never fabricates absent signals; **Slack sweep MUST cover all four channel types — `public_channel`, `private_channel`, `im`, AND `

Track monthly spending, analyze budget vs actual, calculate savings rate. Use when user says "budget review", "monthly spending", "how much did I spend", "savings rate", or "track expenses". Analyzes bank CSVs and generates markdown budget reports.

Company research using Exa search. Finds company info, competitors, news, financials, LinkedIn profiles, builds company lists. Use when researching companies, doing competitor analysis, market research, or building company lists. NOT for individual-person lookups (use /people-research).

Port a local markdown file (design doc, investigation report, runbook) to a Confluence page — handles markdown → ADF conversion, renders embedded mermaid diagrams via mermaid.ink as external media, optionally injects a standard header info panel with Repo / Live / Jira cross-links. Use whenever the user wants to publish a markdown file to Confluence — phrases like "publish this design doc to Confluence", "port this markdown to <space>", "create a Confluence page from this .md", "ship system-design.md to the wiki", "update the Confluence page". Supports both create-new (`--parent-id`) and update-existing (`--page-id`) modes.

Write-mode skill — append a new interaction entry to a matched contact's `## Interaction log` section in `<workspace.root>/<workspace.resources>/contacts/<slug>.md` and auto-bump the `last_interaction` frontmatter to today's date. Append-only via Edit (never Write — preserves prior entries + About / Recurring topics / Open commitments sections). Entry text wikilinks other known contacts/topics per the back-linking iron law (Step 4); materially-involved other contacts get a suggest-only propagation offer. Reuses `/contact`'s fuzzy-match priority order. Use when <user.name> wants to record an interaction — phrases like "/contact-log <name>", "log my meeting with X", "just talked to <name>", "record my call with X". Mutation, single-source, and no-fabrication invariants live in SKILL.md body.

Read-only display of a contact's profile from `<workspace.root>/<workspace.resources>/contacts/<slug>.md` — fuzzy-matches a name, then surfaces frontmatter summary, last interaction, open commitments (To/From split), About blurb, and Recurring topics. Use when the user asks <assistant.name> to recall who a person is or what context exists with them — phrases like "/contact <name>", "who is X?", "what's my context with Y?", "tell me about <name>". PRECEDENCE: `/contact` wins when the query target matches a file in contacts/; `/find` handles topic-keyed recall (research subjects, project topics). Fuzzy-match priority order (locked) lives in SKILL.md body. Read-only — for mutation use `/contact-log` or `/contact-add` (planned).

At end of session, create a structured handoff document so the next Claude instance can continue without re-discovering context. Use when the user says 'I need to stop', 'create a handoff', 'wrap up and document', 'end-of-session notes', 'pass context to the next session', 'handoff doc', or '/create-handoff'. Writes a handoff YAML with mental model, decisions, findings, next steps, and an immediately-actionable next-session prompt.

Sweep loose files off the Mac Desktop (and optionally ~/Downloads) into the right home inside <workspace.root>. Screenshots and images go to a Resources media folder; anything uncertain goes to the Inbox for later triage. Native Bash only, confirmation-gated, never deletes without asking. Use when <user.name> says "organize my desktop", "clean up my desktop", "mac cleanup", "clean up downloads", "sort my screenshots", "tidy the desktop", or any desktop/downloads file-sweep intent.

Recall layer for the second brain. Searches across `<workspace.root>/<workspace.resources>/`, `<workspace.projects>/`, `<workspace.archive>/`, `<workspace.areas>/` (HQ workstations, now PARA Areas), and `memory/` for a topic — by filename and content — then merges, ranks, and optionally synthesizes matches with file citations. Use whenever the user asks <assistant.name> to recall existing knowledge before generating new content — phrases like "do I have anything on X", "what do I know about Y", "search my notes for Z", "find research on W", "is there a project for V", "/find <topic>". Trigger broadly on recall language even when the user doesn't say "find" explicitly.

Friday-batch triage of `<workspace.root>/<workspace.inbox>/` AND of unmigrated `<workspace.root>/<workspace.projects>/*/` folders (missing CLAUDE.md). Iterates each candidate, shows preview, asks disposition via `AskUserQuestion`: promote (→ `/save-resource`), project (→ `/new-project`), scaffold-in-place, move-to-coding, move-to-inbox, archive, delete, or keep. Sister skill to `/prune-projects`. Use when the user wants to clean up Inbox or surface unmigrated debris — phrases like "process inbox", "Friday inbox review", "triage inbox", "what's unmigrated?". Trigger broadly on clean-up / triage language.

Decompose a Jira Epic into N Story tickets in one batch — consistent shape per story (header info panel with Confluence + repo cross-links, ADF taskList for acceptance criteria, parent linkage, custom fields, Blocks links between sequential slices). Use whenever the user wants to break an Epic into vertical slices and bulk-create the corresponding Stories — phrases like "decompose this Epic into stories", "create the slices", "scaffold the stories under <Epic>", "spin up Slices A through G", "bulk-create these vertical slices in Jira". Reads from a YAML/JSON spec the user prepares — does not author the spec from conversation.

Scaffolds a new project — either a meta-project (planning, strategy, content, research, meetings) at `<workspace.root>/<workspace.projects>/YYYY-MM-slug/` or a code repo at `<workspace.root>/<workspace.coding>/<name>/` with optional GitHub integration. Use whenever the user wants to start, kick off, scaffold, set up, or create a new project — phrases like "kick off X", "scaffold a project for Y", "set up the QBR prep", "new MCP server for Z", "spin up a repo for W", "create a TypeScript/Python/Rust project". Branches on project type; body has the full taxonomy and Configuration-token resolution. NOT for wiring Confluence + Jira on an existing engineering project (use /scaffold-engineering-project).

People research using Exa search. Finds LinkedIn profiles, professional backgrounds, experts, team members, and public bios across the web. Use when searching for people, finding experts, or looking up professional profiles. NOT for company-level research (use /company-research); defers to /contact when the person is already a known internal contact.

Before starting any implementation, project failure states and classify risks via a first-principles retrospective — what assumptions could be wrong, what shortcuts become permanent, what is being avoided. Use when the user says 'what could go wrong with this plan', 'risk analysis before we build', 'premortem this spec', 'failure-mode analysis', 'what are we missing'. Outputs tiger (must mitigate) / paper-tiger (bounded) / elephant (avoided) classification with a BLOCK/WARN/PASS gate.

Friday-batch staleness review. Runs `<scripts.project_query>`, filters stale projects (active ≥90 days untouched, paused ≥60 days, status=done that slipped through), shows them in an `AskUserQuestion` multiselect with last-memory-entry context, and chains to `/archive-project` for each one the user approves. All paths come from the Configuration section in root CLAUDE.md — read those first. Use this whenever the user wants to clean up their active project list — phrases like "what's stale?", "any stale projects?", "Friday review", "what should I archive?", "prune projects", "what can I clean up?", "review my projects", "anything I should close out?", "what's gone cold?". Trigger even when the user doesn't say "prune" — clean-up / review / staleness language for the project list should invoke this rather than a manual scan. Skips `ongoing`-type projects (recurring duties — never stale).

Explore, investigate, or reason through something you do not know the answer to yet — open-ended investigation where the destination is not clear. Unlike /autonomous (known goal, TDD), this is for unknowns. Use when the user says 'explore X', 'what do I need to know about Y', 'investigate why Z', 'research the best approach to W'. Runs Ouros REPL sessions for token-efficient exploration. NOT for iterative hypothesis loops (use /autonomous-research) or people/company lookups (use /people-research or /company-research).

Resume work from a previous session's handoff document. Use when the user says 'continue from last session', 'pick up where we left off', 'load the handoff', 'resume from handoff', 'what was I working on', or '/resume-handoff'. Reads the handoff YAML, verifies current codebase state, presents a synthesis with recommended next actions, then optionally resumes an /autonomous session. Pass a path or ticket number, or omit for workspace-wide discovery.

Hybrid code review with structural grounding — anchors Claude's semantic judgment on deterministic tldr facts (impact radius, dead code, call-graph change-impact, diagnostics/lint+type), not LLM opinion alone. Use for 'review this code', 'review my changes', 'review my PR', 'check before I merge', 'what did I break', 'pre-push quality gate'. Phase 1 dispatches parallel agents running tldr diagnostics / impact / dead / change-impact; Phase 2 reasons over those facts plus the git diff. Modes via flags — uncommitted (default), staged, base-ref compare, quick, security-focus, or a PR number. Verdict: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION. Prefer over /code-review when you want multi-agent structural grounding; use /code-review for a single-pass diff review.

Saves content into `<workspace.root>/<workspace.resources>/<type>/...` with the right convention per type — research → `YYYY-MM-<topic>-research/`, reference flat, meetings → `YYYY-MM-DD-<topic>.md`. Use whenever the user wants to file something into Resources — phrases like "save this to research", "file this in reference", "this is a meeting note", "promote this to resources", "save the X file in inbox to <type>", "/save-resource". Handles three sources: file path in invocation, Inbox candidate, or chat content. Trigger broadly on save/file/promote language for reference material.

One-command project scaffold combining Confluence + Jira. Given an existing Jira Epic and a repo with `system-design.md` (and optionally other markdown design docs), the skill publishes the markdown docs to Confluence as a hub-and-spokes structure, then bulk-creates the vertical-slice Stories under the Epic with full cross-links. Use this whenever <user.name> wants to scaffold a new engineering project end-to-end — phrases like "scaffold this engineering project", "set up Confluence + Jira for X", "land this design across both wikis", "boot the project tracking for X", "wire up Confluence and Jira for the new initiative", "publish the design doc and create the slices", or any intent to spin up project-tracking infrastructure all at once. Trigger broadly on combined-publish-and-ticket intent. The skill is a thin orchestration wrapper around `/confluence-publish-markdown` and `/jira-decompose-epic` plus its own hub-page generation. Use the atomic skills directly when you only need one half of the workflow.

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. NOT for auditing or scoring the whole skill library at once (use /skill-audit for the batch best-practices pass).

Audits drift between `<workspace.root>/<workspace.coding>/` (flat — one folder per repo) and `<indexes.code_projects>` (the canonical code-repos index). Three-way diff — repos on disk missing from index → ADD; rows in index without folder → FLAG/remove. Read-only by default; mutates only after `AskUserQuestion` approval. Use whenever the user wants to audit code-repo bookkeeping — phrases like "sync indexes", "check for orphan repos", "audit code repos", "is my index up to date?", "/sync-indexes". Trigger broadly on audit/drift/orphan language.

Add a new external function (bridge function) to the Ouros sandbox harness — a new search provider, Slack integration, database query, or API call. The harness lives at .claude/tools/ouros_harness.py. Use when the user says 'add X to the sandbox', 'extend ouros with', 'new bridge function for', 'give the sandbox access to'. Walks through the async/sync wrapper, SECURITY_POLICY, EXTERNAL_FUNCTIONS registration, and smoke tests. NOT for upgrading the harness version.

Single-file horizontal-swipe HTML deck. Built by copying the seed `assets/template.html` (which carries the proven 5-rule iframe nav script) and pasting slide layouts from `references/layouts.md`. Pitch decks, product overviews, study material. Use when the user says "deck", "slides", "ppt", "presentation".

A long-form article / blog post — masthead, hero image placeholder, article body with figures and pull quotes, author byline, related posts. Use when the brief asks for "blog", "article", "post", "essay", or "case study".

Run a 5-dimension expert design review on any HTML artifact in the project — Philosophy / Visual hierarchy / Detail / Functionality / Innovation, each scored 0–10. Outputs a single self-contained HTML report with a radar chart, evidence-backed scores, and three lists: Keep / Fix / Quick-wins. Use when the brief asks for a "design review", "design critique", "5 维度评审", "design audit", or "what's wrong with my design".

Admin / analytics dashboard in a single HTML file. Fixed left sidebar, top bar with user/search, main grid of KPI cards and one or two charts. Use when the brief asks for a "dashboard", "admin", "analytics", or "control panel" screen.

A documentation page — left nav, scrollable article body, right-rail table of contents. Use when the brief mentions "docs", "documentation", "guide", "API reference", or "tutorial".

Quarterly / monthly financial report — masthead with KPIs, revenue and burn charts, P&L summary table, top-line highlights, and an outlook paragraph. Use when the brief mentions "financial report", "Q3 report", "MRR review", "P&L", or "财报".

Meeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".

Product spec / PRD as a single page — problem, success metrics, scope, user stories, design notes, rollout plan, open questions. Use when the brief mentions "PRD", "spec", "product spec", "feature brief", or "需求文档".

A standalone pricing page — header, plan tiers, feature comparison table, and an FAQ. Use when the brief asks for "pricing", "plans", "subscription tiers", or a "compare plans" page.