O que o Faundr faz sozinho

Com o plugin instalado e a pasta ligada, o Faundr age em sete momentos de cada sessão do agente. Esta página mostra o que acontece em cada um deles.

Duas regras valem para tudo aqui:

• O Faundr nunca trava o agente por erro próprio. Se algo do Faundr falhar (sem internet, servidor fora do ar), ele sai em silêncio e anota o motivo em ~/.faundr/hook.log. O seu trabalho continua.
• Ele só age em pasta ligada. Fora de uma pasta com .faundr.json, o plugin fica quieto.

1. Quando a sessão começa

O Faundr monta um resumo do projeto e entrega ao agente antes do primeiro pedido. O resumo tem no máximo cerca de 10 mil caracteres e traz:

1. Onde parou a última sessão: os pedidos, os commits, as tarefas concluídas, o bilhete de passagem e a última resposta. Isso não entra quando a sessão é só a continuação de uma conversa resumida.
2. Regras do time, para seguir sempre, e decisões técnicas, para não propor alternativas sem você pedir. Se faltar espaço, entram as decisões da funcionalidade atual e as mais recentes.
3. Quem mais está no projeto agora, e em quais arquivos.
4. Aviso de orçamento, se o gasto passou do limite de alerta definido em Insights → Custo.
5. Pedidos, recados e notas do time escritos no painel. Cada um é entregue uma vez só.
6. Lembretes agendados: skills e workflows que o time marcou para um horário que já chegou.
7. A funcionalidade atual e o checklist dela.
8. Os workflows ativos do time, e as skills e workflows marcados para rodar no início da sessão.
9. Preocupações abertas e o que está aberto em segurança, erros, qualidade e testes (por extenso, só o que é novo desde a sessão anterior). O lembrete de qualidade vem junto, se estiver ligado.

Junto vão orientações para o agente registrar o trabalho, consultar o mapa do código (se ele existir) e seguir o design.md (ou sugerir criar um, se o projeto tem telas e não tem guia).

2. A cada pedido seu

Cada pedido vai para o diário da sessão. Isso roda em segundo plano e não atrasa o agente.

Antes de o agente ler o pedido, o Faundr junta avisos curtos, sem usar a internet, cada um só quando vale:

• o pedido parece trabalho novo de vários passos: sugere planejar antes com /faundr:planning;
• o pedido parece uma regra ("a partir de agora", "nunca"): sugere registrar como regra do time;
• o pedido bate com o assunto de um workflow do time ou de uma skill ligada: lembra o agente de usá-los;
• regras e decisões sobre o assunto do pedido, cada uma uma vez por sessão;
• quem mais está mexendo no projeto, quando o time mudou desde o último aviso;
• pedidos e recados que chegaram do painel ou de outras sessões.

No primeiro pedido da sessão, o Faundr também dispara, de uma vez e em segundo plano:

3. Antes de o agente editar um arquivo

Antes de cada gravação ou edição de arquivo, o Faundr confere o conteúdo novo, no seu computador e sem internet:

• Chave secreta no código (Stripe, service_role do Supabase, AWS, chave privada, Google Cloud, OpenAI, Anthropic, GitHub, GitLab): a edição é barrada, e o agente é orientado a pôr o valor no .env e lê-lo pelo código. Em arquivos .env e de exemplo isso não vale. Em testes e documentação, e para chaves menos perigosas, o Faundr só avisa.
• Migração sem volta: se uma migração do banco apaga tabela ou coluna, esvazia tabela, muda todas as linhas, troca o tipo ou renomeia, o agente é avisado antes de gravar: pedir o seu OK, garantir um backup recente, escrever como desfazer e, se o app publicado ainda usa o que vai sumir, fazer em duas etapas.
• Ponto de volta: antes da primeira mudança da sessão, e de novo a cada 30 minutos de edições, o Faundr salva uma foto dos arquivos.
• Alerta de segurança: se a checagem em segundo plano achou um problema novo nos arquivos que o agente mexeu, ele é avisado e pergunta a você se corrige.
• Regra contrariada: se a edição traz um padrão proibido por uma regra do time, o agente é avisado.
• Regras e decisões do arquivo: as que valem só para aquele arquivo chegam antes da primeira edição dele na sessão.
• Quem mais mexe ali: se outra sessão do time está mexendo no mesmo arquivo, o agente é avisado. Pelo mapa do código, ele também fica sabendo que outras partes usam aquele arquivo, antes de mudá-lo.
• Detector de loop: se o mesmo erro voltou 3 vezes seguidas, ou se o arquivo vai ser mudado pela 7ª vez enquanto um comando continua falhando, o agente é orientado a parar, explicar a você o que está acontecendo, procurar a causa e sugerir /faundr:undo.

4. Antes de o agente rodar um comando

Antes de cada comando de terminal (e de cada SQL rodado pelas ferramentas do Supabase), o Faundr confere o que ele faz. Os detalhes estão em Proteção contra desastres. Em resumo:

• o que não tem volta é barrado;
• o que é arriscado faz o agente pedir a sua confirmação;
• pacote que não existe é barrado, e pacote suspeito pede confirmação;
• antes do primeiro comando que pode mudar arquivos, um ponto de volta é salvo.

5. Depois de cada ação do agente

• Diário: cada ação vai para o diário da sessão.
• Mapa do código: um arquivo editado marca o mapa como desatualizado. Ele é refeito no fim da resposta.
• Erros: depois de cada comando de checagem (build, tipos, testes, lint, scripts), o Faundr lê a saída. Falha vira um E-n em Erros. Quando o mesmo comando volta a passar, o erro fecha sozinho. Comandos como git, grep e o servidor de desenvolvimento ficam de fora.
• Eventos: um commit, um push ou um deploy que deu certo, e um erro novo, ficam anotados. No fim da resposta, o Faundr pede as skills e os workflows que o time ligou nesse evento (veja Workflows).
• Commits: um git commit bem-sucedido tira a marca "sem commit" das tarefas concluídas antes dele.
• Planos: um plano aprovado no modo de planejamento do agente vira uma funcionalidade com checklist e passa a ser a atual.
• Listas de tarefas: as listas de tarefas que o agente monta durante o trabalho viram tarefas da funcionalidade atual.

6. No fim de cada resposta

Duas coisas acontecem.

Em segundo plano, sem segurar nada:

• os tokens da conversa são somados e enviados ao Insights (só os números, nunca o texto);
• se a resposta mudou arquivos: o mapa do código é refeito, a segurança e a qualidade são checadas de novo só nos arquivos editados, o design é checado de novo se alguma tela mudou, e a lista de pontos de volta é atualizada.

A conferência do fim, que pode pedir ao agente para continuar. Se faltar algo, o Faundr segura o encerramento e pede, numa lista:

1. Pedido do painel que chegou enquanto o agente trabalhava: tratar antes de encerrar.
2. Registrar o trabalho. A sessão mudou 4 ou mais arquivos e nada foi registrado no Faundr: se foi uma funcionalidade ou uma etapa, registrar o que foi feito. Uma vez por sessão.
3. Prova de que funciona. O código mudou e nenhuma checagem passou depois disso: o agente deve rodar o build, os testes, a checagem de tipos ou o app e contar o resultado. Se não der para rodar, deve dizer. Só é pedido se o projeto tem algo para rodar.
4. Bilhete de passagem. Só em sessões grandes (4 ou mais arquivos editados, ou uns 20 minutos de edições), e de novo a cada 30 minutos.
5. Revisão rápida de design das telas editadas. Só se o projeto tem design.md, e só citando os problemas novos.
6. Critério de pronto, quando o checklist da funcionalidade terminou.
7. Próxima etapa: anunciar a próxima e perguntar se segue, ou registrar as etapas que faltam.
8. Stack desatualizada: atualizar, uma vez por sessão.
9. Skills e workflows do time marcados para o fim das respostas que mexem em certos arquivos, ou para um evento (commit, push, deploy, erro novo).
10. Resultado de uma skill conectada: se rodou uma skill sua que acha problemas, registrar o que ela achou e corrigiu. Veja Workflows.
11. Visão desatualizada: atualizar, uma vez por sessão.

O pedido do painel, os eventos e as skills conectadas valem mesmo quando a resposta não mudou arquivos. O resto só aparece se a sessão mudou arquivos.

Depois dos passos, o agente escreve a resposta final completa: repete o que você precisava saber da resposta anterior (resultado, pendências, perguntas) junto com o que os passos mudaram.

Esta conferência não muda código sozinha: ela só pede ao agente. E não se repete em seguida, para não prender o agente num ciclo.

7. Quando a sessão termina

A sessão é marcada como encerrada no diário e os números finais de uso são enviados. Se esse envio se perder (o computador desligou, a internet caiu), ele é reenviado no começo da próxima sessão.

O que dá para ligar e desligar

Os bloqueios de comandos e de chaves e as checagens de segurança ficam sempre ligados numa pasta ligada. Os outros passos de cada momento têm um interruptor em Configurações → Automações (os mesmos ficam no desenho de cada um, em Workflows → Do Faundr). Desligado, o passo para de rodar para todo o time a partir do próximo pedido.

O Modo econômico, em Configurações → Geral, desliga de uma vez a revisão rápida de design e a atualização da Visão e da Stack no fim das respostas. Elas passam a rodar só quando você pede.

Para desligar tudo, desative o plugin (/plugin) ou trabalhe numa pasta não ligada.

Algumas partes têm controle próprio: