@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/skills/flutter/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: flutter
+description: Padrões de arquitetura, código e qualidade para apps Flutter com Provider, go_router e fpdart. Use ao criar, editar, revisar ou testar arquivos em lib/ ou test/ de um projeto Flutter, como features, providers, services, models, views, rotas, tema ou testes.
+---
+
+# Flutter best practices
+
+Arquitetura em camadas com **Provider + ChangeNotifier**, **go_router** e **fpdart** (`TaskEither`/`Either`), alinhada ao guia oficial de arquitetura do Flutter (MVVM com camada de dados) e ao Effective Dart.
+
+## Stack
+
+- **Estado:** `provider` com `ChangeNotifier`. Não misture Riverpod, Bloc ou GetX.
+- **Navegação:** `go_router`.
+- **Erros e async:** `fpdart`. Operações que podem falhar retornam `TaskEither`, nunca `Future` que lança exceção entre camadas.
+- **Configuração:** `flutter_dotenv` (`.env`) ou `--dart-define`. Nunca coloque segredos ou URLs fixas no código.
+- **Lints:** `flutter_lints`.
+
+## Estrutura de pastas
+
+```
+lib/
+├── main.dart              # bootstrap + composição de dependências
+├── components/            # features
+│   └── <feature>/
+│       ├── models/
+│       ├── providers/     # ChangeNotifier (ViewModel)
+│       ├── services/      # acesso a dados via ports (pode ter dtos/ e mappers/)
+│       ├── views/         # telas
+│       │   └── components/  # widgets exclusivos da feature
+│       └── components/    # subfeatures, com a mesma estrutura
+└── shared/
+    ├── components/        # widgets reutilizáveis (buttons, inputs, widgets...)
+    ├── constraints/       # AppConstraints (bordas, breakpoints, limites)
+    ├── errors/            # Failure, exceções e Log
+    ├── infra/             # armazenamento local etc.
+    ├── models/
+    ├── providers/         # rotas e sessão
+    ├── services/          # implementações de infraestrutura
+    │   └── ports/         # contratos abstratos (HTTP, storage, push...)
+    ├── theme/             # paleta + extensão de ThemeData
+    ├── typography/        # AppTypography.of(context)
+    └── utils/
+```
+
+1. **Diretamente em `lib/`** só podem existir `components/`, `shared/`, `main.dart` e arquivos gerados de configuração (por exemplo, `firebase_options.dart`).
+2. **Na raiz de cada feature** (e de cada subfeature em `components/`), as únicas pastas permitidas são `models`, `providers`, `services`, `views` e `components`.
+3. **Use `components/` para subfeatures** quando a feature se divide por perfil ou área (por exemplo, `admin/components/reports`).
+
+## Camadas e fluxo de dados
+
+```
+View ──context.read/watch──▶ Provider ──▶ Service ──▶ Port (shared/services/ports)
+ ▲   .run() + match/fold      TaskEither<Failure, T>   TaskEither<Exception, T>   ▲
+ └──────── AppSnackBars ◀──── Log.print + Failure ◀───────────────────────────────┘
+                                                        implementado em shared/services
+```
+
+4. **Ports** são classes `abstract` em `shared/services/ports/` e retornam `TaskEither<Exception, T>`. As implementações concretas ficam em `shared/services/`.
+5. **Services de feature** recebem *ports* pelo construtor, nunca a implementação concreta. Eles convertem JSON em model e retornam `TaskEither<Exception, T>`, sem estado, sem `notifyListeners` e sem `BuildContext`.
+6. **Providers** estendem `ChangeNotifier` e recebem o service pelo construtor. Guardam estado privado exposto por getters e retornam `TaskEither<Failure, T>` (normalmente `Unit`). Em erro, registram com `Log` e devolvem a `Failure` do domínio.
+7. **Views** usam `context.read<T>()` para ações e `context.watch<T>()` para estado. Executam com `.run()` e tratam o resultado com `.match(...)` ou `.fold(...)`.
+8. **fpdart em toda fronteira entre camadas:**
+   - Em `views → providers`, a view consome com `.run()` **e** `.match`, `.fold`, `.getOrElse`, `.isLeft` ou `.isRight`. Só `mapLeft` não basta, porque ignora o caminho de sucesso.
+   - Em `providers → services`, o arquivo importa `package:fpdart/fpdart.dart` e trabalha com `TaskEither` ou `Either`.
+   - Em `services → shared/services`, vale a mesma regra.
+9. **Direção única de dependência.** Uma view nunca importa um service, e um provider nunca importa uma view. A lógica de negócio fica fora dos widgets.
+10. **Crie uma camada de *use case*** só quando a lógica for complexa ou compartilhada entre providers. Caso contrário, ela fica no provider ou no service.
+
+## Regras de código
+
+### Documentação e estilo
+
+11. **Toda declaração tem `///` logo acima:** classes, construtores, métodos, getters, funções, enums, extensions, mixins, typedefs e campos de classe. Variáveis locais estão isentas. Siga o Effective Dart: primeira frase curta terminada em ponto, campos descritos com substantivo e booleanos começando com "Indica se...".
+12. **Não use `var`.** Use `final`, `const` ou tipo explícito.
+13. **Todo arquivo passa por `dart format`.** Código fora do formato não é commitado.
+14. **`flutter analyze --fatal-infos` precisa passar limpo.** Não use `// ignore` sem justificativa no próprio comentário.
+15. **Importe pelo caminho do pacote** (`package:<app>/...`). Use alias (`as admin`, `as customer`) quando houver nomes de classe iguais em features diferentes.
+16. **Ao mudar dependências, versione o `pubspec.lock`**, e no CI use `flutter pub get --enforce-lockfile`.
+
+### Models
+
+17. **Models são classes imutáveis**, com campos `final`, construtor `const` e `factory fromJson(Map<String, dynamic>)` defensivo (`?.toString() ?? ''`, `DateTime.tryParse`). Nada de `dynamic` vazando para fora do model.
+18. **Textos de exibição derivados** (rótulo, tradução, ícone) ficam em getters do model ou em `shared/utils`, nunca espalhados pela view.
+19. **DTOs e mappers** ficam em `services/dtos/` e `services/mappers/` quando o formato da API difere do model de domínio.
+
+### Erros e logs
+
+20. **`Failure` é uma `sealed class`** em `shared/errors/failure.dart`, com uma subclasse por domínio (`AuthFailure`, `LoadingFailure`, `ValidationFailure`, `GeneralFailure`...). Use a do domínio certo. Se faltar uma, crie a subclasse em vez de reaproveitar outra.
+21. **A mensagem da `Failure` é texto para o usuário**, claro e sem detalhe técnico. O detalhe técnico vai para o log, com `origin` (classe), `method`, `error` e `stack`.
+22. **Não use `print` nem `debugPrint` soltos.** Centralize em um `Log` com níveis (Debug, Info, Warning, Error, Critical) sobre `dart:developer`. Nunca registre tokens, senhas ou dados pessoais sensíveis.
+
+### Estado e injeção de dependência
+
+23. **A composição é explícita em `main.dart`.** Ela instancia os ports concretos, depois os services e por fim os providers, sempre por construtor. Não use service locator.
+24. **Escopo dos providers:**
+    - Globais (auth, sessão) ficam no `MultiProvider` acima do `MaterialApp.router`.
+    - Providers de uma área ficam com `ChangeNotifierProvider.value` no `ShellRoute` dessa área.
+    - Providers de tela efêmera são criados no `builder` da `GoRoute`.
+25. **Carga inicial** acontece em `initState` com `WidgetsBinding.instance.addPostFrameCallback((_) => _load())`.
+26. **Depois de qualquer `await` na view**, confira `if (!mounted) return;` (ou `context.mounted`) antes de usar o `context`.
+27. **Paralelize com `Future.wait`** somente chamadas independentes, e trate cada resultado com tipo explícito, sem `as List<T>`.
+28. **Exponha coleções como somente leitura** (`List.unmodifiable`) e só chame `notifyListeners()` quando o estado mudar de fato.
+
+### Navegação
+
+29. **Paths são constantes em uma classe `RoutesMapping`.** Nunca escreva string de rota solta na view.
+30. **Toda `GoRoute` tem `name`.** Navegue com `context.go(...)` ou `context.push(...)` usando `RoutesMapping`.
+31. **Autenticação e acesso** são decididos no `redirect` do `GoRouter`, com `refreshListenable` apontando para o provider de auth. Não faça checagem de login dentro das telas.
+32. **Áreas com navegação própria** (por perfil, com bottom bar) usam `ShellRoute` com `navigatorKey` dedicado.
+33. **Push notifications e deep links** passam por um único método do gerenciador de rotas.
+
+### UI, tema e acessibilidade
+
+34. **Cores vêm de uma `enum` de paleta** (com getter `color`) **e de uma extensão de `ThemeData`** (`Theme.of(context).primary`). Evite `Colors.*` e hexadecimais na view.
+35. **Textos usam `AppTypography.of(context).<estilo>(...)`**, que escolhe entre mobile e tablet. Evite `TextStyle(fontSize: ...)` solto.
+36. **Botões, inputs, modais e snackbars** usam os componentes de `shared/components` ou os estilos expostos pela extensão de tema. Raio de borda, breakpoints e limites ficam em `AppConstraints`.
+37. **Feedback ao usuário** passa por `AppSnackBars.showSuccess`, `showError` e `showWarning`.
+38. **Layout responsivo** decide com `AppConstraints.isMobile` ou `isTablet` no nível da tela, e com `LayoutBuilder` dentro dos widgets.
+39. **Widgets pequenos e `const`:** quebre a tela em widgets dentro de `views/components/` em vez de métodos `_buildX()` gigantes.
+40. **Acessibilidade:** ícones clicáveis têm `tooltip` ou `Semantics`, e ícones informativos têm `semanticLabel`.
+
+### Testes
+
+41. **Testes ficam em `test/`, espelhando `lib/`**, com sufixo `_test.dart`.
+42. **Services são testados com um *fake* do port** (uma classe que implementa o contrato). Providers são testados com o service real sobre esse port fake. Não acesse rede nem serviços externos em teste unitário.
+43. **Widgets são testados com `testWidgets`**, envolvendo a tela em `MaterialApp` e `ChangeNotifierProvider.value`. Use `pump` para mudanças simples e `pumpAndSettle` para animações e operações async.
+
+## Fluxo para criar uma feature
+
+- [ ] **1. Pasta.** Crie `lib/components/<feature>/` com `models/`, `services/`, `providers/` e `views/`.
+- [ ] **2. Model.** Crie a classe imutável com `fromJson` defensivo.
+- [ ] **3. Port.** Se precisar de infraestrutura nova, crie o contrato em `shared/services/ports/` e a implementação em `shared/services/`.
+- [ ] **4. Service.** Receba os ports pelo construtor e retorne `TaskEither<Exception, T>`.
+- [ ] **5. Provider.** Estenda `ChangeNotifier`, guarde o estado privado e use `TaskEither.tryCatch`, `Log` e a `Failure` do domínio.
+- [ ] **6. View.** Leia com `context.watch`, aja com `context.read` e consuma com `.run()` + `.match`.
+- [ ] **7. Rota.** Adicione a constante em `RoutesMapping` e a `GoRoute` nomeada.
+- [ ] **8. DI.** Instancie o service e o provider em `main.dart` e registre no escopo certo.
+- [ ] **9. Testes.** Teste o service com port fake, o provider e o widget principal.
+- [ ] **10. Validação:**
+
+```bash
+dart format lib test
+flutter analyze --fatal-infos
+flutter test
+```
+
+## Exemplos (feature ilustrativa: tarefas)
+
+### Port
+
+```dart
+// lib/shared/services/ports/app_http_port.dart
+import 'package:fpdart/fpdart.dart';
+
+/// Contrato de acesso HTTP à API do app.
+abstract class AppHttpPort {
+  /// Executa um GET em [path] e converte a resposta com [fromJson].
+  TaskEither<Exception, T> get<T>(String path, T Function(dynamic) fromJson);
+}
+```
+
+### Model
+
+```dart
+// lib/components/tasks/models/task_model.dart
+
+/// Representa uma tarefa do usuário.
+class TaskModel {
+  /// Identificador da tarefa.
+  final String id;
+
+  /// Título exibido na lista.
+  final String title;
+
+  /// Data de conclusão, quando houver.
+  final DateTime? doneAt;
+
+  /// Cria uma tarefa imutável.
+  const TaskModel({required this.id, required this.title, this.doneAt});
+
+  /// Constrói a tarefa a partir do JSON da API.
+  factory TaskModel.fromJson(Map<String, dynamic> json) {
+    return TaskModel(
+      id: json['id']?.toString() ?? '',
+      title: json['title']?.toString() ?? '',
+      doneAt: DateTime.tryParse(json['done_at']?.toString() ?? ''),
+    );
+  }
+
+  /// Indica se a tarefa foi concluída.
+  bool get isDone => doneAt != null;
+}
+```
+
+### Service
+
+```dart
+// lib/components/tasks/services/tasks_service.dart
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/models/task_model.dart';
+import 'package:my_app/shared/services/ports/app_http_port.dart';
+
+/// Acessa os dados de tarefas.
+class TasksService {
+  /// Porta HTTP para a API.
+  final AppHttpPort _httpPort;
+
+  /// Cria o serviço com a porta HTTP injetada.
+  TasksService(this._httpPort);
+
+  /// Busca as tarefas do usuário autenticado.
+  TaskEither<Exception, List<TaskModel>> getTasks() {
+    return _httpPort.get<List<TaskModel>>('/tasks', (json) {
+      final List<dynamic> list = json is List
+          ? json
+          : (json['data'] ?? <dynamic>[]) as List<dynamic>;
+      return list
+          .map((item) => TaskModel.fromJson(item as Map<String, dynamic>))
+          .toList();
+    });
+  }
+}
+```
+
+### Provider
+
+```dart
+// lib/components/tasks/providers/tasks_provider.dart
+import 'package:flutter/foundation.dart';
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/models/task_model.dart';
+import 'package:my_app/components/tasks/services/tasks_service.dart';
+import 'package:my_app/shared/errors/failure.dart';
+import 'package:my_app/shared/errors/log.dart';
+
+/// Gerencia o estado da tela de tarefas.
+class TasksProvider extends ChangeNotifier {
+  /// Serviço de acesso às tarefas.
+  final TasksService _service;
+
+  /// Cria o provider com o serviço injetado.
+  TasksProvider(this._service);
+
+  /// Tarefas carregadas.
+  List<TaskModel> _tasks = const [];
+
+  /// Indica se as tarefas estão sendo carregadas.
+  bool _isLoading = false;
+
+  /// Tarefas carregadas, somente leitura.
+  List<TaskModel> get tasks => List.unmodifiable(_tasks);
+
+  /// Indica se as tarefas estão sendo carregadas.
+  bool get isLoading => _isLoading;
+
+  /// Carrega as tarefas e notifica a tela.
+  TaskEither<Failure, Unit> load() {
+    return TaskEither.tryCatch(
+      () async {
+        _setLoading(true);
+        try {
+          final result = await _service.getTasks().run();
+          _tasks = result.getOrElse((error) => throw error);
+          return unit;
+        } finally {
+          _setLoading(false);
+        }
+      },
+      (error, stack) {
+        Log.print<Error>(
+          message: 'Erro ao carregar tarefas',
+          origin: 'TasksProvider',
+          method: 'load',
+          error: error,
+          stack: stack,
+        );
+        return const LoadingFailure('Não foi possível carregar suas tarefas.');
+      },
+    );
+  }
+
+  /// Atualiza o indicador de carregamento e notifica os ouvintes.
+  void _setLoading(bool value) {
+    _isLoading = value;
+    notifyListeners();
+  }
+}
+```
+
+### View
+
+```dart
+// lib/components/tasks/views/tasks_view.dart
+import 'package:flutter/material.dart';
+import 'package:my_app/components/tasks/providers/tasks_provider.dart';
+import 'package:my_app/shared/components/widgets/app_snackbars.dart';
+import 'package:my_app/shared/theme/app_theme.dart';
+import 'package:my_app/shared/typography/app_typography.dart';
+import 'package:provider/provider.dart';
+
+/// Tela com a lista de tarefas.
+class TasksView extends StatefulWidget {
+  /// Cria a tela de tarefas.
+  const TasksView({super.key});
+
+  /// Cria o estado da tela.
+  @override
+  State<TasksView> createState() => _TasksViewState();
+}
+
+/// Estado da tela de tarefas.
+class _TasksViewState extends State<TasksView> {
+  /// Agenda a carga inicial após o primeiro frame.
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) => _load());
+  }
+
+  /// Carrega as tarefas e mostra erro amigável em caso de falha.
+  Future<void> _load() async {
+    final result = await context.read<TasksProvider>().load().run();
+    if (!mounted) return;
+    result.match(
+      (failure) => AppSnackBars.showError(context, failure.message),
+      (_) {},
+    );
+  }
+
+  /// Monta a lista de tarefas.
+  @override
+  Widget build(BuildContext context) {
+    final provider = context.watch<TasksProvider>();
+    final typography = AppTypography.of(context);
+
+    if (provider.isLoading) {
+      return Center(
+        child: CircularProgressIndicator(color: Theme.of(context).primary),
+      );
+    }
+
+    return ListView.separated(
+      padding: const EdgeInsets.all(16),
+      itemCount: provider.tasks.length,
+      separatorBuilder: (_, _) => const SizedBox(height: 8),
+      itemBuilder: (context, index) {
+        final task = provider.tasks[index];
+        return ListTile(
+          title: Text(task.title, style: typography.topic()),
+          trailing: Icon(
+            task.isDone ? Icons.check_circle : Icons.schedule,
+            color: Theme.of(context).primary,
+            semanticLabel: task.isDone ? 'Concluída' : 'Pendente',
+          ),
+        );
+      },
+    );
+  }
+}
+```
+
+### Teste do service com port fake
+
+```dart
+// test/components/tasks/services/tasks_service_test.dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:fpdart/fpdart.dart';
+import 'package:my_app/components/tasks/services/tasks_service.dart';
+import 'package:my_app/shared/services/ports/app_http_port.dart';
+
+/// Porta HTTP falsa que devolve uma resposta fixa.
+class _FakeHttpPort implements AppHttpPort {
+  /// Cria a porta com a resposta a devolver.
+  _FakeHttpPort(this.response);
+
+  /// Resposta JSON simulada.
+  final Object response;
+
+  /// Devolve a resposta simulada convertida pelo [fromJson].
+  @override
+  TaskEither<Exception, T> get<T>(String path, T Function(dynamic) fromJson) =>
+      TaskEither.of(fromJson(response));
+}
+
+void main() {
+  test('converte a lista da API em TaskModel', () async {
+    final service = TasksService(
+      _FakeHttpPort({
+        'data': [
+          {'id': '1', 'title': 'Revisar PR', 'done_at': '2026-05-10'},
+        ],
+      }),
+    );
+
+    final result = await service.getTasks().run();
+
+    final tasks = result.getOrElse((error) => throw error);
+    expect(tasks.single.title, 'Revisar PR');
+    expect(tasks.single.isDone, isTrue);
+  });
+}
+```
+
+## Evite
+
+- **`Failure` genérica ou errada:** por exemplo, `AuthFailure` para erro de carregamento.
+- **Estilos fixos na view:** `Colors.white`, `TextStyle(fontSize: 16)`, `Colors.grey.shade300`.
+- **Casts depois de `Future.wait`:** algo como `results[0] as List<T>`.
+- **Import duplicado** do mesmo arquivo com e sem alias.
+- **Declarações sem `///`.**
+- **Consumo de `TaskEither` só com `mapLeft`**, que ignora o caminho de sucesso.
+- **`try/catch` dentro da view** para tratar erro de provider. O erro já chega como `Failure`.
+
+## Referências
+
+- Guia de arquitetura do Flutter: https://docs.flutter.dev/app-architecture
+- Testes no Flutter: https://docs.flutter.dev/testing/overview
+- Effective Dart: https://dart.dev/effective-dart
+- Skills oficiais do Flutter: https://github.com/flutter/skills

package/content/skills/hex-pattern-dart/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: hex-pattern-dart
+description: Padrão hexagonal (ports & adapters) da DS9 para projetos Dart, independente de framework — organização por contexto em domain (models, ports, services) e adapter (controllers, dtos, repository), regra de dependência, camadas de erro fixas (BusinessException, ClientException, MiddlewareException), composição de dependências na borda e resultado tipado com TaskEither. Use ao criar, revisar ou refatorar módulos/features, definir camadas, ports, services, adapters ou repositórios em Dart, ou quando o usuário pedir "arquitetura hexagonal", "ports and adapters" ou "organização de novo contexto".
+---
+
+# Padrão Hexagonal DS9 para Dart (`hex-pattern-dart`)
+
+Base arquitetural dos projetos Dart da DS9. Isola a regra de negócio de protocolo, banco e framework, deixando o núcleo testável e substituível. Siga junto com a skill `dart` (nomenclatura, `///`, OOP). Para um framework específico, use também a skill dele (ex.: `dart-frog` aplica este padrão em APIs HTTP). Esta skill não depende de nenhum framework nem de projeto específico. **Escopo:** back-end e pacotes Dart de domínio. Apps Flutter seguem a skill `flutter` (organização própria em components/providers/services); dela aproveite só os princípios (regra de dependência, ports, `TaskEither`).
+
+Os blocos de código nos arquivos complementares são **pseudocódigo** ilustrativo: adapte à sintaxe e às versões do projeto.
+
+## 1. Regras inegociáveis
+
+1. **Regra de dependência:** `adapter → domain`. O `domain` nunca importa `adapter`, framework, driver de banco nem tipos de protocolo (request/response).
+2. **Resultado tipado:** operações que podem falhar retornam `TaskEither<Exception, T>` (`fpdart`), criado com `TaskEither.tryCatch`. Não lance exceção através das camadas. Se `fpdart` não estiver no `pubspec.yaml`, informe que ele é obrigatório para seguir o padrão DS9 e peça autorização para instalar.
+3. **Composição na borda:** dependências são montadas em um único ponto (composition root) e injetadas por construtor. Nunca instancie service, repositório ou controller dentro da rota/handler.
+4. **Camadas de erro fixas:** `BusinessException` (domínio), `ClientException` (resposta ao cliente) e `MiddlewareException` (borda). Erro 5xx nunca expõe mensagem interna.
+5. **Sem regra de negócio no adapter:** controller traduz protocolo ↔ chamada do service; repositório só persiste e mapeia.
+6. **Projeto existente:** preserve a estrutura atual; aplique o padrão no código novo e no que for pedido, sem refatorar o restante.
+
+## 2. Estrutura por contexto
+
+```text
+lib/
+├── <contexto>/                  # bounded context (ex.: orders)
+│   ├── domain/
+│   │   ├── models/              # entidades e value objects (invariantes)
+│   │   ├── ports/               # contratos que o domínio precisa (saída)
+│   │   └── services/            # casos de uso; dependem só de ports e models
+│   └── adapter/
+│       ├── controllers/         # entrada: traduz protocolo → service → resposta
+│       ├── dtos/                # contratos de entrada/saída + validação
+│       └── repository/          # saída: implementa ports (persistência, clients)
+└── common/                      # exceções, tipos e utilitários compartilhados
+```
+
+- Imports **relativos** dentro de `lib/`; o composition root e os testes usam `package:`.
+- Um contexto não importa `domain`/`adapter` de outro. Comunique-se por port ou por tipos em `common/`.
+
+## 3. Responsabilidades
+
+| Peça | Faz | Não faz |
+|---|---|---|
+| `model` | Invariantes, comportamento do negócio | I/O, serialização de protocolo |
+| `port` | Declara o contrato (`abstract interface class`) | Implementação |
+| `service` | Orquestra ports, aplica regra e autorização de recurso, retorna `TaskEither` | Conhece HTTP, SQL, DTO |
+| `controller` | Valida DTO, chama service, mapeia erro de negócio → `ClientException` | Regra de negócio |
+| `dto` | Entrada/saída do protocolo, `fromJson`/`toJson` | Ser usado no domínio |
+| `repository` | Implementa port, mapeia modelo ↔ persistência | Regra de negócio |
+
+## 4. Erros por camada
+
+- Repositório/service: `TaskEither.tryCatch` converte falha em `BusinessException` (com `domainName`, `statusCode`, mensagem segura, erro original e stack).
+- Controller: converte `BusinessException` em `ClientException` (mensagem segura; 5xx genérico).
+- Borda (middleware/handler): converte `ClientException`/`MiddlewareException` em resposta de protocolo.
+
+## 5. Checklist rápido
+
+- [ ] O `domain` não importa nada de `adapter` nem de framework?
+- [ ] Todo retorno que pode falhar é `TaskEither` via `tryCatch`?
+- [ ] Dependências vêm do composition root por construtor?
+- [ ] Os erros usam as 3 camadas e 5xx não vaza detalhe?
+- [ ] Controller sem regra de negócio; repositório sem regra de negócio?
+- [ ] DTO fica fora do `domain`?
+- [ ] Existem testes do service com fakes das ports?
+
+## 6. Arquivos complementares (leitura sob demanda)
+
+Use `list_skill_files` e `get_skill_file` com `skill: hex-pattern-dart`.
+
+| Dúvida | Arquivo |
+|---|---|
+| Camadas e regra de dependência | `references/layers-and-dependency-rule.md` |
+| Como desenhar ports e adapters | `references/ports-and-adapters.md` |
+| Camadas de erro | `references/error-layers.md` |
+| Injeção e composition root | `references/dependency-injection.md` |
+| Persistência agnóstica e mapper | `references/persistence.md` |
+| Estratégia de testes | `references/testing.md` |
+| Erros comuns | `references/anti-patterns.md` |
+| Checklist completo de review | `references/checklist.md` |
+| Árvore de pastas de exemplo | `examples/structure-tree.md` |
+| Port (`<Papel>Port`), service e adapters (pseudocódigo) | `examples/port.md`, `examples/service.md`, `examples/adapter-in.md`, `examples/adapter-out.md` |
+| Hierarquia de exceções | `examples/errors.md` |

package/content/skills/hex-pattern-dart/examples/adapter-in.md

@@ -0,0 +1,24 @@
+# Adapter de entrada — controller (pseudocódigo)
+
+```text
+// adapter/controllers/order_controller.dart
+/// Traduz o protocolo para o service e o resultado para a resposta.
+class OrderController
+  final OrderService _service
+
+  OrderController(this._service)
+
+  Task<Response> getById(Context context, String id)
+    return _service.getById(id, context.requesterId)
+      .mapLeft(toClientException)                  // BusinessException -> ClientException
+      .match(
+        (client) => Response(status: client.statusCode, body: client.message),
+        (order)  => Response.ok(OrderResponse.from(order)),
+      )
+
+toClientException(BusinessException e)
+  safe = e.statusCode >= 500 ? "Erro interno" : e.message   // 5xx genérico
+  return ClientException(statusCode: e.statusCode, message: safe)
+```
+
+Pontos-chave: sem regra de negócio; service recebido por construtor; erro 5xx sem detalhe interno; o log guarda `e.error` e `e.stackTrace`.

package/content/skills/hex-pattern-dart/examples/adapter-out.md

@@ -0,0 +1,20 @@
+# Adapter de saída — repository (pseudocódigo)
+
+```text
+// adapter/repository/order_repository.dart
+/// Implementa OrderRepositoryPort sobre a tecnologia de persistência do projeto.
+class OrderRepository implements OrderRepositoryPort
+  final DataSource _source              // abstração do acesso físico
+
+  OrderRepository(this._source)
+
+  TaskEither<BusinessException, Order> findById(String id)
+    return TaskEither.tryCatch(
+      () async => OrderMapper.toDomain(await _source.read(id)),
+      (error, stack) => BusinessException(
+        domainName: "orders", statusCode: 500,
+        message: "Falha ao consultar pedido", error: error, stackTrace: stack),
+    )
+```
+
+Pontos-chave: toda chamada de I/O em `tryCatch`; mapper converte persistência → domínio; a falha vira `BusinessException` com mensagem segura.

package/content/skills/hex-pattern-dart/examples/errors.md

@@ -0,0 +1,25 @@
+# Hierarquia de exceções (pseudocódigo)
+
+```text
+// common/exceptions
+/// Falha de regra de negócio ou de infraestrutura vista pelo domínio.
+class BusinessException implements Exception
+  String domainName
+  int    statusCode
+  String message            // segura para o cliente
+  Object? error             // causa original (somente log)
+  StackTrace? stackTrace
+
+/// Falha pronta para ser devolvida ao cliente.
+class ClientException implements Exception
+  int    statusCode
+  String message
+
+/// Falha da borda (autenticação, parsing, composição).
+class MiddlewareException implements Exception
+  int    statusCode
+  String message
+  StackTrace? stackTrace
+```
+
+Regra: `BusinessException` → (controller) → `ClientException`. A borda converte qualquer uma das duas, ou `MiddlewareException`, em resposta de protocolo.

package/content/skills/hex-pattern-dart/examples/port.md

@@ -0,0 +1,11 @@
+# Port (pseudocódigo)
+
+```text
+// domain/ports/order_repository.dart
+/// Contrato de persistência de pedidos exigido pelo domínio.
+abstract interface class OrderRepositoryPort
+  TaskEither<BusinessException, Order>  findById(String id)
+  TaskEither<BusinessException, Unit>   save(Order order)
+```
+
+Pontos-chave: só depende de `Order` e de `BusinessException`; nenhuma menção a banco, SQL ou protocolo.

package/content/skills/hex-pattern-dart/examples/service.md

@@ -0,0 +1,20 @@
+# Service (pseudocódigo)
+
+```text
+// domain/services/order_service.dart
+/// Casos de uso de pedidos.
+class OrderService
+  final OrderRepositoryPort _repository          // recebido por construtor
+
+  OrderService(this._repository)
+
+  TaskEither<BusinessException, Order> getById(String id, String requesterId)
+    return _repository.findById(id).flatMap((order) =>
+      order.belongsTo(requesterId)                       // autorização de recurso aqui
+        ? TaskEither.right(order)
+        : TaskEither.left(BusinessException(
+            domainName: "orders", statusCode: 403, message: "Acesso negado"))
+    )
+```
+
+Pontos-chave: depende só da port; sem DTO, sem protocolo; regra e autorização no service; retorno `TaskEither`.

package/content/skills/hex-pattern-dart/examples/structure-tree.md

@@ -0,0 +1,28 @@
+# Árvore de pastas (exemplo)
+
+```text
+lib/
+├── common/
+│   ├── exceptions/
+│   │   ├── business_exception.dart
+│   │   ├── client_exception.dart
+│   │   └── middleware_exception.dart
+│   └── error_response.dart
+└── orders/
+    ├── domain/
+    │   ├── models/order.dart
+    │   ├── ports/order_repository.dart
+    │   └── services/order_service.dart
+    └── adapter/
+        ├── controllers/order_controller.dart
+        ├── dtos/create_order_dto.dart
+        └── repository/
+            ├── order_mapper.dart
+            └── order_repository.dart
+test/
+└── orders/
+    ├── domain/services/order_service_test.dart
+    └── adapter/controllers/order_controller_test.dart
+```
+
+Adicione um novo contexto criando a mesma árvore sob `lib/<contexto>/`.

package/content/skills/hex-pattern-dart/references/anti-patterns.md

@@ -0,0 +1,16 @@
+# Anti-padrões
+
+| Anti-padrão | Por que é problema | Correção |
+|---|---|---|
+| Instanciar controller/service dentro da rota | Impede troca e teste; acopla borda ao concreto | Injetar pelo composition root |
+| Regra de negócio em middleware/controller | Some em testes de domínio; duplica em outros adapters | Mover para o service |
+| Ler segmento de path por posição para autorizar | Frágil e fácil de burlar | Autorizar no service com o identificador do recurso |
+| `error.toString()` na resposta | Vaza detalhe interno ao cliente | Mensagem segura em `ClientException` |
+| `catch (_) {}` genérico | Engole a causa e o stack | `TaskEither.tryCatch` + `BusinessException` |
+| DTO usado no `domain` | Acopla negócio ao protocolo | DTO só em `adapter/dtos` |
+| Model de persistência exposto ao `domain` | Acopla negócio ao banco | Mapper no repositório |
+| Service que acessa banco/HTTP direto | Quebra a regra de dependência | Criar port e adapter |
+| Service "faz tudo" (god service) | Difícil de testar e evoluir | Um service por caso de uso/agregado |
+| Contexto importando `domain` de outro | Acoplamento entre contextos | Port ou tipo em `common/` |
+| Exceção lançada entre camadas | Fluxo de erro invisível no tipo | Retornar `TaskEither` |
+| `null` como "não encontrado" | Ambíguo | `Option`/`left` explícito |