# Brain Keeper

> When the user wants to ingest sources, change brain pages, register decisions, catalog content publications, or lint brain pages for provenance and link integrity.

- **Type:** Skill
- **Install:** `agentstack add skill-agencia-conversion-agentic-seo-skills-brain-keeper`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agencia-conversion](https://agentstack.voostack.com/s/agencia-conversion)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [agencia-conversion](https://github.com/agencia-conversion)
- **Source:** https://github.com/agencia-conversion/agentic-seo-skills/tree/main/skills/brain-keeper
- **Website:** https://github.com/agencia-conversion/seo-brain

## Install

```sh
agentstack add skill-agencia-conversion-agentic-seo-skills-brain-keeper
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Brain Keeper

You are the steward of the Agentic SEO `project/brain/`. The brain is the only authorial knowledge layer of the project: the canonical pages `index`, `identity`, `voice`, `technology`, `topic-clusters`, `review`, `log` plus one subpage per active topic cluster in `topic-clusters/.md`. `log.md` is the append-only chronicle. Editorial areas (strategic macro layer) live as H2 sections inside `topic-clusters.md` above the auto-generated cluster index — the old standalone `brain/editorial.md` was consolidated there in 2026-05-26. There is no separate `wiki/` layer. The brain is read by every Agentic SEO skill as initial context. The editorial review rules (universal + project-specific) live in `brain/review.md`; this skill references that page instead of duplicating it.

## When To Use

Use this skill when the user asks to ingest a source, change or propose a brain page update, register a decision, catalog a published content, or lint brain pages for provenance, contradictions, broken wikilinks, or gaps.

Do not use this skill to draft strategic content from scratch, run keyword research, build topic clusters, write content, run technical SEO audits, or publish content. Those workflows produce evidence that this skill catalogs through `log.md`.

## Critical Points

Hard rules for every brain-keeper run.

- Every substantive change, proposal, lint, ingestion, or publication registration must leave a Web Companion review target. If an authorial page changed, point to that `project/brain/.md`; if the run only proposes or lints, write a summary under `project/workbench/brain-keeper/.md` or `.yaml`. Return `companion_path`, `companion_slug`, and `browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você revisar esta entrega?", artifact_path: "", open_with: "project-browser" }`. Human approvals that already require a specific handoff (`approve-cluster`, `approve-page`, `review-changes`) keep using that handoff, but the resulting artifact still needs a Companion target.

**Migração de handoffs (status).** Os antigos handoffs HTTP (`scripts/companion.mjs ` em `127.0.0.1`) estão sendo movidos para a superfície do Web Companion. `collect-env`, `approve-cluster` e `dataforseo-bypass` migram para o Companion (credenciais em Settings → Credenciais; aprovação/promoção de cluster e bypass nas telas do Companion). `approve-briefing`, `approve-page`, `review-changes` e `pick-cluster` permanecem atrás de uma flag, com plano documentado de migração. O código de handoff NÃO é removido (outros fluxos ainda o referenciam) — apenas deprecado e documentado.

## Boundaries

Allowed writes:
- `project/brain/log.md` — append entries.
- `project/sources/**` — only to capture a newly provided raw source exactly as received.
- `project/workbench/brain-keeper/**` — drafts of proposed changes, lint reports, contradiction notes.
- `project/contents/**` — register a published content with the canonical frontmatter.

Authorial brain pages (`index`, `identity`, `voice`, `technology`, `topic-clusters`, `topic-clusters/`, `review`) may be written directly when the change is backed by evidence and a `type: decision` entry is appended to `log.md`. For `review.md` specifically: minor stylistic additions (new IA-slop term, new Conversion-explainer verb, recurring typo) are auto-applied with `approver: agent`; checklist changes (new editorial principle, new entry in "Erros comuns observados") are proposed as `type: lint` and wait for human approval before editing the page.

Creating a NEW topic cluster subpage (`brain/topic-clusters/.md` for a cluster that does not yet exist) requires explicit human approval through the Companion `approve-cluster` handoff. Updating an existing subpage (resync the contents table after `content-seo promote`, refresh the resumo, mark a satellite `retired`) is auto-applied with `approver: agent` and a `type: decision` log entry. An explicit user request always overrides this gate — when the user delegates promotion, record `approver: `.

Never modify existing files in `project/sources/**`. Never reuse a wikilink that points to a non-existent page. Never fabricate keyword volume, backlinks, credentials, awards, clients, quotes, proof, or decisions.

## Brain-First Protocol

For any request that would change a brain authorial page:

1. Capture any working draft or review note in `project/workbench/brain-keeper/.md` when useful.
2. Apply the brain page change only with cited evidence or explicit `gap` markers.
3. Append a log entry: `type: decision`, `scope: `, `decision: `, `evidence: `, `approver: agent` or a human name.

For operational events (source ingestion, lint result, content publication, correction, technical decision without strategic impact, evidence cataloging), append the log entry directly with `approver: agent` (or the human's name if a human triggered it). The corresponding non-authorial change (sources/, contents/) is applied immediately.

## Regra editorial

The canonical seat of editorial review rules is `brain/review.md`. Read that page before reviewing any prose written into `brain/` or `contents/`. The page carries the universal rules (lead in the first sentence, visible attribution, anti-IA-slop, anti-Conversion-explainer, pt-BR accents) plus project-specific particularities that grow over time.

If `brain/review.md` is missing or carries only placeholders for the project-specific sections, the universal rules embedded in the page template still apply; record `review_backed: false` in the review artifact and surface the limitation. Conflicts between a project-specific item and a universal rule resolve in favor of the universal rule, with a `type: lint` entry flagging the contradiction.

## Wikilinks e Markdown links

Use Obsidian Wikilinks `[[...]]` only for real files inside `project/brain/`. Use Markdown links for `../sources/`, `../contents/`, and external URLs. A Wikilink that resolves to a non-existent file is a hard lint failure (see `Lint mínimo`).

**Fonte autoral vs. fonte interna.** O brain é a voz da própria marca falando de si mesma. Frases como "a home afirma", "o site diz", "o artigo X defende" tratam a marca como objeto narrado e estão proibidas no corpo de qualquer arquivo autoral. A procedência interna vai sempre para a seção `## Evidência` no rodapé da página, com link. Veja `## Lint editorial` abaixo para a regra completa.

**Stack observado vs. tese editorial (regra dura).** `technology.md` contém **APENAS fatos técnicos observados** do site analisado (stack, CMS, framework, headers, JSON-LD, renderização, sinais de performance). NUNCA opinião editorial, posicionamento de mercado, tese de marca ou valores da empresa. Guia observado vs. opinião — observado (entra em `technology`): "Next.js + Vercel, SSR, schema `Article`". Opinião ("a marca defende Next.js", "preferimos sites estáticos", "stack moderna é diferencial"): roteie para `identity`, `topic-clusters` ou conteúdos publicados em `contents/` — NUNCA em `technology.md`.

**Brain Index.** `index.md` é uma porta de entrada autoral: começa em prosa, resume as páginas centrais e aponta para elas. Ao resumir `[[technology]]`, use apenas tecnologia observada do site da marca. Não descreva o Companion, o plugin, tokens locais, rotas internas, testes automatizados ou `cluster-sync` como se fossem a stack do site, exceto quando o projeto analisado for explicitamente o próprio Companion.

**Lexicons.** As listas de termos por idioma vivem em `skills/brain-keeper/references/lint-lexicon..json` (`pt-br`, `en`). O idioma ativo vem de `project/.agentic-seo/project.json.language`. Idiomas sem lexicon recebem só checks language-agnostic e um `warn` listando o que foi pulado.

## Schema do log

Append entries with this shape:

```markdown
## YYYY-MM-DD - 

- type: approval | decision | correction | lint | ingestion | publication | evidence
- scope: 
- decision: 
- evidence: 
- approver: 
- approved_at: 
- notes: 
```

## Schema de topic-clusters

`brain/topic-clusters.md` is a short index: dashboard `## Painel` with totals and a `## Clusters ativos` table that lists each cluster (wikilink to subpage, area, pillar link, cobertura). It does not contain per-cluster tables of conteúdos.

Each active cluster has its own subpage `brain/topic-clusters/.md` with frontmatter limited to `title` and `updated`, followed by `# `, prose `Resumo`, `## Pilar` (markdown link to the published content or `_slug-italico_` for planned), `## Conteúdos` (Markdown table with columns `Papel | Conteúdo | Intent | Status | Ação | Atualizado`), `## Próximas ações`, `## Evidência`. Published conteúdos appear as markdown links to `../../contents//.md`; planned conteúdos appear as `_slug-italico_` without link. Status is closed (`publicado | planejado | a-revisar | descontinuado`); ação is closed (`manter | revisar | criar | avaliar`).

The cluster operational source of truth is `project/clusters//cluster.yaml`. Draft clusters live as `project/clusters//draft.yaml` and never touch the brain.

## Schema de conteúdo público

Files in `project/contents//.md` require frontmatter:

```yaml
---
title: ""
slug: ""
published_at: ""
source_url: ""
origin: "blog | linkedin | podcast | other"
clusters:
  - 
role:                      # opcional; preenche quando o papel for explícito por cluster
  : pillar | satellite
---
```

`clusters:` must list one or more slugs that exist as folders in `project/clusters//`. Empty array blocks promote. `area:` (singular) is legacy and gradually removed; treat it as a fallback when `clusters:` is missing.

## Conteúdo consumível (no-gap rule)

Hard rule. Brain pages, conteúdos públicos e logs são consumidos por outros agentes (Claude Code, sub-agents Agentic SEO, futuras sessões). Cada arquivo precisa ser auto-suficiente quando lido fora do contexto que o gerou.

**Nunca deixar placeholders, `gap`, ``, `TODO`, "a confirmar", "a definir", `[?]`, células vazias de tabela ou estruturas declaradas sem conteúdo.** Se a evidência não está disponível, faça uma das três coisas, nessa ordem:

1. Buscar a evidência (scrape adicional, provider call, leitura de fonte existente) e preencher.
2. Reescrever a seção para descrever o que foi observado e omitir o item que não tem suporte. Não escrever "não foi observado X" como linha solta. Quando o item não cabe, ele simplesmente não entra.
3. Mover o item para `log.md` como `type: decision` explicando a omissão e o critério para reintroduzir o item depois. O arquivo autoral em si fica limpo.

Estruturas obrigatórias do schema brain (`identity`, `voice`, `technology`, `topic-clusters`, `review`, `index`) podem omitir subseções inteiras quando não há base. O que não pode é manter o cabeçalho com `gap` no corpo, célula de tabela vazia, ou linha "Para quem não fala: `gap`".

Aplicar a regra em:
- Brain pages.
- Conteúdos publicados em `contents/`.
- Workbench drafts que vão virar publicação.
- Reports do Web Companion (`relatorios///report.md`).

Logs (`log.md`) podem citar lacunas observadas como `type: lint` ou `type: decision`, com critério para reintroduzir.

**Documentos autossuficientes (regra dura).** Todo arquivo escrito em `project/` (páginas do Cérebro, reviews, reports, conteúdos) precisa ser autossuficiente quando lido fora do contexto que o gerou e **NUNCA** pode embutir URLs de runtime — `localhost`, `127.0.0.1` ou rotas do Web Companion (ex.: `.../project//brain-review`). Essas URLs são efêmeras (token único, porta efêmera, expiram). Cite URLs públicas ou evidência relativa na seção `## Evidência`, nunca uma URL de debug do Companion.

## Lint editorial

Run before declaring done in any change to an authorial brain page (`identity`, `voice`, `technology`, `topic-clusters`, `index`) and to `contents//.md`. Does not run on `log.md`, `sources/`, or `workbench/`. Severity `block` interrupts the run with `status: blocked`; severity `warn` is logged as `type: lint` and the author decides.

Lexicons per language live in `skills/brain-keeper/references/lint-lexicon..json`, loaded by `project/.agentic-seo/project.json.language`. Languages without a lexicon get only language-agnostic checks plus a `warn` listing skipped checks.

### Order

Lexical pass first (cheap, regex), semantic pass second. A `block` in the lexical pass stops execution before the semantic pass.

**Lexical pass:**
1. `editorial.brain.accents` (V8) — block. Lexicon `accents`.
2. `editorial.brain.no-em-dash` (V7) — block in prose.
3. `editorial.brain.no-ai-slop` (V6) — block. Lexicon `ai_slop`.
4. `editorial.brain.no-blog-tutorial-voice` (V5) — block. Lexicon `blog_tutorial`.
5. `editorial.brain.no-promo-adjectives` (V4) — block when no external source on the same paragraph or in adjacent `## Evidência`. Lexicon `promo_adjectives`.

**Semantic pass:**
6. `editorial.brain.no-source-description` (V1) — block in authorial pages; excluded inside `## Evidência` and in `log.md`. Lexicon `source_description`.
7. `editorial.brain.aposto-shape` (V2) — warn when aposto exceeds 12 words or contains enumerative list; block above 20 words. Heuristic: first proper-noun aposto per section.
8. `editorial.brain.technology-descritivo` (V3) — block in `technology.md` only. Lexicon `technology_editorial_verbs`.

### Standing rules

- Pre-fill check: any file in `brain/` that still contains `` and `` sentinels; the index between `` and ``. Manual edits inside sentinels are silently overwritten by sync.
- No two log entries share the same `## YYYY-MM-DD - ` heading.
- Fenced code, inline code, URLs, wikilinks, and YAML frontmatter are excluded from lexical lint passes.

### Commands — `cluster-sync`, `cluster-doctor`, `cluster-rename`, `cluster-retire`

The Topic Clusters subsystem is governed by `docs/specs/topic-clusters-contract.md` (contract_version 1, plugin 0.2). Read that document first before editing cluster artifacts.

- `node scripts/cluster-sync.mjs [--cluster=] [--check] [--dry-run]` — recomputes the materialized table between sentinels in each `brain/topic-clusters/.md` and the index, from the union of (a) `clusters:[]` in each `contents/**/*.md` frontmatter, (b) `pillar` and `planned_satellites[]` in `cluster.yaml`, and (c) `satellite_overrides`. Idempotent. Preserves authorial prose. Conflicts surface as lints (`content.cluster-missing`, `cluster.unique-pillar`, `cluster.pillar.divergence`, etc.). `--check` returns exit 1 on any block lint or pending change; used by pre-commit. Trigger after `content-seo promote`, after `topic-cluster` Phase 4 promotion, or via explicit request.
- `node scripts/cluster-doctor.mjs` — read-only diagnostic. Prints lints without writing.
- `node scripts/cluster-rename.mjs --from= --to=` — atomic rename across YAML + frontmatters + brain.
- `node scripts/cluster-retire.mjs --slug= [--reassign-to=]` — remove cluster preserving contents.
- `node scripts/install-cluster-sync-hook.mjs --apply` — installs pre-commit hook that runs `cluster-sync --check`.

The Web Companion also fires `cluster-sync --cluster=` server-side after `POST /api/project/file` saves any `contents//.md` or `clusters//cluster.yaml`.

### Failure record

For each violation, append a single entry to `project/brain/log.md`:

```
## YYYY-MM-DD - lint editorial em 

- type: lint
- scope: 
- decision: bloqueio editorial — 
- evidence: linha , trecho: ""
- approver: agent
- notes: sugestão de correção — 
```

Multiple violations in the same file in the same run group under one entry with a list in `notes`.

### Message to the user when blocked

Be factual and propositive. Cite line, ID, excerpt, suggestion, and an active exit. Avoid "erro", "inválido", "rejeitado".

```
Bloqueei a alteração em brain/identity.md por 2 violações editoriais antes de aprovar:

1. Linha 14 — "a home afirma que a marca é referência…" — descrição de fonte interna (editorial.brain.no-source-description).
   Sugestão: "A marca opera consultoria de SEO para empresas brasileiras." Mover o link da home para ## Evidência.
2. Linha 22 — "

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agencia-conversion](https://github.com/agencia-conversion)
- **Source:** [agencia-conversion/agentic-seo-skills](https://github.com/agencia-conversion/agentic-seo-skills)
- **License:** MIT
- **Homepage:** https://github.com/agencia-conversion/seo-brain

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-agencia-conversion-agentic-seo-skills-brain-keeper
- Seller: https://agentstack.voostack.com/s/agencia-conversion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.