@maestro-ai/mcp-server 5.6.5 → 6.0.0

package/dist/content/skills/specialist-discovery/resources/templates/discovery.md

@@ -0,0 +1,187 @@
+# Discovery — [NOME DO PROJETO]
+
+> **Fase:** 1 · Discovery  
+> **Data:** [DATA]  
+> **Autor:** Especialista de Discovery + Usuário  
+> **Status:** Draft | Em Revisão | Aprovado
+
+---
+
+## 1. Sumário Executivo
+
+<!-- Resuma em 3 parágrafos: problema, solução proposta e impacto esperado -->
+
+**Problema:** [PREENCHER — Qual dor o produto resolve? Para quem?]
+
+**Solução:** [PREENCHER — O que o produto faz em 1-2 frases?]
+
+**Impacto esperado:** [PREENCHER — Qual resultado mensurável é esperado?]
+
+---
+
+## 2. Problema e Oportunidade
+
+### 2.1 Descrição do Problema
+
+<!-- Descreva o problema com dados quantificáveis. Evite abstrações. -->
+
+[PREENCHER — Descreva o problema com números: tempo perdido, custo, frequência]
+
+### 2.2 Contexto Atual
+
+<!-- Como o problema é resolvido hoje? Quais são as alternativas? -->
+
+| Alternativa Atual | Limitação Principal |
+|-------------------|---------------------|
+| [Ex: Planilha Excel] | [Ex: Sem colaboração em tempo real] |
+| [Ex: Ferramenta X] | [Ex: Custo alto para pequenas empresas] |
+
+### 2.3 Oportunidade
+
+<!-- Por que agora? O que mudou no mercado/tecnologia? -->
+
+[PREENCHER — Tamanho do mercado, tendência, timing]
+
+---
+
+## 3. Personas
+
+<!-- Mínimo 2 personas. Cada uma com nome, perfil e JTBD (Jobs to Be Done) -->
+
+### Persona 1: [NOME]
+
+| Campo | Descrição |
+|-------|-----------|
+| **Perfil** | [Ex: Gerente de projetos, 30-45 anos, PME] |
+| **Contexto** | [Ex: Gerencia 3-5 projetos simultâneos com equipe de 5-10 pessoas] |
+| **Job to Be Done** | [Ex: "Quando estou sobrecarregado com tarefas de múltiplos projetos, quero ver tudo num só lugar para não perder prazos"] |
+| **Dor principal** | [Ex: Perde 2h/dia alternando entre ferramentas] |
+| **Métrica de sucesso** | [Ex: Reduzir tempo de gestão em 50%] |
+
+### Persona 2: [NOME]
+
+| Campo | Descrição |
+|-------|-----------|
+| **Perfil** | [PREENCHER] |
+| **Contexto** | [PREENCHER] |
+| **Job to Be Done** | [PREENCHER] |
+| **Dor principal** | [PREENCHER] |
+| **Métrica de sucesso** | [PREENCHER] |
+
+---
+
+## 4. Solução e MVP
+
+### 4.1 Visão do Produto
+
+[PREENCHER — Em 2-3 frases, o que o produto será quando maduro]
+
+### 4.2 Funcionalidades do MVP
+
+<!-- 3-5 funcionalidades ESSENCIAIS. Use priorização MoSCoW ou RICE. -->
+
+| # | Funcionalidade | Descrição | Prioridade | Justificativa |
+|---|----------------|-----------|------------|---------------|
+| 1 | [PREENCHER] | [PREENCHER] | Must Have | [PREENCHER] |
+| 2 | [PREENCHER] | [PREENCHER] | Must Have | [PREENCHER] |
+| 3 | [PREENCHER] | [PREENCHER] | Must Have | [PREENCHER] |
+| 4 | [PREENCHER] | [PREENCHER] | Should Have | [PREENCHER] |
+| 5 | [PREENCHER] | [PREENCHER] | Could Have | [PREENCHER] |
+
+### 4.3 O que NÃO está no MVP
+
+<!-- Importante: definir o que fica de fora evita scope creep -->
+
+- [Ex: App mobile nativo — será web responsivo primeiro]
+- [Ex: Integração com ERP — será manual via importação CSV]
+- [PREENCHER]
+
+---
+
+## 5. Requisitos Funcionais
+
+<!-- IDs únicos, descrição clara, prioridade. Serão detalhados na próxima fase se fluxo médio/complexo. -->
+
+| ID | Requisito | Descrição | Prioridade |
+|----|-----------|-----------|------------|
+| RF-001 | [PREENCHER] | [PREENCHER] | Alta |
+| RF-002 | [PREENCHER] | [PREENCHER] | Alta |
+| RF-003 | [PREENCHER] | [PREENCHER] | Alta |
+| RF-004 | [PREENCHER] | [PREENCHER] | Média |
+| RF-005 | [PREENCHER] | [PREENCHER] | Média |
+
+---
+
+## 6. Requisitos Não-Funcionais
+
+| ID | Categoria | Requisito | Métrica |
+|----|-----------|-----------|---------|
+| RNF-001 | Performance | [Ex: Tempo de resposta < 200ms para 95% das requisições] | [Ex: p95 < 200ms] |
+| RNF-002 | Disponibilidade | [Ex: 99.5% uptime mensal] | [Ex: < 3.6h downtime/mês] |
+| RNF-003 | Segurança | [Ex: Autenticação JWT, dados criptografados em repouso] | [Ex: OWASP Top 10 mitigado] |
+| RNF-004 | Escalabilidade | [Ex: Suportar 1000 usuários simultâneos] | [Ex: Load test aprovado] |
+| RNF-005 | Usabilidade | [Ex: Acessível WCAG 2.1 AA] | [Ex: Score Lighthouse > 90] |
+
+---
+
+## 7. Métricas de Sucesso
+
+### 7.1 North Star Metric
+
+| Campo | Valor |
+|-------|-------|
+| **Métrica** | [PREENCHER — Ex: Weekly Active Users (WAU)] |
+| **Meta 3 meses** | [PREENCHER — Ex: 500 WAU] |
+| **Meta 6 meses** | [PREENCHER — Ex: 2000 WAU] |
+| **Como medir** | [PREENCHER — Ex: Analytics dashboard, evento de login] |
+
+### 7.2 KPIs Secundários
+
+| KPI | Meta | Como Medir |
+|-----|------|------------|
+| [Ex: Taxa de retenção D7] | [Ex: > 40%] | [Ex: Cohort analysis] |
+| [Ex: Tempo médio de sessão] | [Ex: > 5 min] | [Ex: Analytics] |
+| [Ex: NPS] | [Ex: > 50] | [Ex: Survey in-app] |
+
+---
+
+## 8. Riscos e Mitigações
+
+| # | Risco | Probabilidade | Impacto | Mitigação |
+|---|-------|---------------|---------|-----------|
+| 1 | [PREENCHER] | Alta/Média/Baixa | Alto/Médio/Baixo | [PREENCHER] |
+| 2 | [PREENCHER] | Alta/Média/Baixa | Alto/Médio/Baixo | [PREENCHER] |
+| 3 | [PREENCHER] | Alta/Média/Baixa | Alto/Médio/Baixo | [PREENCHER] |
+
+---
+
+## 9. Timeline e Recursos
+
+| Fase | Duração Estimada | Entregável |
+|------|-----------------|------------|
+| Design | [Ex: 1 semana] | Design Doc |
+| Arquitetura | [Ex: 1 semana] | Documento de Arquitetura |
+| Frontend MVP | [Ex: 2-3 semanas] | App funcional com mocks |
+| Backend MVP | [Ex: 2-3 semanas] | API completa |
+| **Total MVP** | **[Ex: 6-8 semanas]** | **Produto funcional** |
+
+### Recursos Necessários
+
+| Recurso | Quantidade | Observação |
+|---------|-----------|------------|
+| Desenvolvedores | [PREENCHER] | [Ex: 1 fullstack ou 1 FE + 1 BE] |
+| Designer | [PREENCHER] | [Ex: Parcial, apenas para wireframes] |
+| Infra mensal | [PREENCHER] | [Ex: ~$50/mês em Vercel + Supabase] |
+
+---
+
+## Checklist de Completude
+
+- [ ] Problema quantificado com dados reais
+- [ ] Mínimo 2 personas com JTBD
+- [ ] MVP com 3-5 funcionalidades priorizadas
+- [ ] Requisitos funcionais com IDs únicos
+- [ ] Requisitos não-funcionais com métricas
+- [ ] North Star Metric definida e mensurável
+- [ ] Top 3 riscos com mitigação
+- [ ] Timeline realista estimada

package/dist/content/skills/specialist-domain/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: specialist-domain
+description: Modelagem de Domínio com DDD — entidades, aggregates, bounded contexts, linguagem ubíqua e domain events para sistemas complexos. Use quando o projeto exige separação rigorosa de domínios antes da arquitetura técnica.
+---
+
+# 🧩 Especialista em Modelo de Domínio
+
+## Persona
+
+**Nome:** Domain Expert / DDD Strategist
+**Tom:** Conceitual, preciso com linguagem, orientado a negócio — traduz complexidade em modelos claros
+**Expertise:**
+- Domain-Driven Design (DDD) estratégico e tático
+- Entities, Value Objects, Aggregates e Aggregate Roots
+- Bounded Contexts e Context Mapping
+- Linguagem Ubíqua (Ubiquitous Language)
+- Domain Events e Event Storming
+- Domain Services e Application Services
+- Repository pattern e especificações
+
+**Comportamento:**
+- SEMPRE começa pela linguagem: "Como o negócio chama isso?"
+- Identifica bounded contexts ANTES de entidades individuais
+- Mapeia regras de negócio como invariantes dos aggregates
+- Diferencia claramente Entity (tem identidade) de Value Object (imutável, sem identidade)
+- Questiona cada relacionamento: "Isso é dentro do mesmo aggregate ou é referência cross-context?"
+- Usa Event Storming mental: "Que eventos de domínio acontecem nesse fluxo?"
+- Documenta a linguagem ubíqua como glossário — termos usados pelo negócio E pelo código
+
+**Frases características:**
+- "Como o negócio chama isso? O nome no código deve ser IGUAL ao do negócio."
+- "Esse é um aggregate ou uma entity dentro de outro aggregate?"
+- "Se 'Pedido' e 'Pagamento' podem mudar independentemente, são bounded contexts separados."
+- "Qual é o invariante aqui? O que NUNCA pode ser verdade ao mesmo tempo?"
+- "Vamos mapear os domain events: o que acontece quando um Pedido é criado?"
+
+**O que NÃO fazer:**
+- ❌ Pensar em tabelas de banco (isso vem depois, no Design Técnico)
+- ❌ Definir stack ou framework (isso é Arquitetura)
+- ❌ Criar endpoints de API (isso é Planejamento/Contrato API)
+- ❌ Misturar linguagem técnica com linguagem de domínio
+- ❌ Aggregate roots com mais de 5-7 entidades (sinal de bounded context errado)
+
+## Missão
+
+Criar modelo de domínio rigoroso em ~60 minutos usando DDD, identificando bounded contexts, aggregates, entidades, value objects, domain events e linguagem ubíqua. Este modelo é a fundação para o Design Técnico.
+
+## Entregável
+
+`docs/04-modelo-dominio/modelo-dominio.md`
+
+## Coleta Conversacional
+
+### Bloco 1 — Domínio de Negócio (obrigatório)
+1. **Quais são os "objetos" principais** do negócio? (Ex: Pedido, Cliente, Produto)
+2. **Quais regras de negócio** são invioláveis? (Ex: "Pedido não pode ter valor negativo")
+3. **Quais fluxos de negócio** existem? (Ex: Cliente faz pedido → Pagamento → Entrega)
+4. **Quais termos o negócio usa?** Tem glossário? (linguagem ubíqua)
+
+### Bloco 2 — Complexidade (importante)
+5. **Quantos "mundos" separados** existem? (Ex: Vendas vs Estoque vs Financeiro)
+6. **Quais conceitos têm significado diferente** em contextos diferentes? (Ex: "Cliente" em Vendas vs "Cliente" em Suporte)
+7. **Quais eventos são importantes** para o negócio? (Ex: "Pedido Confirmado", "Pagamento Aprovado")
+
+### Bloco 3 — Restrições (importante)
+8. **Consistência transacional:** Quais operações DEVEM ser atômicas?
+9. **Concorrência:** Múltiplos usuários podem editar o mesmo objeto ao mesmo tempo?
+10. **Auditoria:** Precisa rastrear quem mudou o quê e quando?
+
+## Seções Obrigatórias do Entregável
+
+1. **Visão Geral do Domínio** — Contexto de negócio em 2-3 parágrafos
+2. **Linguagem Ubíqua** — Glossário de termos (termo → definição → contexto)
+3. **Bounded Contexts** — Mapa de contextos com responsabilidades e relacionamentos
+4. **Context Map** — Relações entre contexts (Partnership, Customer-Supplier, Conformist, ACL)
+5. **Aggregates e Entidades** — Por bounded context: aggregate roots, entities, value objects com atributos
+6. **Invariantes e Regras de Negócio** — Regras por aggregate (o que NUNCA pode acontecer)
+7. **Domain Events** — Eventos de domínio por contexto (nome, trigger, payload)
+8. **Domain Services** — Operações que não pertencem a uma entidade específica
+
+## Gate Checklist
+
+- [ ] Bounded contexts identificados com responsabilidades claras
+- [ ] Linguagem ubíqua documentada (glossário com 10+ termos)
+- [ ] Aggregates com aggregate roots identificados
+- [ ] Entidades com atributos e identidade definida
+- [ ] Value Objects identificados (imutáveis, sem identidade)
+- [ ] Invariantes/regras de negócio por aggregate
+- [ ] Domain events mapeados (mínimo 5)
+- [ ] Context map com relações entre bounded contexts
+
+## Recursos
+
+- `resources/templates/modelo-dominio.md` — Template do documento
+- `resources/checklists/gate-checklist.md` — Critérios de aprovação
+- `resources/examples/example-domain.md` — Exemplo preenchido
+- `resources/reference/guide.md` — Guia de DDD
+
+## Skills Complementares
+
+- `@architecture` — Padrões arquiteturais e C4
+
+## Próximo Especialista
+
+Após aprovação → **Especialista de Design Técnico** (`specialist-technical-design`)

package/dist/content/skills/specialist-domain/resources/checklists/gate-checklist.md

@@ -0,0 +1,37 @@
+# Gate Checklist — Modelo de Domínio
+
+> **Score mínimo para aprovação:** 70/100
+
+## Itens Críticos
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 1 | **Bounded contexts identificados** | 15 | Cada context com responsabilidade clara e fronteira definida |
+| 2 | **Aggregates com aggregate roots** | 15 | Cada aggregate com root identificado, entidades e value objects |
+| 3 | **Linguagem ubíqua documentada** | 15 | Glossário com 10+ termos (termo → definição → contexto) |
+
+## Itens Importantes
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 4 | **Entidades com atributos e identidade** | 10 | Cada entidade com ID, atributos tipados, papel no aggregate |
+| 5 | **Value Objects identificados** | 10 | Objetos imutáveis sem identidade separados das entidades |
+| 6 | **Invariantes/regras de negócio** | 10 | Regras por aggregate — o que NUNCA pode acontecer |
+| 7 | **Domain events mapeados** | 10 | Mínimo 5 eventos com nome, trigger e payload |
+
+## Itens Desejáveis
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 8 | **Context map com relações** | 5 | Partnership, Customer-Supplier, ACL entre contexts |
+| 9 | **Domain services identificados** | 5 | Operações que não pertencem a uma entidade |
+| 10 | **Diagramas de aggregate** | 5 | Visualização das fronteiras de cada aggregate |
+
+## Instruções de Correção
+
+| Item Faltando | Como Corrigir |
+|---------------|---------------|
+| Sem bounded contexts | Perguntar: "Quais áreas do negócio podem evoluir independentemente?" |
+| Aggregates vagos | Perguntar: "Quais entidades DEVEM mudar juntas numa transação?" |
+| Linguagem inconsistente | Criar glossário: "Como o NEGÓCIO chama isso? O código usa o MESMO nome?" |
+| Sem domain events | Perguntar: "O que acontece DEPOIS de [ação]? Quem precisa saber?" |

package/dist/content/skills/specialist-domain/resources/reference/guide.md

@@ -0,0 +1,80 @@
+# Guia de Referência — Modelo de Domínio (DDD)
+
+## Conceitos Fundamentais
+
+### Entity vs Value Object vs Aggregate
+
+| Conceito | Identidade | Mutável | Exemplo |
+|----------|:----------:|:-------:|---------|
+| **Entity** | ✅ Tem ID único | ✅ Sim | User, Order, Product |
+| **Value Object** | ❌ Sem ID | ❌ Imutável | Money(amount, currency), Address(street, city) |
+| **Aggregate** | ✅ Via Root | ✅ Sim | Order (root) + OrderItem + ShippingAddress |
+| **Aggregate Root** | ✅ Entry point | ✅ Controla acesso | Order controla seus OrderItems |
+
+### Regra do Aggregate
+- Acesso externo SEMPRE via Aggregate Root (nunca via entity interna)
+- Transação = 1 Aggregate (nunca modificar 2 aggregates na mesma transação)
+- Se precisa modificar 2 aggregates → Domain Event
+
+### Bounded Context
+- Fronteira onde um modelo é CONSISTENTE
+- Mesma palavra pode ter significado diferente em contexts diferentes
+- Ex: "Cliente" em Vendas (comprador) vs "Cliente" em Suporte (ticket owner)
+
+## Context Mapping — Relações
+
+| Relação | Quando usar |
+|---------|------------|
+| **Partnership** | 2 contexts evoluem juntos, time único |
+| **Customer-Supplier** | Consumer depende do Provider, negocia contrato |
+| **Conformist** | Consumer aceita o modelo do Provider sem negociar |
+| **Anti-Corruption Layer (ACL)** | Consumer traduz modelo externo para o interno |
+| **Shared Kernel** | Código compartilhado entre contexts (usar com parcimônia) |
+| **Published Language** | Contrato público (OpenAPI, eventos) |
+
+## Domain Events
+
+### Formato
+```
+Nome: [Substantivo][Verbo no passado]
+  Ex: OrderCreated, PaymentApproved, UserRegistered
+
+Payload: {
+  eventId: UUID
+  occurredAt: DateTime
+  aggregateId: UUID
+  data: { ... campos relevantes }
+}
+```
+
+### Quando usar
+- Quando algo acontece que OUTROS contexts precisam saber
+- Quando precisa de consistência eventual (não transacional)
+- Para desacoplar bounded contexts
+
+## Event Storming (simplificado)
+
+```
+1. Listar EVENTOS (laranja): "O que acontece no sistema?"
+   → OrderPlaced, PaymentReceived, ItemShipped
+
+2. Listar COMANDOS (azul): "O que causa cada evento?"
+   → PlaceOrder, ProcessPayment, ShipItem
+
+3. Listar AGGREGATES (amarelo): "Quem processa cada comando?"
+   → Order, Payment, Shipment
+
+4. Agrupar em BOUNDED CONTEXTS
+   → Sales (Order), Billing (Payment), Logistics (Shipment)
+```
+
+## Anti-patterns de DDD
+
+| Anti-pattern | Por que é ruim | Correção |
+|-------------|----------------|----------|
+| Anemic Domain Model | Entidades sem lógica = procedural | Mover regras para dentro das entidades |
+| God Aggregate | Aggregate com 10+ entidades | Dividir em aggregates menores |
+| Shared DB entre contexts | Acoplamento forte | Cada context tem seu schema/DB |
+| CRUD everywhere | Ignora regras de negócio | Modelar comportamentos, não dados |
+| Linguagem técnica no domínio | Desconexão negócio-código | Glossário ubíquo: negócio = código |
+| Event sourcing sem necessidade | Complexidade desnecessária | Usar apenas quando audit trail é requisito |

package/dist/content/skills/specialist-frontend/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: specialist-frontend
+description: Desenvolvimento frontend com foco operacional — componentes, hooks, pages, testes e integração com mocks. Use quando entrar em fase de código frontend após arquitetura e planejamento definidos.
+---
+
+# 🎨 Especialista Frontend
+
+## Persona
+
+**Nome:** Frontend Developer Lead
+**Tom:** Prático, component-driven, performance-aware — implementa task por task com qualidade
+**Expertise:**
+- Desenvolvimento de componentes reutilizáveis (React, Vue, Angular)
+- State management (Zustand, Redux, Pinia, signals)
+- Hooks e composables patterns
+- Integração com APIs (REST, GraphQL, tRPC) e mock servers (MSW)
+- Testes unitários e de componentes (Vitest, Testing Library)
+- Performance (lazy loading, code splitting, memoization)
+- Responsividade mobile-first e acessibilidade
+
+**Comportamento:**
+- NÃO pergunta sobre stack — ela já está definida na Arquitetura
+- Lê o Design Doc para entender wireframes e fluxos ANTES de codar
+- Lê o Backlog/Discovery para saber quais User Stories implementar
+- Implementa UMA User Story por vez, na ordem do Backlog
+- Para cada US segue: Component → Hook/State → Page → Test
+- Usa mocks (MSW) quando backend ainda não existe
+- Verifica acessibilidade e responsividade em cada componente
+
+**Frases características:**
+- "Vou implementar a US-001 primeiro — é o fluxo principal."
+- "Componente criado. Adicionando testes e verificando responsividade."
+- "Usando MSW para mockar o endpoint até o backend estar pronto."
+- "Essa page precisa de loading, empty e error states — vou implementar os três."
+
+**O que NÃO fazer:**
+- ❌ Redefinir stack ou arquitetura (já decidida)
+- ❌ Pular testes — cada componente crítico precisa de teste
+- ❌ Implementar tudo de uma vez — task por task
+- ❌ Ignorar estados de UI (loading, empty, error)
+- ❌ Criar endpoints backend (isso é Backend)
+
+## Missão
+
+Implementar o frontend task por task seguindo as User Stories do Discovery/Backlog e a stack definida na Arquitetura. Cada task gera componentes, hooks, pages e testes.
+
+## Entregável
+
+Código frontend funcional — componentes, pages, rotas, state management, testes.
+
+## Coleta Conversacional
+
+Pergunte APENAS questões operacionais (a stack já está definida):
+
+### Setup Operacional
+1. **Projeto inicializado?** A pasta frontend já existe ou devo criar?
+2. **Prioridade:** Qual User Story quer começar? (Recomendo o fluxo principal)
+3. **Mocks:** Backend já existe ou devo configurar MSW?
+4. **Estrutura:** Monorepo ou repo separado? Tem design system/component lib?
+
+## Processo de Implementação
+
+Para cada User Story:
+1. **Ler** o Design Doc para wireframe da tela
+2. **Criar** componentes necessários (Atomic Design quando aplicável)
+3. **Implementar** hooks/state management
+4. **Montar** page com rota configurada
+5. **Integrar** com API real ou mock (MSW)
+6. **Testar** componentes críticos (Testing Library)
+7. **Verificar** responsividade e acessibilidade
+8. **Marcar** task como done
+
+## Gate Checklist
+
+- [ ] Componentes implementados conforme design doc e user stories
+- [ ] Pages com rotas configuradas para cada fluxo
+- [ ] State management conectado (hooks/stores)
+- [ ] Integração com mocks ou API real
+- [ ] Testes unitários para componentes críticos
+- [ ] Responsivo mobile-first e acessível
+- [ ] Loading, empty e error states em todas as telas
+
+## Recursos
+
+- `resources/reference/guide.md` — Guia operacional de frontend
+
+## Skills Complementares
+
+Invoque quando necessário:
+- `@react-patterns` — Padrões React modernos (hooks, composition, performance)
+- `@nextjs-best-practices` — SSR/SSG, routing, data fetching Next.js
+- `@tailwind-patterns` — Estilização com Tailwind CSS
+- `@clean-code` — Princípios de código limpo
+- `@tdd-workflow` — Ciclo RED-GREEN-REFACTOR para testes
+- `@testing-patterns` — Padrões de teste (AAA, mocking, fixtures)
+
+## Próximo Especialista
+
+Após aprovação → **Especialista Backend** (`specialist-backend`)

package/dist/content/skills/specialist-frontend/resources/checklists/gate-checklist.md

@@ -0,0 +1,38 @@
+# Gate Checklist — Frontend
+
+> **Score mínimo para aprovação:** 70/100  
+> **Validação:** Por existência de artefatos no disco (code-validator)
+
+## Itens Críticos
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 1 | **Componentes implementados conforme design e user stories** | 20 | Componentes existem no disco, cobrem telas do MVP |
+| 2 | **Pages com rotas configuradas** | 15 | Cada fluxo do MVP tem rota e page correspondente |
+| 3 | **State management conectado** | 15 | Hooks/stores implementados para dados principais |
+
+## Itens Importantes
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 4 | **Integração com mocks ou API real** | 10 | MSW configurado ou chamadas à API funcionando |
+| 5 | **Testes unitários para componentes críticos** | 10 | Pelo menos 1 teste por componente de fluxo principal |
+| 6 | **Responsivo mobile-first** | 10 | Layout funciona em mobile (< 640px) |
+| 7 | **Loading, empty e error states** | 10 | 3 estados implementados para fluxos com dados assíncronos |
+
+## Itens Desejáveis
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 8 | **Acessibilidade básica** | 5 | Labels em inputs, alt em imagens, focus visible |
+| 9 | **Code splitting/lazy loading** | 3 | Pages carregam sob demanda |
+| 10 | **TypeScript sem erros** | 2 | `tsc --noEmit` passa sem erros |
+
+## Instruções de Correção
+
+| Item Faltando | Como Corrigir |
+|---------------|---------------|
+| Componentes faltando | Revisar Design Doc → identificar telas não implementadas → criar componentes |
+| Sem rotas | Configurar router com todas as URLs do mapa de navegação |
+| Sem testes | Criar teste com Testing Library para cada componente de fluxo principal |
+| Sem estados de UI | Adicionar loading (skeleton), empty (mensagem + CTA), error (retry) |

package/dist/content/skills/specialist-frontend/resources/reference/guide.md

@@ -0,0 +1,90 @@
+# Guia de Referência — Frontend
+
+## Processo por User Story
+
+Para cada User Story do Backlog/Discovery:
+
+```
+1. Ler Design Doc → wireframe da tela
+2. Criar componentes → Atomic Design (atoms → molecules → organisms)
+3. Implementar state → hooks/stores para dados
+4. Montar page → rota + layout + componentes
+5. Integrar API → React Query + MSW (mock) ou real
+6. Testar → Testing Library para componentes críticos
+7. Verificar → responsividade + acessibilidade + estados UI
+```
+
+## Padrões de Componentes React
+
+### Estrutura de arquivo
+```typescript
+// 1. Imports
+// 2. Types/Interfaces
+// 3. Component (named export)
+// 4. Sub-components (se pequenos)
+// 5. Styles (se CSS Modules) ou nada (se Tailwind)
+```
+
+### Convenções de naming
+| Tipo | Formato | Exemplo |
+|------|---------|---------|
+| Componente | PascalCase | `TaskCard.tsx` |
+| Hook | camelCase com `use` | `useTaskList.ts` |
+| Utilitário | camelCase | `formatDate.ts` |
+| Constante | SCREAMING_SNAKE | `MAX_TASKS_PER_PAGE` |
+| Tipo/Interface | PascalCase com sufixo | `TaskCardProps`, `TaskDTO` |
+
+## State Management
+
+### Quando usar o quê
+| Cenário | Solução |
+|---------|---------|
+| Dados do servidor (CRUD, listas) | React Query / SWR |
+| Estado global do client (UI, theme, auth) | Zustand / Context |
+| Estado local do componente (forms, toggles) | useState / useReducer |
+| Formulários complexos | React Hook Form + Zod |
+
+## Integração com API
+
+### MSW (Mock Service Worker) — para desenvolvimento sem backend
+```typescript
+// handlers.ts — definir mocks para cada endpoint
+rest.get('/api/tasks', (req, res, ctx) => {
+  return res(ctx.json(mockTasks))
+})
+```
+
+### React Query — para dados do servidor
+```typescript
+// Padrão: 1 hook por recurso
+const useTasks = (projectId: string) =>
+  useQuery({
+    queryKey: ['tasks', projectId],
+    queryFn: () => api.getTasks(projectId),
+  })
+```
+
+## Testes — Mínimo por componente
+
+| Tipo | Ferramenta | O que testar |
+|------|-----------|-------------|
+| Unitário | Vitest + Testing Library | Render, interações, estados |
+| Snapshot | Vitest | Regressão visual (opcional) |
+| E2E | Playwright (na Integração) | Fluxos completos |
+
+### Padrão AAA
+```typescript
+// Arrange — montar componente com props/mocks
+// Act — simular interação (click, type, etc)
+// Assert — verificar resultado (texto, estado, chamada)
+```
+
+## Checklist por Componente
+
+- [ ] Props tipadas com interface
+- [ ] Loading state (skeleton ou spinner)
+- [ ] Error state (mensagem + retry)
+- [ ] Empty state (mensagem + CTA)
+- [ ] Responsivo (mobile + desktop)
+- [ ] Acessível (label, aria, keyboard)
+- [ ] Teste para caminho feliz