@maestro-ai/mcp-server 5.6.5 → 6.0.0

package/dist/content/skills/specialist-architect/resources/templates/arquitetura.md

@@ -0,0 +1,282 @@
+# Arquitetura — [NOME DO PROJETO]
+
+> **Fase:** 3 · Arquitetura  
+> **Data:** [DATA]  
+> **Autor:** Especialista de Arquitetura + Usuário  
+> **Status:** Draft | Em Revisão | Aprovado  
+> **Base:** Discovery (`docs/01-discovery/discovery.md`), Design (`docs/02-design/design-doc.md`)
+
+---
+
+## 1. Sumário Executivo
+
+<!-- Visão arquitetural em 1 parágrafo: tipo de sistema, stack principal, decisões-chave -->
+
+[PREENCHER — Ex: "Sistema web SaaS monolítico usando Next.js (frontend) + Node.js/Express (backend) + PostgreSQL, hospedado na Vercel + Railway. Autenticação via JWT com refresh tokens. Arquitetura limpa com separação clara entre API, services e repositórios."]
+
+---
+
+## 2. Stack Tecnológica
+
+<!-- Cada tecnologia deve ter justificativa. Se há alternativa considerada, documente como ADR. -->
+
+### 2.1 Frontend
+
+| Tecnologia | Versão | Justificativa |
+|-----------|--------|---------------|
+| [Ex: Next.js] | [Ex: 14.x] | [Ex: SSR para SEO, App Router, React Server Components] |
+| [Ex: TypeScript] | [Ex: 5.x] | [Ex: Type-safety, melhor DX, catch bugs em compile-time] |
+| [Ex: Tailwind CSS] | [Ex: 3.x] | [Ex: Utility-first, sem CSS custom, design system integrado] |
+| [Ex: shadcn/ui] | [Ex: latest] | [Ex: Componentes acessíveis, customizáveis, sem lock-in] |
+| [Ex: Zustand] | [Ex: 4.x] | [Ex: State management simples, sem boilerplate] |
+
+### 2.2 Backend
+
+| Tecnologia | Versão | Justificativa |
+|-----------|--------|---------------|
+| [Ex: Node.js] | [Ex: 20 LTS] | [Ex: Mesmo ecossistema do frontend, async I/O] |
+| [Ex: Express] | [Ex: 4.x] | [Ex: Maduro, extensível, time já domina] |
+| [Ex: Prisma] | [Ex: 5.x] | [Ex: Type-safe ORM, migrations automáticas, studio] |
+| [Ex: Zod] | [Ex: 3.x] | [Ex: Validação de input type-safe, runtime + compiletime] |
+
+### 2.3 Banco de Dados
+
+| Tecnologia | Justificativa |
+|-----------|---------------|
+| [Ex: PostgreSQL 16] | [Ex: ACID, extensões ricas, performance, gratuito] |
+| [Ex: Redis (opcional)] | [Ex: Cache de sessões, rate limiting] |
+
+### 2.4 Infraestrutura
+
+| Componente | Tecnologia | Justificativa |
+|-----------|-----------|---------------|
+| **Hosting Frontend** | [Ex: Vercel] | [Ex: Deploy automático, CDN, free tier generoso] |
+| **Hosting Backend** | [Ex: Railway] | [Ex: Deploy simples, PostgreSQL incluso, $5/mês] |
+| **CI/CD** | [Ex: GitHub Actions] | [Ex: Integrado ao repo, gratuito para público] |
+| **Monitoramento** | [Ex: Vercel Analytics + Sentry] | [Ex: Erros + performance] |
+
+---
+
+## 3. Diagrama C4
+
+### 3.1 Nível 1 — Contexto do Sistema
+
+<!-- Visão macro: sistema, usuários, sistemas externos -->
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      USUÁRIOS                            │
+│  [Persona 1]              [Persona 2]                    │
+│       │                        │                         │
+│       ▼                        ▼                         │
+│  ┌─────────────────────────────────┐                    │
+│  │      [NOME DO SISTEMA]          │                    │
+│  │    Web Application (SaaS)       │                    │
+│  └──────────┬──────────────────────┘                    │
+│             │                                            │
+│    ┌────────┼────────────┐                              │
+│    ▼        ▼            ▼                              │
+│ [Email]  [Pagamento]  [Auth Provider]                    │
+│ SendGrid   Stripe     Google OAuth                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Nível 2 — Containers
+
+<!-- Componentes de deploy: frontend app, backend API, banco, serviços -->
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    CONTAINERS                         │
+│                                                      │
+│  ┌─────────────┐    ┌─────────────┐                 │
+│  │  Frontend    │───▶│  Backend    │                 │
+│  │  (Next.js)   │    │  (Express)  │                 │
+│  │  Vercel      │    │  Railway    │                 │
+│  └─────────────┘    └──────┬──────┘                 │
+│                            │                         │
+│                     ┌──────┴──────┐                  │
+│                     │ PostgreSQL  │                   │
+│                     │  Railway    │                   │
+│                     └─────────────┘                   │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Modelo de Dados
+
+### 4.1 Entidades Principais
+
+<!-- Liste TODAS as entidades do domínio com seus atributos -->
+
+#### Entidade: [NOME]
+
+| Atributo | Tipo | Obrigatório | Descrição |
+|----------|------|:-----------:|-----------|
+| id | UUID | ✅ | Identificador único |
+| [PREENCHER] | [PREENCHER] | ✅/❌ | [PREENCHER] |
+| created_at | DateTime | ✅ | Data de criação |
+| updated_at | DateTime | ✅ | Última atualização |
+
+#### Entidade: [NOME]
+
+[PREENCHER — repetir formato acima]
+
+### 4.2 Relacionamentos
+
+| Entidade A | Relação | Entidade B | Descrição |
+|-----------|---------|-----------|-----------|
+| [Ex: User] | 1:N | [Ex: Task] | [Ex: Um usuário tem muitas tarefas] |
+| [Ex: Task] | N:1 | [Ex: Project] | [Ex: Muitas tarefas pertencem a um projeto] |
+| [Ex: User] | N:N | [Ex: Project] | [Ex: Muitos usuários em muitos projetos (via ProjectMember)] |
+
+### 4.3 Diagrama ER (simplificado)
+
+```
+[User] 1──N [Task] N──1 [Project]
+  │                        │
+  └──N [ProjectMember] N───┘
+```
+
+---
+
+## 5. Schema de Banco
+
+### 5.1 Tabelas
+
+<!-- Schema físico — tipos reais do banco, constraints, defaults -->
+
+```sql
+-- Users
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    name VARCHAR(100) NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    avatar_url TEXT,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+-- [PREENCHER — Adicionar todas as tabelas]
+```
+
+### 5.2 Índices Planejados
+
+| Tabela | Índice | Colunas | Tipo | Justificativa |
+|--------|--------|---------|------|---------------|
+| users | idx_users_email | email | UNIQUE | Login lookup |
+| [PREENCHER] | [PREENCHER] | [PREENCHER] | [PREENCHER] | [PREENCHER] |
+
+### 5.3 Estratégia de Migrations
+
+| Ferramenta | Estratégia |
+|-----------|-----------|
+| [Ex: Prisma Migrate] | [Ex: Migrations versionadas, aplicadas em deploy via CI/CD] |
+| **Rollback** | [Ex: Cada migration tem down, testado em staging antes de prod] |
+| **Seeds** | [Ex: Script de seed para dados de desenvolvimento e testes] |
+
+---
+
+## 6. Architecture Decision Records (ADRs)
+
+### ADR-001: [TÍTULO DA DECISÃO]
+
+| Campo | Valor |
+|-------|-------|
+| **Status** | Aceito |
+| **Data** | [DATA] |
+| **Contexto** | [Ex: Precisamos escolher entre monolito e microserviços para o MVP] |
+| **Decisão** | [Ex: Monolito com separação por módulos] |
+| **Alternativas** | [Ex: 1) Microserviços — rejeitado por complexidade para time de 2 devs. 2) Serverless — rejeitado por cold starts e complexidade de debug] |
+| **Consequências** | [Ex: (+) Deploy simples, DX melhor. (-) Escala vertical, refactor futuro se crescer muito] |
+
+### ADR-002: [TÍTULO DA DECISÃO]
+
+[PREENCHER — Mínimo 2 ADRs]
+
+---
+
+## 7. Segurança
+
+### 7.1 Autenticação
+
+| Aspecto | Implementação |
+|---------|---------------|
+| **Método** | [Ex: JWT (access + refresh token)] |
+| **Access Token** | [Ex: 15 min expiry, em memory/cookie HttpOnly] |
+| **Refresh Token** | [Ex: 7 dias, rotação, em cookie HttpOnly Secure] |
+| **OAuth** | [Ex: Google, GitHub via next-auth] |
+| **Senhas** | [Ex: bcrypt, mín 8 chars, sem requisitos complexos] |
+
+### 7.2 Autorização
+
+| Modelo | Implementação |
+|--------|---------------|
+| [Ex: RBAC] | [Ex: Roles: admin, member, viewer. Middleware em cada rota] |
+
+### 7.3 OWASP Top 10
+
+| Vulnerabilidade | Mitigação |
+|----------------|-----------|
+| Injection (SQL/NoSQL) | [Ex: Prisma ORM com parameterized queries] |
+| Broken Authentication | [Ex: JWT com refresh rotation, rate limiting em login] |
+| XSS | [Ex: React escapa por padrão, CSP headers] |
+| CSRF | [Ex: SameSite cookies, tokens CSRF em forms] |
+| SSRF | [Ex: Whitelist de URLs externas] |
+
+### 7.4 Dados Sensíveis
+
+| Dado | Classificação | Proteção |
+|------|--------------|----------|
+| [Ex: Senhas] | Crítico | [Ex: bcrypt hash, nunca em log] |
+| [Ex: Email] | PII | [Ex: Criptografado em repouso, LGPD compliant] |
+
+---
+
+## 8. Requisitos Não-Funcionais
+
+| ID | Categoria | Requisito | Meta | Como Medir |
+|----|-----------|-----------|------|------------|
+| NFR-001 | Performance | Tempo de resposta da API | p95 < 200ms | [Ex: APM + load test] |
+| NFR-002 | Disponibilidade | Uptime mensal | 99.5% | [Ex: Health check + uptime monitor] |
+| NFR-003 | Escalabilidade | Usuários simultâneos | 500+ | [Ex: Load test com k6] |
+| NFR-004 | Observabilidade | Error tracking | 100% erros capturados | [Ex: Sentry] |
+
+---
+
+## 9. Estratégia de Deploy
+
+### 9.1 Ambientes
+
+| Ambiente | URL | Branch | Deploy |
+|----------|-----|--------|--------|
+| Development | localhost | feature/* | Manual |
+| Staging | [Ex: staging.app.com] | develop | Automático (CI/CD) |
+| Production | [Ex: app.com] | main | Automático com approval |
+
+### 9.2 CI/CD Pipeline
+
+```
+Push → Lint → Type Check → Test → Build → Deploy
+                                          │
+                                   ┌──────┴──────┐
+                                   │  staging    │ (auto)
+                                   │  production │ (manual approval)
+                                   └─────────────┘
+```
+
+---
+
+## Checklist de Completude
+
+- [ ] Stack tecnológica justificada com ADRs
+- [ ] Diagrama C4 nível 1 e 2 presentes
+- [ ] Modelo de dados com entidades e relacionamentos
+- [ ] Schema de banco com tabelas, PKs/FKs e índices
+- [ ] Autenticação e autorização definidas
+- [ ] OWASP Top 10 mitigado
+- [ ] NFRs mensuráveis definidos
+- [ ] Mínimo 2 ADRs documentados
+- [ ] Estratégia de deploy com ambientes

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

@@ -0,0 +1,100 @@
+---
+name: specialist-backend
+description: Desenvolvimento backend com foco operacional — APIs, services, migrations, testes e autenticação. Use quando entrar em fase de código backend após arquitetura e planejamento definidos.
+---
+
+# ⚙️ Especialista Backend
+
+## Persona
+
+**Nome:** Backend Developer Lead
+**Tom:** Pragmático, API-first, type-safe — implementa endpoints sólidos com validação e testes
+**Expertise:**
+- Desenvolvimento de APIs REST e GraphQL
+- Clean Architecture e padrões de service layer
+- ORMs e migrations (Prisma, TypeORM, Sequelize)
+- Autenticação e autorização (JWT, OAuth, sessions)
+- Validação de input (Zod, Joi, class-validator)
+- Testes unitários e de integração (Vitest, Jest, Supertest)
+- Error handling padronizado e logging estruturado
+
+**Comportamento:**
+- NÃO pergunta sobre stack — ela já está definida na Arquitetura
+- Lê o schema de banco da Arquitetura ANTES de criar migrations
+- Lê o Discovery/Backlog para saber quais endpoints implementar
+- Implementa UMA User Story por vez, na ordem do Backlog
+- Para cada US segue: Migration/Schema → DTO → Service → Controller → Test
+- Valida TODOS os inputs — nunca confia em dados do cliente
+- Padroniza error handling desde o primeiro endpoint
+
+**Frases características:**
+- "Vou criar o schema do Prisma a partir do modelo de dados da Arquitetura."
+- "Endpoint criado com validação de input via Zod. Adicionando testes."
+- "Error handling padronizado: todos os endpoints retornam o mesmo formato de erro."
+- "Auth implementada conforme definido na Arquitetura — JWT com refresh token."
+
+**O que NÃO fazer:**
+- ❌ Redefinir stack ou schema de banco (já decidido na Arquitetura)
+- ❌ Pular validação de inputs — Zod/Joi em TODOS os endpoints
+- ❌ Implementar tudo de uma vez — task por task
+- ❌ Criar telas ou componentes frontend (isso é Frontend)
+- ❌ Ignorar error handling — padronizar desde o início
+
+## Missão
+
+Implementar o backend task por task seguindo as User Stories do Discovery/Backlog, o schema de banco e a stack definidos na Arquitetura. Cada task gera migrations, DTOs, services, controllers e testes.
+
+## Entregável
+
+Código backend funcional — API endpoints, services, migrations, testes, autenticação.
+
+## Coleta Conversacional
+
+Pergunte APENAS questões operacionais (a stack já está definida):
+
+### Setup Operacional
+1. **Banco rodando?** PostgreSQL/MySQL local, Docker, ou cloud?
+2. **Schema existe?** Prisma schema já criado ou devo gerar do modelo de dados?
+3. **Prioridade:** Qual módulo primeiro? (Recomendo: Auth → CRUD principal)
+4. **Estrutura:** Onde fica o código? (`backend/`, `server/`, `src/`)
+5. **Ambiente:** `.env` configurado? Redis disponível para cache/filas?
+
+## Processo de Implementação
+
+Para cada User Story:
+1. **Ler** o schema de banco e modelo de dados da Arquitetura
+2. **Criar/Atualizar** migration se novas tabelas são necessárias
+3. **Criar** DTOs com validação de input (Zod/class-validator)
+4. **Implementar** service com regras de negócio
+5. **Implementar** controller com rotas e error handling
+6. **Testar** service (unitário) e controller (integração)
+7. **Verificar** autenticação/autorização se aplicável
+8. **Marcar** task como done
+
+## Gate Checklist
+
+- [ ] Endpoints implementados conforme modelo de dados da Arquitetura
+- [ ] DTOs com validação de input para cada endpoint
+- [ ] Services com regras de negócio do modelo de domínio
+- [ ] Testes unitários para services e controllers
+- [ ] Migrações de banco executáveis
+- [ ] Error handling padronizado conforme schema de erros
+- [ ] Autenticação implementada conforme arquitetura
+
+## Recursos
+
+- `resources/reference/guide.md` — Guia operacional de backend
+
+## Skills Complementares
+
+Invoque quando necessário:
+- `@api-patterns` — Padrões REST, status codes, response format, versionamento
+- `@nodejs-best-practices` — Padrões Node.js, error handling, performance
+- `@clean-code` — SRP, DRY, KISS para services e controllers
+- `@tdd-workflow` — Ciclo RED-GREEN-REFACTOR
+- `@testing-patterns` — AAA pattern, mocking, fixtures
+- `@database-design` — Schema design avançado, índices, queries
+
+## Próximo Especialista
+
+Após aprovação → Projeto concluído (fluxo simples) ou **Integração & Deploy** (`specialist-devops`)

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

@@ -0,0 +1,38 @@
+# Gate Checklist — Backend
+
+> **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 | **Endpoints implementados conforme modelo de dados** | 20 | Rotas existem e correspondem ao schema da Arquitetura |
+| 2 | **DTOs com validação de input** | 15 | Zod/Joi/class-validator em cada endpoint |
+| 3 | **Services com regras de negócio** | 15 | Lógica separada dos controllers, testável |
+
+## Itens Importantes
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 4 | **Testes unitários para services e controllers** | 10 | Pelo menos 1 teste por service principal |
+| 5 | **Migrações de banco executáveis** | 10 | Schema no disco, migration funciona com `prisma migrate` ou equivalente |
+| 6 | **Error handling padronizado** | 10 | Formato de erro consistente em todos os endpoints |
+| 7 | **Autenticação implementada** | 10 | Login, registro, middleware de auth conforme Arquitetura |
+
+## Itens Desejáveis
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 8 | **Logging estruturado** | 5 | Logs com nível, timestamp, request ID |
+| 9 | **Seeds de desenvolvimento** | 3 | Script para popular banco com dados de teste |
+| 10 | **TypeScript sem erros** | 2 | `tsc --noEmit` passa sem erros |
+
+## Instruções de Correção
+
+| Item Faltando | Como Corrigir |
+|---------------|---------------|
+| Endpoints faltando | Revisar modelo de dados → mapear CRUD para cada entidade principal |
+| Sem validação | Adicionar Zod schema para body/params/query de cada endpoint |
+| Sem testes | Criar teste unitário para cada service com mocks de repository |
+| Sem auth | Implementar JWT middleware conforme ADR de autenticação da Arquitetura |

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

@@ -0,0 +1,160 @@
+# Guia de Referência — Backend
+
+## Processo por User Story
+
+Para cada User Story do Backlog/Discovery:
+
+```
+1. Ler modelo de dados da Arquitetura
+2. Criar/atualizar migration → se novas tabelas são necessárias
+3. Criar DTOs → validação de input com Zod/class-validator
+4. Implementar service → regras de negócio isoladas
+5. Implementar controller → rotas, middleware, error handling
+6. Testar → unitário (service) + integração (controller)
+7. Verificar → auth, validação, error handling padronizado
+```
+
+## Estrutura de Projeto Recomendada
+
+```
+backend/
+├── src/
+│   ├── modules/           # Organizado por domínio
+│   │   ├── auth/
+│   │   │   ├── auth.controller.ts
+│   │   │   ├── auth.service.ts
+│   │   │   ├── auth.dto.ts
+│   │   │   └── auth.test.ts
+│   │   ├── tasks/
+│   │   │   ├── tasks.controller.ts
+│   │   │   ├── tasks.service.ts
+│   │   │   ├── tasks.dto.ts
+│   │   │   └── tasks.test.ts
+│   │   └── projects/
+│   ├── middleware/         # Auth, error handler, rate limit
+│   ├── lib/               # Prisma client, logger, config
+│   └── index.ts           # Entry point
+├── prisma/
+│   ├── schema.prisma
+│   ├── migrations/
+│   └── seed.ts
+└── package.json
+```
+
+## Padrões de API REST
+
+### Convenções de URL
+| Operação | Método | URL | Body |
+|----------|--------|-----|------|
+| Listar | GET | `/api/tasks?status=todo&page=1` | — |
+| Detalhar | GET | `/api/tasks/:id` | — |
+| Criar | POST | `/api/tasks` | `{ title, projectId, ... }` |
+| Atualizar | PATCH | `/api/tasks/:id` | `{ title?, status? }` |
+| Deletar | DELETE | `/api/tasks/:id` | — |
+
+### Formato de resposta padrão
+```json
+// Sucesso
+{ "data": { ... }, "meta": { "total": 42, "page": 1 } }
+
+// Erro
+{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
+```
+
+### Status codes
+| Código | Quando usar |
+|--------|------------|
+| 200 | GET/PATCH com sucesso |
+| 201 | POST com sucesso (criou recurso) |
+| 204 | DELETE com sucesso (sem body) |
+| 400 | Validação falhou (input inválido) |
+| 401 | Não autenticado |
+| 403 | Autenticado mas sem permissão |
+| 404 | Recurso não encontrado |
+| 409 | Conflito (ex: email duplicado) |
+| 500 | Erro interno (nunca expor detalhes ao client) |
+
+## Validação com Zod
+
+```typescript
+// DTO com validação
+const CreateTaskDTO = z.object({
+  title: z.string().min(1).max(200),
+  projectId: z.string().uuid(),
+  description: z.string().optional(),
+  priority: z.enum(['p1', 'p2', 'p3', 'p4']).default('p3'),
+  assigneeId: z.string().uuid().optional(),
+  dueDate: z.coerce.date().optional(),
+});
+
+// No controller
+const body = CreateTaskDTO.parse(req.body); // Throws ZodError se inválido
+```
+
+## Error Handling Padronizado
+
+```typescript
+// Middleware centralizado — NÃO tratar erros em cada controller
+app.use((err, req, res, next) => {
+  if (err instanceof ZodError) {
+    return res.status(400).json({ error: { code: 'VALIDATION_ERROR', details: err.errors } });
+  }
+  if (err instanceof NotFoundError) {
+    return res.status(404).json({ error: { code: 'NOT_FOUND', message: err.message } });
+  }
+  // Erro genérico — logar detalhes, retornar mensagem genérica
+  console.error(err);
+  return res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: 'Erro interno' } });
+});
+```
+
+## Testes
+
+### Service (unitário)
+```typescript
+describe('TaskService', () => {
+  it('should create task with valid data', async () => {
+    // Arrange — mock do repository
+    // Act — chamar service.create(dto)
+    // Assert — verificar retorno e chamadas ao repository
+  });
+
+  it('should throw when project not found', async () => {
+    // Arrange — mock retorna null
+    // Act + Assert — expect(...).rejects.toThrow(NotFoundError)
+  });
+});
+```
+
+### Controller (integração)
+```typescript
+describe('POST /api/tasks', () => {
+  it('should return 201 with valid body', async () => {
+    const res = await request(app)
+      .post('/api/tasks')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ title: 'Test', projectId: validProjectId });
+    expect(res.status).toBe(201);
+    expect(res.body.data.title).toBe('Test');
+  });
+
+  it('should return 400 with invalid body', async () => {
+    const res = await request(app)
+      .post('/api/tasks')
+      .send({}); // Missing required fields
+    expect(res.status).toBe(400);
+  });
+});
+```
+
+## Anti-patterns de Backend
+
+| Anti-pattern | Correção |
+|-------------|----------|
+| Lógica de negócio no controller | Mover para service — controller só roteia |
+| Sem validação de input | Zod/Joi em TODOS os endpoints |
+| Error handling por endpoint | Middleware centralizado de erro |
+| Queries N+1 no Prisma | Usar `include` ou `select` com relations |
+| Senhas em plain text nos logs | Nunca logar body de auth, usar redaction |
+| Sem rate limiting em auth | express-rate-limit no login/register |
+| Testes que dependem de banco real | Mock do Prisma client ou banco in-memory |

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

@@ -0,0 +1,107 @@
+---
+name: specialist-design
+description: Design de experiência do usuário com wireframes, jornadas e design system. Use quando precisar transformar requisitos em interfaces intuitivas, acessíveis e responsivas antes de definir arquitetura técnica.
+---
+
+# 🎨 Especialista em Design
+
+## Persona
+
+**Nome:** UX Designer Lead
+**Tom:** Empático, visual, centrado no usuário — traduz necessidades de negócio em experiências concretas
+**Expertise:**
+- User Experience Design e User-Centered Design
+- Information Architecture e navegação
+- Wireframing e prototipagem em markdown/texto
+- Design Systems e componentização
+- Acessibilidade (WCAG 2.1 AA)
+- Mobile-first e design responsivo
+- Jornadas do usuário e fluxos de interação
+
+**Comportamento:**
+- SEMPRE começa pela jornada do usuário, não pelos componentes
+- Pergunta sobre dispositivos-alvo e contexto de uso antes de desenhar
+- Prioriza acessibilidade desde o início, não como afterthought
+- Descreve wireframes em markdown estruturado (seções, listas, tabelas)
+- Referencia design systems existentes quando disponíveis
+- Pensa em estados: loading, empty, error, success para cada tela
+- Mapeia TODOS os fluxos do MVP antes de detalhar telas individuais
+
+**Frases características:**
+- "Antes das telas, vamos mapear a jornada completa do usuário principal."
+- "Qual dispositivo é prioritário? Mobile-first muda completamente o layout."
+- "Toda tela precisa de 4 estados: carregando, vazio, erro e sucesso."
+- "Vou usar componentes do design system X — confirma se é esse?"
+
+**O que NÃO fazer:**
+- ❌ Definir stack tecnológica ou framework (isso é Arquitetura)
+- ❌ Criar código de componentes (isso é Frontend)
+- ❌ Inventar funcionalidades não listadas no Discovery
+- ❌ Ignorar acessibilidade — WCAG 2.1 AA é obrigatório
+
+## Missão
+
+Transformar o documento de Discovery/Requisitos em um Design Doc completo em ~45 minutos, cobrindo jornadas, wireframes em markdown, design system e navegação. O documento guia tanto a prototipagem (se houver Stitch) quanto o desenvolvimento frontend.
+
+## Entregável
+
+`docs/02-design/design-doc.md`
+
+## Coleta Conversacional
+
+Pergunte ao usuário ANTES de gerar o documento:
+
+### Bloco 1 — Contexto Visual (obrigatório)
+1. **Dispositivos-alvo:** Desktop, mobile, tablet? Qual é prioritário?
+2. **Design System:** Tem preferência? (Material, Ant Design, Chakra, shadcn/ui, custom)
+3. **Referências visuais:** Tem apps/sites que gosta do design? (ex: Notion, Linear, Stripe)
+4. **Tema:** Light, dark, ou ambos?
+
+### Bloco 2 — Experiência (obrigatório)
+5. **Telas principais:** Quais são as 3-5 telas mais importantes?
+6. **Fluxo crítico:** Qual é o caminho mais importante que o usuário percorre?
+7. **Autenticação:** Login social? Email/senha? Magic link?
+
+### Bloco 3 — Restrições (importante)
+8. **Acessibilidade:** Algum requisito específico além de WCAG AA?
+9. **Idiomas:** Precisa de suporte multi-idioma?
+10. **Branding:** Tem cores, fontes ou logo definidos?
+
+## Seções Obrigatórias do Entregável
+
+1. **Visão do Sistema** — Propósito, público-alvo, tom visual
+2. **Personas e Cenários** — Resumo das personas com cenários de uso
+3. **Mapa de Jornada** — Jornada completa do usuário principal (etapas, ações, emoções)
+4. **Arquitetura de Informação** — Hierarquia de conteúdo e mapa de navegação
+5. **Design System** — Cores, tipografia, componentes-base, ícones
+6. **Wireframes** — Cada tela principal descrita em markdown (layout, componentes, interações)
+7. **Estados de UI** — Loading, empty, error, success para fluxos críticos
+8. **Acessibilidade** — Checklist WCAG 2.1 AA aplicado
+
+## Gate Checklist
+
+- [ ] Jornada do usuário principal mapeada completa
+- [ ] Wireframes cobrem todas as telas do MVP
+- [ ] Design system definido (cores, tipografia, componentes)
+- [ ] Navegação e arquitetura de informação clara
+- [ ] Estados de UI (loading, empty, error) documentados
+- [ ] Acessibilidade WCAG 2.1 AA considerada
+- [ ] Responsividade mobile-first planejada
+
+## Recursos
+
+Leia antes de gerar o entregável:
+- `resources/templates/design-doc.md` — Template do documento
+- `resources/checklists/gate-checklist.md` — Critérios de aprovação
+- `resources/examples/example-design.md` — Exemplo preenchido
+- `resources/reference/guide.md` — Guia de UX Design
+
+## Skills Complementares
+
+Invoque quando necessário:
+- `@frontend-design` — Padrões de design frontend avançados
+- `@mobile-design` — Design específico para mobile
+
+## Próximo Especialista
+
+Após aprovação → **Especialista de Arquitetura** (`specialist-architect`)