Second Brain

A Brain is a centralized knowledge repository. Projects, reference knowledge, decisions, meeting notes — all in one Git repo of plain GitHub-flavored markdown, optimized for AI navigation.

Source code lives in source repos. Documentation, context, plans, and decisions live here.

When to Create One

You need a Brain when context is scattered across your head, notes apps, and stale docs. One repo. One truth. AI reads it, you read it, everything stays current because it’s version-controlled and trivial to update.

Structure

brain-repo/
  CLAUDE.md                # hub -- routing, structure, workspace index
  about-me.md              # owner profile -- background, focus, values
  ref/                     # document templates
    template-plan.md
    template-issue.md
    template-weekly.md
    template-note.md
    template-decision.md
    template-ref.md
    template-manifest.md
  weekly/                  # weekly planning files
    2026-W19.md            # YYYY-WNN format
  workspaces/              # per-domain context
    <workspace>/
      00-manifest.md       # workspace overview and project index
      CLAUDE.md            # workspace-specific agent context (optional)
      docs/                # cross-project reference knowledge
        00-manifest.md
        ref-*.md           # durable reference documents
        meetings/          # note-YYYY-MM-DD-*.md
        decisions/         # decision-YYYY-MM-DD-*.md (ADRs)
        _archive/
      plans/               # active project execution
        <project>/
          PLAN.md          # execution roadmap
          ISSUES.md        # checkbox issue list
          issues/          # numbered issue specs
            01-slug.md
          files/           # data, exports, research output
          scripts/         # project-specific scripts
      _archive/            # completed/abandoned projects
  scripts/                 # repo-level CLI tools
  .gitignore

A workspace is a domain — a company, a side project, a life area. It contains multiple projects and shared reference knowledge. Projects are execution-scoped: they start, produce issues, and eventually archive. Reference docs outlive projects.

Every Brain has exactly one root CLAUDE.md and one about-me.md. Every workspace has exactly one 00-manifest.md. Every project has exactly one PLAN.md and one ISSUES.md.

about-me.md

A profile of the Brain owner at the repo root. Gives agents immediate context about who they’re working with — background, current focus areas, values, and working style preferences. This lets agents tailor tone, depth, and suggestions without inferring from scattered workspace content.

Keep it factual and agent-useful. Not a bio page — a calibration document.

CLAUDE.md

The hub. An AI agent drops into this repo and reads CLAUDE.md first. It must answer four questions:

What is this repo?
What is the directory structure?
Where is each workspace and what does it contain?
What file should an agent read when a specific topic comes up?

Use the template in claude-md.md.

What Goes in CLAUDE.md vs This Skill

CLAUDE.md is always in the model’s working memory. This skill is loaded on demand and can be forgotten. That drives what goes where.

CLAUDE.md (always in context):

What this repo is (1 sentence)
Structure tree (compact — enough to orient, not more)
Context routing table (topic -> file -> when to read)
File placement rules (content type -> location)
Workspace index
Maintenance reminders (keep indexes current, record as you go)
Pointer to this skill for conventions

This skill (loaded on demand):

Document type specs (how to write a PLAN.md, issue, ADR, meeting note)
Naming conventions
Template specifications
Anti-patterns
Init path
Formatting rules

If it’s a hint about when to look, it goes in CLAUDE.md. If it’s a spec about how to write, it stays here.

Context Routing Table

Include a topic-to-file lookup so agents know where to find domain knowledge without searching:

| Topic | File | When to read |
|---|---|---|
| People | docs/ref-people.md | Any mention of a person by name |
| Infrastructure | docs/ref-tech-stack.md | Architecture or deployment work |

Only add entries where an agent would otherwise guess wrong. Self-explanatory file names don’t need routing entries.

File Placement Rules

Include a routing table for content types so agents create files in the right place:

| Content type | Location |
|---|---|
| Project scripts, tools | plans/{project}/scripts/ |
| Data, exports, research | plans/{project}/files/ |
| Issue specs | plans/{project}/issues/ |
| Meeting notes | docs/meetings/note-YYYY-MM-DD-*.md |
| Architecture decisions | docs/decisions/decision-YYYY-MM-DD-*.md |
| Durable reference | docs/ref-*.md |

Key distinction: meetings/ is for meetings with people. Research output and investigation notes go in the relevant project’s files/ directory or in a ref- doc.

Index Integrity

CLAUDE.md indexes every workspace. Within each workspace, 00-manifest.md indexes projects and docs. docs/00-manifest.md indexes reference documents. Every structural change requires an index update:

New workspace -> add to root CLAUDE.md
New project -> add to workspace 00-manifest.md
New doc -> add to docs/00-manifest.md
New issue -> add to ISSUES.md and PLAN.md issue index
Removed file -> remove from its parent index

No project-specific detail in root CLAUDE.md. It’s an index, not a notebook.

Workspace CLAUDE.md

Each workspace can have its own CLAUDE.md with environment-specific context: source code locations, cloud profiles, available tools, external service references. Root CLAUDE.md indexes workspaces; workspace CLAUDE.md provides operational detail for working within that workspace.

Not every workspace needs one. Create it when the workspace has source repos, cloud resources, or tool configurations that an agent needs.

Keep workspace CLAUDE.md focused on operational context. Don’t duplicate the root hub.

Weekly Files

The weekly file is where thinking happens in time. Plans, priorities, reflections — tied to a specific week. Stored permanently.

weekly/
  2026-W19.md
  2026-W20.md

Naming: weekly/YYYY-WNN.md — ISO year and week number, zero-padded. Flat directory, no year subdirectories.

Content

A weekly file is freeform. Common sections:

Goals for the week (top 1-3 outcomes)
Tasks by workspace
Ideas and notes that surfaced
Retro (what went well, what didn’t, what to adjust)

Link to workspace docs, plans, and issues freely. The weekly file ties project structure to how work actually happens.

Creation

Create the weekly file at the start of each week, or when you first need it. If a scripts/weekly helper exists, use it. Otherwise:

# create or open weekly/$(date +%Y)-W$(date +%V).md

Don’t pre-create future weeks. Don’t backfill missed weeks.

Workspaces

One directory per domain under workspaces/. The name is lowercase, one word when possible, hyphens when not.

00-manifest.md

The workspace overview and index. Opens with H1 title, one sentence stating what this workspace tracks.

# Workspace Name

## Purpose

One-sentence purpose.

## Contents

- **plans/project-a**: Description
- **plans/project-b**: Description
- **docs/ref-people.md**: Contacts directory
- **docs/ref-tech-stack.md**: Architecture reference

## Status

Active

Index all projects and significant docs. An unindexed file is invisible to AI agents.

docs/

Cross-project reference knowledge that outlives any single project. Organized by type prefix:

Prefix	Use	Example
`ref-`	Durable reference knowledge	`ref-tech-stack.md`, `ref-people.md`
`note-YYYY-MM-DD-`	Meeting notes	`note-2026-03-23-kickoff.md`
`decision-YYYY-MM-DD-`	Architecture decision records	`decision-2026-03-23-auth.md`

Standard subdirectories:

meetings/ — Notes from meetings with people. Always note-YYYY-MM-DD-topic.md. Not for research, investigation output, or general notes.
decisions/ — Architecture decision records. Always decision-YYYY-MM-DD-topic.md.

When a topic has 3+ related docs, create a topic subdirectory.

Index all docs in docs/00-manifest.md.

Reference Documents (ref-*.md). Durable knowledge about a subject. When you learn something during project work that will be useful beyond that project, capture it in the appropriate ref- doc. Examples: contacts directory, architecture overview, operational runbook, infrastructure inventory.

Ref docs grow over time. They’re living documents, not one-shot notes.

Meeting Notes. Live in docs/meetings/. Structure: Context (who, what prompted it), Content (discussion, decisions, takeaways), Actions (follow-up checkboxes).

Architecture Decision Records. Live in docs/decisions/. Structure: Context (what prompted the decision), Options Considered (with tradeoffs), Decision (what was chosen and why), Consequences (tradeoffs accepted).

Create an ADR when a choice will constrain future work or when someone will later ask “why did we do it this way?“

plans/

Active project execution. Each project gets its own subdirectory:

plans/<project>/
  PLAN.md        # execution roadmap, priorities, status
  ISSUES.md      # flat checkbox list linking to issue files
  issues/        # numbered issue specs
    01-slug.md
    02-slug.md
    03-slug/     # sub-dir when issue has artifacts
      03-slug.md
      migrate.sql
  files/         # data, exports, research output
  scripts/       # project-specific scripts

PLAN.md is the central driver:

Context — what, why, source repos involved
Execution Order — done and next sections with links to issues
Issue Index — table: | # | Issue | Effort | Status | Doc |
Key Decisions — rationale for significant choices, links to ADRs

ISSUES.md is a flat checkbox list:

- [x] [01 - First thing](issues/01-first-thing.md)
- [ ] [02 - Second thing](issues/02-second-thing.md)

Issue files are numbered sequentially: NN-slug.md.

Problem — what’s wrong or missing
Current State — what exists today
Plan — steps to resolve (checkboxes)
Dependencies — what this blocks or is blocked by
Status — Open | In Progress | Done

When an issue has associated artifacts, promote the file to a subdirectory: 03-slug/03-slug.md with artifacts alongside.

Effort estimates use t-shirt sizes: S, M, L. No time estimates.

When a project is complete or abandoned, move its directory to _archive/.

Entity Subdirectories

When a workspace has first-class objects that each need their own page, create a subdirectory in docs/ named for the entity type (plural).

workspaces/<workspace>/docs/
  companies/
    acme-corp.md
    initech.md

Use when an entity has enough context to warrant its own file. The manifest links into entity pages. Entity pages are short — identity, key facts, status.

_archive/

Every workspace and docs/ directory can have _archive/ for completed or inactive content. Move files here instead of deleting.

When archiving, remove the file from its parent index. Archived content is still searchable via rg but not navigable from indexes. The underscore prefix sorts it to the bottom and signals “not active.”

Don’t archive weekly files. They stay in weekly/ permanently.

Templates

A template library at the repo root ensures consistent structure. Store in ref/:

ref/
  template-plan.md
  template-issue.md
  template-issues.md
  template-weekly.md
  template-note.md
  template-decision.md
  template-ref.md
  template-manifest.md

When creating a new document of a known type, start from the template. Templates define the structural skeleton — headings and their order — not example content. Templates may include frontmatter with placeholder tags.

Information Retrieval

Two retrieval modes: navigation (follow links from CLAUDE.md) and search (grep across content).

CLAUDE.md -> workspace 00-manifest.md -> docs/ or plans/ -> specific file. Every piece of content is reachable in at most three hops from root. If an agent can’t find something by following links, it’s a structural failure.

Search

Use rg (ripgrep) as the primary search tool. Flat markdown means full-text search works without indexing.

rg "search term" workspaces/
rg "search term" --type md
rg -l "term"                              # list matching files
rg "tags:.*workspace"                      # by tag
rg "status: blocked"                       # by status
rg --glob '!**/_archive/**' "\[ \]"        # open items outside archives

Organization for Discoverability

Descriptive H1 titles. The first line of every file is its identity. Make it grep-friendly.
One topic per file. If a note covers two unrelated subjects, split it.
Consistent vocabulary. Pick one term for a concept. Don’t alternate synonyms.
Descriptive file names. market-research-2026-q2.md beats notes-3.md.
Link text matches titles. The link text should approximate the target’s H1.

Naming Conventions

Thing	Convention	Example
Workspace dirs	lowercase, hyphens	`publishing`, `home-lab`
Workspace overview	always `00-manifest.md`	`00-manifest.md`
Root hub	always `CLAUDE.md`	`CLAUDE.md`
Owner profile	always `about-me.md`	`about-me.md`
Workspace agent context	always `CLAUDE.md` (optional)	`workspace/CLAUDE.md`
Reference docs	`ref-` prefix	`ref-tech-stack.md`
Meeting notes	`note-YYYY-MM-DD-topic.md`	`note-2026-03-23-kickoff.md`
Decision records	`decision-YYYY-MM-DD-topic.md`	`decision-2026-03-23-auth.md`
Project plans	always `PLAN.md`	`PLAN.md`
Project issue list	always `ISSUES.md`	`ISSUES.md`
Issue files	`NN-slug.md`, sequential	`01-setup.md`, `02-deploy.md`
Weekly files	`YYYY-WNN.md`	`2026-W19.md`
Templates	`template-type.md` in `ref/`	`ref/template-plan.md`
Note files	lowercase, hyphens, optional date	`market-research-2026-q2.md`
Entity files	lowercase, hyphens, entity name	`acme-corp.md`

Formatting Rules

Plain GFM. No HTML. No custom syntax. No templating.
Relative links for all cross-references.
Tables for inventories and comparisons.
Checkbox lists for tasks (- [ ] / - [x]).
H1 for page title. H2 for major sections. H3 sparingly.

Frontmatter

Optional. When present, limited to tags and status:

---
tags: [workspace, topic]
status: active
---

Tags enable rg-based filtered search. Always include the workspace name. status is optional: active | done | blocked | archived.

Use frontmatter on docs/ files (ref-, note-, decision-), manifests, and weekly files. Skip it on issue files inside plans/ (numbering provides structure) and on CLAUDE.md files (structural, not content).

Don’t add dates, priorities, authors, or custom fields. If you need more than tags and status, the information belongs in the document body.

Init Path

mkdir brain && cd brain
git init
# write CLAUDE.md from template
# write about-me.md -- owner profile (background, focus, values)
mkdir -p ref
# copy templates into ref/
mkdir -p weekly
mkdir -p workspaces
# for each initial workspace:
mkdir -p workspaces/<workspace>/{docs,plans}
# write workspaces/<workspace>/00-manifest.md
# write workspaces/<workspace>/docs/00-manifest.md
echo ".env" > .gitignore
git add -A && git commit -m "init brain"

Start with 1-3 workspaces. Add more as needed. Don’t pre-create workspaces you won’t use this month.

Active Maintenance

A Brain is only useful if it stays current. Every conversation that touches Brain content is an opportunity to update it.

Auto-Record

When working in or adjacent to the Brain, record new information as it emerges:

A decision was made? Write it to a ref- doc or create an ADR.
A new project surfaces? Create the project directory (PLAN.md + ISSUES.md) and index it.
A task is identified? Add it to the relevant ISSUES.md or create an issue file.
A task is completed? Check it off. Update the PLAN.md status.
Context changes (new tools, new people, new constraints)? Update the relevant ref- doc.

Don’t wait to be asked. If information belongs in the Brain, put it there.

Detection

Watch for signals that the Brain needs updating:

New workspace needed: a topic keeps coming up that doesn’t fit existing workspaces.
New ref doc needed: knowledge keeps being rediscovered because it isn’t written down.
New project needed: work has enough issues to warrant its own PLAN.md.
Stale content: information contradicts what’s in a doc. Update or remove it.

Anti-Patterns

Code in the Brain. Source repos hold code. The Brain holds context, plans, decisions.
Deep nesting. Three levels max from workspace root. If you need a fourth level, restructure.
Stale CLAUDE.md. If you add a workspace and don’t update CLAUDE.md, agents can’t find it.
Orphan files. Every file must be linked from its parent index. Unlinked files are invisible.
Giant manifests. If a manifest exceeds ~80 lines, extract content into docs or notes.
Frontmatter bloat. Tags and status only. No dates, priorities, authors, or custom fields.
Meetings as catch-all. docs/meetings/ is for meetings with people. Research output goes in project files/ or ref- docs.
Plans as permanent docs. Projects in plans/ are execution-scoped. Knowledge that outlives the project belongs in a ref- doc.
Unnumbered issues. Issue files use sequential numbering: 01-slug.md. No date-prefixed or descriptive-only names for issues.

Second Brain

Getting started

Second Brain

When to Create One

Structure

about-me.md

CLAUDE.md

What Goes in CLAUDE.md vs This Skill

Context Routing Table

File Placement Rules

Index Integrity

Workspace CLAUDE.md

Weekly Files

Content

Creation

Workspaces

00-manifest.md

docs/

plans/

Entity Subdirectories

_archive/

Templates

Information Retrieval

Navigation Path

Search

Organization for Discoverability

Naming Conventions

Formatting Rules

Frontmatter

Init Path

Active Maintenance

Auto-Record

Detection

Anti-Patterns