Skip to content

Commit 9512524

Browse files
committed
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.
1 parent 5576b38 commit 9512524

1 file changed

Lines changed: 99 additions & 3 deletions

File tree

‎docs/spec.md‎

Lines changed: 99 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ botloft/
6565
crates/
6666
botloft-core/ tipos de domínio, IDs, erros, render de envelope, tipos do protocolo
6767
botloft-store/ SQLite: conexão, migrations, repositórios
68-
botloftd/ binário do daemon (rpc, supervisor, runtime, chat, courier, tools, platform)
68+
botloftd/ binário do daemon (rpc, supervisor, runtime, chat, courier, tools, platform) e, em catalog/, as fichas dos modelos de bot (26)
6969
app/
7070
src/ React (o app e, em src/setup/, a tela de instalação)
7171
src-tauri/ shell nativa
@@ -568,7 +568,9 @@ Transporte: Streamable HTTP, só POST e resposta `application/json`, sem sessão
568568
| `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 |
569569
| `complete_task` | `task_id`, `result`, `status?` (`done` padrão, `failed`) | `task_id`, `status` e quem recebe o resultado |
570570
| `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 |
572574
| `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) |
573575
| `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) |
574576
| `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
629631
- **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.
630632
- **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.
631633
- **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.
632635
- Bots criados assim são bots comuns: o dono conversa, muda, pausa e arquiva cada um como qualquer outro.
633636

634637
### 10.3 Bots que se mudam
@@ -682,6 +685,9 @@ Endpoint: `ws://127.0.0.1:45710/rpc`. Mensagens seguem JSON-RPC 2.0: requests co
682685
| `bots.list` | `crewId?` | `Bot[]` |
683686
| `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) |
684687
| `bots.create` | `crewId, name, role, instructions, color?, model?` | `Bot` |
688+
| `catalog.list` | `category?` | `BotTemplate[]`: os modelos de bot do catálogo, sem as instruções (26.4) |
689+
| `catalog.get` | `id` | `BotTemplateFull`: o modelo com `instructions`, `model` e `effort` (26.4) |
690+
| `catalog.add` | `crewId, templateId, name, role` | `Bot`: cria na equipe um bot a partir do modelo (26.4) |
685691
| `bots.update` | `botId, name?, role?, instructions?, color?` | `Bot` |
686692
| `bots.setPaused` | `botId, paused` | `Bot` |
687693
| `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/
835841
features/
836842
onboarding/ checagens (claude instalado e versão, daemon rodando) e instalação do serviço
837843
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)
838845
bots/ conversas na barra lateral, criar, editar, estado, detalhes
839846
chat/ conversa com o bot: itens, texto ao vivo, aprovações, compositor com anexos
840847
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
9971004

9981005
### 15.6 Idiomas
9991006

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.
10011008
- Componentes leem com `useT()`; código fora do React (toasts, formatação, erros da conexão) com `t()` na hora do uso.
10021009
- 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>`.
10031010
- 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
10981105
9. Navegador dos bots, com o dono assistindo ao vivo. Desenho na seção 21.
10991106
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`.
11001107
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.
11011109

11021110
## 19. Pontos a verificar na versão alvo do Claude Code
11031111

@@ -1924,3 +1932,91 @@ Login por navegador de servidor remoto (o `/mcp` do Claude Code), ferramentas li
19241932
| **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 |
19251933
| **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 |
19261934
| **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

Comments
 (0)