npm package: @satlab/protocol
Description: SatLab Protocol: CLI for distributing skills and configuring MCPs (Cursor, Claude Code)
Author: SatLab
Latest version: 1.0.0

# 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.), desde que as regras e ferramentas do repositório-alvo (e os MCPs abaixo) estejam disponíveis.

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`](skills/satlab-protocol/SKILL.md) | Protocolo completo **para o agente** |
| [`skills/satlab-protocol/templates.md`](skills/satlab-protocol/templates.md) | Modelos úteis para alinhar requisito, spec, ADR e plano (time + agente) |
| [`rules/satlab-protocol.mdc`](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:** `npx @satlab/protocol init` copia `skills/` e `rules/` do pacote para `.cursor/skills`, `.cursor/rules` (ou equivalente `.claude/...`).

---

## Instalação

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.).

---

## Dependências

Sem isso, o protocolo não fecha como desenhado:

| Ferramenta | Para quê |
|------------|----------|
| **Lexomni** (MCP)  | Guidelines e referências do seu processo — [instalação / uso](https://www.pagansdev.site/pt/lexomni) |
| **Context7** (MCP) | Documentação atual de bibliotecas e APIs — [instalação](https://github.com/upstash/context7#installation) |

Detalhes de *quando* e *como* o agente usa cada um 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 (repo, MCPs) 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.

---