@daniel-da-silva-alves/sddk 2.0.0

package/sddk/skills/software-requirements-specification/references/socratic-interview-guide.md

@@ -0,0 +1,96 @@
+# Guia de Entrevista Socrática para Levantamento de Requisitos
+
+## Princípios do Pensamento Socrático Aplicado
+
+A entrevista socrática não busca respostas diretas — busca **clareza de pensamento**. O objetivo é guiar o stakeholder a articular exatamente o que precisa, eliminando suposições implícitas.
+
+### Técnicas Fundamentais
+
+#### 1. Pergunta Clarificadora
+Usada quando uma resposta é vaga ou usa termos ambíguos.
+
+**Padrão**: "Quando você diz '{termo}', o que exatamente isso significa neste contexto?"
+
+**Exemplos**:
+- Usuário: "O login deve ser seguro"
+- Agente: "Quando você diz 'seguro', você está se referindo a: autenticação multifator, criptografia de senhas, proteção contra brute force, ou todas essas?"
+
+#### 2. Pergunta de Suposição
+Usada para expor premissas não declaradas.
+
+**Padrão**: "Você está assumindo que {premissa}. Essa premissa é válida?"
+
+**Exemplos**:
+- Usuário: "O usuário faz login e acessa o dashboard"
+- Agente: "Você está assumindo que existe apenas um tipo de usuário. Existem diferentes papéis (admin, operador, visitante) com acessos diferentes?"
+
+#### 3. Pergunta de Contraponto
+Usada para testar a robustez de um requisito propondo cenários contrários.
+
+**Padrão**: "E se {cenário oposto ou edge case} acontecer? Como o sistema deve reagir?"
+
+**Exemplos**:
+- Usuário: "O sistema envia um email de confirmação"
+- Agente: "E se o email for inválido? E se o servidor de email estiver fora do ar? O usuário fica bloqueado ou pode prosseguir?"
+
+#### 4. Pergunta de Consequência
+Usada para explorar impactos de uma decisão.
+
+**Padrão**: "Se implementarmos {decisão}, qual seria o impacto em {aspecto relacionado}?"
+
+**Exemplos**:
+- Usuário: "Quero que o sistema permita upload de arquivos ilimitados"
+- Agente: "Se permitirmos uploads ilimitados, qual seria o impacto no custo de armazenamento e na performance do sistema? Devemos ter um limite por usuário?"
+
+#### 5. Pergunta de Priorização
+Usada para rankear requisitos quando há muitos.
+
+**Padrão**: "Se você tivesse que lançar amanhã com apenas 3 funcionalidades, quais seriam?"
+
+---
+
+## Fluxo da Entrevista
+
+### Abertura (1-2 perguntas)
+Objetivo: Entender o contexto geral da feature.
+
+- "Descreva em uma frase o que essa feature deve fazer"
+- "Quem são os principais usuários dessa feature?"
+- "Qual problema de negócio essa feature resolve?"
+
+### Aprofundamento (N perguntas por tópico)
+Objetivo: Detalhar cada aspecto do checklist.
+
+Para cada tópico do checklist:
+1. Pergunte abertamente primeiro
+2. Use perguntas clarificadoras para respostas vagas
+3. Use perguntas de contraponto para edge cases
+4. Use perguntas de suposição para premissas implícitas
+5. Marque como `[x]` quando inequívoco
+
+### Validação (2-3 perguntas finais)
+Objetivo: Garantir completude antes de gerar o documento.
+
+- "Revisando tudo que discutimos, há algum cenário que não cobrimos?"
+- "Existe alguma integração com sistema externo que não mencionamos?"
+- "Há alguma restrição regulatória ou de compliance que afeta essa feature?"
+
+---
+
+## Sinais de Alerta (Não Aceitar)
+
+| Sinal | Ação |
+|:---|:---|
+| "Depois a gente vê isso" | Insistir — decisão adiada vira bug |
+| "É óbvio que..." | Questionar — o óbvio do stakeholder pode não ser do dev |
+| "Algo parecido com o sistema X" | Pedir detalhes — "parecido" é ambíguo |
+| "O usual" / "O padrão" | Definir explicitamente o que é "padrão" neste contexto |
+| Requisitos contraditórios | Apontar a contradição e pedir resolução |
+
+## Quando Encerrar um Tópico
+
+Um tópico está **concluído** quando:
+- A resposta é específica e mensurável
+- Não há interpretação alternativa possível
+- O critério de aceitação é verificável
+- Edge cases foram cobertos

package/sddk/skills/system-design-document/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: system-design-document
+description: "Criação de System Design Document (SDD) por feature com entrevista técnica guiada. ATIVE esta skill quando o usuário mencionar: SDD, system design, design document, arquitetura da feature, decisões técnicas, definir stack, design técnico, planejamento técnico, como implementar tecnicamente, estrutura do código, design de API, modelo de dados, componentes do sistema. Também acione quando o agente completar a skill SRS e o usuário confirmar a transição para o SDD."
+---
+
+# Skill de Criação de System Design Document (SDD)
+
+## Identidade
+
+Você é um **Arquiteto de Software Sênior** com experiência em design de sistemas, seleção de stack tecnológica e tomada de decisões arquiteturais fundamentadas.
+
+## Contexto do Pipeline
+
+Esta é a **Skill 2 de 5** do pipeline Spec-Driven Development (SDD):
+
+```
+1. SRS ✅ → ► [2. SDD] → 3. Planejamento → 4. Dev → 5. CodeReview
+```
+
+> [!IMPORTANT]
+> O SRS DEVE ter sido concluído antes desta skill. Se o arquivo `.specs/features/{feature-name}/srs.md` não existir, PARE e instrua o usuário a completar a Skill 1 (SRS) primeiro.
+
+## Pré-condição
+
+Antes de iniciar, verificar que existe:
+- `.specs/features/{feature-name}/srs.md` — ler este arquivo completamente para entender os requisitos
+
+## Regras Obrigatórias
+
+1. **SEMPRE ler o SRS.md** como primeiro passo antes de qualquer ação
+2. **SEMPRE detectar a stack do projeto** — analisar `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, etc. Se não houver stack definida, sugerir e validar com o usuário
+3. **NUNCA tomar decisões de arquitetura sem validar com o usuário** — cada decisão técnica deve ser apresentada e confirmada
+4. **SEMPRE usar ask_question** para decisões que têm múltiplas opções válidas
+5. **SEMPRE resolver TODAS as dúvidas técnicas** antes de gerar o documento SDD
+6. **SEMPRE salvar o SDD.md** em `.specs/features/{feature-name}/sdd.md`
+7. **SEMPRE atualizar o Implementation Plan** artifact com links para SRS e SDD
+8. **SEMPRE verificar `.specs/standards/`** — se não existe, conduzir onboarding antes de prosseguir. Se existe, ler e respeitar os padrões definidos
+
+## Fluxo de Execução
+
+### Fase 0: Verificação de Padrões do Projeto (Onboarding)
+
+Antes de qualquer análise técnica, verificar se o projeto tem padrões definidos:
+
+1. **Verificar se `.specs/standards/` existe** no projeto do usuário
+2. **Se NÃO existe** → conduzir onboarding seguindo `references/standards-onboarding-guide.md`:
+   - Entrevistar o usuário sobre: Arquitetura, Nomenclatura, Design System, API, Boas Práticas
+   - Gerar os 5 arquivos de standards usando os templates em `references/standards-*-template.md`
+   - Salvar em `.specs/standards/`
+3. **Se existe mas incompleto** (faltam arquivos) → perguntar se quer completar agora
+4. **Se existe e completo** → ler todos os arquivos para ter contexto dos padrões
+5. Anunciar: "Padrões do projeto carregados. Prosseguindo para análise do SRS."
+
+> [!IMPORTANT]
+> Os padrões em `.specs/standards/` são **de projeto, não de feature**. Eles se aplicam a TODAS as features e NUNCA devem ser contrariados pelo SDD de uma feature específica.
+
+### Fase 1: Análise do Contexto
+
+1. **Ler o SRS.md** da feature para entender os requisitos
+2. **Ler os standards do projeto** em `.specs/standards/` (se existem) para respeitar padrões
+3. **Analisar o projeto existente** (se houver):
+   - Detectar stack/linguagem/framework
+   - Identificar padrões já em uso
+   - Mapear estrutura de diretórios existente
+4. **Resumir** para o usuário: "Li o SRS, os standards do projeto e analisei o código. Aqui está o que encontrei: {resumo}"
+
+### Fase 2: Entrevista Técnica
+
+Conduzir entrevista técnica guiada — ver `references/tech-stack-analysis.md`:
+
+**Decisões a tomar (uma por vez, via `ask_question` quando aplicável):**
+
+1. **Stack tecnológica** (se não definida):
+   - Linguagem/runtime
+   - Framework principal
+   - Banco de dados
+   - Ferramentas de build/dev
+
+2. **Arquitetura**:
+   - Padrão arquitetural (MVC, Clean Architecture, Hexagonal, etc.)
+   - Estrutura de camadas/módulos
+   - Padrão de comunicação entre componentes
+
+3. **Modelo de dados**:
+   - Entidades e relacionamentos
+   - Estratégia de persistência
+   - Migrations / schema management
+
+4. **Design de API** (se aplicável):
+   - Endpoints / rotas
+   - Formato de request/response
+   - Autenticação / autorização
+
+5. **Frontend** (se aplicável):
+   - Componentização
+   - State management
+   - Routing
+   - Design system / tokens
+
+6. **Integrações externas**:
+   - APIs de terceiros
+   - Serviços de infraestrutura (email, storage, CDN)
+   - Webhooks / eventos
+
+7. **Edge cases e tratamento de erros**:
+   - Estratégia de error handling
+   - Fallbacks e graceful degradation
+   - Logging e monitoramento
+
+### Fase 2.5: Fontes de Documentação Técnica
+
+Após definir a stack completa, configurar as fontes de documentação que o agente usará durante o desenvolvimento e code review. Ver `references/documentation-sources-guide.md`:
+
+1. **Para cada tecnologia da stack**, perguntar ao usuário via `ask_question`:
+   - Existe um MCP/Skill local para esta tecnologia?
+   - Qual é a URL oficial da documentação (pinada na versão)?
+   - O projeto tem documentação local (`docs/`, `README.md`)?
+
+2. **Montar a tabela de fontes** com a hierarquia de consulta:
+   - Prioridade 1: Documentação local do projeto
+   - Prioridade 2: MCP/Skill (se disponível)
+   - Prioridade 3: URL oficial (via `read_url_content`)
+   - Prioridade 4: Web search (via `search_web`, filtrando por site oficial)
+
+3. **Registrar no SDD** na seção "10. Fontes de Documentação Técnica"
+
+### Fase 3: Validação de Completude
+
+Antes de gerar o documento:
+
+1. Apresentar um **resumo de todas as decisões técnicas** tomadas
+2. Perguntar: "Antes de gerar o SDD, há alguma decisão técnica que gostaria de revisar?"
+3. Só prosseguir após confirmação
+
+### Fase 4: Geração do SDD
+
+1. Gerar o documento SDD.md seguindo o template em `references/sdd-template.md`
+2. Salvar em `.specs/features/{feature-name}/sdd.md`
+3. **Atualizar o Implementation Plan** artifact:
+   - Adicionar links para SRS.md e SDD.md
+   - Resumo das decisões técnicas principais
+4. Apresentar ao usuário para revisão
+
+### Fase 5: Transição
+
+Após aprovação do SDD pelo usuário:
+
+1. Anunciar: "✅ SDD concluído e salvo em `.specs/features/{feature-name}/sdd.md`. Próxima etapa: **Planejamento de Implementação**. Deseja prosseguir?"
+2. **AGUARDAR** confirmação explícita antes de ativar a próxima skill
+
+## Routing Table
+
+### References
+
+- Se precisar do template de estrutura do documento SDD, leia `references/sdd-template.md`
+- Se precisar de referência sobre padrões arquiteturais para orientar decisões, leia `references/architecture-patterns.md`
+- Se precisar de orientação sobre análise e sugestão de stack tecnológica, leia `references/tech-stack-analysis.md`
+- Se precisar de orientação sobre como configurar fontes de documentação por tecnologia, leia `references/documentation-sources-guide.md`
+- Se precisar do guia de onboarding de padrões do projeto, leia `references/standards-onboarding-guide.md`
+- Se precisar do template de padrões arquiteturais, leia `references/standards-architecture-template.md`
+- Se precisar do template de convenções de nomenclatura, leia `references/standards-naming-template.md`
+- Se precisar do template de design system, leia `references/standards-design-system-template.md`
+- Se precisar do template de convenções de API, leia `references/standards-api-template.md`
+- Se precisar do template de boas práticas de código, leia `references/standards-coding-template.md`

package/sddk/skills/system-design-document/references/architecture-patterns.md

@@ -0,0 +1,105 @@
+# Catálogo de Padrões Arquiteturais
+
+Referência para o agente ao conduzir decisões arquiteturais com o usuário. Apresente as opções relevantes e ajude o usuário a escolher com base no contexto do projeto.
+
+---
+
+## Padrões de Arquitetura de Aplicação
+
+### MVC (Model-View-Controller)
+- **Quando usar**: Aplicações web tradicionais, APIs simples, projetos menores
+- **Prós**: Simples, bem documentado, fácil onboarding
+- **Contras**: Pode ficar desorganizado em projetos grandes, acoplamento entre camadas
+- **Exemplos**: Express.js + templates, Ruby on Rails, Django
+
+### Clean Architecture
+- **Quando usar**: Aplicações de médio/grande porte, domínios complexos, quando testabilidade é prioridade
+- **Prós**: Independência de frameworks, alta testabilidade, separação clara de responsabilidades
+- **Contras**: Mais boilerplate, curva de aprendizado, overengineering para projetos simples
+- **Exemplos**: NestJS com módulos, FastAPI com camadas, aplicações enterprise
+
+### Hexagonal (Ports & Adapters)
+- **Quando usar**: Sistemas com múltiplas integrações externas, quando a lógica de negócio precisa ser isolada
+- **Prós**: Facilita troca de dependências externas, excelente para testes
+- **Contras**: Complexidade adicional, muitas interfaces/abstrações
+- **Exemplos**: Sistemas financeiros, aplicações com múltiplos data sources
+
+### Feature-Based (Vertical Slicing)
+- **Quando usar**: Aplicações frontend/fullstack, quando cada feature é relativamente independente
+- **Prós**: Código organizado por funcionalidade (não por tipo), fácil de navegar
+- **Contras**: Pode haver duplicação entre features, difícil quando há muita lógica compartilhada
+- **Exemplos**: Next.js App Router, módulos NestJS, features de app mobile
+
+---
+
+## Padrões de Comunicação
+
+### REST
+- **Quando usar**: APIs públicas, CRUD simples, integração com múltiplos clientes
+- **Prós**: Universal, stateless, cacheable, bem documentado
+- **Contras**: Over/under-fetching, múltiplas requisições para dados relacionados
+
+### GraphQL
+- **Quando usar**: Frontends complexos com dados aninhados, múltiplas views do mesmo dado
+- **Prós**: Fetch exato do necessário, tipagem forte, introspection
+- **Contras**: Complexidade no backend, N+1 queries, caching mais difícil
+
+### tRPC
+- **Quando usar**: Fullstack TypeScript, quando cliente e servidor estão no mesmo repo
+- **Prós**: Type-safety end-to-end sem código gerado, DX excelente
+- **Contras**: Só funciona com TypeScript, acoplamento client-server
+
+---
+
+## Padrões de State Management (Frontend)
+
+### React Context
+- **Quando usar**: Estado simples e pouco frequente (theme, auth, locale)
+- **Prós**: Nativo, zero dependências
+- **Contras**: Re-renders desnecessários, não escala bem
+
+### Zustand
+- **Quando usar**: Estado moderado, performance importa, simplicidade é prioridade
+- **Prós**: API mínima, seletores granulares, sem boilerplate
+- **Contras**: Menos estruturado que Redux, pode virar "bag of state"
+
+### Redux Toolkit
+- **Quando usar**: Estado complexo com muitas interações, quando previsibilidade é crítica
+- **Prós**: DevTools, time-travel debugging, ecosistema maduro
+- **Contras**: Boilerplate, curva de aprendizado, overengineering para projetos simples
+
+### TanStack Query (React Query)
+- **Quando usar**: Estado que vem do servidor (server state), cache de API
+- **Prós**: Cache automático, invalidação, refetch em background, loading states
+- **Contras**: Não substitui client state, curva para cache policies
+
+---
+
+## Padrões de Acesso a Dados
+
+### ORM (Prisma, TypeORM, SQLAlchemy)
+- **Quando usar**: CRUD-heavy, migrations automatizadas, type-safety
+- **Prós**: Produtividade, migrations, tipagem
+- **Contras**: Performance em queries complexas, abstração leaky
+
+### Query Builder (Knex, Drizzle)
+- **Quando usar**: Queries complexas, performance importa, controle fino
+- **Prós**: Flexibilidade, performance, composabilidade
+- **Contras**: Mais verboso que ORM, sem migrations automáticas (alguns)
+
+### Raw SQL
+- **Quando usar**: Queries altamente otimizadas, stored procedures, DBA no time
+- **Prós**: Máxima performance e controle
+- **Contras**: Sem tipagem, vulnerável a SQL injection se mal feito, difícil manutenção
+
+---
+
+## Como Apresentar ao Usuário
+
+Ao conduzir a entrevista técnica:
+
+1. Identifique qual **categoria** de decisão está em jogo
+2. Apresente **2-3 opções relevantes** (não todas) com base no contexto
+3. Inclua a **recomendação** baseada no projeto
+4. Use `ask_question` com as opções formatadas
+5. Registre a decisão com justificativa no SDD

package/sddk/skills/system-design-document/references/documentation-sources-guide.md

@@ -0,0 +1,126 @@
+# Guia de Configuração de Fontes de Documentação Técnica
+
+## Propósito
+
+Durante o desenvolvimento (Skill 4) e code review (Skill 5), o agente precisa consultar documentação técnica das tecnologias da stack. Este guia define como configurar as fontes de documentação para cada tecnologia, garantindo que o agente use **a versão correta** e **a fonte mais confiável**.
+
+## Hierarquia de Consulta
+
+Ao precisar de documentação técnica, o agente segue esta ordem de prioridade:
+
+```
+1. 📁 Docs locais do projeto     (docs/, README, ARCHITECTURE.md)
+    ↓ se não encontrar
+2. 🔌 MCP/Skill da tecnologia    (se existir e for da versão correta)
+    ↓ se não existir
+3. 🌐 URL oficial pré-configurada (registrada no SDD, pinada à versão)
+    ↓ se não cobrir o caso
+4. 🔍 Web search como fallback   (pesquisa direcionada ao site oficial)
+```
+
+### Por que esta ordem?
+
+| Prioridade | Fonte | Justificativa |
+|:---:|:---|:---|
+| 1 | **Docs locais** | Mais específico ao projeto, padrões customizados, convenções internas |
+| 2 | **MCP/Skill** | Curado, confiável, eficiente em tokens, funciona offline |
+| 3 | **URL oficial** | Fonte canônica da tecnologia, pinada à versão correta |
+| 4 | **Web search** | Fallback universal, mas ruidoso e pode trazer versão errada |
+
+---
+
+## Como Conduzir a Entrevista de Fontes
+
+Durante a Fase 2.5 do SDD, após definir a stack, perguntar para cada tecnologia:
+
+### Pergunta padrão (via ask_question):
+
+```
+Para a tecnologia {nome} v{versão}, qual fonte de documentação devemos usar?
+```
+
+**Opções:**
+1. **URL oficial** — informar a URL da documentação oficial pinada na versão
+2. **MCP disponível** — informar qual MCP server provê docs desta tecnologia
+3. **Skill local** — o projeto tem uma skill customizada para esta tecnologia
+4. **Docs no projeto** — existe pasta `docs/` ou wiki com documentação interna
+
+### Tecnologias com MCPs conhecidos:
+
+| Tecnologia | MCP Disponível | Notas |
+|:---|:---|:---|
+| Múltiplas libs | Context7 | Cobre muitas bibliotecas populares via `context7` |
+| PostgreSQL | postgres-mcp | Schema awareness |
+| GitHub | github-mcp | Issues, PRs, repos |
+| Filesystem | filesystem-mcp | Nativo do Antigravity |
+
+> [!NOTE]
+> A disponibilidade de MCPs muda frequentemente. Pergunte ao usuário se ele tem MCPs configurados no projeto.
+
+---
+
+## Formato da Seção no SDD
+
+A seção "10. Fontes de Documentação Técnica" no SDD deve seguir este formato:
+
+```markdown
+## 10. Fontes de Documentação Técnica
+
+### 10.1 Configuração de Fontes
+
+| Tecnologia | Versão | Fonte Primária | URL Oficial | MCP/Skill |
+|:---|:---|:---|:---|:---|
+| Next.js | 15.2 | URL oficial | https://nextjs.org/docs | — |
+| React | 19.1 | URL oficial | https://react.dev/reference | — |
+| Prisma | 6.3 | MCP | https://prisma.io/docs | context7 |
+| Tailwind CSS | 4.0 | URL oficial | https://tailwindcss.com/docs | — |
+| PostgreSQL | 16 | MCP | https://www.postgresql.org/docs/16/ | postgres-mcp |
+| TypeScript | 5.7 | URL oficial | https://www.typescriptlang.org/docs/ | — |
+
+### 10.2 Documentação Local do Projeto
+
+| Caminho | Conteúdo |
+|:---|:---|
+| `docs/api.md` | Documentação da API interna |
+| `docs/conventions.md` | Convenções de código do projeto |
+| `ARCHITECTURE.md` | Arquitetura geral do sistema |
+
+### 10.3 Regra de Consulta
+
+Ordem de prioridade para consulta de documentação durante o desenvolvimento:
+1. Documentação local do projeto (caminhos listados em 10.2)
+2. MCP/Skill (se listado na coluna MCP/Skill em 10.1)
+3. URL oficial (usar `read_url_content` na URL listada em 10.1)
+4. Web search (usar `search_web` com query: "{tecnologia} {versão} {tópico} site:{domínio oficial}")
+```
+
+---
+
+## Instruções para o Agente (Dev e CodeReview)
+
+Quando o agente precisar consultar documentação durante o desenvolvimento:
+
+### Passo 1: Ler a seção 10 do SDD
+Abrir `.specs/features/{feature}/sdd.md` e ler a seção "10. Fontes de Documentação Técnica"
+
+### Passo 2: Seguir a hierarquia
+1. **Docs local?** → `view_file` no caminho listado em 10.2
+2. **MCP/Skill?** → Usar a ferramenta/skill configurada em 10.1
+3. **URL oficial?** → `read_url_content("{url-da-tabela-10.1}/topico-especifico")`
+4. **Nenhum?** → `search_web("{tecnologia} {versão} {tópico} site:{domínio}")`
+
+### Passo 3: Validar a versão
+> [!WARNING]
+> Antes de usar qualquer informação de documentação, verificar se corresponde à versão listada na tabela 10.1. Documentação da versão errada pode gerar código incompatível.
+
+### Exemplo prático de consulta:
+
+```
+Microtask: "Implementar server action de criação de usuário"
+Stack: Next.js 15.2
+
+1. Docs local? → Não tem docs sobre server actions
+2. MCP/Skill? → Não tem MCP de Next.js
+3. URL oficial? → read_url_content("https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations")
+4. Se URL não cobrir → search_web("Next.js 15 server actions mutations site:nextjs.org")
+```