You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9512524
Browse filesBrowse the repository at this point in the historyBrowse files
docs(spec): bot catalog (section 26), chief tools and suggest_bot template
Ready-made bot roles the owner can browse and add to a crew, and the chief can read and suggest from. 12 first roles, written from scratch (no text from other agent projects). Daemon holds the English sheets and instructions; the app holds the owner-facing text in en, pt-BR and es.
botloftd/ binário do daemon (rpc, supervisor, runtime, chat, courier, tools, platform) e, em catalog/, as fichas dos modelos de bot (26)
69
69
app/
70
70
src/ React (o app e, em src/setup/, a tela de instalação)
71
71
src-tauri/ shell nativa
@@ -568,7 +568,9 @@ Transporte: Streamable HTTP, só POST e resposta `application/json`, sem sessão
568
568
|`send_message`|`to` (handle, com ou sem `@`), `crew?` (outra crew, 10.4), `body`, `kind?` (`note` padrão, `task`), `deadline_minutes?` (só task) |`message_id`, `task_id` e `due` (task), e um lembrete de que a resposta chega depois |
569
569
|`complete_task`|`task_id`, `result`, `status?` (`done` padrão, `failed`) |`task_id`, `status` e quem recebe o resultado |
570
570
|`my_tasks`|`role?` (`assigned`, `requested`) | tasks `open` e `expired`: id, de, para, status, prazo relativo, hops e o pedido original |
571
-
|`suggest_bot`|`name`, `role`, `instructions` (até 8 000 caracteres), `model?`, `effort?`, `reason` (até 1 000) |`created` e, criado, `handle`, `name`, `role`, `model`, `effort` e um lembrete para mandar a primeira task; recusado ou sem resposta, o porquê (10.2). Só o chefe |
571
+
|`suggest_bot`|`name`, `role`, `instructions` (até 8 000 caracteres), `model?`, `effort?`, `reason` (até 1 000), `template?` (um id do catálogo, 26.4: com ele `role` e `instructions` ficam opcionais) |`created` e, criado, `handle`, `name`, `role`, `model`, `effort` e um lembrete para mandar a primeira task; recusado ou sem resposta, o porquê (10.2). Só o chefe |
572
+
|`list_bot_templates`|`category?`|`templates`: `id`, `category`, `name`, `role` e `summary` de cada modelo de bot do catálogo (26). Só o chefe |
573
+
|`get_bot_template`|`id`| a ficha de um modelo: os campos acima, `model`, `effort` e `instructions` (26.2). Só o chefe |
572
574
|`schedule_routine`|`name`, `prompt` (até 8 000 caracteres), `schedule` (como em 20.2), `bot?` (handle de outro bot da crew) |`created` e, criada, `routine_id`, nome, pedido, horário, fuso e a próxima vez; recusada ou sem resposta, o aviso de que nada foi agendado (20.12) |
573
575
|`ask_crew_access`|`crew` (nome da outra crew), `bot?` (handle de um bot dela), `access` (`talk`, `read`, `edit`), `why` (até 1 000) |`allowed` e, permitido, como usar; recusado ou sem resposta, o porquê (10.4) |
574
576
|`crew_files`, `read_crew_file`, `write_crew_file`|`crew`, e `bot?`, `path` ou `path` e `content`| os arquivos de outra crew que o bot alcança, o texto de um, ou o aviso de que gravou (10.4) |
@@ -629,6 +631,7 @@ Toda crew nova nasce com um **chefe**: `crews.create` com `lead` cria a crew e e
629
631
-**Aprovação:** a sugestão vira um pedido no chat do chefe, pelo mesmo caminho das aprovações (10.1): `approval` com `toolName: "mcp__botloft__suggest_bot"`, entrada até 64 KB e resumo com o nome sugerido. O chefe fica `needs_approval`, e a chamada MCP espera a resposta até `approval_timeout_minutes`. A tool vem liberada por `--allowedTools mcp__botloft`, então o Claude Code não pede permissão antes: quem decide é o dono, pelo cartão.
630
632
-**Resposta:** permitir cria o bot na crew do chefe, com modo Manual e o modelo e o esforço sugeridos. O dono pode mudar nome, papel, modelo, esforço e instruções antes: `approvals.answer` leva `input`, o JSON da sugestão como ele deixou, que substitui a entrada gravada (o cartão mostra o que foi criado); `input` só vale para sugestões de bot e pedidos de rotina (20.12). Negar volta ao chefe com a nota do dono, e nada é criado. Sem resposta no prazo, o chefe lê que pode sugerir de novo depois. O bot novo sobe na hora e aparece na barra lateral, com o próprio chat; o resultado da tool lembra o chefe de mandar a primeira task.
631
633
-**Chefe em `bypass_permissions`:** a sugestão cria o bot na hora, sem cartão, como tudo o que esse modo faz sem perguntar (13). O resultado diz ao chefe que foi criado sem pedir.
634
+
-**Catálogo:** antes de escrever instruções do zero, o chefe olha os modelos de bot (`list_bot_templates`, `get_bot_template`) e, se um serve, sugere com `template` (26.4). O cartão e a resposta não mudam: o dono vê, e pode editar, os mesmos campos.
632
635
- Bots criados assim são bots comuns: o dono conversa, muda, pausa e arquiva cada um como qualquer outro.
|`archive.list`||`{crews, bots}`: o que está arquivado, que `crews.list` e `bots.list` deixam de fora, do arquivado mais recente ao mais antigo. `bots` traz todos os bots arquivados, também os das crews arquivadas (7.6) |
|`bots.setPermissionMode`|`botId, mode` (`default`, `accept_edits`, `plan`, `auto`, `bypass_permissions`) |`Bot`; o bot reinicia no novo modo quando nada estiver em andamento (7.4) |
@@ -835,6 +841,7 @@ app/src/
835
841
features/
836
842
onboarding/ checagens (claude instalado e versão, daemon rodando) e instalação do serviço
837
843
crews/ lista, criar, renomear, pausar; página da crew com timeline e tasks
844
+
catalog/ modelos de bot: a tela de explorar, "Saber mais" e "Adicionar na equipe" (26.5)
838
845
bots/ conversas na barra lateral, criar, editar, estado, detalhes
839
846
chat/ conversa com o bot: itens, texto ao vivo, aprovações, compositor com anexos
840
847
files/ painel dos arquivos que o bot fez: lista, prévia, abrir
@@ -997,7 +1004,7 @@ Identidade: o mascote do Botloft é uma chama com olhos. O ícone do app (`app/a
997
1004
998
1005
### 15.6 Idiomas
999
1006
1000
-
- O app fala **inglês, português (Brasil) e espanhol**. Todo texto que o dono lê fica em `app/src/i18n/<idioma>/`, um arquivo por área (`common`, `shell`, `onboarding`, `updates`, `bots`, `chat`, `crews`, `messages`, `setup`). O inglês é a referência: o formato dele é o tipo `Messages`, e um texto que falte ou sobre em outro idioma não compila. Texto com valores é função (`ready(version)`), com o plural escrito para cada idioma.
1007
+
- O app fala **inglês, português (Brasil) e espanhol**. Todo texto que o dono lê fica em `app/src/i18n/<idioma>/`, um arquivo por área (`common`, `shell`, `onboarding`, `updates`, `bots`, `catalog`, `chat`, `crews`, `messages`, `setup`). O inglês é a referência: o formato dele é o tipo `Messages`, e um texto que falte ou sobre em outro idioma não compila. Texto com valores é função (`ready(version)`), com o plural escrito para cada idioma.
1001
1008
- Componentes leem com `useT()`; código fora do React (toasts, formatação, erros da conexão) com `t()` na hora do uso.
1002
1009
- Escolha na área da conta (Idioma, ou Configurações), e no botão de idioma da barra de título só nas telas de preparo: "Idioma do sistema" segue o Windows (o primeiro idioma suportado entre os preferidos; `pt-PT` vira `pt-BR`; nenhum, inglês) ou um idioma fixo. A escolha fica no `localStorage` do app (`botloft.locale`) e marca `<html lang>`.
1003
1010
- Datas e horas (`lib/format.ts`) usam o idioma escolhido.
@@ -1098,6 +1105,7 @@ M2 a M4 foram entregues com ConPTY, terminal com replay, inbox por named pipe e
1098
1105
9. Navegador dos bots, com o dono assistindo ao vivo. Desenho na seção 21.
1099
1106
10. Bots vendo e usando os apps abertos no desktop do dono, com permissões por app ou do desktop inteiro. Desenho na seção 24 e em `docs/adr/0002-desktop-use.md`.
1100
1107
11. Ferramentas conectadas: o dono liga servidores MCP próprios (LinkedIn, sistemas internos) a bots escolhidos, sem tirar o `--strict-mcp-config`. Desenho na seção 25.
1108
+
12. Catálogo de bots: modelos prontos de função (Designer, Pesquisador...) que o dono explora e adiciona à equipe, e que o chefe usa para sugerir bots com instruções melhores. Desenho na seção 26.
1101
1109
1102
1110
## 19. Pontos a verificar na versão alvo do Claude Code
1103
1111
@@ -1924,3 +1932,91 @@ Login por navegador de servidor remoto (o `/mcp` do Claude Code), ferramentas li
1924
1932
|**E1** Cadastro e arquivo | tabelas, `mcp.save`/`mcp.servers`/`mcp.delete`/`bot.mcp.set`, segredos em `secrets\mcp`, `mcp_json` com os servidores, ambiente do bot, reinício | unidade; supervisor com `FakeRuntime` conferindo o `mcp.json` e o ambiente; bot sem ligação não vê nada |
1925
1933
|**E2** Aprovação e estado |`permission_prompt` para `mcp__<slug>__*`, "Permitir sempre" por ferramenta (e a limpeza ao excluir ou renomear), estado por `mcp_status`| courier e chat com `FakeRuntime`; manual (PR): um servidor `stdio` de teste e outro `http` com o Claude Code real |
1926
1934
|**E3** App | Ferramentas conectadas nas Configurações, chaves nos detalhes do bot, diálogo de conectar com a confirmação, três idiomas |`FakeBotloft`; `pnpm check`; a tela no preview |
1935
+
1936
+
## 26. Catálogo de bots
1937
+
1938
+
### 26.1 O que é
1939
+
1940
+
Quem abre o Botloft pela primeira vez tem uma equipe com o chefe e mais nada, e muitas vezes não sabe que bots criar. E o chefe, ao sugerir um bot (10.2), escreve as instruções do zero, na hora, com o que sabe daquela conversa. Esta seção traz um **catálogo de modelos de bot**: funções prontas ("Designer", "Pesquisador"), cada uma com instruções bem escritas, que servem a dois leitores.
1941
+
1942
+
-**O dono** explora uma lista, lê o que cada bot faz e adiciona o que quiser à equipe, já com instruções boas. Depois o bot é um bot comum, que ele personaliza.
1943
+
-**O chefe** consulta o mesmo catálogo por tool e sugere o bot a partir de um modelo, com instruções melhores do que as que escreveria sozinho.
1944
+
1945
+
O catálogo é uma lista fixa que vem dentro do app, sem rede e sem conta. Não é uma loja nem aceita contribuição do dono nesta etapa (26.7).
1946
+
1947
+
**Autoria.** As fichas são escritas do zero para o Botloft, a partir do que cada função faz na prática e das tools que os nossos bots têm. Nenhum texto vem de outro projeto de agentes (CLAUDE.md, "Regra de autoria"). Se uma ficha vier a ser baseada em material externo, isso é decidido à parte e a atribuição vai para o `NOTICE`.
1948
+
1949
+
### 26.2 A ficha
1950
+
1951
+
Uma ficha por arquivo em `crates/botloftd/catalog/<id>.toml`, embutida no binário do daemon. O `id` é o nome do arquivo (`[a-z0-9-]{1,32}`, como `code-reviewer`).
1952
+
1953
+
```toml
1954
+
category = "code"# code, design, content, research, business
1955
+
name = "Code Reviewer"# em inglês; o app escreve o nome no idioma do dono (26.5)
1956
+
role = "Reviews other bots' code changes and points out bugs and risks"
1957
+
summary = "Reads changes and says what is wrong, risky or too complicated"
1958
+
model = "default"# como em bots.setModel
1959
+
effort = "high"# como em bots.setEffort
1960
+
instructions = """
1961
+
...
1962
+
"""
1963
+
```
1964
+
1965
+
-**Quem lê o quê.** O daemon guarda a ficha em inglês, que é o que o chefe lê e o que o bot recebe. O texto que o **dono** lê (nome, função, resumo e a explicação "Saber mais") fica em `app/src/i18n/<idioma>/catalog.ts`, nos três idiomas, por `id` (15.6: o daemon não escreve texto para o dono). Um `id` sem texto no idioma do app cai no inglês da ficha; um teste do app falha se faltar texto num dos três idiomas para algum arquivo do catálogo.
1966
+
-**Instruções.** Em inglês, até **4 000 caracteres**, para sobrar espaço para o que o chefe acrescenta (26.4) dentro do limite de 8 000 de 7.4. Estrutura fixa: uma linha dizendo quem o bot é; "responda na língua em que o dono escreve"; o que ele faz; como trabalha, em passos curtos; o que entrega e em que forma (um arquivo pronto vai ao chat com `share_file`); o que pergunta ao dono antes de fazer (`ask_owner`); como trabalha com os outros (tasks por `send_message`, pedir ao chefe um especialista que falta). Nada de personalidade de enfeite, de exemplo de código longo nem de tool que os bots não têm: só se cita o que todo bot tem (`share_file`, `ask_owner`, `send_message`, o navegador, as telas) e, quando o dono tiver ligado uma ferramenta conectada (25) para aquilo, "use-a".
1967
+
-**Dado pessoal.** Toda ficha diz que o que o bot lê no trabalho é privado: não o copia para mensagens a outros bots além do que a tarefa pede (13).
1968
+
-**Sem "Claude".** O texto não cita o nome do modelo nem do programa, só "você" e o papel.
1969
+
-**Um teste vigia a forma** (`catalog_lint`): campos presentes e válidos, `id` igual ao nome do arquivo, instruções até 4 000 caracteres e todas as seções, categoria conhecida, e a lista do código igual aos arquivos da pasta (uma ficha esquecida na lista falha o teste).
1970
+
1971
+
### 26.3 Os 12 primeiros papéis
1972
+
1973
+
`model` e `effort` ficam `default`, como em todo bot novo, exceto onde a coluna diz.
1974
+
1975
+
|`id`| Categoria | O que faz |
1976
+
|---|---|---|
1977
+
|`developer`|`code`| Escreve e muda código, roda os testes e explica o que mudou |
1978
+
|`code-reviewer`|`code`| Lê o que outro bot fez e aponta erros, riscos e o que dá para simplificar, sem editar (`effort``high`) |
1979
+
|`qa-tester`|`code`| Testa o que foi feito, tenta quebrar e devolve os passos para repetir cada problema |
1980
+
|`designer`|`design`| Desenha telas e peças em HTML na área de design (22) e ajusta com o que o dono pedir |
1981
+
|`writer`|`content`| Escreve textos (artigos, e-mails, páginas) no tom do dono |
1982
+
|`social-media`|`content`| Propõe ideias, calendário e posts por rede; nunca publica sozinho |
1983
+
|`translator`|`content`| Traduz e adapta mantendo o tom, e avisa onde a tradução perde algo |
1984
+
|`researcher`|`research`| Pesquisa na web pelo navegador (21), confere as fontes e entrega um resumo com links e o que não achou |
1985
+
|`data-analyst`|`research`| Lê planilhas e dados, calcula, mostra a conta e explica o que achou, com gráficos numa tela HTML |
1986
+
|`sales-prospector`|`business`| Acha e qualifica contatos e rascunha as mensagens; nada é enviado sem o dono |
1987
+
|`customer-support`|`business`| Responde dúvidas com base no material que o dono deu e passa adiante o que não sabe |
1988
+
|`personal-assistant`|`business`| Organiza tarefas, resume o que o dono precisa ler e rascunha e-mails; agenda e e-mail só com ferramenta conectada (25) |
1989
+
1990
+
### 26.4 Daemon: protocolo e tools
1991
+
1992
+
-**Tipos** em `botloft-core`, exportados por `ts-rs`: `BotTemplate` (`id`, `category`, `name`, `role`, `summary`) e `BotTemplateFull` (os mesmos mais `model`, `effort` e `instructions`).
1993
+
-**Métodos** (11.2): `catalog.list {category?}`, `catalog.get {id}` (`-32002` se não existe) e `catalog.add {crewId, templateId, name, role}`. O app passa `name` e `role` já no idioma do dono, como faz com o chefe (10.2); o daemon põe as instruções, o modelo e o esforço da ficha. `catalog.add` valida como `bots.create` (nome livre na crew, papel numa linha, crew ativa e com menos de `max_per_crew` bots) e cria o bot em modo Manual, sem ferramentas conectadas e sem acesso a outras crews. Nada na ficha dá permissão a mais.
1994
+
-**Tools do chefe** (10): `list_bot_templates` e `get_bot_template`. Aparecem para todos os bots, mas só o chefe pode usar, como `suggest_bot`. O resultado é JSON em texto, e um `id` desconhecido volta com `isError`.
1995
+
-**`suggest_bot` com `template`.** Com `template`, `role` e `instructions` ficam opcionais: o papel vem da ficha se faltar, e as instruções são as da ficha, seguidas, se o chefe mandou `instructions`, de uma linha em branco e "For this crew:" com o que ele escreveu. `model` e `effort` vêm da ficha se faltarem. O limite de 8 000 vale para o texto final. O cartão de aprovação (10.2) mostra o que será criado, e o dono pode editar tudo antes, como hoje.
1996
+
-**Regras do chefe** (5.1): olhe o catálogo antes de escrever instruções do zero; use `template` quando a função serve; acrescente em `instructions` só o que é daquela equipe; não invente papel que o catálogo já tem.
1997
+
1998
+
### 26.5 App
1999
+
2000
+
-**Onde aparece.** (1) Numa equipe que só tem o chefe, a página da equipe mostra o catálogo como convite: "Quem você quer na sua equipe?". (2) Em qualquer equipe, um botão "Explorar bots" ao lado de criar bot abre a mesma tela. Ela é sempre da equipe aberta.
2001
+
-**Tela.** Uma grade de cartões, com filtro por categoria e busca por nome e resumo (no idioma do app). Cada cartão tem o nome ("Designer"), uma linha dizendo o que o bot faz, e dois botões: **Adicionar na equipe** e **Saber mais**.
2002
+
-**Saber mais** abre um painel com o texto de `catalog.ts`: o que faz, quando chamar, com quem combina e o que vale ligar (por exemplo uma ferramenta conectada). Em "Detalhes", como o resto do que é técnico (15.6), ficam as instruções do bot (somente leitura, em inglês), o modelo e o esforço: o dono pode ler o que o bot vai receber. O painel tem também o botão de adicionar.
2003
+
-**Adicionar** cria na hora, sem diálogo, com o nome do idioma do dono (se já existe na equipe, "Designer 2") por `catalog.add`. Um aviso diz que o bot entrou na equipe, com "Personalizar", que abre os detalhes do bot, onde o dono muda nome, função, instruções, modelo e o resto como em qualquer bot. O catálogo não muda, e o dono pode adicionar a mesma função de novo.
2004
+
-**Textos** nos três idiomas (15.6), sem jargão: "bot" e "equipe", nunca "template", "prompt" ou "daemon", e descrevendo o bot pelo nome, não por "Claude".
2005
+
2006
+
### 26.6 Segurança e privacidade
2007
+
2008
+
- Um modelo só preenche campos que o dono já edita; não liga ferramenta, não muda o modo de permissão e não dá acesso a outra crew.
2009
+
- O catálogo não tem dado do dono, não usa a rede e não entra no `backup` (14.2): vem com o app. Os bots criados entram, como qualquer bot.
2010
+
- As instruções são texto nosso e público; não passam por nenhum log a mais do que as de qualquer bot (13).
2011
+
2012
+
### 26.7 Fora desta etapa
2013
+
2014
+
Mais de 12 papéis (a lista cresce depois, uma ficha por vez); o dono criar, importar ou compartilhar fichas; **restaurar o padrão** de um bot criado de um modelo (pede guardar o `id` do modelo no bot, e o histórico de instruções do item 5 da seção 18 cobre melhor); marcar no catálogo o que já está na equipe; atualizar bots já criados quando uma ficha muda (eles foram personalizados); modelos de equipe inteira; indicar ferramentas conectadas por papel de forma automática.
2015
+
2016
+
### 26.8 Marcos
2017
+
2018
+
| Marco | O que entra | Teste |
2019
+
|---|---|---|
2020
+
|**G1** Catálogo e daemon | formato da ficha, `catalog.rs`, as 12 fichas, `catalog.list`/`get`/`add`, tipos `ts-rs`|`catalog_lint`; unidade e RPC: `catalog.add` valida como `bots.create`, cria em Manual com modelo e esforço da ficha, nome repetido e crew cheia recusam |
2021
+
|**G2** Chefe |`list_bot_templates`, `get_bot_template`, `template` em `suggest_bot`, regras do chefe | tools com `FakeRuntime`: só o chefe, `id` desconhecido, junção de `instructions`, limite de 8 000; manual (PR): pedir ao chefe real "preciso de alguém para as redes sociais" e ver o cartão |
2022
+
|**G3** App | tela de explorar, "Saber mais", "Adicionar na equipe", convite na equipe só com o chefe, textos nos três idiomas |`FakeBotloft`; teste de que toda ficha tem texto nos três idiomas; `pnpm check`; a tela no preview. Manual (PR): criar cada um dos 12 com o Claude Code real e dar a cada um uma tarefa típica |
0 commit comments