@ds9-solutions/mcp 0.1.0 → 0.3.0

package/content/agents/test-writer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: Test Writer
-description: "Cria e atualiza testes (Jest) sempre que arquivos de código-fonte de pastas específicas do projeto (ex: src/) são criados ou alterados e ainda não têm teste correspondente. A estrutura de testes deve espelhar exatamente a estrutura do projeto (mesma hierarquia de pastas). Use quando pedirem para criar/atualizar testes, cobrir um arquivo novo, ou quando um arquivo de código for criado/editado sem teste associado."
-tools: ["read", "search", "edit"]
+description: "Cria, atualiza e/ou executa testes de qualquer linguagem/framework, conforme o modo pedido (somente criar, somente executar, ou criar e executar), e informa a cobertura de linhas quando executa. Segue as convenções de testes do projeto e as skills do MCP aplicáveis. Use quando pedirem para criar/atualizar testes, executar testes, medir cobertura, cobrir um arquivo novo, ou quando um arquivo de código for criado/editado sem teste associado."
+tools: ["read", "search", "edit", "execute", "web"] # permissionamento do agente no caso de usar como plugin. Não válido via MCP. `execute` só para rodar testes/cobertura e instalar dependências já autorizadas pelo usuário; `web` só como fallback quando não há skill aplicável
 disable-model-invocation: false
 user-invocable: true
 is_background: true
@@ -9,57 +9,106 @@ is_background: true
 
 # Test Writer — DS9
 
-Cria/atualiza testes Jest para o código alterado, seguindo as convenções da skill `jest-testing` (e `nestjs`/`hexagonal` quando aplicável). Regra inegociável: **a estrutura de pastas usada para os testes tem que espelhar 1:1 a estrutura do código-fonte do projeto.**
+Cria, atualiza e/ou executa testes para qualquer linguagem ou framework, seguindo as convenções do projeto e as skills do MCP aplicáveis. Regra inegociável: **a organização dos testes deve seguir a convenção já existente no projeto; se os testes ficarem em pasta separada, ela espelha 1:1 a estrutura do código-fonte.**
 
-## Quando agir
+## 0. Entradas obrigatórias
 
-- Um arquivo de código-fonte foi criado ou alterado (ex.: em `src/`) e não existe teste correspondente, ou o teste existente ficou desatualizado em relação ao novo comportamento.
-- O usuário pede explicitamente para "criar teste", "cobrir esse arquivo", "gerar testes para X".
+Antes de qualquer ação, confirme duas informações. Se o agente principal ou o usuário não as informou, **pergunte** — não presuma.
 
-## 1. Descobrir a convenção de testes do projeto
+1. **Pasta principal do projeto** (raiz onde ficam manifestos, código-fonte e testes). Não assuma `src/`, a raiz do repositório nem qualquer outro caminho; todos os caminhos relativos partem dela.
+2. **Modo de operação** (ver abaixo).
 
-Antes de criar qualquer arquivo, identifique como o projeto já organiza testes (não presuma — inspecione o projeto real):
+### Modos de operação
 
-1. Existe uma pasta `test/` na raiz, separada de `src/`? Ou os testes ficam ao lado do arquivo-fonte (`*.spec.ts` colocado junto ao `.ts` correspondente)?
-2. Existe `jest.config.*`/seção `jest` no `package.json`? Verifique `roots`, `testMatch`/`testRegex` para confirmar onde o Jest procura testes.
-3. Se o projeto é NestJS seguindo a skill `jest-testing`: testes unitários (`*.spec.ts`) ficam colocados ao lado do arquivo testado; testes e2e (`*.e2e-spec.ts`) ficam em `test/`, espelhando a estrutura de `src/`.
+| Modo | O que faz | Edita arquivos | Executa testes |
+|---|---|---|---|
+| **Criar** | Cria/atualiza os testes e para. Não roda nada. | sim | não |
+| **Executar** | Roda os testes existentes e informa resultado e cobertura. | não | sim |
+| **Criar e executar** | Cria/atualiza os testes, depois roda e informa resultado e cobertura. | sim | sim |
 
-A regra de espelhamento 1:1 se aplica sempre que o teste for colocado em uma pasta de testes separada (`test/`): o caminho dentro de `test/` deve reproduzir exatamente o caminho relativo em `src/` (ou pasta equivalente), trocando apenas o nome do arquivo final.
+- Identifique o modo pelo pedido ("só crie", "rode os testes", "crie e rode", "qual a cobertura?"). Se for ambíguo, pergunte.
+- No modo **Criar**, nunca execute testes, nem para "conferir".
+- No modo **Executar**, nunca crie nem altere arquivos.
 
-| Arquivo em `src/` | Teste em `test/` (quando o projeto usa pasta `test/` separada) |
-|---|---|
-| `src/orders/application/use-cases/create-order.use-case.ts` | `test/orders/application/use-cases/create-order.use-case.spec.ts` |
-| `src/orders/infrastructure/adapters/in/order.controller.ts` | `test/orders/infrastructure/adapters/in/order.controller.e2e-spec.ts` |
+## 0.1 Progresso durante a execução
 
-Se o projeto usa testes colocados ao lado do arquivo-fonte (padrão `jest-testing`), siga esse padrão em vez de forçar uma pasta `test/` — a regra de espelhamento então se aplica à estrutura de pastas dentro de `src/` em si (o teste já nasce espelhado por estar ao lado do arquivo).
+Mantenha o usuário informado enquanto trabalha, com mensagens curtas, de uma linha, **antes** de cada passo relevante (não apenas no resumo final):
 
-## 2. Selecionar o que testar
+- **Skills:** ao carregar cada skill do MCP, informe qual (`Skill carregada: <id>`). Se usar fallback web, informe a fonte (`Referência externa: <nome/link>`).
+- **Bibliotecas:** informe a biblioteca de testes e de cobertura detectadas e as demais em uso (`Biblioteca de testes: <nome> <versão>`). Ao instalar uma dependência autorizada, informe cada uma.
+- **Criação/atualização:** antes de escrever, informe o arquivo (`Criando: <caminho>` ou `Atualizando: <caminho>`), indicando o arquivo-fonte que ele cobre.
+- **Execução:** informe o comando e o alvo (`Executando: <comando> — <arquivo ou suíte>`) e, ao concluir cada execução, o resultado resumido (passaram/falharam).
+- **Ignorados:** ao pular um arquivo, informe o motivo na hora.
 
-- Priorize: entidades/value objects de domínio, use cases/application services, repositórios/adapters de saída, controllers.
-- Não gere teste para arquivos de configuração pura (`*.module.ts` sem lógica, barris `index.ts`, DTOs sem método) — a menos que o usuário peça explicitamente.
-- Não sobrescreva um teste existente que já tem asserções reais; neste caso, **complemente** (adicione casos faltantes) em vez de recriar o arquivo do zero.
+Não repita no progresso o conteúdo dos testes; o detalhe fica no resumo final.
+
+## 1. Descobrir a stack e a convenção de testes
+
+Não presuma — inspecione o projeto real, a partir da pasta principal informada:
+
+1. **Linguagem e framework:** identifique pela extensão dos arquivos, imports/dependências declaradas, manifestos/configuração do ecossistema em uso e estrutura de pastas.
+2. **Biblioteca de testes e de cobertura:** descubra qual está instalada/configurada (dependências declaradas, arquivos de configuração do runner, scripts/tarefas de teste do projeto). Use somente a que o projeto já usa; não instale nem troque de biblioteca sem pedir ao usuário.
+3. **Skills do MCP:** descubra as disponíveis (plugin, ou via MCP: `list_skills`, `recommend_for_task`, `search_guidelines`) e carregue (`get_skill`) apenas as relevantes à stack e a testes. Elas são a fonte de verdade das convenções. Se indicarem arquivos complementares, leia só os necessários (`list_skill_files` / `get_skill_file`).
+4. **Fallback externo:** se não houver skill aplicável à stack ou à biblioteca de testes, consulte referências confiáveis na web (documentação oficial da biblioteca/framework). Use a web somente nesse caso, nunca para contradizer uma skill existente.
+5. **Onde ficam os testes:** observe os testes já existentes e a configuração do runner (padrões/diretórios de busca de testes) para saber se ficam ao lado do código-fonte ou em pasta separada, e qual o padrão de nome de arquivo.
+
+### Dependências necessárias e autorização
+
+Concluída a análise, determine quais bibliotecas faltam para realizar **todas** as tarefas do modo escolhido (por exemplo: runner de testes, biblioteca de mocks, ferramenta de cobertura, utilitários de teste de integração) e que não estão instaladas nem declaradas no projeto.
+
+- Se não faltar nada, siga em frente.
+- Se faltar algo, **pare e peça autorização** antes de instalar, apresentando em uma lista: cada biblioteca, para que serve, versão sugerida (compatível com a stack e a biblioteca de testes já em uso), se é dependência de desenvolvimento e o comando exato que será executado com o gerenciador de pacotes do projeto.
+- Só instale após resposta afirmativa explícita, e apenas o que foi autorizado. Se o usuário negar, siga com o que já existe e informe as limitações (por exemplo, execução sem cobertura ou testes sem determinado tipo de mock).
+- Após instalar, informe no resumo o que foi adicionado e quais arquivos de manifesto/lock foram alterados.
+
+### Espelhamento
+
+- Se o projeto usa **pasta de testes separada**, o caminho dentro dela reproduz exatamente o caminho relativo do arquivo-fonte, trocando apenas o nome/sufixo do arquivo final conforme o padrão do projeto.
+- Se o projeto coloca testes **ao lado do código-fonte**, siga esse padrão; o espelhamento já é implícito.
+- Se não houver testes existentes para inferir a convenção, use a recomendada pela skill/referência aplicável e informe a escolha no resumo.
+
+## 2. Selecionar o que testar (modos Criar e Criar e executar)
+
+- Identifique o código criado/alterado sem teste correspondente (ou com teste desatualizado). Se o usuário indicou arquivos, restrinja-se a eles.
+- Priorize lógica de negócio, regras de domínio, serviços/casos de uso, acesso a dados e camadas de entrada (controllers/handlers).
+- Não gere teste para arquivos sem lógica (configuração pura, barris de exportação, estruturas de dados sem comportamento), a menos que o usuário peça.
+- Não sobrescreva um teste existente que já tem asserções reais; **complemente** com os casos faltantes.
 
 ## 3. Escrever o teste
 
-Siga integralmente a skill `jest-testing`: nomes de `describe`/`it` descrevendo comportamento, mocks/fakes das `ports` (skill `hexagonal`) em vez de dependências reais, matchers específicos, determinismo (sem tempo real sem fake timers).
+Siga as skills/referências aplicáveis à stack. Princípios gerais:
+
+- Nomes que descrevem comportamento, não implementação.
+- Isole dependências externas com mocks/fakes/stubs no estilo da biblioteca em uso.
+- Teste pelo comportamento público; cubra o caminho feliz, bordas e pelo menos um caso de erro.
+- Determinismo: sem dependência de tempo real, rede, ordem de execução ou estado compartilhado.
+- Não deixe apenas esqueleto vazio (`todo`/`skip`) se for possível escrever uma asserção real; use-os só quando faltar contexto de verdade e explique no resumo.
+
+## 4. Executar e medir cobertura (modos Executar e Criar e executar)
 
-- Para use cases: teste unitário mockando as ports (`InMemory*Repository` ou `jest.Mocked<Port>`), cobrindo o caminho feliz e pelo menos um erro de domínio.
-- Para controllers: teste de integração com `supertest`, cobrindo status code, shape da resposta e um caso de validação inválida.
-- Para entidades/value objects: teste unitário puro das invariantes (construtor/factory lançando erro de domínio em estado inválido).
-- Não implemente apenas esqueleto vazio (`it.todo`) quando for possível escrever uma asserção real com a informação disponível no arquivo-fonte; use `it.todo`/`.skip` apenas quando genuinamente faltar contexto (ex.: dependência externa não mapeada) e explique o motivo no resumo final.
+1. Use o comando de teste e de cobertura que o projeto já define; se não houver, derive-o da documentação da biblioteca descoberta. Execute a partir da pasta principal.
+2. Rode com cobertura habilitada. Se a ferramenta de cobertura não estiver instalada/configurada, inclua-a na solicitação de autorização de dependências (seção 1). Sem autorização, execute os testes sem cobertura e informe que ela não está disponível, sugerindo como habilitar.
+3. Execute somente comandos de teste/cobertura e, quando autorizado, a instalação das dependências aprovadas. Não rode comandos que alterem o repositório ou o ambiente (`git commit/push/checkout/reset`, migrations, deploy etc.).
+4. Se houver falhas, **não corrija o código de produção**. Reporte cada teste que falhou, com a mensagem e a causa provável.
+5. Extraia do relatório a **cobertura de linhas** (percentual total e, quando disponível, por arquivo revisado/alterado). Se o relatório também trouxer ramos/funções, pode citar, mas o número principal é o de linhas.
 
-## 4. Resumo final
+## 5. Resumo final
 
-Ao terminar, apresente:
+Apresente, conforme o modo:
 
-1. **Criados:** arquivos de teste novos, com o caminho completo.
-2. **Atualizados:** arquivos de teste existentes que receberam novos casos.
-3. **Ignorados:** arquivos de código sem teste gerado e o motivo (ex.: módulo sem lógica, DTO puro).
-4. **Pendências:** casos que ficaram como `it.todo`/`.skip` e o que falta para implementá-los.
+1. **Stack detectada:** linguagem/framework, biblioteca de testes e de cobertura, skills consultadas ou referências externas usadas (nome e link).
+2. **Criados / Atualizados / Ignorados:** caminhos completos e o motivo dos ignorados (modos com criação).
+3. **Execução:** comando usado, total de testes, passaram, falharam, ignorados (modos com execução).
+4. **Cobertura de linhas:** percentual total e dos arquivos relevantes; ou o motivo de não estar disponível (modos com execução).
+5. **Pendências:** testes marcados como `todo`/`skip`, falhas a tratar e o que falta para resolvê-los.
 
 ## Não fazer
 
-- Não alterar código de produção (`src/`) — apenas arquivos de teste.
-- Não quebrar a estrutura espelhada entre `src/` e `test/` quando o projeto usa pasta `test/` separada.
+- Não presumir a pasta principal do projeto nem o modo de operação; perguntar.
+- Não alterar código de produção — apenas arquivos de teste.
+- Não executar testes no modo Criar, nem criar/alterar arquivos no modo Executar.
+- Não instalar dependências sem autorização explícita do usuário, nem trocar a biblioteca de testes do projeto.
+- Não corrigir código de produção para fazer teste passar; apenas reportar a falha.
 - Não sobrescrever testes existentes com asserções reais sem necessidade.
-- Não testar detalhes de implementação privada — teste pelo comportamento público (ver skill `jest-testing`).
+- Não usar a web quando houver skill aplicável, nem para contradizer uma skill.
+- Não aplicar tratamento diferente por linguagem/framework além do que a skill ou referência aplicável determinar.

package/content/skills/dart/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: dart
+description: Convenções da linguagem Dart da DS9 — orientação a objetos como abordagem padrão, nomenclatura oficial do Dart (Effective Dart), documentação com `///`, null safety, tratamento de erros, análise estática, formatação e testes. Use ao escrever ou revisar qualquer código Dart (CLI, servidor, pacote ou app Flutter), definir classes/tipos, nomear arquivos e identificadores, documentar código, ou quando o usuário pedir "boas práticas Dart", "padrão Dart", "nomenclatura Dart" ou "documentar com ///".
+---
+
+# Dart — Diretrizes DS9
+
+Convenções da **linguagem Dart**, válidas para qualquer projeto (CLI, servidor, pacote ou aplicativo). Regras específicas de Flutter (widgets, estado, UI) não fazem parte desta skill. Base: guia oficial *Effective Dart*, documentação do Dart e as skills Dart do projeto `lazy_forge` (`.agents/skills`). Em caso de dúvida sobre versão da linguagem, confirme a versão do SDK no `pubspec.yaml` antes de usar recursos novos.
+
+## 1. Orientação a objetos como padrão
+
+O código Dart da DS9 é **orientado a objetos**. Modele o domínio com classes e deixe o comportamento junto dos dados.
+
+- **Comportamento em métodos, não em funções soltas:** lógica de negócio vive em classes (entidades, serviços, casos de uso). Funções de nível superior ficam restritas a `main()` e a pequenos utilitários verdadeiramente genéricos e sem estado; mesmo estes, prefira como métodos estáticos de uma classe coesa ou como `extension`.
+- **Encapsulamento:** campos privados (`_campo`) com acesso por getters/métodos; exponha o mínimo necessário. Estado interno nunca é alterado de fora da classe.
+- **Imutabilidade por padrão:** campos `final`, construtores `const` quando possível, e novas instâncias (`copyWith`/métodos que retornam um novo objeto) em vez de mutação onde o domínio pedir.
+- **Composição sobre herança:** injete dependências pelo construtor (como `abstract interface class` ou `abstract class`) e componha objetos; use herança só para relação "é um" genuína.
+- **Polimorfismo no lugar de `if`/`switch` por tipo:** variação de comportamento vai em subclasses/implementações, não em cadeias de `is`/`switch` espalhadas. Use `sealed class` para famílias fechadas de tipos; `switch` exaustivo sobre elas é aceitável quando o comportamento não pertence ao tipo (ex.: decodificar dados externos).
+- **Contratos explícitos:** dependências externas (banco, rede, relógio) atrás de uma interface (`abstract interface class`), para troca e teste.
+
+### Evite o estilo funcional como abordagem principal
+
+Dart é multiparadigma, mas aqui o padrão é objetos. Isso **não** proíbe os recursos idiomáticos da linguagem; proíbe construir a arquitetura em torno de funções.
+
+- Evite pipelines longos e encadeados (`map().where().fold().expand()...`) que escondem regra de negócio; se passar de 2 ou 3 etapas, extraia para um método nomeado ou use um laço `for` claro.
+- Evite passar funções/closures como mecanismo principal de extensão (callbacks em cascata, funções de ordem superior como "estratégia"); prefira um objeto com método bem nomeado.
+- Evite funções que retornam funções, currying e composição de funções; evite tipos como `Function` solto (use `typedef` ou interface quando um callback for inevitável).
+- Evite `Either`/`Result` genéricos e estilos monádicos criados à mão quando exceção tipada ou um tipo de resultado `sealed` do domínio resolve de forma mais legível. **Exceção:** em projetos que seguem as skills `hex-pattern-dart`, `dart-frog` ou `flutter`, o `TaskEither` do `fpdart` (com `TaskEither.tryCatch`, `map`, `flatMap`, `mapLeft`) é o padrão obrigatório nos contratos entre camadas; ele não se estende ao domínio e aos models, que continuam orientados a objetos.
+- Aceitável e idiomático: `for` com `collection-if`/`collection-for` em literais, `map`/`where`/`toList` simples (1 a 2 etapas), `async`/`await`, callbacks exigidos por APIs de terceiros e a composição de `TaskEither` conforme essas skills.
+
+## 2. Nomenclatura (Effective Dart)
+
+| Elemento | Convenção | Exemplo |
+|---|---|---|
+| Classes, enums, mixins, extensions, typedefs, parâmetros de tipo | `UpperCamelCase` | `OrderService`, `PaymentStatus`, `T` |
+| Variáveis, parâmetros, campos, métodos, funções, getters | `lowerCamelCase` | `totalPrice`, `findById()` |
+| **Constantes** (incl. `const`/`static const`/valores de enum) | `lowerCamelCase` (**não** `SCREAMING_CAPS`) | `defaultTimeout`, `maxRetries` |
+| Pacotes, diretórios, arquivos, prefixos de import | `lowercase_with_underscores` | `order_service.dart`, `import '...' as http_client;` |
+| Membros e tipos privados da biblioteca | prefixo `_` | `_cache`, `_OrderMapper` |
+
+Regras adicionais:
+
+- **Arquivo = classe principal:** `UserRepository` fica em `user_repository.dart`. Uma classe pública principal por arquivo; testes em `<nome>_test.dart`.
+- **Siglas:** com mais de duas letras, capitalize como palavra (`HttpClient`, `JsonParser`, `UserId`); com duas letras, mantenha maiúsculas (`IOSink`).
+- **Sem prefixos/sufixos de tipo:** não use `I` para interfaces (`IUserRepository`), notação húngara, nem `k` em constantes (`kTimeout`).
+- **Booleanos** com nome afirmativo: `isEmpty`, `hasPermission`, `canRetry`; evite negações (`isNotValid`).
+- **Métodos** começam com verbo (`calculateTotal`, `save`); **getters e propriedades** são substantivos, sem prefixo `get` (`total`, não `getTotal`).
+- **Nomes descritivos:** sem abreviações obscuras nem nomes de uma letra fora de laços/lambdas curtos; o nome expressa intenção, não implementação.
+- **Variáveis não usadas:** use `_` (wildcard) em vez de nomes sem uso.
+- **Ordem em arquivos:** `dart:` → `package:` → relativos, cada grupo em ordem alfabética; prefira imports relativos dentro de `lib/` do próprio pacote, exceto quando a skill do framework definir outro padrão (a `flutter` usa `package:`).
+
+## 3. Documentação e comentários (`///`)
+
+**Regra de inclusão:** toda declaração **pública** (biblioteca, classe, enum, mixin, extension, construtor nomeado relevante, método, função, getter/setter, campo e constante) **deve** ter comentário de documentação com `///`. Declarações privadas só precisam quando a lógica não for óbvia. Código novo sem `///` nas declarações públicas é pendência de review.
+
+- Use **sempre `///`**, em linhas consecutivas; **nunca** `/** ... */`. Use `//` apenas para comentários de implementação internos, explicando o **porquê**, nunca o óbvio.
+- **Primeira linha:** uma frase única e resumida, terminada em ponto, seguida de uma linha `///` vazia antes do restante. Uma linha totalmente em branco (sem `///`) encerra o comentário.
+- **Abertura por tipo de membro:** propriedades/getters com sintagma nominal (`/// O raio da esfera.`); booleanos com "Se"/"Whether" no idioma do projeto (`/// Se a conexão está ativa.`); métodos com verbo na 3ª pessoa (`/// Inicializa o banco.`).
+- **Sem redundância:** não repita a assinatura nem o nome ("Esta classe é...", "O método foo faz...").
+- **Sem tags estilo Javadoc** (`@param`, `@return`, `@throws`): descreva parâmetros, retorno e exceções em prosa, referenciando parâmetros com `[nome]`.
+- **Links:** use colchetes para símbolos no escopo (`[Order]`, `[Order.total]`, sem parênteses); construtor sem nome como `[Order.new]`; crases para palavras-chave e literais (`` `null` ``, `` `true` ``). Blocos de código com a linguagem (` ```dart `).
+- **Posição:** o comentário `///` vem **antes** das anotações (`@override` etc.).
+- **Herança e pares getter/setter:** não duplique documentação em `@override` sem mudança de comportamento; em par getter/setter, documente só o getter.
+- **Idioma:** siga o idioma já usado no projeto, de forma consistente.
+- Valide com `dart analyze` (referências entre colchetes resolvidas) e, opcionalmente, `dart doc`.
+
+```dart
+// Evitar
+/**
+ * Busca o pedido.
+ * @param id identificador
+ * @return o pedido
+ */
+Order find(String id) { ... }
+
+// Preferir
+/// Busca o pedido pelo [id].
+///
+/// Lança [OrderNotFoundException] se não existir pedido com esse identificador.
+Order findById(String id) { ... }
+```
+
+## 4. Construtores e classes
+
+- Prefira **parâmetros iniciais** (`this.campo`) e `super.parametro` a atribuições manuais; use `required` em parâmetros nomeados obrigatórios.
+- Construtores `const` em classes imutáveis; `factory` para validação/cache e para criar a partir de dados externos (`fromJson`).
+- **Invariantes no construtor/factory:** estado inválido não pode existir; valide e lance exceção de domínio.
+- **Primary constructors** (declarar campos no cabeçalho da classe): disponíveis só a partir do Dart 3.13 (experimental no 3.12, via flag). Use **somente se o SDK do projeto suportar**; caso contrário, use construtores tradicionais. Não migre código existente apenas por isso.
+- Use `sealed`, `final`, `base` e `interface` para controlar quem pode estender ou implementar uma classe, quando a API for pública.
+
+## 5. Null safety e tipos
+
+- Nada de `dynamic` em código novo; tipos explícitos em APIs públicas, em genéricos (`List<Order>`) e em retornos.
+- Evite `!` (asserção de nulo); prefira promoção de tipo, `?.`, `??` ou tratar o nulo. `late` só quando a inicialização estiver garantida antes do uso.
+- Prefira `final` a `var` quando o valor não muda; evite `as` sem garantia do tipo em tempo de execução.
+- **Pattern matching e records** (Dart 3): use para decodificar dados externos (JSON) e `switch` exaustivo em `sealed`; não use para o que um `is` simples, um acesso a propriedade ou uma comparação booleana resolvem. Dados malformados devem falhar com erro explícito (`FormatException`), nunca ser descartados em silêncio.
+
+## 6. Tratamento de erros
+
+- Falhas recuperáveis: **`Exception` tipada do domínio** (`class OrderNotFoundException implements Exception`), nunca `throw 'texto'` nem lançar `Exception` genérica. Em projetos `hex-pattern-dart`/`dart-frog`, as falhas trafegam como `Left` de `TaskEither` com as exceções por camada definidas em `hex-pattern-dart` (em Flutter, siga a skill `flutter`) (`BusinessException`, `ClientException`, `MiddlewareException`).
+- **Nunca capture `Error`** (nem `TypeError`, `ArgumentError`, etc.): indicam bugs de programação. Capture tipos específicos; não use `catch (e)` amplo sem relançar.
+- Use `rethrow` para propagar preservando o stack trace; não engula exceções em silêncio nem registre dados sensíveis.
+- Mensagens de erro expostas a usuários não vazam detalhes internos.
+
+## 7. Assincronismo
+
+- `async`/`await` em vez de encadear `.then()`; sempre aguarde (`await`) ou trate explicitamente os `Future`s (sem "fire-and-forget" acidental).
+- Libere recursos (`close`/`cancel`/`dispose`) em `try/finally`; cancele subscriptions e controllers de `Stream`.
+- Não bloqueie o isolate principal com trabalho pesado síncrono; use isolates quando necessário.
+
+## 8. Qualidade, formatação e testes
+
+- **Análise estática:** `analysis_options.yaml` na raiz do pacote com um conjunto base (`package:lints/recommended.yaml` ou `package:flutter_lints/flutter.yaml`) e `strict-casts`, `strict-inference` e `strict-raw-types` ativos. Exclua só código gerado (`**/*.g.dart`).
+- Rode `dart analyze` e corrija os avisos; use `dart fix --apply` para correções mecânicas (revise com `--dry-run`) e `dart format .` antes de commitar. Suprima diagnósticos (`// ignore:`) só com justificativa e no menor escopo.
+- **Testes:** `package:test` (ou `flutter_test` em Flutter), arquivos em `test/` espelhando `lib/` com sufixo `_test.dart`; `group()` por funcionalidade, `setUp()`/`tearDown()` para preparo, `expect()` com matchers; dependências externas isoladas por interface/mocks. Para criar e executar testes, use o agente `test-writer`.
+
+## 9. Checklist de review
+
+- [ ] Regra de negócio está em classes, sem funções soltas nem cadeias funcionais longas?
+- [ ] Toda declaração pública tem `///` no formato da seção 3?
+- [ ] Nomes seguem a tabela da seção 2 (inclusive constantes em `lowerCamelCase` e arquivos em `snake_case`)?
+- [ ] Sem `dynamic`, `!` desnecessário ou `catch` de `Error`?
+- [ ] Campos `final`, encapsulamento e construtores `const` onde cabem?
+- [ ] `dart analyze` limpo, `dart format` aplicado e testes cobrindo o comportamento novo?
+
+## 10. Arquivos complementares
+
+Em caso de dúvida, consulte (via `list_skill_files` / `get_skill_file` com `skill="dart"`; ou direto na pasta `dart/`, se o host não tiver as tools):
+
+- `examples/` — código de referência: `entity.dart`, `repository.dart`, `error_handling.dart`, `order_test.dart`. Use quando precisar de um exemplo de entidade, contrato/caso de uso, erros ou teste.
+- `references/` — `naming.md` (nomenclatura), `documentation.md` (`///`), `checklist.md` (review detalhado).
+
+## Não fazer
+
+- Não usar `/** ... */` nem tags `@param`/`@return`/`@throws`.
+- Não usar `SCREAMING_CAPS`, prefixo `I`, `k` ou notação húngara.
+- Não criar funções de nível superior com regra de negócio nem pipelines funcionais extensos (exceto a composição de `TaskEither` exigida pelas skills `hex-pattern-dart`, `dart-frog` e `flutter`).
+- Não declarar `dynamic`, `Function` solto ou `throw` de strings.
+- Não duplicar regras de outras skills; para testes, ver o agente `test-writer`.

package/content/skills/dart/examples/entity.dart

@@ -0,0 +1,37 @@
+/// Exemplo: entidade imutável, encapsulada e documentada com `///`.
+library;
+
+/// Status possíveis de um [Order].
+enum OrderStatus {
+  /// Pedido criado e ainda não pago.
+  pending,
+
+  /// Pedido pago.
+  paid,
+}
+
+/// Pedido do domínio, com invariantes validadas na criação.
+class Order {
+  /// Cria um pedido.
+  ///
+  /// Lança [ArgumentError] se [id] estiver vazio ou [total] for negativo.
+  Order({required this.id, required this.total, this.status = OrderStatus.pending}) {
+    if (id.isEmpty) throw ArgumentError.value(id, 'id', 'não pode ser vazio');
+    if (total < 0) throw ArgumentError.value(total, 'total', 'não pode ser negativo');
+  }
+
+  /// Identificador único do pedido.
+  final String id;
+
+  /// Valor total do pedido.
+  final double total;
+
+  /// Situação atual do pedido.
+  final OrderStatus status;
+
+  /// Se o pedido já foi pago.
+  bool get isPaid => status == OrderStatus.paid;
+
+  /// Retorna uma cópia deste pedido já marcada como paga.
+  Order markAsPaid() => Order(id: id, total: total, status: OrderStatus.paid);
+}

package/content/skills/dart/examples/error_handling.dart

@@ -0,0 +1,36 @@
+/// Exemplo: exceções tipadas e tratamento sem engolir erros.
+library;
+
+/// Falha ao decodificar dados externos.
+class InvalidPayloadException implements Exception {
+  /// Cria a exceção com a [message] explicando o problema.
+  const InvalidPayloadException(this.message);
+
+  /// Descrição do problema, segura para exibir.
+  final String message;
+
+  @override
+  String toString() => 'InvalidPayloadException: $message';
+}
+
+/// Lê um valor numérico de um payload externo.
+class PayloadReader {
+  /// Lê o campo `amount` de [json].
+  ///
+  /// Lança [InvalidPayloadException] se ele não existir ou não for numérico.
+  double readAmount(Map<String, Object?> json) {
+    return switch (json['amount']) {
+      final num amount => amount.toDouble(),
+      _ => throw const InvalidPayloadException('campo "amount" ausente ou inválido'),
+    };
+  }
+
+  /// Lê o valor e propaga falhas de domínio preservando o stack trace.
+  double readOrRethrow(Map<String, Object?> json) {
+    try {
+      return readAmount(json);
+    } on InvalidPayloadException {
+      rethrow; // nunca `catch (e)` amplo nem captura de `Error`
+    }
+  }
+}

package/content/skills/dart/examples/order_test.dart

@@ -0,0 +1,34 @@
+/// Exemplo: teste unitário com `group`, `setUp` e `expect`.
+///
+/// Em um projeto real o arquivo fica em `test/`, espelhando `lib/`.
+library;
+
+import 'package:test/test.dart';
+
+import 'entity.dart';
+import 'repository.dart';
+
+void main() {
+  group('PayOrder', () {
+    late InMemoryOrderRepository repository;
+    late PayOrder useCase;
+
+    setUp(() {
+      repository = InMemoryOrderRepository();
+      useCase = PayOrder(repository);
+    });
+
+    test('marca o pedido como pago e persiste', () async {
+      await repository.save(Order(id: '1', total: 10));
+
+      final paid = await useCase.execute('1');
+
+      expect(paid.isPaid, isTrue);
+      expect((await repository.findById('1'))!.isPaid, isTrue);
+    });
+
+    test('lança OrderNotFoundException quando o pedido não existe', () {
+      expect(() => useCase.execute('x'), throwsA(isA<OrderNotFoundException>()));
+    });
+  });
+}

package/content/skills/dart/examples/repository.dart

@@ -0,0 +1,57 @@
+/// Exemplo: contrato (porta) e implementação, com dependência injetada.
+library;
+
+import 'entity.dart';
+
+/// Contrato de persistência de pedidos.
+abstract interface class OrderRepository {
+  /// Busca o pedido pelo [id]; retorna `null` se não existir.
+  Future<Order?> findById(String id);
+
+  /// Salva o [order].
+  Future<void> save(Order order);
+}
+
+/// Implementação em memória, útil em testes.
+class InMemoryOrderRepository implements OrderRepository {
+  final Map<String, Order> _orders = {};
+
+  @override
+  Future<Order?> findById(String id) async => _orders[id];
+
+  @override
+  Future<void> save(Order order) async {
+    _orders[order.id] = order;
+  }
+}
+
+/// Caso de uso: paga um pedido existente.
+class PayOrder {
+  /// Cria o caso de uso com o [repository] injetado.
+  PayOrder(this._repository);
+
+  final OrderRepository _repository;
+
+  /// Marca como pago o pedido [id].
+  ///
+  /// Lança [OrderNotFoundException] se o pedido não existir.
+  Future<Order> execute(String id) async {
+    final order = await _repository.findById(id);
+    if (order == null) throw OrderNotFoundException(id);
+    final paid = order.markAsPaid();
+    await _repository.save(paid);
+    return paid;
+  }
+}
+
+/// Erro de domínio: pedido não encontrado.
+class OrderNotFoundException implements Exception {
+  /// Cria a exceção para o pedido [id].
+  const OrderNotFoundException(this.id);
+
+  /// Identificador procurado.
+  final String id;
+
+  @override
+  String toString() => 'Pedido não encontrado: $id';
+}

package/content/skills/dart/references/checklist.md

@@ -0,0 +1,12 @@
+# Dart — Checklist de review detalhado
+
+- [ ] Regra de negócio em classes; sem funções soltas nem pipelines longos.
+- [ ] Dependências externas atrás de `abstract interface class`, injetadas no construtor.
+- [ ] Campos `final`, construtores `const` onde couber, estado privado encapsulado.
+- [ ] Toda declaração pública com `///` (sem `/** */`, sem `@param`).
+- [ ] Nomes: `UpperCamelCase` (tipos), `lowerCamelCase` (membros e constantes), `snake_case` (arquivos).
+- [ ] Sem `dynamic`, `!` desnecessário, `Function` solto ou `throw` de string.
+- [ ] Sem `catch` de `Error`; `rethrow` preserva o stack trace.
+- [ ] `Future`s aguardados; recursos liberados em `try/finally`.
+- [ ] `dart analyze` limpo, `dart format` aplicado.
+- [ ] Testes em `test/` espelhando `lib/`, com `group`/`setUp`/`expect`.

package/content/skills/dart/references/documentation.md

@@ -0,0 +1,26 @@
+# Dart — Documentação com `///` (referência detalhada)
+
+Complementa a seção 3 do `SKILL.md`.
+
+## Modelo
+
+```dart
+/// Calcula o total do pedido.
+///
+/// Soma os itens de [items] e aplica [discount] (entre 0 e 1).
+/// Lança [ArgumentError] se [discount] estiver fora do intervalo.
+double calculateTotal(List<Item> items, {double discount = 0}) { ... }
+```
+
+## Regras rápidas
+
+- Primeira linha: frase única, terminada em ponto; depois linha `///` vazia.
+- Propriedade: sintagma nominal. Booleano: "Se ...". Método: verbo na 3ª pessoa.
+- Sem `@param`/`@return`; use prosa e `[nome]`.
+- `///` antes de `@override` e outras anotações.
+- Par getter/setter: documente só o getter.
+- Não documente `@override` sem mudança de comportamento.
+
+## Validação
+
+`dart analyze` resolve referências entre colchetes; `dart doc` gera a documentação.

package/content/skills/dart/references/naming.md

@@ -0,0 +1,27 @@
+# Dart — Nomenclatura (referência detalhada)
+
+Complementa a seção 2 do `SKILL.md`.
+
+## Certo x errado
+
+| Evitar | Preferir | Motivo |
+|---|---|---|
+| `MAX_RETRIES`, `kMaxRetries` | `maxRetries` | Constantes usam `lowerCamelCase` |
+| `IUserRepository` | `UserRepository` | Sem prefixo `I` |
+| `UserRepository.dart` | `user_repository.dart` | Arquivos em `snake_case` |
+| `getTotal()` | `total` (getter) | Propriedade é substantivo, sem `get` |
+| `isNotValid` | `isValid` | Booleano afirmativo |
+| `HTTPClient` | `HttpClient` | Siglas com mais de 2 letras viram palavra |
+| `data`, `tmp`, `x` | `orderTotals` | Nome expressa intenção |
+
+## Ordem de imports
+
+1. `dart:`
+2. `package:`
+3. relativos
+
+Cada grupo em ordem alfabética, separado por linha em branco.
+
+## Privacidade
+
+O prefixo `_` torna o membro privado à **biblioteca** (arquivo), não à classe.