---
name: workspace-governance
description: "Governanca do workspace Clara Staff. Use ao criar, editar, mover ou organizar qualquer documento. Define estrutura de pastas, frontmatter, tags, convencoes de nomes e formato de arquivo. Garante compatibilidade com Obsidian e ChromaDB RAG."
version: 1.1.0
tags: [governance, workspace, writing]
metadata:
  openclaw:
    triggers:
      - criar arquivo
      - novo documento
      - onde salvar
      - organizar
      - mover arquivo
      - escrever nota
      - frontmatter
      - tags
---

# Workspace Governance — Clara Staff v1.1.0

Regras de governanca para escrita e organizacao de arquivos no workspace. Compativel com Obsidian (humano) e ChromaDB (RAG agentes).

**Glossario rapido:** RAG = Retrieval-Augmented Generation (busca semantica + LLM). ChromaDB = banco vetorial que indexa documentos para busca por similaridade. Embeddings = representacao numerica do texto que permite busca semantica. Wikilinks = `[[links]]` que conectam notas no Obsidian.

---

## 1. Estrutura de Pastas

```
workspace/
├── Pendencias.md                <- TODOs abertos (bootstrap)
├── Tarefas.md                   <- Tarefas com prazo (bootstrap)
├── MEMORY.md                    <- Memoria curada (~100 linhas max)
├── memory/                      <- Tier 2: logs diarios (auto hoje+ontem)
│   └── YYYY-MM-DD.md
├── knowledge/                   <- Tier 3: deep knowledge por dominio
│   ├── aprendizados/            <- Licoes por dominio
│   ├── bracha-capital/          <- Empresa, pipeline content, leads
│   ├── banco-canonico/          <- Prompts e regras canonicas
│   ├── backups/                 <- Backups de configs
│   ├── blogs/                   <- Blogs AI monitorados
│   ├── briefings/               <- Briefings historicos
│   ├── comunidade/              <- Discord/Telegram digests
│   ├── identidade/              <- Guia imagens, persona visual
│   ├── infra/                   <- Credenciais, emergencias, SSH
│   ├── instagram/               <- Cookies, monitoramento
│   ├── juridico/                <- Processos, jurisprudencia
│   ├── newsletters/             <- Newsletters assinadas
│   ├── para-claude-code/        <- Canal Clara -> CC
│   ├── planos/                  <- Auto-melhoria, estrategia
│   ├── receita/                 <- Plano mestre, leads, scorecard
│   └── sessoes/                 <- Historico de sessoes
├── projects/                    <- Projetos ativos
│   ├── bracha-os/
│   ├── bracha-mining/
│   └── bracha-capital/
├── curadoria/                   <- Pipeline de conteudo
│   ├── pendentes/
│   └── processados/
├── skills/                      <- Skills da Clara
└── vault-sync/                  <- BRACHA OS vault (read-only)
```

### Onde colocar cada arquivo (decision tree)

```
Novo arquivo?
├── TODO ou pendencia ativa? -> Pendencias.md (root)
├── Tarefa com prazo? -> Tarefas.md (root)
├── Insight duravel (<100 linhas total)? -> MEMORY.md
├── Log do dia? -> memory/YYYY-MM-DD.md
├── Licao aprendida? -> knowledge/aprendizados/
├── Pipeline content (LinkedIn, blog)? -> knowledge/bracha-capital/
├── Lead, scorecard, ebook? -> knowledge/receita/
├── Processo judicial? -> knowledge/juridico/
├── Credencial, SSH, emergency? -> knowledge/infra/
├── Discord/Telegram digest? -> knowledge/comunidade/
├── Blog AI monitorado? -> knowledge/blogs/
├── Newsletter? -> knowledge/newsletters/
├── Briefing historico? -> knowledge/briefings/
├── Mensagem para Claude Code? -> knowledge/para-claude-code/
├── Plano estrategico? -> knowledge/planos/
├── Backup de config? -> knowledge/backups/
├── Projeto ativo? -> projects/<nome>/
├── Item de curadoria? -> curadoria/pendentes/ ou processados/
├── Consulta ao BRACHA OS? -> vault-sync/ (READ-ONLY, nunca escrever)
└── Nao sei -> knowledge/ (pasta mais proxima do tema)
```

---

## 2. Convencoes de Nomes

1. **kebab-case sempre:** `parecer-recurso-caso-xyz.md`, nunca `Parecer Recurso.md`
2. **Max ~50 caracteres** no nome (sem extensao)
3. **Sem versao no nome** — versao no frontmatter
4. **Datas no nome quando temporal:** `2026-03-24-discord-digest.md`
5. **Sem espacos, sem maiusculas, sem caracteres especiais**
6. **Pastas novas:** kebab-case, so criar dentro de `knowledge/` ou `projects/`

---

## 3. Frontmatter Obrigatorio

Todo arquivo no workspace (exceto bootstrap files e memory/) DEVE ter frontmatter YAML.

### Campos obrigatorios

```yaml
---
type: <tipo>                     # Ver taxonomia abaixo
status: active                   # active | draft | deprecated | archived
tags:                            # Min 1 dominio + 1 tipo (ver Secao 4)
  - dom-juridico
  - tipo-analise
domain: legal                    # ChromaDB collection (ver lista abaixo)
summary: "Sujeito + verbo + contexto. Max 100 palavras."
created: 2026-03-24              # YYYY-MM-DD
updated: 2026-03-24              # YYYY-MM-DD
---
```

### Campos condicionais (quando aplicavel)

```yaml
---
author: clara-staff              # Quem criou (default: clara-staff)
priority: alto                   # critico | alto | medio | baixo
related_to: [plano-mestre, scorecard]  # Grafo de conhecimento
consumers: ["[[clara-staff]]"]   # Quem deve ler (wikilinks, futuro multi-agent)
visibility: public               # public | agent-only | restricted
version: "1.0.0"                 # SemVer para docs versionados
aliases:                         # Nomes alternativos para busca
  - scorecard receita
---
```

### Document Types (`type`)

| type | Para que | Onde |
|------|----------|------|
| `briefing` | Resumo executivo, TL;DR | knowledge/briefings/, memory/ |
| `report` | Relatorio, digest, resumo periodico | knowledge/comunidade/, knowledge/blogs/ |
| `analysis` | Analise, avaliacao, pesquisa | knowledge/ (qualquer) |
| `plan` | Plano, estrategia, roadmap | knowledge/planos/, knowledge/receita/ |
| `reference` | Material de referencia, lookup | knowledge/infra/, knowledge/banco-canonico/ |
| `lead` | Lead, prospect, contato | knowledge/receita/leads/ |
| `legal` | Documento juridico, peticao, acordao | knowledge/juridico/ |
| `decision` | Decisao tomada, questao resolvida | knowledge/ (qualquer) |
| `template` | Template reutilizavel | knowledge/bracha-capital/templates/ |
| `learning` | Retro, licao aprendida | knowledge/aprendizados/ |
| `asset` | Entregavel publicado (ebook, post) | knowledge/bracha-capital/, projects/ |
| `draft` | Rascunho em progresso | knowledge/ (qualquer) |
| `data` | Dados brutos, dataset, export | knowledge/ (qualquer) |
| `task` | Acao pendente, lembrete | root (Pendencias.md, Tarefas.md) |
| `log` | Log diario, sessao | memory/, knowledge/sessoes/ |
| `digest` | Compilado periodico | knowledge/comunidade/, knowledge/newsletters/ |
| `pipeline` | Pipeline de vendas/conteudo | knowledge/bracha-capital/, knowledge/receita/ |

### Tabela Mestra de Dominios (pasta + domain + tag DEVEM estar alinhados)

Um arquivo em `knowledge/juridico/` **DEVE** ter `domain: legal` e tag `dom-juridico`. Nunca misturar.

| Pasta (`knowledge/`) | `domain` (ChromaDB) | Tag (`dom-`) | Collection |
|----------------------|--------------------|--------------|-----------|
| `juridico/` | `legal` | `dom-juridico` | clara-legal |
| `receita/` | `revenue` | `dom-receita` | clara-revenue |
| `bracha-capital/` | `corporate` | `dom-corporativo` | clara-corporate |
| `infra/` | `infra` | `dom-infra` | clara-infra |
| `comunidade/` | `community` | `dom-comunidade` | clara-community |
| `blogs/`, `newsletters/` | `research` | `dom-pesquisa` | clara-research |
| `aprendizados/` | `learning` | `dom-aprendizado` | clara-learning |
| `briefings/` | `personal` | `dom-pessoal` | clara-personal |
| `planos/` | `learning` | `dom-aprendizado` | clara-learning |
| `identidade/`, `backups/` | `infra` | `dom-infra` | clara-infra |
| `instagram/` | `content` | `dom-conteudo` | clara-content |
| `para-claude-code/` | `infra` | `dom-infra` | clara-infra |
| `sessoes/` | `learning` | `dom-aprendizado` | clara-learning |
| (projects/) | `corporate` | `dom-corporativo` | clara-corporate |
| (curadoria/) | `content` | `dom-conteudo` | clara-content |

Dominios sem pasta fixa (usados em qualquer `knowledge/` subpasta):

| `domain` | Tag | Quando usar |
|----------|-----|------------|
| `trading` | `dom-trading` | Trading AI, sinais, backtests |
| `personal` | `dom-pessoal` | Agenda, lembretes pessoais do Samuel |

**Regra de consistencia:** `related_to` no frontmatter cria grafo de conhecimento estruturado (lido por agentes). Wikilinks `[[]]` no corpo criam navegacao contextual (lido por humanos no Obsidian). Os dois coexistem sem conflito.

---

## 4. Taxonomia de Tags

Tags em 4 eixos. Prefixos evitam ambiguidade e facilitam ChromaDB.

**Regra:** todo documento recebe no minimo 1 `dom-` + 1 `tipo-`. `ciclo-` e `pri-` sao opcionais.

### DOMINIO (`dom-` — onde o assunto vive)

| Tag | Escopo |
|-----|--------|
| `dom-juridico` | Processos, jurisprudencia, contratos |
| `dom-receita` | Revenue, leads, pipeline vendas |
| `dom-conteudo` | Social media, blog, editorial |
| `dom-infra` | Servidores, credenciais, emergencias |
| `dom-comunidade` | Discord, Telegram, community |
| `dom-corporativo` | M&A, mining, negocios Bracha |
| `dom-pessoal` | Agenda, lembretes, pessoal Samuel |
| `dom-pesquisa` | Research, tendencias, AI news |
| `dom-aprendizado` | Licoes, retros, auto-melhoria |
| `dom-trading` | Trading AI, sinais, backtests |

### TIPO (`tipo-` — o que o documento faz)

| Tag | Natureza |
|-----|----------|
| `tipo-documento` | Registro formal (contrato, decisao judicial) |
| `tipo-analise` | Avaliacao, pesquisa, parecer |
| `tipo-relatorio` | Digest, resumo periodico |
| `tipo-plano` | Estrategia, roadmap, calendario |
| `tipo-referencia` | Material de consulta, lookup |
| `tipo-modelo` | Template reutilizavel |
| `tipo-lead` | Prospect, contato comercial |
| `tipo-tarefa` | Acao pendente, lembrete |
| `tipo-briefing` | Resumo executivo, TL;DR |
| `tipo-decisao` | Questao resolvida |
| `tipo-retro` | Licao aprendida, post-mortem |
| `tipo-rascunho` | Draft em progresso |
| `tipo-pipeline` | Pipeline de vendas/conteudo |
| `tipo-dado` | Dados brutos, dataset |

### CICLO (`ciclo-` — estagio no lifecycle, opcional)

| Tag | Significado |
|-----|-------------|
| `ciclo-inbox` | Chegou, nao triado |
| `ciclo-em-andamento` | Sendo trabalhado |
| `ciclo-revisao` | Aguardando aprovacao |
| `ciclo-aprovado` | Pronto para executar/publicar |
| `ciclo-concluido` | Feito, arquivado |
| `ciclo-pausado` | Aguardando input externo |
| `ciclo-cancelado` | Descartado |

### PRIORIDADE (`pri-` — urgencia, opcional)

| Tag | Significado |
|-----|-------------|
| `pri-critico` | Acao imediata (prazo judicial, server down) |
| `pri-alto` | Esta semana |
| `pri-medio` | Este mes |
| `pri-baixo` | Backlog |

**Total: 35 tags** (10 dominio + 14 tipo + 7 ciclo + 4 prioridade)

---

## 5. Formato de Escrita

### Regras de escrita (otimizacao RAG + Obsidian)

| Regra | Valor |
|-------|-------|
| 1 topico = 1 arquivo | Nota atomica |
| Tamanho ideal | 500-2.000 tokens |
| Split obrigatorio acima de | 3.000 tokens |
| Cada secao `##` autocontida | 150-600 tokens |
| Primeira frase nomeia o sujeito | Nunca "Este", "Isso" — nome do sujeito |
| H1 unico por arquivo | Titulo descritivo |
| Summary no frontmatter | "Sujeito + verbo + contexto" |

### Wikilinks — usar SEMPRE para referencias internas

```markdown
Conforme o [[plano-mestre|Plano Mestre de Receita]], ...
O lead [[lead-joao-silva]] foi qualificado em ...
Ver detalhes em [[scorecard|Scorecard de Receita]].
Licao registrada em [[aprendizados/erros-comuns|Erros Comuns]].
```

**Quando usar wikilinks:**
- Mencionou outro arquivo do workspace -> `[[nome-arquivo]]`
- Mencionou pessoa/empresa recorrente -> `[[nome]]` (cria breadcrumb)
- Mencionou decisao ou plano -> `[[nome-plano]]`

**Quando usar markdown links:**
- URL externa -> `[texto](https://...)`

### Callouts (para destaques visuais)

```markdown
> [!warning] Prazo judicial
> Audiencia em 48h. Preparar documentacao.

> [!tip] Oportunidade
> Lead qualificado com potencial de R$500k.

> [!info] Contexto
> Pipeline atualizado pelo cron de conteudo.

> [!danger] Urgente
> Servidor com disco >90%. Rodar rotacao de logs.
```

Tipos: `note`, `tip`, `warning`, `info`, `danger`, `success`, `failure`, `question`, `example`, `quote`, `bug`, `todo`, `abstract`.

### Tabelas

Sempre preceder tabelas com uma frase de contexto. Nunca comecar secao com tabela.

### Embeds (referenciar conteudo de outros arquivos)

```markdown
![[scorecard]]                    <- Embed arquivo inteiro
![[plano-mestre#Metas Q2]]       <- Embed secao especifica
![[imagem-clara.png|400]]        <- Embed imagem com largura
```

---

## 6. Memory Tiers

| Tier | Local | Comportamento | O que colocar |
|------|-------|--------------|---------------|
| **Tier 1** | `MEMORY.md` (root) | Carregado SEMPRE | Insights duraveis, max ~100 linhas |
| **Tier 2** | `memory/YYYY-MM-DD.md` | Auto hoje + ontem | Logs do dia, decisoes, eventos |
| **Tier 3** | `knowledge/` | Via embeddings (LanceDB) | Deep knowledge por dominio |

### Higiene de memoria

- **Diario:** append em `memory/YYYY-MM-DD.md`
- **Semanal:** promover insights duraveis de daily logs -> MEMORY.md
- **Mensal:** audit MEMORY.md (cortar bloat, manter <100 linhas)
- **Ao arquivar:** mudar `status: archived` no frontmatter

---

## 7. Template Rapido

```markdown
---
type: analysis
status: active
tags:
  - dom-receita
  - tipo-analise
domain: revenue
summary: "Analise do pipeline de leads Q1 2026 identifica 3 gargalos no funil de conversao."
created: 2026-03-24
updated: 2026-03-24
related_to: [plano-mestre, scorecard]
---

# Analise Pipeline de Leads — Q1 2026

O pipeline de leads do primeiro trimestre apresenta 3 gargalos no funil de conversao.

---

## Gargalo 1 — Taxa de Resposta DM

A taxa de resposta nas DMs LinkedIn caiu de 15% para 8% em marco.
Causa provavel: mensagens longas. Ver [[templates/dm-linkedin-ia|Template DM IA]].

> [!tip] Acao sugerida
> Testar mensagem curta (2 linhas) na proxima batch.
```

---

## 8. Governanca de Tags

- **Nunca criar tag nova** sem adicionar a esta skill
- **Proposta de nova tag:** informar Samuel com nome (kebab-case, PT), eixo (dom/tipo/ciclo/pri) e justificativa
- **Max 40 tags total** — simplicidade > completude
- **Tags reservadas para futuro multi-agent:** `agent-ops`, `agent-content`, `agent-analyst` (nao usar ainda)

---

## 9. Tratamento de Excecoes

### Arquivo pertence a dois dominios

Escolher o dominio **primario** (onde o arquivo vive fisicamente). Registrar o secundario em `related_to` no frontmatter. Exemplo: um lead de M&A vive em `knowledge/receita/` com `domain: revenue`, e tem `related_to: [bracha-capital]`.

### Arquivo excede 3.000 tokens

Dividir em partes atomicas. Excecoes permitidas:
- **Contratos e peticoes** (`type: legal`) — manter inteiro, ChromaDB faz chunking automatico via MarkdownHeaderTextSplitter
- **Planos mestres** (`type: plan`) — manter inteiro se <5.000 tokens, senao dividir por secao

### Arquivos binarios (PDF, imagens, videos)

Arquivos nao-Markdown nao recebem frontmatter. Regras:
- **Imagens:** salvar em `knowledge/identidade/` (Clara) ou junto ao documento que referencia
- **PDFs:** salvar junto ao documento e criar um `.md` companion com frontmatter + summary do conteudo
- **Videos/audio:** nao armazenar no workspace — usar links externos

### Arquivos orfaos (sem frontmatter ou fora da estrutura)

Se encontrar arquivo sem frontmatter em `knowledge/`:
1. Adicionar frontmatter minimo (`type`, `status: draft`, `domain`, `tags`, `summary`)
2. Mover para a pasta correta se estiver fora do lugar
3. Registrar no log diario (`memory/YYYY-MM-DD.md`)

### Fluxo de arquivamento

Quando um documento e superado:
1. Mudar `status: archived` no frontmatter
2. **NAO mover** — manter na mesma pasta (ChromaDB filtra por status)
3. Adicionar callout no topo: `> [!warning] Arquivado — substituido por [[novo-doc]]`

---

## 10. Protocolo Multi-Agente (futuro)

Quando o split multi-agente acontecer (Clara, Ops, Content, Analyst), estas regras se aplicam:

### Autoria

Todo documento recebe `author: <agent-id>` no frontmatter. Cada agente so escreve em seu proprio workspace.

### Recursos compartilhados

Skills em `~/.openclaw/skills/` (shared) sao acessiveis por todos. Documentos em `knowledge/` sao do agente que os criou — outros acessam via `memory_search` (embeddings) ou `sessions_history`.

### Resolucao de conflitos

Se dois agentes precisam do mesmo documento:
1. O dono (author) tem prioridade de escrita
2. Outros agentes devem criar uma copia local ou referenciar via `related_to`
3. Em caso de conflito real, escalar para Samuel

### Comunicacao inter-agente

- **Clara -> Ops:** cron systemEvent com instrucao
- **Qualquer -> Clara:** announce delivery no canal principal
- **Handoff de tarefa:** escrever em `knowledge/para-<agent-id>/` do agente destino

### Tags de agente (reservadas)

Nao usar ate o split acontecer: `agent-ops`, `agent-content`, `agent-analyst`, `agent-clara`.

---

## 11. Evolucao desta Skill

Esta skill segue **SemVer** (Semantic Versioning):
- **PATCH** (1.1.X): correcoes menores, typos, clarificacoes
- **MINOR** (1.X.0): novas secoes, novos tipos/tags, expansoes
- **MAJOR** (X.0.0): mudanca de estrutura de pastas, breaking changes

### Processo de mudanca (RFC)

1. **Proposta:** descrever a mudanca desejada (nova tag, nova pasta, nova regra)
2. **Avaliacao:** verificar impacto em documentos existentes e crons
3. **Aprovacao:** Samuel aprova. Clara pode propor mas nunca auto-aprovar mudancas estruturais
4. **Implementacao:** atualizar SKILL.md + CHANGELOG.md + version no frontmatter
5. **Comunicacao:** registrar no log diario + notificar via canal principal

### Processo para novos dominios

Quando um novo dominio de negocio surgir:
1. Criar pasta `knowledge/<novo-dominio>/`
2. Adicionar na Tabela Mestra (Secao 3) — pasta + domain + tag
3. Atualizar tag taxonomy (Secao 4)
4. Bump MINOR version

### Revisao periodica

- **Trimestral:** revisar se tags estao sendo usadas (remover orfas)
- **Ao adicionar agente:** revisar bindings, crons e skills compartilhadas
- **Ao atingir 40 tags:** avaliar se alguma pode ser consolidada

### Anti-padroes (o que NAO fazer)

```
NAO: Nome Com Espacos.md          -> SIM: nome-com-espacos.md
NAO: frontmatter sem domain       -> SIM: sempre incluir domain
NAO: arquivo em knowledge/ sem tags -> SIM: min 1 dom- + 1 tipo-
NAO: tag nova sem registrar aqui  -> SIM: propor via RFC
NAO: misturar domain e pasta      -> SIM: consultar Tabela Mestra
NAO: status: archived + mover     -> SIM: archived in-place
NAO: PDF sem .md companion        -> SIM: criar .md com summary
```