Architecture — Second-Brain OS

§2 · The file tree

The repo at a glance.

Everything Second-Brain OS knows about you lives in one folder. Here's the layout — context files at the root, the agent runtime config under .claude/, two memory locations (one in-repo, one per-machine), and the PARA workspace where your real work lives.

second-brain-harness/
├── CLAUDE.md           ← project rules + Configuration tokens
├── SOUL.md             ← persona, voice, operating principles
├── USER.md             ← your profile (role, team, preferences)
├── IDENTITY.md         ← AI name, version, origin
├── TOOLS.md            ← every connected tool, MCP, CLI
├── DESIGN.md           ← active brand/design system
├── README.md           ← project map
├── INSTALL.md          ← setup instructions
├── .mcp.json           ← MCP server registry
├── .claude/
│   ├── skills/         ← 84 slash commands
│   ├── hooks/          ← 6 event-driven scripts
│   ├── tools/          ← Python harness (Ouros, Exa, NIA)
│   └── settings.json   ← Claude Code config
├── memory/             ← Folder B: project memory (in git)
│   ├── memory.md       ← curated long-form
│   ├── YYYY-MM-DD.md   ← daily logs (append-only)
│   ├── writing-style.md
│   └── learned-preferences.md
├── workspace/          ← PARA work area
│   ├── 0-Inbox/        ← capture zone
│   ├── 1-Projects/     ← active projects
│   ├── 2-Coding/       ← code repos
│   ├── 3-Resources/    ← templates, meetings, reference
│   └── 4-Archive/      ← completed projects
├── docs/               ← briefings, prep, reports
├── scripts/            ← installer + lib helpers
└── ...

~/.claude/projects/<repo-slug>/memory/   ← Folder A: auto-memory (per-machine, NOT in git)
└── MEMORY.md           ← index + per-fact files Claude writes automatically

The shape

Eight identity files at the root, the agent config under .claude/, two memory locations (one tracked, one per-machine), and a five-folder PARA workspace. Everything else is supporting infrastructure.

§3 · Identity files

The 8 files at the root.

Every session, Claude reads these at startup. They're your AI's identity, your profile, your project rules, and your tool catalog. Edit them and your AI updates the next time it boots.

CLAUDE.md — project rules + Configuration tokens

The project-scoped instructions Claude follows. Loads at every session. Defines the load order for other identity files, project-specific output paths, and — critically — the Configuration token block that skills read symbolically (e.g., <user.name>, <workspace.root>) so the same skill works in any fork.

# Second-Brain OS — Project Instructions

## Load Order at Session Start
1. @SOUL.md      — persona, voice, boundaries
2. @USER.md      — your profile, role, team
3. @IDENTITY.md  — AI name, version, origin
4. @TOOLS.md     — available tools
5. @README.md    — project map

## Configuration — source of truth for skills

### workspace
- workspace.root      = workspace
- workspace.inbox     = 0-Inbox
- workspace.projects  = 1-Projects
- workspace.coding    = 2-Coding
- workspace.resources = 3-Resources
- workspace.archive   = 4-Archive

### user
- user.name      = Your Name
- user.email     = you@yourcompany.com
- user.github    = your-github-handle
- user.timezone  = America/Los_Angeles

When you'd edit this: adding a new output convention (e.g., "briefings go to docs/briefings/"), changing the workspace folder names, or adjusting a project-wide rule about how Claude should behave on this repo.

SOUL.md — persona, voice, operating principles

How your AI thinks and talks. Voice, phrases it uses, phrases it avoids, boundaries on what it will and won't do without asking. Also home to the Operating Principles — the rules that sit above any individual skill (Connect before create, Eliminate before automate, Consolidate before duplicate, etc.).

# SOUL.md — Who You Are

*You're the AI. Your job is to be helpful.*

## Core Truths

**You're not a chatbot — you're a right hand.** You know the
projects, the priorities, the quirks. When you speak, it
should feel like a trusted advisor who's been in the room.

**Have opinions.** You're allowed to disagree, prefer things,
flag when something seems off. An assistant with no
perspective is just a search engine with extra steps.

## Voice
Professional but warm. Direct, no corporate fluff.

Phrases you use: "Here's what matters...", "Worth noting...",
"My take on this..."

Phrases you never use: "Per your request...", "I'd be happy
to help!", "Actionable items include..."

When you'd edit this: tuning the voice (more casual / more formal), adding a new operating principle, or expanding the "phrases you never use" list when a tic creeps in.

USER.md — your profile (role, team, preferences)

Who Claude is helping. Your role, your team, your priorities, your communication preferences, your priority signals (which channels matter, which collaborators are HIGH-priority, what's calendar-conflict-grade urgent). This is the file that lets every skill act personally.

# USER.md — About Your Human

- **Name:** Your Name
- **Timezone:** America/Los_Angeles
- **Email:** you@yourcompany.com
- **Company:** Your Company

## Role
Product Manager on the Platform team.
Leads internal AI initiatives, runs office hours.

## Communication Preferences
- Direct and efficient — no corporate fluff
- Detail-heavy — wants specifics, not summaries
- Cross-referenced — connect emails, meetings, calendar
- Quantified — always include metrics

## Priority Signals
- Direct collaborators + manager = HIGH
- Calendar conflicts = URGENT
- Team blockers = URGENT
- Generic newsletters = LOW

When you'd edit this: changing role, team, manager, priority Slack channels, or shifting how you want the AI to communicate (more terse, more detailed, etc.).

IDENTITY.md — AI name, version, origin

The AI's name and origin story. Short, stable, rarely touched. Lets you give your AI an actual name (not just "Claude") so it feels like a colleague. Most users edit this once on first setup and never again.

# IDENTITY.md — Who Am I?

- **Name:** [Your AI's name]
- **Creature:** Chief of Staff AI + Personal Assistant
- **Vibe:** Professional but warm — like a trusted exec
  assistant who's worked with you for years.
- **Emoji:** 🎯

---

Born: 2026-05-06
Created with: Your Name
Version: 4.0.0

When you'd edit this: renaming the AI, bumping the version after a major harness upgrade, or shifting the vibe summary.

TOOLS.md — every connected tool, MCP, CLI

Slim inventory of every tool wired up right now. One line per tool with a status indicator (✅ verified, ⏳ pending, ❌ broken). The quick-reference Claude reads to know what's available without going on a discovery quest. Deeper verified-state catalog lives at workspace/3-Resources/reference/tool-inventory.md.

# TOOLS.md — Tool Index

## Connected MCPs (this repo's .mcp.json)
- ✅ gemini-vision — local stdio, 7 tools (image, OCR,
  PDF, video). Free Gemini tier.
- ✅ exa — HTTP MCP. ONLY web_search_advanced_exa.
- ✅ slack — read/send/search messages, threads, canvases.
- ⏳ atlassian — Jira + Confluence. Verify before relying.
- ⏳ figma — read designs, generate code, FigJam.

## CLIs (installed via samba-onboarding)
- ✅ gws — Google Workspace CLI (Gmail, Calendar, Drive...)
- ✅ gh — GitHub CLI
- ⚠️  databricks — pass -p <profile> (default invalid)
- ⚠️  sf — Salesforce; auth broken (run sf org login web)

## Pipeline tools
- ✅ jq, rg — installed
- ✅ ffmpeg 8.1.1 — required by hyperframes render
- ✅ hyperframes v0.4.45 — HTML video composition CLI

When you'd edit this: adding a new MCP server, a new CLI, fixing a broken tool's status, or after a quarterly tool-audit pass.

DESIGN.md — active brand/design system

The active brand. Read by every design-* skill when generating visuals — landing pages, decks, dashboards, posters. Hot-swappable: run /use-design <brand> to copy a brand preset from workspace/3-Resources/design-systems/ into the root. 72+ brand presets available out of the box (linear-app, stripe, claude, airbnb, etc.).

# DESIGN.md — Active Brand: Linear App

## Color tokens
--bg-canvas:    #08090a
--bg-panel:     #0f1011
--text-primary: #f7f8f8
--brand-indigo: #5e6ad2
--accent-violet: #7170ff

## Typography
font-family: 'Inter', -apple-system, system-ui, sans-serif;
font-feature-settings: "cv01", "ss03";

## Layout principles
- Dark canvas, light text
- Sticky nav, blur backdrop
- Container max-width 960px
- Tight letter-spacing on headings (-1.056px)

When you'd edit this: rarely directly. Use /use-design <brand> to swap presets. Edit only when authoring a new brand for the design-systems library.

README.md — the project map

The folder-by-folder tour. What's at the root, what's in .claude/, what's in workspace/, what's in docs/. Plus the update rules — when to update which file, and what does NOT belong at root. Onboarding doc for anyone (human or agent) joining the project.

# Second-Brain OS

Your personal Chief-of-Staff workspace.

## Update Rules — "What goes where, when"

### Identity / Persona Files (root)
| File         | When to update                          |
|--------------|------------------------------------------|
| SOUL.md      | Voice, boundaries, "how to be helpful"  |
| USER.md      | Role, team, preferences shift           |
| IDENTITY.md  | Version bumps, name changes. Rare.      |
| CLAUDE.md    | Project-specific context only           |
| TOOLS.md     | Toolchain changes (MCP, hooks, skills)  |

### Memory — dual-folder model
Two memory folders, distinct roles. Both load at session
start. See Architecture page §3 for the visual.

When you'd edit this: adding a new top-level folder, changing a naming convention, or after a major reorganization. Treat it as the canonical project map.

INSTALL.md — setup instructions

The text version of this onboarding guide. Step-by-step setup, prerequisites, troubleshooting. For people who prefer terminals to web pages, or for the moment when someone clones the repo at 11pm and the web docs aren't loaded in their head.

# Second-Brain OS — Installation

## Prerequisites
- macOS / Linux / WSL2
- bash, curl, tar (built-in on Mac)

## Two-step install

### Step 1 — Install the tools (~8 min)
curl -fL -o samba-onboarding.tar.gz \
  https://github.com/the-sid-dani/samba-onboarding/...
tar xzf samba-onboarding.tar.gz
cd samba-onboarding-main && ./install.sh

### Step 2 — Install the OS (~5 min)
git clone https://github.com/the-sid-dani/\
  second-brain-harness.git
cd second-brain-harness && ./scripts/install.sh

## Verify
gh auth status
gws auth status
claude --version

When you'd edit this: if the install steps change, when prerequisites shift (new Node version pin, new platform support), or to add a troubleshooting section for a recurring install failure.

§5 · Skills

How skills work.

Skills are slash commands that bundle context, prompts, and tools into one repeatable action. You can invoke them directly (/briefing, /new-project) or just say what you want in plain English — the harness detects the intent and surfaces the suggestion. Eighty-four skills ship by default. Most of the work you do will go through them.

Two ways to invoke a skill

By slash command — direct: /briefing. Fastest if you know the skill name.

By natural language — say what you want: "brief me this morning", "what's on my plate", "give me the lay of the land." The intent-detector (a small background helper) recognizes the pattern and suggests /briefing. You confirm; the skill runs.

The natural-language path is the default for new users. You learn the slash commands by seeing them suggested.

How skills compose

A skill often calls other skills. This is the part that feels like magic the first time you see it.

Example — /briefing morning routine:

/briefing is the entry point. It owns the flow.
It calls /find to search your active projects and recent memory.
It calls gws-calendar-agenda to read today's calendar.
It calls gws-gmail-triage to surface unread email priorities.
It cross-references — meeting attendees against your contacts directory.
It writes the result to docs/briefings/morning-briefing-YYYY-MM-DD.md.

One prompt. Six tools touched. The skill is the orchestration, not the work.

One prompt invokes /briefing; the skill composes four tools and writes one artifact.

Skills by category (high-level)

Project lifecycle — /new-project, /archive-project, /prune-projects
Chief of staff — /briefing, /meeting-prep, /contact, /find
Design — 26 skills covering decks, dashboards, landing pages, mobile UI
Persona workflows — exec-assistant, sales-ops, content-creator, project-manager
Google Workspace — ~40 skills for Gmail, Calendar, Drive, Docs, Sheets, etc.

See Reference for the complete catalog organized by category.

Why this is Capabilities

Skills are pillar 3 of the 4 Cs — Capabilities. Each one is a packaged outcome: "morning briefing", "archive this project", "draft this email in my voice." The harness ships 84 by default; you'll write a few of your own once you spot a workflow you keep doing manually.

Step 1 of 2 — Install the tools

Install the tools →

What's actually inside.

Connect the tools.

The repo at a glance.

The 8 files at the root.

The dual-folder memory model.

How skills work.

Two ways to invoke a skill

How skills compose

Skills by category (high-level)