andresanemic/lore-plugin

create-bot — Construa um bot: um lugar instalável para trabalhar

Cria um bot: uma pasta que é ao mesmo tempo um plugin do Claude Code, um projeto Lore e o local onde uma sessão de trabalho é aberta. Um bot não responde perguntas sobre os projetos — ele trabalha neles. A instrução entra, o bot a executa contra arquivos reais, o resultado volta.

O norte, e o único teste que importa: uma instrução curta é o suficiente. Se o projeto tivesse que ser explicado ao bot para obter o resultado, critérios estavam faltando na carga.

O que um bot é, e o que não é

create-bot é um irmão de create-project, não de create-area. O caminho padrão é bots/proyectos/{slug}/ — bots é a área que hospeda bots, da mesma forma que uma área web hospeda sites. Se essa área ainda não existir, create-area a cria primeiro, exatamente como para qualquer outro projeto. Outra área pode hospedar um bot quando o usuário disser; não assuma isso.

	Área	Projeto	Bot
Contém	projetos	uma parte do trabalho	uma sessão de trabalho
Seu Lore governa	o método do domínio	aquele trabalho	como o agente se comporta
Aberto para	ver o registro	avançar aquele trabalho	trabalhar em vários projetos

Um bot é o único artefato neste kit que roteia para fora. Áreas e projetos são lugares; um bot é uma lente que você leva para dentro deles.

Um bot não é automaticamente um plugin. Por padrão, é uma pasta com seu cânon e seu CLAUDE.md: abra uma sessão lá e o critério já está carregado, sem nada instalado. Empacotá-lo em um skill com .claude-plugin/ e seu próprio repositório é um selo opcional (§10) que serve a um propósito — entregá-lo a uma equipe. Para uma pessoa trabalhando sozinha, é um andaime que ainda precisa ser mantido.

Por que não deve ser uma área. Uma área é um contêiner de projetos e é dona dos critérios de seu domínio. Um bot não é dono de nenhum critério para o qual roteia — ele o toma emprestado. Construí-lo como uma área cria um pai que acumula critérios que nunca pagou, e a primeira consequência aparece rápido: quando um critério se generaliza, ele é promovido para o bot em vez de para a área que o mereceu.

Dois modos

Modo	Quando	O que produz
nuevo	Do zero. Não há Lore anterior para reunir.	Cânon nascido de uma chuva de ideias + documentos-fonte.
federar	O critério já existe, disperso em várias áreas.	Cânon mais uma cópia sincronizada e uma tabela de roteamento sobre esses corpos de Lore.

Ambos produzem o mesmo artefato. federar adiciona scripts/ecosistema.json, scripts/sync.js e dois arquivos gerados: lore/enrutamiento.md (a tabela de roteamento) e .claude/settings.local.json (o acesso às árvores vivas). Não copia nada, a menos que a cópia esteja ativada (§7).

Quando o bot já existe

Ambos os modos acima constroem do zero, e essa não é a única maneira como este skill é invocado. Ele também é apontado para um bot já na árvore — para corrigir seu escopo, reescrever seu README, adicionar uma fonte. Execute a auditoria abaixo em vez de o procedimento de criação, depois retorne ao §7 (sincronização), §10 (empacotamento) e §11 (verificação).

Verificação	Como	Falha quando
Escopo	Compare cada entrada do manifesto contra o registro da instituição	Uma fonte é roteada que o registro não lista
Fronteiras	Leia a declaração de fora de escopo do cânon	Um projeto limítrofe está faltando, ou está listado sem motivo para a confusão
Órfãos	ls o destino da sincronização contra o manifesto — somente se a cópia estiver ativa	Uma pasta sobrevive cuja fonte não está mais no manifesto
Cópia	Pergunte quem usa o bot e se eles têm a árvore	lore-ecosistema/ está ativo para pessoas que compartilham a árvore de pastas — é duplicação sem leitor
README	Leia-o como o público, não como o autor	Argumenta o método, ou seus exemplos são sobre projetos que o bot não atende mais
Instalação	Execute os comandos, não os leia	Foram escritos de memória ou copiados de um bot público
Portão	node scripts/validar.js, se o bot estiver empacotado	Qualquer coisa menos saída 0

A auditoria não é um procedimento mais leve. Ela encontra o que uma construção nova não consegue: o desvio entre o que o bot foi construído para atender e o que atende agora, que é exatamente o que ninguém redescobre por conta própria.

Quando uma fonte ainda não tem Lore

O ponto de partida comum não é um conjunto arrumado de corpos de Lore. É matéria-prima: pastas de documentos, uma base de código, um banco de dados, um espaço de trabalho do Notion — nada disso destilado. Esse material não pode ser federado, e a correção é uma cadeia, não um atalho:

fonte bruta (sem Lore)
   └─ create-area        → a área de trabalho que será a DONA deste critério
        └─ transmute-lore (add)  → recupera o critério já disperso dentro dela
             └─ create-bot (federar)  → o bot roteia para ela

A lei: o bot nunca destila dentro de si. Uma fonte sem Lore obtém seu Lore na área que a possui, e só então é federada. Deixar o bot destilar matéria-prima diretamente o torna dono de critérios que nunca mereceu — a falha precisa que a distinção área/bot existe para prevenir, e é irreversível na prática: uma vez que a única cópia daquele critério vive no bot, a área não pode mais ser sua fonte da verdade.

Concretamente, no passo 2 abaixo, inventarie cada fonte antes de projetar qualquer coisa. O inventário tem duas perguntas, e a posse vem primeiro.

Primeira pergunta: isso pertence à instituição?

O escopo de um bot vem do registro da instituição que ele atende, nunca da árvore de pastas da máquina em que está sendo construído.

Antes de perguntar se uma fonte tem Lore, pergunte de quem é ela. Abra o próprio registro da instituição — seu FASES.md, seu catálogo, sua carta — e confirme que a fonte está listada lá. Se não estiver listada, ela não entra no manifesto.

Por que esta é a primeira barreira e não uma verificação posterior: a falha é silenciosa. Um manifesto preenchido percorrendo a árvore de projetos do construtor produz uma tabela de roteamento que parece completa e internamente consistente enquanto está errada, e ninguém a redescobre depois. Proximidade no disco é confundida com pertencimento institucional uma vez, e a partir daí é herdada.

Uma fonte limítrofe é declarada, nunca meramente omitida. Um projeto que compartilha pessoas com a instituição, que aparece em sua vitrine pública, ou que foi o próprio primeiro caso de uso do bot parecerá que pertence. Coloque-o no cânon como explicitamente fora de escopo, com a razão pela qual se confunde. Uma fronteira escrita com sua razão se mantém; uma que é apenas omitida é cruzada novamente na próxima vez que alguém olhar a árvore de pastas.

Segunda pergunta: em que estado está seu Lore?

Estado da fonte	O que fazer
Tem Lore, em uma área	Federar diretamente.
Tem critérios mas não tem Lore (um projeto nascido sem ele)	transmute-lore add nesse projeto primeiro. O critério é resgatado, nunca inventado.
Matéria-prima, nenhuma área a possui ainda	create-area para o domínio, depois transmute-lore add, depois federar.
Não é texto (um banco de dados, uma planilha, uma base do Notion)	Extrair para texto primeiro — dump de esquema, exportação, pdftotext -layout. A extração cai na fuente/ daquela área, nunca no bot. sync.js só copia .md, .txt e .json, então qualquer coisa não extraída fica silenciosamente invisível para o bot.
Uma caixa de entrada de notas livres (um cofre do Obsidian notas/, uma pasta de Markdown)	Nunca federado. Não contém Lore — é experiência bruta, e é .md, que é exatamente o que torna o erro fácil: sync.js o copiaria feliz e a tabela de roteamento listaria notas como se fossem critérios. Mine-o com obsidian-lore primeiro; o que sobreviver cai na área que o possui, e o bot roteia para essa.

Reporte este inventário ao usuário como parte da chuva de ideias, com o custo honesto: cada fonte sem Lore é uma execução de create-area/transmute-lore antes que o bot possa existir. Propor pular isso e "destilar tudo no bot" é mais rápido e produz um artefato que não pode ser mantido.

Pré-condição

A área alvo existe e seu lore/ tem pelo menos identidad.md + principios.md. Se não tiver, pare e proponha create-area primeiro — um bot herda o método da área como qualquer projeto.

Regra de idioma: escreva TUDO gerado — conteúdo E nomes de artefatos — no idioma do usuário, não no idioma em que este skill está escrito. identidad.md, principios.md, FASES.md, proyectos/, canon/, enrutamiento.md são as formas canônicas em espanhol: localize-as. Fixos em todos os idiomas: CLAUDE.md, lore/, index.md, skills/, .claude-plugin/. Os nomes estabelecidos da área vencem dentro de sua árvore; sinalize um conflito, nunca o resolva silenciosamente.

---

A lei que este skill existe para aplicar

Um bot contém três corpos de critérios com três donos diferentes. Mesclá-los é o modo de falha padrão, e é silencioso: tudo ainda funciona, e a cópia lentamente começa a superar sua fonte.

Corpo	O que é	Regra
skills/{slug}/canon/	critérios que o bot é — carregados antes de cada decisão	destilado; viaja dentro do skill
lore/	critérios para manter o bot	o próprio do projeto, como qualquer projeto
critérios emprestados	o Lore de todos os outros projetos	alcançado por ponteiro, em seu próprio endereço; nunca autoritativo

Três nomes porque três donos. O teste que os mantém separados:

A fonte seria descartável? Destilar produz algo menor que pode substituir sua origem. Copiar produz algo idêntico que não pode.

Critérios emprestados são alcançados por ponteiro, não por cópia. A tabela de roteamento dá o endereço, o acesso gerado o abre, e aquele Lore mantém um dono e uma versão — a mesma regra DRY que o resto do kit executa, onde um projeto referencia os módulos de sua área em vez de duplicá-los. lore-ecosistema/ (§7) transforma esses ponteiros em uma cópia para uma situação apenas, e está desligado por padrão.

E a lei que faz o roteamento funcionar:

Roteie por tipo de tarefa, não por nome de projeto.

Uma entidade pode possuir vários corpos de critérios cujos próprios princípios proíbem cruzá-los. A divisão comum é o que faz versus como conta — produto contra comunicações — e se mantém quer a entidade seja um único projeto ou a instituição que o bot atende. Nomeá-lo não seleciona um Lore: a instituição aparece duas vezes na tabela de roteamento, de propósito. Se uma tarefa for ambígua entre duas, pergunte — é mais barato do que seis parágrafos escritos contra o critério errado.

Escreva esta seção a partir da entidade que o bot realmente atende. A tabela de roteamento é a peça que um leitor verifica contra seu próprio caso, e um exemplo trazido de outro bot os envia para o Lore errado enquanto parece autoritativo.

---

Procedimento

1. Pergunte ao usuário — três perguntas, em linguagem simples

Fale claramente. Este documento é denso porque instrui um modelo. A conversa com o usuário não é. Ao usar este skill, não diga cânon, federar, destilar, limite de validade, pista invariante, anti-escopo ou Entre. Diga o que significam: o que o bot sempre sabe, conecte-o a, os critérios que vale a pena manter, onde isso deixa de ser verdade, uma regra, para que não serve. Se uma frase precisar de um glossário, reescreva a frase.

Pergunte uma de cada vez, e receba as respostas nas próprias palavras do usuário:

1. ¿Cómo se va a llamar el bot?
2. ¿Para qué lo vas a usar? — texto livre. Não o arrume; será relido depois para verificar se uma tarefa corresponde ao que foi declarado.
3. ¿Dónde están las carpetas con la información que le va a servir? — peça caminhos. Pastas, bancos de dados, despejos de documentos, notas. Aceite "no sé todavía" e continue: um bot pode ser criado com uma fonte e crescer.

Todo o resto é derivado dessas três, ou lido do disco. Não interrogue o usuário por isso:

Derivado	De
{{BOT_SLUG}}	o nome, em kebab-case; este também é o nome do skill, se for empacotado
{{BOT_TITLE}}	o nome conforme fornecido
{{AREA_PATH}}	a área bots por padrão — proponha-a, confirme em uma linha
{{MODE}}	federar se houver fontes existentes, nuevo se não houver nenhuma
{{PURPOSE}}	resposta 2, ipsis litteris
{{SOURCE_DOCS}} / {{ECOSYSTEM}}	resposta 3, após inspecionar cada caminho no disco

Em seguida, inspecione os caminhos você mesmo e reporte o que encontrou em uma tabela curta — quantos arquivos, quais já têm critérios escritos, quais são brutos. Esse relatório é o que transforma a resposta 3 no inventário do passo 2. Nunca peça ao usuário para classificar suas próprias pastas.

2. Leia o contexto (OBRIGATÓRIO antes de criar qualquer coisa)

1. O Lore da área: identidad.md + principios.md (+ index.md e módulos temáticos).
2. A área FASES.md, e qualquer bot irmão já registrado lá.
3. Os documentos-fonte. Para um PDF, extraia texto (pdftotext -layout). O cânon é destilado destes — nunca do próprio conhecimento do modelo sobre o tópico.
4. federar apenas — inventarie as fontes primeiro (veja a tabela acima). Classifique cada fonte pretendida por se já tem Lore, e traga à tona aquelas que precisam de create-area / transmute-lore antes que o bot possa federá-las. Faça isso antes da chuva de ideias: isso muda o que o bot pode rotear no primeiro dia.
5. federar apenas: leia cada corpo de Lore para o qual pretende rotear. Você precisa de seu propósito e seu anti-escopo — o anti-escopo é o que lhe diz onde a fronteira entre dois irmãos corre, e a fronteira é a única coisa aqui que é genuinamente destilável.

3. Chuva de ideias do cânon (BLOQUEIO DURO)

Invoque brainstorming. Não crie nenhum arquivo antes que o design seja aprovado. Mantenha a regra de linguagem simples do §1 em vigor aqui — apresente o design no

…

[truncado para tradução]