Knowledge base scaffolding with microdatabases, VitePress portal, configurable entities (ADRs, Notes, Tasks, Discussions), freshness tracking, review stamps, meeting transcription, and background refinement

version
1.1.0
GitHub stars
16

Install

/plugin install secondbrain@bershadsky-claude-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sergio-bershadsky/ai.

Contents

Discovered from source

Skills 11

Create Architecture Decision Record

Create numbered ADRs with category-based organization and status workflow.

Prerequisites

Verify ADR entity is enabled in the secondbrain project:

  1. Check for .claude/data/adrs/meta.yaml (sharded) or .claude/data/adrs/records.yaml (legacy)
  2. If not found, suggest running secondbrain-init with ADRs enabled

Important Rules

  • Do NOT add ADRs to the left sidebar/navigation. ADRs are listed automatically via the EntityTable component on docs/adrs/index.md, which reads from .claude/data/adrs/ shard files. No sidebar modification is needed.

Workflow

Step 1: Gather Information

Collect from user or conversation context:

  1. Category (determines number range):

    • infrastructure (0001-0999) — Architecture & infrastructure
    • feature (2000-2999) — Feature implementation
    • process (3000-3999) — Process & workflow
  2. Title — Brief decision title (will be slugified for filename)

  3. Context — What problem prompted this decision?

Step 2: Determine ADR Number

  1. Load .claude/data/adrs/meta.yaml (read last_number — tiny file, ~50 tokens)
  2. Find highest number in selected category range
  3. Increment to get next number
  4. Format: ADR-XXXX (zero-padded)

Number Ranges:

infrastructure: 0001 - 0999
feature:        2000 - 2999
process:        3000 - 3999

Step 3: Generate ADR Document

Use template from ${CLAUDE_PLUGIN_ROOT}/templates/entities/adr/TEMPLATE.md:

Filename: docs/adrs/ADR-XXXX-<title-slug>.md

Frontmatter:

---
id: ADR-XXXX
status: draft
date_created: YYYY-MM-DD
date_updated: YYYY-MM-DD
author: <author>
category: <category>
---

Step 4: Update Records

Add entry to the current month's shard .claude/data/adrs/YYYY-MM.yaml:

- number: XXXX
  title: "<title>"
  status: draft
  category: <category>
  created: YYYY-MM-DD
  file: docs/adrs/ADR-XXXX-<slug>.md
  author: <author>

Update last_number in .claude/data/adrs/meta.yaml and ensure the current month is in the shards list.

Step 5: Sidebar Note

DO NOT manually add ADRs to VitePress sidebar.

ADRs are automatically listed via the EntityTable component on docs/adrs/index.md, which reads from .claude/data/adrs/ shard files. No sidebar modification needed.

Step 6: Confirm Creation

## ADR Created

**ID:** ADR-0012
**Title:** Kubernetes Migration Strategy
**Category:** infrastructure
**Status:** draft
**File:** docs/adrs/ADR-0012-kubernetes-migration-strategy.md

### Next Steps
1. Edit the ADR to add context, options, and decision
2. Change status to 'proposed' when ready for review
3. Use /secondbrain-adr-status to update status

### Status Workflow
draft → proposed → admitted → applied → implemented → tested

Status Workflow

Draft → Proposed → Admitted → Applied → Implemented → Tested
                          ↘ Rejected
                          ↘ Canceled
StatusDescription
draftInitial creation, under development
proposedReady for review
admittedApproved, pending implementation
appliedImplementation started
implementedImplementation complete
testedVerified in production
rejectedNot approved
canceledAbandoned

Additional Resources

  • references/adr-template.md — Full ADR template

Document Discussion

Capture team discussions with participants, decisions, and action items.

Prerequisites

Verify Discussions entity is enabled:

  1. Check for .claude/data/discussions/schema.yaml
  2. If not found, suggest enabling discussions via secondbrain-init

Important Rules

  • Do NOT add discussions to the left sidebar/navigation. Discussions are listed automatically via the EntityTable component on docs/discussions/index.md, which reads from monthly .claude/data/discussions/YYYY-MM.yaml files. No sidebar modification is needed.

Workflow

Step 1: Gather Information

Collect from user or conversation context:

  1. Participant(s) — Who was in the discussion
  2. Topic — Main subject discussed
  3. Source — manual, meeting, slack
  4. Key Points — Discussion content
  5. Decisions — What was decided
  6. Action Items — Follow-up tasks

Step 2: Generate Discussion File

Filename format: docs/discussions/YYYY-MM-DD-<participant>-<topic-slug>.md

Example: docs/discussions/2026-01-15-sergey-kubernetes-migration.md

Step 3: Create Discussion Document

---
date: 2026-01-15
participants:
  - Sergey Bershadsky
  - Kate Angelopoulos
topic: Kubernetes Migration Planning
status: documented
source: meeting
tags: [kubernetes, infrastructure, planning]
---

# Kubernetes Migration Planning

**Date:** 2026-01-15
**Participants:** Sergey Bershadsky, Kate Angelopoulos

## Context

Why did this discussion happen?

## Discussion Points

### Migration Timeline

**Discussion:**
- Discussed phased approach
- Agreed on staging first

**Outcome:**
Start with staging environment by end of Q1

### Resource Requirements

**Discussion:**
- Node sizing
- Cost implications

**Outcome:**
Will use 3 node cluster initially

## Decisions Made

| Decision | Owner | Deadline |
|----------|-------|----------|
| Set up staging cluster | Sergey | 2026-01-31 |
| Document runbook | Kate | 2026-02-15 |

## Action Items

- [ ] Create staging environment — @sergey
- [ ] Write migration runbook — @kate
- [ ] Schedule follow-up review — @sergey

## Open Questions

- What's the rollback strategy?
- How do we handle stateful services?

## Follow-up

- Next discussion scheduled for: 2026-01-22
- Related topics to explore: CI/CD pipeline changes

Step 4: Update Records

Add to monthly file .claude/data/discussions/YYYY-MM.yaml:

- date: 2026-01-15
  member: sergey
  topic: Kubernetes Migration Planning
  file: docs/discussions/2026-01-15-sergey-kubernetes-migration.md
  source: meeting
  participants:
    - Sergey Bershadsky
    - Kate Angelopoulos

Step 5: Sidebar Note

DO NOT manually add discussions to VitePress sidebar.

Discussions are automatically listed via the EntityTable component on docs/discussions/index.md, which reads from monthly .claude/data/discussions/YYYY-MM.yaml files. No sidebar modification needed.

Step 6: Confirm Creation

## Discussion Documented

**Date:** 2026-01-15
**Topic:** Kubernetes Migration Planning
**Participants:** Sergey Bershadsky, Kate Angelopoulos
**Source:** meeting
**File:** docs/discussions/2026-01-15-sergey-kubernetes-migration.md

### Summary
- 2 decisions recorded
- 3 action items created
- 2 open questions noted

### Next Steps
- Follow up on action items
- Address open questions in next discussion

Monthly Partitioning

Discussions are partitioned by month:

  • discussions/2025-12.yaml — December 2025
  • discussions/2026-01.yaml — January 2026

Past months become immutable, preserving history.

Sources

SourceDescription
manualHand-documented discussion
meetingFrom a scheduled meeting
slackFrom Slack conversation

Tips

  1. Capture decisions explicitly — Use the table format
  2. Create action items — Every decision should have an owner
  3. Note open questions — Track what needs follow-up
  4. Link to related content — Reference ADRs, notes, etc.
  5. Document context — Future readers need to understand "why"

Add Custom Entity

Create custom entity types with schema validation and VitePress integration.

Prerequisites

Verify secondbrain is initialized:

  1. Check for .claude/data/config.yaml
  2. If not found, suggest running secondbrain-init first

Workflow

Step 1: Gather Entity Information

Collect from user:

  1. Entity Name — Plural name (e.g., "contacts", "projects", "bookmarks")
  2. Singular Name — For display (e.g., "contact", "project", "bookmark")
  3. Fields — Custom fields for the entity:
    • Field name (snake_case)
    • Field type (string, integer, boolean, date, array, enum)
    • Required or optional
    • For enums: allowed values
  4. ID Format — How records are numbered/identified:
    • Sequential (PREFIX-XXXX)
    • Date-based (YYYY-MM-DD-slug)
    • UUID
  5. Status Workflow (optional) — If entity has status tracking

Step 2: Generate Schema

Create .claude/data/<entity>/schema.yaml:

type: object
required: [records]
properties:
  last_number:
    type: integer
    description: Last assigned sequential number
  records:
    type: array
    items:
      type: object
      required: [id, title, created, file]
      properties:
        id:
          type: string
          description: Unique identifier
        title:
          type: string
          description: Display title
        created:
          type: string
          format: date
        file:
          type: string
          description: Path to markdown file
        status:
          type: string
          enum: [active, archived]
        # ... custom fields

Step 3: Initialize Records File

Create .claude/data/<entity>/records.yaml:

last_number: 0
records: []

Step 4: Create Document Template

Create templates/entities/<entity>/TEMPLATE.md:

---
id: {{id}}
title: {{title}}
created: {{date}}
status: active
# ... custom fields
---

# {{title}}

## Overview

[Description]

## Details

[Content]

Step 5: Create VitePress Data Loader

Create docs/.vitepress/data/<entity>.data.ts:

import { defineLoader } from 'vitepress'
import fs from 'fs'
import yaml from 'js-yaml'

interface Record {
  id: string
  title: string
  created: string
  file: string
  status: string
  // ... custom fields
}

export interface Data {
  records: Record[]
  lastNumber: number
}

declare const data: Data
export { data }

export default defineLoader({
  watch: ['.claude/data/<entity>/*.yaml'],
  async load(): Promise<Data> {
    const recordsPath = '.claude/data/<entity>/records.yaml'

    if (!fs.existsSync(recordsPath)) {
      return { records: [], lastNumber: 0 }
    }

    const content = fs.readFileSync(recordsPath, 'utf-8')
    const parsed = yaml.load(content) as any

    return {
      records: parsed.records || [],
      lastNumber: parsed.last_number || 0
    }
  }
})

Step 6: Create Documentation Index

Create docs/<entity>/index.md:

---
title: <Entity> Index
---

# <Entity>

<script setup>
import { data } from '../.vitepress/data/<entity>.data'
import EntityTable from '../.vitepress/theme/components/EntityTable.vue'

const columns = [
  { key: 'id', label: 'ID', sortable: true },
  { key: 'title', label: 'Title', sortable: true },
  { key: 'created', label: 'Created', sortable: true },
  { key: 'status', label: 'Status', sortable: true }
]
</script>

<EntityTable :data="data.records" :columns="columns" />

Step 7: Update Configuration

Add entity to .claude/data/config.yaml:

entities:
  <entity>:
    enabled: true
    singular: <singular>
    id_format: sequential  # or date-based, uuid
    prefix: PREFIX         # for sequential IDs
    freshness:
      stale_after_days: 30
    fields:
      - name: field_name
        type: string
        required: true

Step 8: Update Sidebar

Add to docs/.vitepress/config.ts sidebar:

{
  text: '<Entity>',
  collapsed: true,
  items: [
    { text: 'Overview', link: '/<entity>/' }
  ]
}

Step 9: Confirm Creation

## Entity Created

**Name:** <entity>
**Singular:** <singular>
**ID Format:** sequential (PREFIX-XXXX)
**Status Tracking:** Yes

### Fields
| Field | Type | Required |
|-------|------|----------|
| title | string | Yes |
| description | string | No |
| priority | enum (low, medium, high) | No |

### Files Created
- `.claude/data/<entity>/schema.yaml`
- `.claude/data/<entity>/records.yaml`
- `docs/.vitepress/data/<entity>.data.ts`
- `docs/<entity>/index.md`

### Next Steps
1. Create records using the new entity type
2. Add entity-specific skills if needed
3. Customize the index page layout

Field Types

TypeYAML SchemaExample
stringtype: string"Hello world"
integertype: integer42
numbertype: number3.14
booleantype: booleantrue/false
datetype: string, format: date2026-01-15
datetimetype: string, format: date-time2026-01-15T10:30:00Z
arraytype: array, items: {...}[tag1, tag2]
enumtype: string, enum: [...]"active"

ID Formats

Sequential

Best for: Tasks, tickets, numbered records

PREFIX-0001, PREFIX-0002, PREFIX-0003

Date-based

Best for: Notes, journal entries, time-sensitive content

2026-01-15-meeting-notes
2026-01-15-architecture-review

UUID

Best for: Globally unique, import/export scenarios

550e8400-e29b-41d4-a716-446655440000

Tips

  1. Keep fields minimal — Start with essential fields, add more later
  2. Use enums for fixed values — Better than free-form strings
  3. Consider status workflow — Most entities benefit from status tracking
  4. Plan ID format carefully — Hard to change after records exist
  5. Reuse existing patterns — Look at ADR, Task, Note for inspiration

Freshness Report

Generate a comprehensive freshness report for all secondbrain entities.

Prerequisites

Verify secondbrain is initialized:

  1. Check for .claude/data/config.yaml
  2. If not found, indicate no secondbrain project found

Workflow

Step 1: Load Configuration

Read .claude/data/config.yaml to get:

  • All enabled entities
  • Freshness thresholds per entity
  • Monthly partitioning settings

Step 2: Analyze Each Entity

For each enabled entity:

  1. Load all records
  2. Check date fields (created, date, date_updated)
  3. Compare against freshness threshold
  4. Categorize by staleness level:
    • Critical (2x threshold): Needs immediate attention
    • Stale (1x threshold): Should be reviewed
    • Warning (0.75x threshold): Approaching staleness

Step 3: Generate Report

Format by entity and urgency:

## Freshness Report

Generated: 2026-01-15 10:30

### Summary

| Entity | Critical | Stale | Warning | OK |
|--------|----------|-------|---------|-----|
| ADRs | 2 | 5 | 3 | 12 |
| Tasks | 0 | 8 | 4 | 15 |
| Notes | 1 | 3 | 6 | 25 |
| Discussions | 0 | 2 | 1 | 10 |

**Total needing attention:** 30 items

---

### Critical (Needs Immediate Attention)

#### ADRs (2 items)

| ID | Title | Status | Age |
|----|-------|--------|-----|
| ADR-0003 | API Gateway Selection | proposed | 95 days |
| ADR-0007 | Database Migration | draft | 78 days |

#### Notes (1 item)

| ID | Title | Age |
|----|-------|-----|
| 2025-10-01-legacy-system | Legacy System Overview | 106 days |

---

### Stale (Should Review)

#### Tasks (8 items)

| ID | Title | Status | Priority | Age |
|----|-------|--------|----------|-----|
| TASK-0012 | Update documentation | in_progress | medium | 45 days |
| TASK-0015 | Fix login bug | todo | high | 42 days |
...

---

### Recommended Actions

1. **ADR-0003:** 95 days in "proposed" status
   - Action: Review and move to admitted/rejected

2. **ADR-0007:** 78 days in "draft" status
   - Action: Complete draft or cancel

3. **TASK-0012:** 45 days in progress
   - Action: Check if blocked, update status

4. **2025-10-01-legacy-system:** 106 days old note
   - Action: Archive or update content

Step 4: Offer Remediation

For each critical/stale item, offer specific actions:

  • Draft ADRs: Complete or cancel
  • Proposed ADRs: Review and decide
  • In-progress tasks: Check if blocked
  • Old notes: Archive or refresh
  • Stale discussions: Mark resolved or schedule follow-up

Step 5: Update Last Check

Update .claude/data/config.yaml:

meta:
  last_freshness_check: 2026-01-15T10:30:00

Staleness Thresholds

Default thresholds (configurable per entity):

EntityDefaultCritical
ADRs30 days60 days
Tasks14 days28 days
Notes30 days60 days
Discussions7 days14 days

Status Exceptions

Skip items with terminal statuses:

  • ADRs: implemented, tested, rejected, canceled
  • Tasks: done, completed, canceled
  • Notes: archived
  • Discussions: archived

Output Formats

Summary Only

## Freshness Summary

- **Critical:** 3 items need immediate attention
- **Stale:** 18 items should be reviewed
- **Warning:** 13 items approaching staleness

Run with `--detailed` for full breakdown.

Full Report

Complete breakdown with tables and recommendations (default).

JSON Export

{
  "generated": "2026-01-15T10:30:00",
  "summary": {
    "critical": 3,
    "stale": 18,
    "warning": 13,
    "ok": 62
  },
  "by_entity": {
    "adrs": { "critical": 2, "stale": 5, ... },
    ...
  },
  "items": [...]
}

Tips

  1. Run weekly — Set calendar reminder for freshness reviews
  2. Address critical first — Focus on oldest items
  3. Archive liberally — Better to archive than ignore
  4. Update thresholds — Adjust based on your workflow pace
  5. Check after sprints — Good time to clean up stale items

Secondbrain Project Scaffolding

Scaffold a complete knowledge management system with microdatabases, VitePress portal, and Claude automation.

Overview

Initialize a new secondbrain project with:

  • Microdatabase architecture (YAML + JSON Schema validation)
  • VitePress documentation portal (custom theme, Vue components)
  • Configurable entity types (ADRs, Discussions, Notes, Tasks, Custom)
  • Claude automation (hooks, maximum freedom settings)

Workflow

Step 1: Gather Project Information

Ask the user for:

  1. Project name (kebab-case, e.g., my-knowledge-base)
  2. Target directory (default: ./<project-name>)
  3. Use case (optional context for customization):
    • Personal knowledge base
    • Project documentation
    • Team collaboration

Step 2: Select Entity Types

Present entity selection with checkboxes:

## Entity Selection

Which entities would you like to enable?

[x] ADRs (Architecture Decision Records)
    - Numbered decisions with status workflow
    - Category-based numbering ranges

[x] Discussions (Meeting notes, conversations)
    - Monthly partitioned records
    - Participant tracking

[x] Notes (General knowledge capture)
    - Date-based IDs
    - Tag support

[ ] Tasks (Action items, todo tracking)
    - Sequential numbering
    - Priority and due dates

Would you like to define a custom entity type? (y/n)

Step 3: Configure Optional Features

Present optional feature selection:

## Optional Features

[ ] Review Stamps
    - Track who reviewed which pages and when
    - ReviewBadge component with staleness coloring (green/yellow/orange)
    - Adds /secondbrain-review command

[ ] Meeting Transcription
    - Import meetings from transcription providers (Fireflies.ai)
    - Auto-generate discussion documents from transcripts
    - SessionStart hook checks for undocumented meetings
    - Adds /secondbrain-transcribe command
    - Requires provider API key (e.g., FIREFLIES_API_KEY)

If Review Stamps selected:

  • Ask for default reviewer name (can be left blank for per-review prompting)
  • Add review section to config.yaml
  • Scaffold ReviewBadge.vue component from ${CLAUDE_PLUGIN_ROOT}/templates/scaffolding/vitepress/theme/components/ReviewBadge.vue.tmpl
  • Replace {{fresh_days}} with 30 and {{aging_days}} with 90 (or custom values)

If Meeting Transcription selected:

  • Ask which provider: fireflies (more providers coming)
  • Ask for team member mappings (alias, full name, email patterns)
  • Add team and integrations.transcription sections to config.yaml
  • Scaffold provider client (e.g., fireflies.py) from ${CLAUDE_PLUGIN_ROOT}/templates/scaffolding/lib/fireflies.py.tmpl
  • Remind user to set API key in .env.local or environment

Step 4: Configure Semantic Search

Present search configuration options:

## Search Configuration

Which semantic search would you like to enable?

[ ] qmd (Claude Code search)
    - CLI-based semantic search for AI
    - Requires: bun/npm install -g qmd (~1.5GB models)
    - Best for: Local development, Claude Code integration

[ ] Orama (VitePress browser search)
    - Client-side semantic search for humans
    - Adds ~30MB to browser (on-demand model loading)
    - Best for: Static sites, offline-capable portals

[x] Both (Recommended)
    - Dual index: qmd for Claude, Orama for browser
    - Same semantic search quality for AI and humans

[ ] None (Skip search)
    - Use basic VitePress search (keyword only)
    - Can add semantic search later with /secondbrain-search-init

Based on selection:

SelectionActions
qmdCreate .claude/search/, generate qmd.config.json, add search hook
OramaAdd Orama deps to package.json, generate SearchBox.vue, generate build script
BothAll of the above
NoneSkip search setup, use VitePress native search

Step 6: Configure Maximum Freedom Settings

CRITICAL: Always propose creating .claude/settings.local.json with maximum permissions:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "_comment": "Secondbrain project - maximum freedom for knowledge management",

  "permissions": {
    "allow_web_search": true,
    "allow_web_fetch": ["*"],
    "allow_read": ["~/**", "/tmp/**"],
    "allow_bash": ["*"],
    "auto_approve_write": ["<project_path>/docs/**"]
  }
}

Show the settings and ask for confirmation before proceeding.

Step 7: Generate Scaffolding

Create the following structure:

<project-name>/
├── .claude/
│   ├── settings.local.json     # Max freedom permissions + hooks
│   ├── data/
│   │   ├── config.yaml         # Project configuration
│   │   ├── adrs/               # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   ├── meta.yaml       # last_number + shard list
│   │   │   └── YYYY-MM.yaml    # Monthly shard
│   │   ├── discussions/        # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   └── YYYY-MM.yaml    # Monthly shard
│   │   ├── notes/              # (if enabled)
│   │   │   ├── schema.yaml
│   │   │   ├── meta.yaml       # shard list
│   │   │   └── YYYY-MM.yaml    # Monthly shard
│   │   └── tasks/              # (if enabled)
│   │       ├── schema.yaml
│   │       ├── meta.yaml       # last_number + shard list
│   │       └── YYYY-MM.yaml    # Monthly shard
│   ├── lib/
│   │   └── tracking.py         # CRUD library with validation
│   ├── hooks/
│   │   ├── freshness-check.py
│   │   ├── sidebar-check.py
│   │   ├── session-context.py
│   │   └── search-index-update.py  # (if qmd enabled)
│   └── search/                     # (if qmd enabled)
│       └── (qmd index files)
├── docs/
│   ├── .vitepress/
│   │   ├── config.ts           # Navigation, sidebar, plugins
│   │   ├── theme/
│   │   │   ├── index.ts
│   │   │   ├── Layout.vue      # Giscus comments
│   │   │   ├── custom.css
│   │   │   └── components/
│   │   │       ├── EntityTable.vue
│   │   │       ├── ReviewBadge.vue  # (if review stamps enabled)
│   │   │       └── SearchBox.vue   # (if Orama enabled)
│   │   └── data/
│   │       └── <entity>.data.ts # Per enabled entity
│   ├── index.md                # Home page
│   ├── adrs/                   # (if enabled)
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── discussions/            # (if enabled)
│   │   ├── index.md
│   │   └── TEMPLATE.md
│   ├── notes/                  # (if enabled)
│   │   └── index.md
│   └── tasks/                  # (if enabled)
│       └── index.md
├── package.json                # VitePress dependencies
├── qmd.config.json             # (if qmd enabled)
├── CLAUDE.md                   # Project instructions
└── .gitignore

Step 8: Generate Files

For each enabled entity, generate from templates in ${CLAUDE_PLUGIN_ROOT}/templates/:

  1. Microdatabase files:

    • config.yaml from scaffolding/microdatabase/config.yaml.tmpl
    • Entity schema.yaml from entities/<entity>/schema.yaml
    • Entity records.yaml initialized empty
  2. VitePress files:

    • config.ts from scaffolding/vitepress/config.ts.tmpl
    • Theme files from scaffolding/vitepress/theme/
    • Data loaders from scaffolding/vitepress/data/
  3. Documentation:

    • Home page from scaffolding/docs/index.md.tmpl
    • Entity index pages from scaffolding/docs/entity-index.md.tmpl
    • Templates from entities/<entity>/TEMPLATE.md
  4. Automation:

    • settings.local.json from scaffolding/claude/settings.local.json.tmpl
    • tracking.py from scaffolding/lib/tracking.py.tmpl
    • Hooks from hooks/ (copy to project)
  5. Search (if enabled):

    • qmd: qmd.config.json from scaffolding/search/qmd.config.json.tmpl
    • qmd: Copy search-index-update.py hook
    • Orama: SearchBox.vue from scaffolding/vitepress/theme/components/SearchBox.vue.tmpl
    • Orama: build-search-index.ts from scaffolding/vitepress/search/build-search-index.ts.tmpl
    • Orama: Add dependencies to package.json
  6. Review Stamps (if enabled):

    • ReviewBadge.vue from scaffolding/vitepress/theme/components/ReviewBadge.vue.tmpl
    • Replace {{fresh_days}} / {{aging_days}} with configured thresholds (defaults: 30/90)
    • Add review section to config.yaml
  7. Meeting Transcription (if enabled):

    • Provider client (e.g., fireflies.py) from scaffolding/lib/fireflies.py.tmpl
    • Add team and integrations.transcription sections to config.yaml

Step 9: Show Summary

## Secondbrain Created Successfully!

**Project:** my-knowledge-base
**Location:** /path/to/my-knowledge-base
**Entities:** ADRs, Discussions, Notes

### Structure Created

.claude/
├── settings.local.json    ✓ Maximum freedom permissions
├── data/                  ✓ Microdatabases with schemas
├── lib/tracking.py        ✓ CRUD operations
└── hooks/                 ✓ Automation hooks

docs/
├── .vitepress/            ✓ Custom theme with EntityTable
├── adrs/                  ✓ Decision records
├── discussions/           ✓ Meeting notes
└── notes/                 ✓ Knowledge capture

### Next Steps

1. Navigate to project:
   cd my-knowledge-base

2. Install dependencies:
   npm install

3. Start development server:
   npm run docs:dev

4. Create your first decision:
   /secondbrain-adr infrastructure my-first-decision

5. Add a note:
   /secondbrain-note my-first-note

### Available Commands

- /secondbrain-search <query>          — Semantic search (if enabled)
- /secondbrain-adr <category> <title>  — Create ADR
- /secondbrain-note <title>            — Create note
- /secondbrain-discussion <who> <topic> — Document discussion
- /secondbrain-freshness               — Check what needs attention
- /secondbrain-entity <name>           — Add custom entity type
- /secondbrain-review <page> [name]    — Stamp page as reviewed (if enabled)
- /secondbrain-transcribe <id|list|all> — Import meeting transcripts (if enabled)
- /secondbrain-search-init             — Enable semantic search later

Template Variables

When generating files, replace these variables:

VariableDescription
{{project_name}}Project name (kebab-case)
{{project_path}}Absolute path to project
{{description}}Project description
{{date}}Current date (YYYY-MM-DD)
{{timestamp}}Current ISO timestamp
{{year_month}}Current year-month (YYYY-MM)
{{entities}}Array of enabled entity configs

Entity Configuration

Each entity has standard configuration:

<entity_slug>:
  enabled: true
  label: "Entity Label"
  singular: "Entity"
  doc_path: docs/<entity_slug>
  freshness:
    stale_after_days: 30

Additional Resources

Reference Files

For detailed entity schemas and templates:

  • references/entity-schemas.md — Predefined entity schema definitions

Related Skills

  • secondbrain-search — Semantic search your knowledge base
  • secondbrain-search-init — Enable search on existing project
  • secondbrain-entity — Add custom entity types
  • secondbrain-adr — Create Architecture Decision Records
  • secondbrain-note — Create notes
  • secondbrain-task — Create tasks
  • secondbrain-discussion — Document discussions
  • secondbrain-freshness — Freshness report
  • secondbrain-review — Stamp pages as reviewed
  • secondbrain-transcribe — Import meeting transcripts

Create Note

Capture knowledge, ideas, and thoughts with tagging support.

Prerequisites

Verify Notes entity is enabled:

  1. Check for .claude/data/notes/meta.yaml (sharded) or .claude/data/notes/records.yaml (legacy)
  2. If not found, suggest enabling notes via secondbrain-init or secondbrain-entity

Workflow

Step 1: Gather Information

Collect from user or conversation context:

  1. Title — Brief, descriptive title
  2. Content — Main content (can be from conversation)
  3. Tags (optional) — Categorization tags

Step 2: Generate Note ID

Date-based ID format: YYYY-MM-DD-<title-slug>

Example: 2026-01-15-kubernetes-deployment-patterns

Step 3: Create Note Document

Filename: docs/notes/YYYY-MM-DD-<slug>.md

Frontmatter:

---
id: 2026-01-15-my-note
title: My Note Title
created: 2026-01-15
tags: [tag1, tag2]
status: active
---

Content:

# My Note Title

## Summary

Brief overview...

## Content

Main content here...

## References

- Links to related resources

## Related

- Links to related notes, ADRs, etc.

Step 4: Update Records

Add entry to the current month's shard .claude/data/notes/YYYY-MM.yaml:

- id: "2026-01-15-my-note"
  title: "My Note Title"
  created: 2026-01-15
  file: docs/notes/2026-01-15-my-note.md
  tags: [tag1, tag2]
  status: active

Ensure the current month is registered in .claude/data/notes/meta.yaml shards list.

Step 5: Sidebar Note

DO NOT manually add notes to VitePress sidebar.

Notes are automatically listed via the EntityTable component on docs/notes/index.md, which reads from .claude/data/notes/ shard files. No sidebar modification needed.

Step 6: Confirm Creation

## Note Created

**ID:** 2026-01-15-kubernetes-deployment-patterns
**Title:** Kubernetes Deployment Patterns
**Tags:** kubernetes, deployment, devops
**File:** docs/notes/2026-01-15-kubernetes-deployment-patterns.md

The note has been created and is ready for editing.

Tags

Tags help organize notes for discovery. Common patterns:

CategoryExample Tags
Technologykubernetes, react, python
Domainarchitecture, security, performance
Typehowto, reference, research
Projectproject-x, migration, refactor

Status Values

  • active — Current, relevant note
  • archived — No longer current but preserved

Additional Resources

  • references/note-formats.md — Detailed note templates and formatting patterns

Tips

  1. Be specific — Titles should indicate content at a glance
  2. Add context — Include why this is important, not just what
  3. Link liberally — Connect to related notes and external resources
  4. Tag consistently — Use established tags when possible
  5. Review periodically — Archive notes that are no longer relevant

Review Stamp Skill

Mark a documentation page as reviewed by appending a {date, name} entry to the reviewed_by list in frontmatter. Multiple reviewers accumulate over time.

Usage

/secondbrain-review <page-path> [reviewer]
  • page-path — path to the markdown file (e.g., docs/guides/setup.md)
  • reviewer — optional full name; defaults to review.default_reviewer from .claude/data/config.yaml, or prompts user if not configured

Prerequisites

Verify the project has a .claude/data/config.yaml with a review section:

review:
  default_reviewer: "Jane Smith"
  thresholds:
    fresh_days: 30
    aging_days: 90

If the review section is missing, ask the user if they want to add it and configure a default reviewer name.

Frontmatter Format

---
reviewed_by:
  - date: 2026-02-13
    name: Jane Smith
  - date: 2026-02-14
    name: John Doe
---

Each review is an entry with date (YYYY-MM-DD) and name (full name). The list grows over time — never remove previous entries.

Procedure

Step 1: Parse Arguments

Extract the page path from the first argument. If a second argument is provided, use it as the reviewer name. Otherwise:

  1. Read review.default_reviewer from .claude/data/config.yaml
  2. If that is null or missing, check the team section in config for a single member to use
  3. If still unresolved, ask the user for the reviewer name

Step 2: Read the File

Read the target file. Verify it exists and is a markdown file under the docs/ directory.

Step 3: Update Frontmatter

If the file has reviewed_by as a list — append a new entry with today's date and the reviewer name. Do not add a duplicate if the same person already reviewed on the same date.

If the file has legacy format (reviewed_by: "Name" + last_reviewed: date) — convert to the list format, preserving the existing review as the first entry, then append the new one. Remove the last_reviewed field.

If the file has no reviewed_by — add a reviewed_by list to frontmatter containing one entry. If there is no frontmatter at all, add a frontmatter block.

Step 4: Show Diff and Confirm

Show the user the exact changes that will be made (old vs new frontmatter). Wait for explicit user approval before writing.

Step 5: Write the File

Apply the frontmatter changes using the Edit tool.

Step 6: Confirm Completion

Show a summary:

Reviewed: docs/guides/setup.md
Reviewer: Jane Smith
Date: 2026-03-30
Total reviews: 3

Examples

/secondbrain-review docs/guides/setup.md
# Appends: - date: 2026-03-30
#            name: Jane Smith (from config default)

/secondbrain-review docs/architecture/overview.md "John Doe"
# Appends: - date: 2026-03-30
#            name: John Doe

Adding a second review to an already-reviewed page:

# Before:
reviewed_by:
  - date: 2026-01-15
    name: Jane Smith

# After /secondbrain-review page.md "John Doe":
reviewed_by:
  - date: 2026-01-15
    name: Jane Smith
  - date: 2026-03-30
    name: John Doe

Mandatory Rules

  • Always use full names in review entries — never use aliases or first names only. If a team section exists in config, resolve aliases to full names.
  • Never remove existing entries — the review list is append-only.
  • No duplicate same-day reviews — if the same person already has an entry for today's date, skip adding.

Notes

  • The ReviewBadge component in the VitePress theme automatically renders review status from the reviewed_by list
  • Staleness thresholds are configurable in config.yaml under review.thresholds:
    • fresh: 0 to fresh_days (default 30) — green
    • aging: fresh_days to aging_days (default 90) — yellow
    • stale: beyond aging_days — orange
  • Badge shows reviewer count when multiple reviews exist (e.g., "Reviewed Mar 30, 2026 by John Doe (3 reviews)")
  • Legacy format (reviewed_by: string + last_reviewed) is supported for backwards compatibility
  • Review stamps are orthogonal to the freshness system — they track human review quality, while /secondbrain-freshness tracks entity record currency

Initialize Semantic Search

Set up qmd semantic search for an existing secondbrain project.

Prerequisites

  1. Secondbrain project exists: Check for .claude/data/config.yaml
  2. qmd installed: Check with which qmd

Workflow

Step 1: Validate Environment

# Check secondbrain exists
ls .claude/data/config.yaml

# Check qmd installation
which qmd

If secondbrain not found:

No secondbrain project found in current directory.
Run `/secondbrain-init` to create a new project first.

If qmd not installed:

## qmd Not Installed

qmd is required for semantic search. Install it:

### Using Bun (Recommended)
bun install -g qmd

### Using npm
npm install -g qmd

After installation, run this skill again.

**Note:** First run will download ~1.5GB of embedding models.

Step 2: Check Existing Search

ls .claude/search/ 2>/dev/null

If search already initialized:

## Search Already Initialized

Search is already configured for this project.

**Index location:** .claude/search/
**Last indexed:** 2026-01-15 10:30

### Options

1. **Rebuild index** — Re-index all documents
   `/secondbrain-search-init --rebuild`

2. **Search now** — Start searching
   `/secondbrain-search "your query"`

3. **Check status** — View index statistics
   `qmd status`

Step 3: Create Search Configuration

Create .claude/search/ directory and qmd config:

mkdir -p .claude/search

Generate qmd.config.json in project root:

{
  "name": "{{project_name}}-secondbrain",
  "paths": ["docs"],
  "ignore": [
    "**/node_modules/**",
    "**/.vitepress/cache/**",
    "**/.vitepress/dist/**",
    "**/TEMPLATE.md"
  ],
  "indexDir": ".claude/search",
  "chunk": {
    "size": 800,
    "overlap": 0.15
  },
  "metadata": {
    "extractFrontmatter": true,
    "includeFileMetadata": true
  }
}

Step 4: Update .gitignore

Add search index to .gitignore (index should not be committed):

# Semantic search index (regenerate with /secondbrain-search-init)
.claude/search/
qmd.config.json

Step 5: Build Initial Index

Run initial indexing:

qmd index

Show progress:

## Building Search Index

Scanning docs/...
Found 47 documents

Indexing:
[████████████████████░░░░░░░░░░] 35/47 documents

Downloading models (first run only):
- embedding-gemma-300M... done
- qwen3-reranker... done

Building embeddings:
[██████████████████████████████] 47/47 documents

Index built successfully!
- Documents: 47
- Chunks: 312
- Index size: 2.4 MB
- Location: .claude/search/

Step 6: Register Hook (Optional)

Ask user if they want automatic index updates:

## Automatic Index Updates

Would you like to automatically update the search index
when documents are modified?

[x] Yes, add PostToolUse hook (Recommended)
    - Updates index incrementally on file changes
    - Adds ~0.5s to Write/Edit operations

[ ] No, I'll rebuild manually
    - Run `qmd index` or `/secondbrain-search-init --rebuild`

If yes, add hook to .claude/settings.local.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/search-index-update.py\"",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

Copy hook script:

cp "${CLAUDE_PLUGIN_ROOT}/hooks/search-index-update.py" .claude/hooks/

Step 7: Show Summary

## Search Initialized Successfully!

**Project:** my-knowledge-base
**Documents indexed:** 47
**Index location:** .claude/search/

### Quick Start

Search your knowledge base:
/secondbrain-search "kubernetes deployment strategies"

Search with filters:
/secondbrain-search --entity=adrs "database"
/secondbrain-search --recent=30d "authentication"

### Index Management

Rebuild index:
qmd index --rebuild

Check status:
qmd status

View recent searches:
qmd history

### Automatic Updates

Index updates: Enabled (PostToolUse hook)
Documents in docs/ will be re-indexed on save.

Options

--rebuild

Force rebuild of entire index:

qmd index --rebuild

--no-hook

Skip adding the automatic update hook:

/secondbrain-search-init --no-hook

Troubleshooting

Models Download Stuck

If model download hangs:

# Clear cache and retry
rm -rf ~/.cache/qmd/models/
qmd index

Index Corruption

If search returns errors:

# Remove and rebuild
rm -rf .claude/search/
qmd index

Slow Indexing

For large document sets (>500 docs):

  • Initial indexing may take several minutes
  • Consider using --batch-size=50 for progress visibility

Related Skills

  • secondbrain-search — Search your knowledge base
  • secondbrain-init — Create new secondbrain project

Semantic Search

Search your secondbrain knowledge base using semantic similarity (meaning-based) and full-text search.

Prerequisites

  1. qmd installed: Check with which qmd

    • Install: bun install -g qmd or npm install -g qmd
    • First run downloads ~1.5GB models
  2. Search initialized: Check for .claude/search/ directory

    • If not initialized, suggest running /secondbrain-search-init

Usage

/secondbrain-search "your natural language query"
/secondbrain-search --entity=adrs "database migration"
/secondbrain-search --recent=30d "authentication"
/secondbrain-search --status=active --tag=kubernetes "deployment"

Workflow

Step 1: Validate Environment

# Check qmd is installed
which qmd

# Check search is initialized
ls .claude/search/

If qmd not installed:

qmd is not installed. Install it with:
  bun install -g qmd
  # or
  npm install -g qmd

Then initialize search with: /secondbrain-search-init

If search not initialized:

Search not initialized for this project.
Run: /secondbrain-search-init

Step 2: Parse Query and Filters

Extract from user input:

FilterSyntaxExample
Entity--entity=<type>--entity=adrs,notes
Recent--recent=<period>--recent=7d, --recent=2w, --recent=1m
Date from--from=<date>--from=2025-01-01
Date to--to=<date>--to=2025-12-31
Status--status=<status>--status=active, --status=!archived
Tag--tag=<tag>--tag=kubernetes
Limit--limit=<n>--limit=10 (default: 5)
Format--format=<fmt>--format=brief, --format=detailed, --format=json

Step 3: Execute Search

Run qmd search command:

cd <project_root>
qmd query "<user_query>" --json --limit=<limit>

Parse JSON output:

{
  "results": [
    {
      "id": "docs/adrs/ADR-0012-kubernetes-deployment.md",
      "score": 0.92,
      "title": "Kubernetes Deployment Strategy",
      "excerpt": "We decided to use Blue-Green deployment for stateless services...",
      "metadata": {
        "frontmatter": {
          "status": "implemented",
          "created": "2025-12-15"
        }
      }
    }
  ]
}

Step 4: Enrich with Metadata

Load YAML records to add entity-specific metadata:

For each result:

  1. Determine entity type from file path (e.g., docs/adrs/ → ADRs)
  2. Load corresponding records from .claude/data/<entity>/records.yaml
  3. Match by file path and enrich with status, tags, dates, etc.

Step 5: Apply Post-Filters

Filter results based on user criteria:

# Pseudocode
for result in results:
    if entity_filter and result.entity not in entity_filter:
        skip
    if status_filter and result.status != status_filter:
        skip
    if tag_filter and tag_filter not in result.tags:
        skip
    if date_filter and not in_date_range(result.date, from_date, to_date):
        skip

Step 6: Format Output

Brief Format (default for >3 results)
## Search Results

**Query:** "kubernetes deployment"
**Results:** 4 matches

1. **[ADR-0012] Kubernetes Deployment Strategy** (0.92)
   Status: implemented | Updated: 2025-12-15

2. **[Note] Kubernetes Scaling Best Practices** (0.87)
   Tags: kubernetes, scaling | Created: 2025-11-20

3. **[Discussion] Platform Team - Deployment Pipeline** (0.79)
   Date: 2025-10-05 | Participants: Alice, Bob

4. **[Task] Implement Canary Deployments** (0.71)
   Status: in_progress | Priority: high
Detailed Format (default for ≤3 results)
## Search Results

**Query:** "kubernetes deployment"
**Results:** 2 matches

---

### 1. [ADR-0012] Kubernetes Deployment Strategy
**Score:** 0.92 | **Status:** implemented | **Category:** infrastructure

**File:** [ADR-0012-kubernetes-deployment.md](docs/adrs/ADR-0012-kubernetes-deployment.md)

**Excerpt:**
> We decided to use Blue-Green deployment for stateless services
> and Rolling updates for stateful workloads. This approach provides
> zero-downtime deployments while minimizing resource overhead...

**Metadata:**
- Created: 2025-12-15
- Author: sergey
- Category: infrastructure

---

### 2. [Note] Kubernetes Scaling Best Practices
**Score:** 0.87 | **Tags:** kubernetes, scaling

**File:** [2025-11-20-kubernetes-scaling.md](docs/notes/2025-11-20-kubernetes-scaling.md)

**Excerpt:**
> Key considerations for scaling Kubernetes deployments:
> 1. Horizontal Pod Autoscaler configuration
> 2. Resource requests and limits
> 3. Pod disruption budgets...

**Metadata:**
- Created: 2025-11-20
- Status: active
JSON Format
{
  "query": "kubernetes deployment",
  "total": 4,
  "results": [
    {
      "entity": "adrs",
      "id": "ADR-0012",
      "title": "Kubernetes Deployment Strategy",
      "file": "docs/adrs/ADR-0012-kubernetes-deployment.md",
      "score": 0.92,
      "excerpt": "We decided to use Blue-Green deployment...",
      "metadata": {
        "status": "implemented",
        "category": "infrastructure",
        "created": "2025-12-15",
        "author": "sergey"
      }
    }
  ]
}

Search Tips

Display helpful tips when no results found:

## No Results Found

**Query:** "foobar nonexistent"

### Tips

1. **Try broader terms** — Use general concepts instead of specific jargon
2. **Check spelling** — Semantic search handles typos but exact terms may miss
3. **Remove filters** — Try without --entity or --status filters first
4. **Use related concepts** — "authentication" instead of "OAuth2"

### Alternative Actions

- `/secondbrain-freshness` — See all recent content
- Run without filters: `/secondbrain-search "foobar"`

Refine Search

After showing results, offer refinement options:

### Refine Search

- `--entity=adrs` — Filter to ADRs only
- `--recent=30d` — Limit to last 30 days
- `--status=active` — Exclude archived items
- `"kubernetes AND deployment"` — Boolean operators

Related Skills

  • secondbrain-search-init — Initialize search for this project
  • secondbrain-freshness — View items by freshness/staleness

Create Task

Create tracked tasks with priority, due dates, and status workflow.

Prerequisites

Verify Tasks entity is enabled:

  1. Check for .claude/data/tasks/meta.yaml (sharded) or .claude/data/tasks/records.yaml (legacy)
  2. If not found, suggest enabling tasks via secondbrain-init or secondbrain-entity

Important Rules

  • Do NOT add tasks to the left sidebar/navigation. Tasks are listed automatically via the EntityTable component on docs/tasks/index.md, which reads from .claude/data/tasks/ shard files. No sidebar modification is needed.

Workflow

Step 1: Gather Information

Collect from user or conversation context:

  1. Title — Brief task description
  2. Description (optional) — Detailed description
  3. Priority — low, medium, high, critical
  4. Due Date (optional) — Target completion date
  5. Assignee (optional) — Person responsible

Step 2: Generate Task Number

Sequential ID format: TASK-XXXX (zero-padded)

  1. Load .claude/data/tasks/meta.yaml (read last_number — tiny file, ~50 tokens)
  2. Increment by 1
  3. Format as TASK-0042

Step 3: Create Task Record

Add to the current month's shard .claude/data/tasks/YYYY-MM.yaml:

- number: 42
  title: "Implement user authentication"
  description: "Add OAuth2 login flow"
  status: todo
  priority: high
  created: 2026-01-15
  due_date: 2026-01-31
  assignee: sergey
  tags: [auth, security]

Update last_number: 42 in .claude/data/tasks/meta.yaml and ensure the current month is in the shards list.

Step 4: Create Task Document (Optional)

For complex tasks, create a document:

Filename: docs/tasks/TASK-0042-implement-authentication.md

---
id: TASK-0042
title: Implement user authentication
status: todo
priority: high
created: 2026-01-15
due_date: 2026-01-31
assignee: sergey
tags: [auth, security]
---

# TASK-0042: Implement user authentication

## Description

Add OAuth2 login flow for the application.

## Acceptance Criteria

- [ ] OAuth2 provider configuration
- [ ] Login redirect flow
- [ ] Token storage
- [ ] Logout functionality

## Notes

Implementation notes here...

Step 5: Sidebar Note

DO NOT manually add tasks to VitePress sidebar.

Tasks are automatically listed via the EntityTable component on docs/tasks/index.md, which reads from .claude/data/tasks/ shard files. No sidebar modification needed.

Step 6: Confirm Creation

## Task Created

**ID:** TASK-0042
**Title:** Implement user authentication
**Priority:** high
**Due:** 2026-01-31
**Status:** todo

### Next Steps
- Update status as work progresses
- Add notes to the task document
- Mark complete when done

Status Workflow

todo → in_progress → done
            ↓
         blocked → in_progress
            ↓
        canceled
StatusDescription
todoNot started
in_progressWork in progress
blockedWaiting on dependency
doneCompleted
canceledWon't be done

Priority Levels

PriorityUse When
criticalUrgent, blocks other work
highImportant, should be done soon
mediumNormal priority
lowNice to have, no rush

Additional Resources

  • references/task-workflows.md — Detailed task lifecycle, priority guidelines, and workflow patterns

Tips

  1. Keep titles actionable — Start with a verb (Implement, Fix, Add)
  2. Set realistic due dates — Better to underpromise
  3. Update status promptly — Keeps the backlog accurate
  4. Use tags — Helps filter and group related tasks
  5. Add acceptance criteria — Makes "done" unambiguous

Transcribe Skill

Process meeting transcripts from external providers into structured discussion documents, with optional ADR extraction from decisions.

Usage

/secondbrain-transcribe <id | list | all>
  • id — specific meeting ID from the provider to process
  • list — show recent undocumented meetings
  • all — batch process all undocumented meetings

Examples:

/secondbrain-transcribe list
/secondbrain-transcribe 01KCY1N2ZMSVEKK0DJ0D0HM4CE
/secondbrain-transcribe all

Prerequisites

Verify the project has transcription configured in .claude/data/config.yaml:

integrations:
  transcription:
    enabled: true
    provider: fireflies
    check_on_session_start: true
    lookback_days: 7
    fireflies:
      api_key_env: FIREFLIES_API_KEY

If not configured, guide the user through setup:

  1. Choose a provider (fireflies is currently supported)
  2. Configure API key (environment variable or .env.local)
  3. Add the integrations section to config

Also verify that discussions entity is enabled (transcriptions create discussion documents).

Procedure

Step 1: Load Configuration

Read .claude/data/config.yaml and extract:

  • integrations.transcription.provider — which provider to use
  • integrations.transcription.lookback_days — how far back to check (default: 7)
  • team section — for participant name mapping

Load the provider-specific reference from references/provider-<name>.md for API details.

Step 2: Route by Subcommand

list — Fetch recent meetings from provider, filter against processed list, display table:

## Undocumented Meetings (Last 7 Days)

| ID | Date | Title | Duration | Participants |
|----|------|-------|----------|--------------|
| 01KCY1N2ZM... | 2026-03-28 | Team Sync | 40 min | Jane, John |

Run `/secondbrain-transcribe <id>` to process a specific meeting.
Run `/secondbrain-transcribe all` to process all meetings.

<id> — Process a specific meeting (continue to Step 3).

all — Iterate through all unprocessed meetings, processing each (continue to Step 3 for each).

Step 3: Fetch Meeting Data

Use the provider's client library to fetch meeting data. For provider-specific instructions, read the corresponding reference file:

  • Fireflies: See references/provider-fireflies.md

The client should be available at .claude/lib/<provider>.py in the user's project (scaffolded during init).

import sys
sys.path.insert(0, '.claude/lib')

# Provider-specific import
from fireflies import FirefliesClient
client = FirefliesClient()
transcript = client.get_transcript("<meeting-id>")

Step 4: Check Processed Status

Use the tracking library to check if this meeting was already documented:

from tracking import is_meeting_processed
if is_meeting_processed("<meeting-id>"):
    # Already processed — show existing doc location

If already processed, inform the user and show the existing discussion file path.

Step 5: Extract Structured Data

From the transcript, extract:

  1. Participants — Map to team aliases using the team config section. Match email patterns and name patterns to resolve full names.
  2. Date — Meeting date
  3. Duration — Meeting length
  4. Key Discussion Points — Main topics covered
  5. Decisions Made — Any conclusions or agreements
  6. Action Items — Tasks assigned with owners
  7. Open Questions — Unresolved items

Use the provider's AI summary if available (e.g., Fireflies summary.overview, summary.action_items, summary.keywords).

Step 6: Generate Discussion Document

Create a discussion document following the existing secondbrain-discussion patterns:

File path: docs/discussions/YYYY-MM-DD-<participant>-<topic-slug>.md

Frontmatter:

---
date: YYYY-MM-DD
participants:
  - Jane Smith
  - John Doe
topic: Meeting Title
status: documented
source: <provider_name>
meeting_id: <provider_meeting_id>
tags: [extracted, keywords]
---

Body template:

# Meeting Title

## Context

<From transcript summary or overview>

## Discussion Points

### Topic 1
<Details from transcript>

### Topic 2
<Details from transcript>

## Decisions

| Decision | Rationale | Owner |
|----------|-----------|-------|
| Decision from transcript | Context | Assignee |

## Action Items

- [ ] Item from transcript — Owner
- [ ] Item from transcript — Owner

## Open Questions

1. Unresolved items from discussion

---

*Source: <provider> transcript*
*Meeting ID: <id>*
*Documented: YYYY-MM-DD*

CRITICAL: Do NOT add the discussion to the VitePress sidebar. Discussion documents are auto-listed via the EntityTable component.

Step 7: Identify Potential ADRs

Scan decisions for architectural/technical choices:

ADR Candidates:

  • Technology choices ("we decided to use X")
  • Architecture patterns ("we'll implement Y approach")
  • Process changes ("going forward we'll do Z")

Present to user with confirmation for each:

## Potential ADRs from Meeting

Found 2 decisions that might warrant ADRs:

1. "Decided to use Docker Compose for local development"
   → Create ADR? [Y/N]

2. "Will implement Redis for caching layer"
   → Create ADR? [Y/N]

Never auto-create ADRs — always wait for user confirmation on each.

Step 8: Show Draft and Confirm

Present the full draft before writing:

## Meeting Transcript Documentation

**Meeting:** Jane <> John
**Date:** 2026-03-28
**Duration:** 40 minutes
**Provider ID:** 01KCY1N2ZMSVEKK0DJ0D0HM4CE

### Files to Create/Update
1. CREATE: docs/discussions/2026-03-28-john-doe-team-sync.md
2. UPDATE: .claude/data/discussions/2026-03.yaml (add record)

### ADRs to Create (if confirmed)
- ADR-0005: Docker Compose for Local Development

### Draft Document
---
[Document content]
---

Proceed with documentation?

Step 9: Create Files and Update Records

After approval:

  1. Create the discussion markdown file
  2. Add a record to the monthly discussion partition (.claude/data/discussions/YYYY-MM.yaml):
    - date: 'YYYY-MM-DD'
      member: john
      topic: Team Sync
      file: docs/discussions/2026-03-28-john-doe-team-sync.md
      source: fireflies
      meeting_id: 01KCY1N2ZMSVEKK0DJ0D0HM4CE
    
  3. Create any confirmed ADRs using the /secondbrain-adr skill workflow

Team Member Mapping

If a team section exists in config, map provider participant names/emails to team aliases:

team:
  jane:
    full_name: "Jane Smith"
    patterns: ["jane@*", "Jane*"]
  john:
    full_name: "John Doe"
    patterns: ["john@*", "John*"]

Match participant names/emails against patterns to resolve full names. Unmatched participants are kept as-is.

Rules

  1. Always check processed status — don't re-document meetings
  2. Map participants correctly — use team config for name resolution
  3. Extract decisions carefully — only suggest ADRs for technical/architectural decisions
  4. Manual ADR confirmation — never auto-create ADRs without user approval
  5. Update discussion records — add to monthly partition YAML
  6. Preserve transcript source — include meeting_id and source in frontmatter
  7. Handle API errors gracefully — report provider API issues clearly
  8. Do NOT add to sidebar — discussions are auto-listed via EntityTable

Agents 2

You are a secondbrain refinement agent specializing in autonomous knowledge base improvement with user-confirmed actions.

Your Core Responsibilities:

  1. Analyze secondbrain content quality across all entities
  2. Identify improvement opportunities (stale content, broken links, missing metadata)
  3. Propose specific refinements with clear rationale
  4. Execute improvements only after user confirmation
  5. Send notifications when awaiting user input

Analysis Process:

  1. Discovery Phase

    • Load .claude/data/config.yaml to understand project structure
    • Inventory all enabled entities and their records
    • Build content map with file paths and metadata
  2. Quality Analysis

    • Check frontmatter completeness
    • Verify internal links are valid
    • Identify duplicate or similar content
    • Find orphaned files (not in records)
    • Detect stale content based on freshness thresholds
  3. Improvement Identification

    • Missing tags or metadata
    • Incomplete sections (empty ## headers)
    • Outdated references
    • Status inconsistencies (draft items over 30 days)
    • Opportunities for cross-linking
  4. Proposal Generation

    • Create specific, actionable improvement proposals
    • Group related changes
    • Prioritize by impact and effort
  5. User Confirmation

    • Present proposals clearly
    • Use AskUserQuestion for decisions
    • Send notification if configured
    • Wait for explicit approval before changes
  6. Execution

    • Apply approved changes
    • Update records as needed
    • Log all modifications
    • Report completion

Notification Support:

When user confirmation is needed, send notifications via configured method:

Mobile (ntfy.sh):

curl -d "Secondbrain refinement needs your input: [summary]" ntfy.sh/your-topic

Desktop Sound (macOS):

afplay /System/Library/Sounds/Ping.aiff

Desktop Notification (macOS):

osascript -e 'display notification "Refinement needs input" with title "Secondbrain"'

Check .claude/secondbrain.local.md for notification preferences:

---
notifications:
  method: ntfy  # or sound, desktop, none
  ntfy_topic: your-topic
  sound_file: /System/Library/Sounds/Ping.aiff
---

Quality Standards:

  • Never modify content without user approval
  • Preserve original intent when suggesting edits
  • Maintain consistent formatting across entities
  • Keep changes atomic and reversible
  • Document all proposed changes clearly

Output Format:

For each refinement batch:

## Refinement Proposal #N

### Summary
- X improvements identified
- Estimated impact: High/Medium/Low

### Proposed Changes

#### 1. [Category]: [Brief Description]
**File:** path/to/file.md
**Issue:** What's wrong or missing
**Proposed Fix:** Specific change
**Rationale:** Why this improves the secondbrain

#### 2. [Category]: [Brief Description]
...

### Actions Required
- [ ] Approve all changes
- [ ] Approve selected changes (specify numbers)
- [ ] Reject and provide feedback
- [ ] Skip this batch

Awaiting your decision...

Edge Cases:

  • Large secondbrain: Process in batches of 10-20 items
  • Conflicting changes: Present options, don't assume
  • Breaking changes: Warn explicitly, require confirmation
  • External links: Note but don't modify (may require verification)

Important:

  • Run Read on files before proposing edits
  • Use Glob/Grep to find related content efficiently
  • Batch related changes for efficient review
  • Send notification only when awaiting input, not for progress updates

You are a secondbrain document reviewer specializing in knowledge quality assessment.

Your Core Responsibilities:

  1. Analyze document structure and completeness
  2. Evaluate content clarity and actionability
  3. Check alignment with entity best practices
  4. Identify missing elements or unclear sections
  5. Provide specific, actionable improvement suggestions

Review Process:

  1. Document Identification

    • Determine entity type (ADR, Note, Task, Discussion, Custom)
    • Load the document content
    • Parse frontmatter and structure
  2. Structural Analysis

    • Verify required frontmatter fields
    • Check section completeness
    • Validate internal consistency
  3. Content Evaluation

    • Clarity of purpose/problem statement
    • Actionability of content
    • Technical accuracy (within scope)
    • Appropriate level of detail
  4. Cross-Reference Check

    • Links to related documents
    • References to external resources
    • Connection to other entities
  5. Recommendation Generation

    • Specific improvements with examples
    • Priority ranking (must-have vs nice-to-have)
    • Effort estimate for changes

Entity-Specific Criteria:

ADR Review

Required Elements:

  • Clear problem context
  • Decision statement
  • Options considered (2+ options)
  • Consequences (positive/negative)
  • Implementation plan

Quality Markers:

  • Rationale explains "why" not just "what"
  • Trade-offs are explicit
  • Related ADRs linked
  • Status matches content maturity

Note Review

Required Elements:

  • Clear title and topic
  • Summary/overview section
  • Main content with structure
  • Relevant tags

Quality Markers:

  • Future-self readable (context preserved)
  • Actionable takeaways
  • References to sources
  • Links to related notes

Task Review

Required Elements:

  • Clear, actionable title
  • Acceptance criteria (for complex tasks)
  • Appropriate priority assignment
  • Realistic due date (if set)

Quality Markers:

  • Title starts with verb
  • Scope is clear and bounded
  • Dependencies noted if any
  • Success is measurable

Discussion Review

Required Elements:

  • Participants listed
  • Context/background
  • Key discussion points
  • Decisions made (if any)
  • Action items (if any)

Quality Markers:

  • Decisions have owners and deadlines
  • Open questions captured
  • Follow-up scheduled if needed
  • Actionable outcomes

Output Format:

## Document Review: [Title]

**Entity Type:** ADR/Note/Task/Discussion
**Document:** path/to/document.md
**Overall Score:** X/10

### Summary
[2-3 sentence assessment]

### Strengths
- [What's working well]
- [Another strength]

### Areas for Improvement

#### 1. [Issue Category] - Priority: High/Medium/Low
**Finding:** What's missing or unclear
**Suggestion:** Specific improvement
**Example:** How it could be written

#### 2. [Issue Category] - Priority: High/Medium/Low
...

### Checklist
- [x] Required field present
- [ ] Missing element
- [x] Quality marker met
...

### Recommendations

**Before publishing:**
1. [Must-do improvement]
2. [Must-do improvement]

**Nice to have:**
1. [Optional improvement]
2. [Optional improvement]

### Final Verdict
[ ] Ready to publish
[ ] Minor revisions needed
[ ] Major revisions needed
[ ] Needs rethinking

Quality Standards:

  • Be specific, not vague ("Add context about the legacy system" not "Add more context")
  • Provide examples when suggesting changes
  • Acknowledge what's working well
  • Prioritize suggestions (don't overwhelm)
  • Consider the document's purpose and audience

Edge Cases:

  • Draft documents: Focus on structure, defer detail review
  • Technical content: Note areas needing expert verification
  • Time-sensitive: Prioritize blockers over nice-to-haves
  • Personal notes: Lighter review, focus on retrievability

Sponsors

Details

Marketplace
sergio-bershadsky/ai
Source
plugins/secondbrain
Category
Productivity

More from sergio-bershadsky/ai

All 13