Satlab Protocol

Repositório de skills para agentes (Claude Code, Cursor e ferramentas compatíveis). O núcleo é o SatLab Protocol: fluxo de engenharia full stack e agnóstico de stack e de tipo de projeto — pensado para qualquer codebase em que vocês trabalhem (backend, frontend, mobile, CLI, dados, etc.).

Para instalar no projeto via npm, use o pacote publicado: o comando npx @satlab/protocol init copia skills e regras, configura o Lexomni no mcp.json do IDE e oferece o setup do Context7 (npx ctx7 setup) de forma guiada — não é necessário instalar esses MCPs manualmente antes (basta seguir o assistente e reiniciar o IDE quando pedido). O conteúdo padrão (guidelines SatLab) para indexar no Lexomni vem do repositório satlab-lexomni e deve ser copiado ou baixado de lá, conforme as instruções desse projeto — não é embutido no @satlab/protocol.

Além do orquestrador, há sub-skills usadas só quando faz sentido: documentação de libs/APIs (Context7), refatoração em larga escala, revisão crítica de código e, só se a tarefa envolver interface web, diretrizes de frontend e revisão de UI.

Papéis

• Humano: dono de regra de negócio, prioridades, trade-offs, aceite e decisões arquiteturais que importam.
• Agente: executor técnico que segue o SKILL.md — especificação, testes, código, refatoração e revisão no formato do protocolo.

O que existe neste repositório

| Caminho (raiz do repo) | Conteúdo | |------------------------|----------| | skills/satlab-protocol/SKILL.md | Protocolo completo para o agente | | skills/satlab-protocol/templates.md | Modelos úteis para alinhar requisito, spec, ADR e plano (time + agente) | | rules/satlab-protocol.mdc | Regra Cursor/Claude (copiada para .cursor/rules ou .claude/rules pelo init) | | skills/satlab-protocol/context7-mcp/ | Skill auxiliar: docs atuais de libs/APIs via Context7 | | skills/satlab-protocol/large-scale-refactor/ | Refatorações grandes ou migrações estruturais | | skills/satlab-protocol/critical-code-review/ | Revisão de código em modo auditor | | skills/satlab-protocol/frontend-guidelines/ | Opcional: trabalho com UI web | | skills/satlab-protocol/web-design-guidelines/ | Opcional: revisão de UI e acessibilidade |

Instalação no projeto (recomendado): na raiz do projeto, rode npx @satlab/protocol init. O assistente copia skills/ e rules/ para .cursor/skills, .cursor/rules (ou equivalente .claude/...), integra o Lexomni ao mcp.json e pergunta se deseja rodar o Context7 na hora (use --skip-context7 para pular a pergunta). Em seguida, use o repositório satlab-lexomni para o conteúdo Lexomni SatLab (clone ou download).

Instalação

Via pacote npm (recomendado)

1. Na pasta do projeto ou pasta em comum entre projetos: npx @satlab/protocol init.
2. Conclua o menu (IDE, cópia de arquivos, Lexomni, Context7 opcional).
3. Reinicie o IDE e registre o skill satlab-protocol conforme a documentação do Cursor ou Claude Code.
4. Obtenha o conteúdo padrão Lexomni (SatLab) a partir do repositório satlab-lexomni — clone ou baixe o repositório e siga as instruções dele para copiar/configurar o material no Lexomni (índice e guidelines). Esse conteúdo não é distribuído dentro do @satlab/protocol.

Não é preciso instalar manualmente o servidor Lexomni nem o Context7 antes: o init cuida da entrada no mcp.json e do fluxo do Context7 quando você aceitar. O satlab-lexomni é só a fonte do material indexado no Lexomni, não o binário do MCP.

Manual (clone ou cópia deste repositório)

1. Clone o repositório ou copie a pasta desejada para o projeto.
2. Coloque as skills onde a ferramenta as carrega (ex.: ./.cursor/skills ou ./.claude/skills).
3. Registrem o skill satlab-protocol apontando para o SKILL.md correspondente, conforme a documentação do cliente (Cursor, Claude Code, etc.).
4. Nesse modo, configure Lexomni e Context7 à mão nos MCPs do IDE — veja a tabela abaixo e os links.
5. Use o repositório satlab-lexomni como fonte do conteúdo padrão (guidelines SatLab) a ser copiado ou baixado e ligado ao Lexomni, conforme o README do satlab-lexomni.

Dependências (MCPs)

Quem usa npx @satlab/protocol init já recebe o Lexomni aplicado no mcp.json e pode concluir o Context7 pelo próprio assistente. Os links abaixo servem como referência (documentação, troubleshooting ou instalação manual se você não usar o CLI):

| Ferramenta | Para quê | |------------|----------| | Lexomni (MCP) | Guidelines e referências do seu processo — instalação / uso | | Context7 (MCP) | Documentação atual de bibliotecas e APIs — instalação |

Conteúdo padrão Lexomni (SatLab)

O material padrão de guidelines e documentos SatLab para o Lexomni não fica embutido neste repositório nem no pacote npm: deve ser obtido a partir do repositório satlab-lexomni — clone ou baixe esse projeto e siga as instruções dele para disponibilizar o conteúdo ao Lexomni (cópia, caminhos e indexação).

O init apenas registra o servidor MCP Lexomni no IDE; carregar o índice SatLab a partir do satlab-lexomni é um passo separado, descrito no próprio repositório satlab-lexomni e na documentação do Lexomni.

Detalhes de quando e como o agente usa cada MCP estão no SKILL.md e nas sub-skills.

Como proceder

• Seja explícito no pedido: problema, comportamento esperado, o que conta como pronto e o que está fora de escopo. O agente vai pedir o que faltar — responder cedo evita retrabalho.
• Participe das decisões que não são só código: novos padrões, exceções a ADRs, stack em projeto novo, definição de “pronto” em time.
• Nas mudanças grandes ou arriscadas, alinhem spec e testes com o agente antes da implementação; o protocolo prevê isso — o seu papel é validar se os testes refletem a regra de negócio certa.
• Não precisa decorar fases nem checklist: quem executa o passo a passo é o agente segundo o SKILL.md. O README só deixa claro o que vocês precisam ter (projeto com protocolo instalado — de preferência via npx @satlab/protocol init) e como participar (requisito, aceite, ADRs).

Valores que o protocolo pressupõe (comuns ao time e ao agente): sem especificação verificável não há base sólida para teste; sem teste antes do código de produção o fluxo não fecha; entrega “green” inclui refatoração mínima e revisão crítica no fim — o detalhe operacional está no SKILL.md.

Quando faz sentido usar este pacote

Quando quiserem trabalho orientado a requisito, testes, refatoração e revisão estruturada — desde correção de bug até feature, definição de arquitetura ou projeto novo — sem amarrar a um stack específico.