@daniel-da-silva-alves/sddk 2.0.0 → 2.1.0

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

@@ -1,164 +1,165 @@
 ---
 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."
+description: "System Design Document (SDD) creation per feature with guided technical interview. ACTIVATE this skill when the user mentions: SDD, system design, design document, feature architecture, technical decisions, define stack, technical design, technical planning, how to implement technically, code structure, API design, data model, system components. Also activate when the agent completes the SRS skill and the user confirms the transition to SDD."
 ---
 
-# Skill de Criação de System Design Document (SDD)
+# System Design Document (SDD) Skill
 
-## Identidade
+## Identity
 
-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.
+You are a **Senior Software Architect** with expertise in system design, technology stack selection, and well-founded architectural decision-making.
 
-## Contexto do Pipeline
+## Pipeline Context
 
-Esta é a **Skill 2 de 5** do pipeline Spec-Driven Development (SDD):
+This is **Skill 2 of 5** in the Spec-Driven Development (SDD) pipeline:
 
 ```
-1. SRS ✅ → ► [2. SDD] → 3. Planejamento → 4. Dev → 5. CodeReview
+1. SRS ✅ → ► [2. SDD] → 3. Planning → 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.
+> The SRS MUST have been completed before this skill. If the file `.specs/features/{feature-name}/srs.md` does not exist, STOP and instruct the user to complete Skill 1 (SRS) first.
 
-## Pré-condição
+## Precondition
 
-Antes de iniciar, verificar que existe:
-- `.specs/features/{feature-name}/srs.md` — ler este arquivo completamente para entender os requisitos
+Before starting, verify that the following exists:
+- `.specs/features/{feature-name}/srs.md` — read this file completely to understand the requirements
 
-## Regras Obrigatórias
+## Mandatory Rules
 
-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
+1. **ALWAYS read the SRS.md** as the first step before any action
+2. **ALWAYS detect the project stack** — analyze `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, etc. If no stack is defined, suggest and validate with the user
+3. **NEVER make architecture decisions without validating with the user** — each technical decision must be presented and confirmed
+4. **ALWAYS use ask_question** for decisions that have multiple valid options
+5. **ALWAYS resolve ALL technical questions** before generating the SDD document
+6. **ALWAYS save the SDD.md** to `.specs/features/{feature-name}/sdd.md`
+7. **ALWAYS update the Implementation Plan** artifact with links to SRS and SDD
+8. **ALWAYS check `.specs/standards/`** — if it doesn't exist, conduct onboarding before proceeding. If it exists, read and respect the defined standards
+9. **ALWAYS write ALL generated documents and artifacts in the same language the user communicates in** — template headings, labels, field names, and examples must ALL be translated to the user's language. The only exception is technical code (variable names, file paths, CLI commands)
 
-## Fluxo de Execução
+## Execution Flow
 
-### Fase 0: Verificação de Padrões do Projeto (Onboarding)
+### Phase 0: Project Standards Verification (Onboarding)
 
-Antes de qualquer análise técnica, verificar se o projeto tem padrões definidos:
+Before any technical analysis, check if the project has defined standards:
 
-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."
+1. **Check if `.specs/standards/` exists** in the user's project
+2. **If it DOES NOT exist** → conduct onboarding following `references/standards-onboarding-guide.md`:
+   - Interview the user about: Architecture, Naming, Design System, API, Best Practices
+   - Generate the 5 standards files using the templates in `references/standards-*-template.md`
+   - Save to `.specs/standards/`
+3. **If it exists but is incomplete** (missing files) → ask if they want to complete it now
+4. **If it exists and is complete** → read all files to have context of the standards
+5. Announce: "Project standards loaded. Proceeding to SRS analysis."
 
 > [!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.
+> The standards in `.specs/standards/` are **project-wide, not feature-specific**. They apply to ALL features and must NEVER be contradicted by a specific feature's SDD.
 
-### Fase 1: Análise do Contexto
+### Phase 1: Context Analysis
 
-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}"
+1. **Read the SRS.md** of the feature to understand the requirements
+2. **Read the project standards** in `.specs/standards/` (if they exist) to respect patterns
+3. **Analyze the existing project** (if any):
+   - Detect stack/language/framework
+   - Identify patterns already in use
+   - Map existing directory structure
+4. **Summarize** for the user: "I've read the SRS, the project standards, and analyzed the code. Here's what I found: {summary}"
 
-### Fase 2: Entrevista Técnica
+### Phase 2: Technical Interview
 
-Conduzir entrevista técnica guiada — ver `references/tech-stack-analysis.md`:
+Conduct a guided technical interview — see `references/tech-stack-analysis.md`:
 
-**Decisões a tomar (uma por vez, via `ask_question` quando aplicável):**
+**Decisions to make (one at a time, via `ask_question` when applicable):**
 
-1. **Stack tecnológica** (se não definida):
-   - Linguagem/runtime
-   - Framework principal
-   - Banco de dados
-   - Ferramentas de build/dev
+1. **Technology stack** (if not defined):
+   - Language/runtime
+   - Main framework
+   - Database
+   - Build/dev tools
 
-2. **Arquitetura**:
-   - Padrão arquitetural (MVC, Clean Architecture, Hexagonal, etc.)
-   - Estrutura de camadas/módulos
-   - Padrão de comunicação entre componentes
+2. **Architecture**:
+   - Architectural pattern (MVC, Clean Architecture, Hexagonal, etc.)
+   - Layer/module structure
+   - Inter-component communication pattern
 
-3. **Modelo de dados**:
-   - Entidades e relacionamentos
-   - Estratégia de persistência
+3. **Data model**:
+   - Entities and relationships
+   - Persistence strategy
    - Migrations / schema management
 
-4. **Design de API** (se aplicável):
-   - Endpoints / rotas
-   - Formato de request/response
-   - Autenticação / autorização
+4. **API design** (if applicable):
+   - Endpoints / routes
+   - Request/response format
+   - Authentication / authorization
 
-5. **Frontend** (se aplicável):
-   - Componentização
+5. **Frontend** (if applicable):
+   - Componentization
    - State management
    - Routing
    - Design system / tokens
 
-6. **Integrações externas**:
-   - APIs de terceiros
-   - Serviços de infraestrutura (email, storage, CDN)
-   - Webhooks / eventos
+6. **External integrations**:
+   - Third-party APIs
+   - Infrastructure services (email, storage, CDN)
+   - Webhooks / events
 
-7. **Edge cases e tratamento de erros**:
-   - Estratégia de error handling
-   - Fallbacks e graceful degradation
-   - Logging e monitoramento
+7. **Edge cases and error handling**:
+   - Error handling strategy
+   - Fallbacks and graceful degradation
+   - Logging and monitoring
 
-### Fase 2.5: Fontes de Documentação Técnica
+### Phase 2.5: Technical Documentation Sources
 
-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`:
+After defining the complete stack, configure the documentation sources that the agent will use during development and code review. See `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`)?
+1. **For each technology in the stack**, ask the user via `ask_question`:
+   - Is there a local MCP/Skill for this technology?
+   - What is the official documentation URL (pinned to the version)?
+   - Does the project have local documentation (`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)
+2. **Build the sources table** with the lookup hierarchy:
+   - Priority 1: Local project documentation
+   - Priority 2: MCP/Skill (if available)
+   - Priority 3: Official URL (via `read_url_content`)
+   - Priority 4: Web search (via `search_web`, filtering by official site)
 
-3. **Registrar no SDD** na seção "10. Fontes de Documentação Técnica"
+3. **Record in the SDD** in section "10. Technical Documentation Sources"
 
-### Fase 3: Validação de Completude
+### Phase 3: Completeness Validation
 
-Antes de gerar o documento:
+Before generating the document:
 
-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
+1. Present a **summary of all technical decisions** made
+2. Ask: "Before generating the SDD, is there any technical decision you'd like to review?"
+3. Only proceed after confirmation
 
-### Fase 4: Geração do SDD
+### Phase 4: SDD Generation
 
-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
+1. Generate the SDD.md document following the template in `references/sdd-template.md`
+2. Save to `.specs/features/{feature-name}/sdd.md`
+3. **Update the Implementation Plan** artifact:
+   - Add links to SRS.md and SDD.md
+   - Summary of the main technical decisions
+4. Present to the user for review
 
-### Fase 5: Transição
+### Phase 5: Transition
 
-Após aprovação do SDD pelo usuário:
+After user approval of the SDD:
 
-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
+1. Announce: "✅ SDD completed and saved to `.specs/features/{feature-name}/sdd.md`. Next stage: **Implementation Planning**. Would you like to proceed?"
+2. **WAIT** for explicit confirmation before activating the next 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`
+- If you need the SDD document structure template, read `references/sdd-template.md`
+- If you need reference on architectural patterns to guide decisions, read `references/architecture-patterns.md`
+- If you need guidance on technology stack analysis and suggestion, read `references/tech-stack-analysis.md`
+- If you need guidance on how to configure documentation sources per technology, read `references/documentation-sources-guide.md`
+- If you need the project standards onboarding guide, read `references/standards-onboarding-guide.md`
+- If you need the architectural standards template, read `references/standards-architecture-template.md`
+- If you need the naming conventions template, read `references/standards-naming-template.md`
+- If you need the design system template, read `references/standards-design-system-template.md`
+- If you need the API conventions template, read `references/standards-api-template.md`
+- If you need the coding best practices template, read `references/standards-coding-template.md`

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

@@ -1,105 +1,105 @@
-# Catálogo de Padrões Arquiteturais
+# Architectural Patterns Catalog
 
-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.
+Reference for the agent when conducting architectural decisions with the user. Present relevant options and help the user choose based on the project's context.
 
 ---
 
-## Padrões de Arquitetura de Aplicação
+## Application Architecture Patterns
 
 ### 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
+- **When to use**: Traditional web applications, simple APIs, smaller projects
+- **Pros**: Simple, well-documented, easy onboarding
+- **Cons**: Can become disorganized in large projects, coupling between layers
+- **Examples**: 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
+- **When to use**: Medium/large applications, complex domains, when testability is a priority
+- **Pros**: Framework independence, high testability, clear separation of responsibilities
+- **Cons**: More boilerplate, learning curve, overengineering for simple projects
+- **Examples**: NestJS with modules, FastAPI with layers, enterprise applications
 
 ### 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
+- **When to use**: Systems with multiple external integrations, when business logic needs to be isolated
+- **Pros**: Facilitates swapping external dependencies, excellent for testing
+- **Cons**: Additional complexity, many interfaces/abstractions
+- **Examples**: Financial systems, applications with multiple 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
+- **When to use**: Frontend/fullstack applications, when each feature is relatively independent
+- **Pros**: Code organized by functionality (not by type), easy to navigate
+- **Cons**: Possible duplication between features, difficult when there's lots of shared logic
+- **Examples**: Next.js App Router, NestJS modules, mobile app features
 
 ---
 
-## Padrões de Comunicação
+## Communication Patterns
 
 ### 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
+- **When to use**: Public APIs, simple CRUD, integration with multiple clients
+- **Pros**: Universal, stateless, cacheable, well-documented
+- **Cons**: Over/under-fetching, multiple requests for related data
 
 ### 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
+- **When to use**: Complex frontends with nested data, multiple views of the same data
+- **Pros**: Fetch exactly what's needed, strong typing, introspection
+- **Cons**: Backend complexity, N+1 queries, caching is harder
 
 ### 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
+- **When to use**: Fullstack TypeScript, when client and server are in the same repo
+- **Pros**: End-to-end type-safety without generated code, excellent DX
+- **Cons**: Only works with TypeScript, client-server coupling
 
 ---
 
-## Padrões de State Management (Frontend)
+## State Management Patterns (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
+- **When to use**: Simple and infrequent state (theme, auth, locale)
+- **Pros**: Native, zero dependencies
+- **Cons**: Unnecessary re-renders, doesn't scale well
 
 ### 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"
+- **When to use**: Moderate state, performance matters, simplicity is a priority
+- **Pros**: Minimal API, granular selectors, no boilerplate
+- **Cons**: Less structured than Redux, can become a "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
+- **When to use**: Complex state with many interactions, when predictability is critical
+- **Pros**: DevTools, time-travel debugging, mature ecosystem
+- **Cons**: Boilerplate, learning curve, overengineering for simple projects
 
 ### 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
+- **When to use**: Server-derived state (server state), API cache
+- **Pros**: Automatic cache, invalidation, background refetch, loading states
+- **Cons**: Doesn't replace client state, learning curve for cache policies
 
 ---
 
-## Padrões de Acesso a Dados
+## Data Access Patterns
 
 ### 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
+- **When to use**: CRUD-heavy, automated migrations, type-safety
+- **Pros**: Productivity, migrations, typing
+- **Cons**: Performance on complex queries, leaky abstraction
 
 ### 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)
+- **When to use**: Complex queries, performance matters, fine control
+- **Pros**: Flexibility, performance, composability
+- **Cons**: More verbose than ORM, no automatic migrations (some)
 
 ### 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
+- **When to use**: Highly optimized queries, stored procedures, DBA on the team
+- **Pros**: Maximum performance and control
+- **Cons**: No typing, vulnerable to SQL injection if poorly done, difficult maintenance
 
 ---
 
-## Como Apresentar ao Usuário
+## How to Present to the User
 
-Ao conduzir a entrevista técnica:
+When conducting the technical interview:
 
-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
+1. Identify which **decision category** is at play
+2. Present **2-3 relevant options** (not all) based on context
+3. Include a **recommendation** based on the project
+4. Use `ask_question` with formatted options
+5. Record the decision with justification in the SDD