
secondbrain
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-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add sergio-bershadsky/ai.
Contents
Discovered from sourceSkills 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:
- Check for
.claude/data/adrs/meta.yaml(sharded) or.claude/data/adrs/records.yaml(legacy) - If not found, suggest running
secondbrain-initwith ADRs enabled
Important Rules
- Do NOT add ADRs to the left sidebar/navigation. ADRs are listed automatically via the
EntityTablecomponent ondocs/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:
-
Category (determines number range):
infrastructure(0001-0999) — Architecture & infrastructurefeature(2000-2999) — Feature implementationprocess(3000-3999) — Process & workflow
-
Title — Brief decision title (will be slugified for filename)
-
Context — What problem prompted this decision?
Step 2: Determine ADR Number
- Load
.claude/data/adrs/meta.yaml(readlast_number— tiny file, ~50 tokens) - Find highest number in selected category range
- Increment to get next number
- 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
| Status | Description |
|---|---|
| draft | Initial creation, under development |
| proposed | Ready for review |
| admitted | Approved, pending implementation |
| applied | Implementation started |
| implemented | Implementation complete |
| tested | Verified in production |
| rejected | Not approved |
| canceled | Abandoned |
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:
- Check for
.claude/data/discussions/schema.yaml - 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
EntityTablecomponent ondocs/discussions/index.md, which reads from monthly.claude/data/discussions/YYYY-MM.yamlfiles. No sidebar modification is needed.
Workflow
Step 1: Gather Information
Collect from user or conversation context:
- Participant(s) — Who was in the discussion
- Topic — Main subject discussed
- Source — manual, meeting, slack
- Key Points — Discussion content
- Decisions — What was decided
- 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 2025discussions/2026-01.yaml— January 2026
Past months become immutable, preserving history.
Sources
| Source | Description |
|---|---|
| manual | Hand-documented discussion |
| meeting | From a scheduled meeting |
| slack | From Slack conversation |
Tips
- Capture decisions explicitly — Use the table format
- Create action items — Every decision should have an owner
- Note open questions — Track what needs follow-up
- Link to related content — Reference ADRs, notes, etc.
- 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:
- Check for
.claude/data/config.yaml - If not found, suggest running
secondbrain-initfirst
Workflow
Step 1: Gather Entity Information
Collect from user:
- Entity Name — Plural name (e.g., "contacts", "projects", "bookmarks")
- Singular Name — For display (e.g., "contact", "project", "bookmark")
- 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
- ID Format — How records are numbered/identified:
- Sequential (
PREFIX-XXXX) - Date-based (
YYYY-MM-DD-slug) - UUID
- Sequential (
- 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
| Type | YAML Schema | Example |
|---|---|---|
| string | type: string | "Hello world" |
| integer | type: integer | 42 |
| number | type: number | 3.14 |
| boolean | type: boolean | true/false |
| date | type: string, format: date | 2026-01-15 |
| datetime | type: string, format: date-time | 2026-01-15T10:30:00Z |
| array | type: array, items: {...} | [tag1, tag2] |
| enum | type: 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
- Keep fields minimal — Start with essential fields, add more later
- Use enums for fixed values — Better than free-form strings
- Consider status workflow — Most entities benefit from status tracking
- Plan ID format carefully — Hard to change after records exist
- 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:
- Check for
.claude/data/config.yaml - 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:
- Load all records
- Check date fields (created, date, date_updated)
- Compare against freshness threshold
- 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):
| Entity | Default | Critical |
|---|---|---|
| ADRs | 30 days | 60 days |
| Tasks | 14 days | 28 days |
| Notes | 30 days | 60 days |
| Discussions | 7 days | 14 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
- Run weekly — Set calendar reminder for freshness reviews
- Address critical first — Focus on oldest items
- Archive liberally — Better to archive than ignore
- Update thresholds — Adjust based on your workflow pace
- 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:
- Project name (kebab-case, e.g.,
my-knowledge-base) - Target directory (default:
./<project-name>) - 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
reviewsection to config.yaml - Scaffold
ReviewBadge.vuecomponent 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
teamandintegrations.transcriptionsections 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.localor 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:
| Selection | Actions |
|---|---|
| qmd | Create .claude/search/, generate qmd.config.json, add search hook |
| Orama | Add Orama deps to package.json, generate SearchBox.vue, generate build script |
| Both | All of the above |
| None | Skip 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/:
-
Microdatabase files:
config.yamlfromscaffolding/microdatabase/config.yaml.tmpl- Entity
schema.yamlfromentities/<entity>/schema.yaml - Entity
records.yamlinitialized empty
-
VitePress files:
config.tsfromscaffolding/vitepress/config.ts.tmpl- Theme files from
scaffolding/vitepress/theme/ - Data loaders from
scaffolding/vitepress/data/
-
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
- Home page from
-
Automation:
settings.local.jsonfromscaffolding/claude/settings.local.json.tmpltracking.pyfromscaffolding/lib/tracking.py.tmpl- Hooks from
hooks/(copy to project)
-
Search (if enabled):
- qmd:
qmd.config.jsonfromscaffolding/search/qmd.config.json.tmpl - qmd: Copy
search-index-update.pyhook - Orama:
SearchBox.vuefromscaffolding/vitepress/theme/components/SearchBox.vue.tmpl - Orama:
build-search-index.tsfromscaffolding/vitepress/search/build-search-index.ts.tmpl - Orama: Add dependencies to
package.json
- qmd:
-
Review Stamps (if enabled):
ReviewBadge.vuefromscaffolding/vitepress/theme/components/ReviewBadge.vue.tmpl- Replace
{{fresh_days}}/{{aging_days}}with configured thresholds (defaults: 30/90) - Add
reviewsection toconfig.yaml
-
Meeting Transcription (if enabled):
- Provider client (e.g.,
fireflies.py) fromscaffolding/lib/fireflies.py.tmpl - Add
teamandintegrations.transcriptionsections toconfig.yaml
- Provider client (e.g.,
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:
| Variable | Description |
|---|---|
{{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:
- Check for
.claude/data/notes/meta.yaml(sharded) or.claude/data/notes/records.yaml(legacy) - If not found, suggest enabling notes via
secondbrain-initorsecondbrain-entity
Workflow
Step 1: Gather Information
Collect from user or conversation context:
- Title — Brief, descriptive title
- Content — Main content (can be from conversation)
- 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:
| Category | Example Tags |
|---|---|
| Technology | kubernetes, react, python |
| Domain | architecture, security, performance |
| Type | howto, reference, research |
| Project | project-x, migration, refactor |
Status Values
active— Current, relevant notearchived— No longer current but preserved
Additional Resources
references/note-formats.md— Detailed note templates and formatting patterns
Tips
- Be specific — Titles should indicate content at a glance
- Add context — Include why this is important, not just what
- Link liberally — Connect to related notes and external resources
- Tag consistently — Use established tags when possible
- 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 toreview.default_reviewerfrom.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:
- Read
review.default_reviewerfrom.claude/data/config.yaml - If that is
nullor missing, check theteamsection in config for a single member to use - 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
teamsection 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
ReviewBadgecomponent in the VitePress theme automatically renders review status from thereviewed_bylist - Staleness thresholds are configurable in
config.yamlunderreview.thresholds:- fresh: 0 to
fresh_days(default 30) — green - aging:
fresh_daystoaging_days(default 90) — yellow - stale: beyond
aging_days— orange
- fresh: 0 to
- 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-freshnesstracks entity record currency
Initialize Semantic Search
Set up qmd semantic search for an existing secondbrain project.
Prerequisites
- Secondbrain project exists: Check for
.claude/data/config.yaml - 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=50for 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
-
qmd installed: Check with
which qmd- Install:
bun install -g qmdornpm install -g qmd - First run downloads ~1.5GB models
- Install:
-
Search initialized: Check for
.claude/search/directory- If not initialized, suggest running
/secondbrain-search-init
- If not initialized, suggest running
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:
| Filter | Syntax | Example |
|---|---|---|
| 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:
- Determine entity type from file path (e.g.,
docs/adrs/→ ADRs) - Load corresponding records from
.claude/data/<entity>/records.yaml - 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:
- Check for
.claude/data/tasks/meta.yaml(sharded) or.claude/data/tasks/records.yaml(legacy) - If not found, suggest enabling tasks via
secondbrain-initorsecondbrain-entity
Important Rules
- Do NOT add tasks to the left sidebar/navigation. Tasks are listed automatically via the
EntityTablecomponent ondocs/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:
- Title — Brief task description
- Description (optional) — Detailed description
- Priority — low, medium, high, critical
- Due Date (optional) — Target completion date
- Assignee (optional) — Person responsible
Step 2: Generate Task Number
Sequential ID format: TASK-XXXX (zero-padded)
- Load
.claude/data/tasks/meta.yaml(readlast_number— tiny file, ~50 tokens) - Increment by 1
- 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
| Status | Description |
|---|---|
| todo | Not started |
| in_progress | Work in progress |
| blocked | Waiting on dependency |
| done | Completed |
| canceled | Won't be done |
Priority Levels
| Priority | Use When |
|---|---|
| critical | Urgent, blocks other work |
| high | Important, should be done soon |
| medium | Normal priority |
| low | Nice to have, no rush |
Additional Resources
references/task-workflows.md— Detailed task lifecycle, priority guidelines, and workflow patterns
Tips
- Keep titles actionable — Start with a verb (Implement, Fix, Add)
- Set realistic due dates — Better to underpromise
- Update status promptly — Keeps the backlog accurate
- Use tags — Helps filter and group related tasks
- 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 processlist— show recent undocumented meetingsall— 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:
- Choose a provider (fireflies is currently supported)
- Configure API key (environment variable or
.env.local) - Add the
integrationssection 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 useintegrations.transcription.lookback_days— how far back to check (default: 7)teamsection — 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:
- Participants — Map to team aliases using the
teamconfig section. Match email patterns and name patterns to resolve full names. - Date — Meeting date
- Duration — Meeting length
- Key Discussion Points — Main topics covered
- Decisions Made — Any conclusions or agreements
- Action Items — Tasks assigned with owners
- 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:
- Create the discussion markdown file
- 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 - Create any confirmed ADRs using the
/secondbrain-adrskill 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
- Always check processed status — don't re-document meetings
- Map participants correctly — use team config for name resolution
- Extract decisions carefully — only suggest ADRs for technical/architectural decisions
- Manual ADR confirmation — never auto-create ADRs without user approval
- Update discussion records — add to monthly partition YAML
- Preserve transcript source — include
meeting_idandsourcein frontmatter - Handle API errors gracefully — report provider API issues clearly
- 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:
- Analyze secondbrain content quality across all entities
- Identify improvement opportunities (stale content, broken links, missing metadata)
- Propose specific refinements with clear rationale
- Execute improvements only after user confirmation
- Send notifications when awaiting user input
Analysis Process:
-
Discovery Phase
- Load
.claude/data/config.yamlto understand project structure - Inventory all enabled entities and their records
- Build content map with file paths and metadata
- Load
-
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
-
Improvement Identification
- Missing tags or metadata
- Incomplete sections (empty ## headers)
- Outdated references
- Status inconsistencies (draft items over 30 days)
- Opportunities for cross-linking
-
Proposal Generation
- Create specific, actionable improvement proposals
- Group related changes
- Prioritize by impact and effort
-
User Confirmation
- Present proposals clearly
- Use AskUserQuestion for decisions
- Send notification if configured
- Wait for explicit approval before changes
-
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:
- Analyze document structure and completeness
- Evaluate content clarity and actionability
- Check alignment with entity best practices
- Identify missing elements or unclear sections
- Provide specific, actionable improvement suggestions
Review Process:
-
Document Identification
- Determine entity type (ADR, Note, Task, Discussion, Custom)
- Load the document content
- Parse frontmatter and structure
-
Structural Analysis
- Verify required frontmatter fields
- Check section completeness
- Validate internal consistency
-
Content Evaluation
- Clarity of purpose/problem statement
- Actionability of content
- Technical accuracy (within scope)
- Appropriate level of detail
-
Cross-Reference Check
- Links to related documents
- References to external resources
- Connection to other entities
-
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