second-brain

second-brain

Plugin Claude privado com os workflows do Second Brain de Fernando — INGEST, QUERY, LINT, AUTORESEARCH, SAVE, GAP-REVIEW — como skills auto-triggeráveis + slash commands.

Premissas

• Plugin privado. Repo second-brain-plugin é do Fernando, não é público (DL-03 do plan de impl Fase 1).
• Ativação escopada ao vault. Plugin só se ativa em sessões cujo working directory (ou ancestral) contém CLAUDE.md + SECOND-BRAIN-ARCHITECTURE.md com claude_md_title: Second Brain (DL-08). Fora do vault, todas as skills ficam inertes e os hooks retornam exit 0 silencioso. Guardrail: G-VAULT-SCOPED.
• Sem acoplamento com superpowers. O plugin não depende, não carrega, nem assume superpowers (ou qualquer outro plugin). Guardrail: G-NO-SUPERPOWERS-COUPLING.
• Plugin nunca faz commit no vault. Auto-backup do vault é responsabilidade do Obsidian Git. Guardrail: G-NO-VAULT-COMMITS-FROM-PLUGIN.

Arquitetura

Três camadas (governança + execução + dados):

1. Governança — CLAUDE.md + SECOND-BRAIN-ARCHITECTURE.md no vault (schema operacional, sempre carregados).
2. Execução — este plugin (skills on-demand + slash commands + hooks).
3. Dados — wiki/, .raw/, operations/ no vault.

Spec autoritativa: outputs/second-brain-plugin-design-2026-04-19.md §2 no vault.

DAG canônico (G-DAG-ACYCLIC)

Composição entre skills é um DAG acíclico:

sb-save ──▶ sb-ingest ──▶ sb-lint
sb-gap-review ──▶ sb-autoresearch ──▶ sb-lint
sb-query (leaf) ──▶ (sugere) sb-ingest / sb-autoresearch
sb-lint (leaf) ──▶ (sugere) /sb:gap-review

Regra: uma skill nunca invoca outra que esteja a montante no DAG. Isso garante ausência de loops (R-07 do spec §12) e permite validação estática em v0.2.0 do plugin.

Skills

sb-save

Recorta trecho relevante da conversa atual e salva em .raw/conversations/{slug}-{date}.md com frontmatter raw. Implementa workflow SAVE (CLAUDE.md §4.5). Triggers: /sb:save {descrição} ou linguagem natural ("salva isso como X"). Auto-chain para sb-ingest após escrever em .raw/. (Delivered PR-4, v0.2.0-alpha+)

Scope: Recorte sempre — nunca conversa inteira. Idempotente via merge (2ª invocação oferece merge ou novo slug).

sb-ingest

Ingere fonte bruta (URL, PDF, markdown em .raw/) no Second Brain. Implementa workflow INGEST (CLAUDE.md §4.1) com 8 passos (DL-M3-B: detecção de 3 tipos — markdown/URL/PDF). Triggers: /sb:ingest <path> ou linguagem natural ("ingere isso", "compila pro wiki"). Auto-chain de sb-save.

Scope: Produz/atualiza artigo wiki/ com frontmatter completo, backlinks bidirecionais, e pre-write check G-NO-SELF-LEAK crítico. Idempotente: 2ª invocação = NO-OP. (Delivered PR-5, v0.3.0-alpha)

Key constraints:

• Error handling matrix (design §6): url-fetch 404/timeout → stub com [!gap]; pdf-parse corrupted → stub com [!gap].
• DL-M3-J (url-fetch 5MB limit) + DL-M3-K (pdf OCR deferred M1.5+).
• PRÉ-WRITE CHECK: [[ "$target_path" != *"/self/"* ]] in passo 5 (gates code-quality).

Roadmap (M1.4+)

• sb-query: query skill para perguntas sobre conteúdo do vault (responde citando notas, sugere INGEST/AUTORESEARCH).
• sb-gap-review: GAP-REVIEW workflow (triagem semanal de lacunas em OPERATIONS-STATE).
• sb-autoresearch: AUTORESEARCH skill com 3-rondas / 15-páginas / 40-fetches limite.
• Hooks reais: session-start.sh + post-tool-use.sh (substituir stubs exit 0).
• LINT cheio: 8 categorias (cats 1, 3, 4, 7 além das 4 atuais).
• Fixtures expansão: ~10-12 arquivos cobrindo todos os 6 tipos do vault.

Instalação

Ambos clientes (Claude Desktop + Claude Code CLI) compartilham o mesmo user profile; config e markers são resolvidos da mesma maneira.

Via marketplace local (fluxo oficial do Claude Code):

O repo inclui .claude-plugin/marketplace.json — então basta apontar o marketplace pra raiz do repo e instalar pelo nome.

Claude Code CLI (aplica pros dois clientes porque config é user-scoped em ~/.claude/plugins/):

# Registrar marketplace (uma vez)
claude plugin marketplace add ~/Documents/tech_projects/second-brain-plugin

# Instalar (uma vez)
claude plugin install second-brain@second-brain

Ou dentro de uma sessão Claude (Desktop ou CLI):

/plugin marketplace add ~/Documents/tech_projects/second-brain-plugin
/plugin install second-brain@second-brain

Verificar:

claude plugin list
# deve mostrar: second-brain@second-brain (0.2.0-alpha) — enabled

Escape hatch — ENV var (DL-08 + spec §5):

Se a detecção walk-up falhar (ex.: invocar Claude de um path fora do vault mas querer o plugin ativo), setar:

export SECOND_BRAIN_VAULT_PATH=/Users/fernando/Documents/tech_projects/second-brain

A variável sobrepõe a resolução normal (ENV → ~/.claude/plugins/second-brain/config.json → walk-up).