Imported from gabrielkfive/gest-odeagencia (
AGENTS.md). Install upstream withnpx skills add gabrielkfive/gest-odeagencia. Copyright stays with the author.
AGENTS.md · como um agente de IA trabalha no WorkFlowArk
Regras para qualquer agente (Claude Code, Codex, Hermes) que mexe neste repositório. Segurança vem antes de tudo: o sistema guarda a operação real da ARK (clientes, CRM, tarefas, financeiro) e está sendo anunciado para agências de fora.
Antes de começar
git pulle trabalhar em worktree a partir deorigin/mainquando a pasta principal tiver alteração de outra sessão.- Ler, nesta ordem:
docs/PRD.md,docs/ARCHITECTURE.md,docs/DESIGN_SYSTEM.md,CLAUDE.md(guardrails de operação) especs/system.mdse mexer em sync. - Procurar componente, módulo ou teste parecido antes de criar um novo.
Regras de segurança (inegociáveis)
- Toda autorização é no servidor. Esconder aba no front não protege nada. Quem não pode
ver um bloco
wfa-*não recebe esse bloco no GET e não grava no POST (verpodeVerBlocoemsrc/routes/api/workflowark.state.ts). - Conta nova fica pendente. Quem cria conta sem convite entra com
active: falsee não lê nada até o admin liberar. Regra única emsrc/lib/acesso.js, teste emdeploy/teste-acesso.mjs. Nunca voltar a "entra na hora como viewer". - Não existe multi-agência ainda. Todo dado mora numa tabela só (
workflowark_state). Não dar acesso de teste a agência de fora dentro desta instância. Teste externo só em instância separada ou depois do isolamento portenant_id(ver PRD, fora de escopo). - Segredo só em variável de ambiente do Worker (
wrangler secret), nunca no código, nopublic/, em log, em commit ou em resposta de API. Blocoswfa-*-secret,wfa-*-oauthewfa-portal-tokensnunca voltam do servidor para o navegador. - Rota pública precisa de dono explícito. Rota sem login (portal, aprovação, lead-site, webhooks) valida entrada, limita tamanho, usa token criptográfico e só grava o bloco que precisa. Rota nova sem login exige revisão de segurança antes do deploy.
- Validar toda entrada (tipo, tamanho, formato) e responder erro genérico; detalhe só no log do servidor, sem dado pessoal.
- Dado de cliente real não sai do sistema: print de landing, demo e material de venda usam agência e clientes fictícios. Nome de cliente real só com autorização do Gabriel.
- Nada criado sozinho: agente não cria tarefa, cartão, notificação ou mensagem para cliente sem aprovação humana. Robô prepara, fila recebe, humano aprova.
Regras de código
- Lógica nova em módulo puro (
src/lib/*.js) com teste emdeploy/teste-*.mjsescrito antes. - Arquivo do app com data no nome: mudou o conteúdo, renomeia (
git mv), troca a referência no HTML e o marcador<!-- build AAAAMMDDx-tag -->. - Lista sincronizada nova entra em
WFA_CLOUD_KEYS,STATE_KEYSe, se tiver id, nas chaves de mescla.npm run teste:mergeenode deploy/teste-chaves-sync.mjsprovam. - Texto de interface e de documento em português simples, sem travessão.
Comandos
npm ci instala
npm run build tem que passar antes de qualquer deploy
node deploy/teste-acesso.mjs regra de conta nova
npm run teste:mobile obrigatório ao mexer no public/workflowark.html
npm run teste:confiabilidade obrigatório ao mexer em tarefa, arrasto ou sync
npm run teste:arrastar
npm run teste:merge
Fronteiras (pedir aprovação do Gabriel antes)
- Mudar papel, permissão, RLS, rota pública ou qualquer regra de acesso.
- Adicionar dependência nova ou serviço externo.
- Deploy em produção: sempre commit + push (o CI publica), conferir
gh run liste o marcador na URL real antes de dizer que está no ar. - Apagar dado, chave de estado ou membro.
