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

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

@@ -1,126 +1,126 @@
-# Guia de Configuração de Fontes de Documentação Técnica
+# Technical Documentation Sources Configuration Guide
 
-## Propósito
+## Purpose
 
-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**.
+During development (Skill 4) and code review (Skill 5), the agent needs to consult technical documentation for the stack's technologies. This guide defines how to configure documentation sources for each technology, ensuring the agent uses **the correct version** and **the most reliable source**.
 
-## Hierarquia de Consulta
+## Lookup Hierarchy
 
-Ao precisar de documentação técnica, o agente segue esta ordem de prioridade:
+When needing technical documentation, the agent follows this priority order:
 
 ```
-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)
+1. 📁 Local project docs          (docs/, README, ARCHITECTURE.md)
+    ↓ if not found
+2. 🔌 Technology MCP/Skill        (if it exists and matches the version)
+    ↓ if it doesn't exist
+3. 🌐 Pre-configured official URL (registered in the SDD, pinned to version)
+    ↓ if it doesn't cover the case
+4. 🔍 Web search as fallback      (search directed at the official site)
 ```
 
-### Por que esta ordem?
+### Why this order?
 
-| Prioridade | Fonte | Justificativa |
+| Priority | Source | Justification |
 |:---:|:---|:---|
-| 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 |
+| 1 | **Local docs** | Most specific to the project, custom standards, internal conventions |
+| 2 | **MCP/Skill** | Curated, reliable, token-efficient, works offline |
+| 3 | **Official URL** | Canonical source of the technology, pinned to the correct version |
+| 4 | **Web search** | Universal fallback, but noisy and may bring the wrong version |
 
 ---
 
-## Como Conduzir a Entrevista de Fontes
+## How to Conduct the Sources Interview
 
-Durante a Fase 2.5 do SDD, após definir a stack, perguntar para cada tecnologia:
+During Phase 2.5 of the SDD, after defining the stack, ask for each technology:
 
-### Pergunta padrão (via ask_question):
+### Standard question (via ask_question):
 
 ```
-Para a tecnologia {nome} v{versão}, qual fonte de documentação devemos usar?
+For technology {name} v{version}, which documentation source should we use?
 ```
 
-**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
+**Options:**
+1. **Official URL** — provide the official documentation URL pinned to the version
+2. **MCP available** — specify which MCP server provides docs for this technology
+3. **Local skill** — the project has a custom skill for this technology
+4. **Docs in project** — there's a `docs/` folder or wiki with internal documentation
 
-### Tecnologias com MCPs conhecidos:
+### Technologies with known MCPs:
 
-| Tecnologia | MCP Disponível | Notas |
+| Technology | MCP Available | Notes |
 |:---|:---|:---|
-| Múltiplas libs | Context7 | Cobre muitas bibliotecas populares via `context7` |
+| Multiple libs | Context7 | Covers many popular libraries via `context7` |
 | PostgreSQL | postgres-mcp | Schema awareness |
 | GitHub | github-mcp | Issues, PRs, repos |
-| Filesystem | filesystem-mcp | Nativo do Antigravity |
+| Filesystem | filesystem-mcp | Native to Antigravity |
 
 > [!NOTE]
-> A disponibilidade de MCPs muda frequentemente. Pergunte ao usuário se ele tem MCPs configurados no projeto.
+> MCP availability changes frequently. Ask the user if they have MCPs configured in their project.
 
 ---
 
-## Formato da Seção no SDD
+## SDD Section Format
 
-A seção "10. Fontes de Documentação Técnica" no SDD deve seguir este formato:
+Section "10. Technical Documentation Sources" in the SDD should follow this format:
 
 ```markdown
-## 10. Fontes de Documentação Técnica
+## 10. Technical Documentation Sources
 
-### 10.1 Configuração de Fontes
+### 10.1 Source Configuration
 
-| Tecnologia | Versão | Fonte Primária | URL Oficial | MCP/Skill |
+| Technology | Version | Primary Source | Official URL | MCP/Skill |
 |:---|:---|:---|:---|:---|
-| Next.js | 15.2 | URL oficial | https://nextjs.org/docs | — |
-| React | 19.1 | URL oficial | https://react.dev/reference | — |
+| Next.js | 15.2 | Official URL | https://nextjs.org/docs | — |
+| React | 19.1 | Official URL | https://react.dev/reference | — |
 | Prisma | 6.3 | MCP | https://prisma.io/docs | context7 |
-| Tailwind CSS | 4.0 | URL oficial | https://tailwindcss.com/docs | — |
+| Tailwind CSS | 4.0 | Official URL | 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/ | — |
+| TypeScript | 5.7 | Official URL | https://www.typescriptlang.org/docs/ | — |
 
-### 10.2 Documentação Local do Projeto
+### 10.2 Local Project Documentation
 
-| Caminho | Conteúdo |
+| Path | Content |
 |:---|:---|
-| `docs/api.md` | Documentação da API interna |
-| `docs/conventions.md` | Convenções de código do projeto |
-| `ARCHITECTURE.md` | Arquitetura geral do sistema |
+| `docs/api.md` | Internal API documentation |
+| `docs/conventions.md` | Project code conventions |
+| `ARCHITECTURE.md` | General system architecture |
 
-### 10.3 Regra de Consulta
+### 10.3 Lookup Rule
 
-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}")
+Priority order for documentation lookup during development:
+1. Local project documentation (paths listed in 10.2)
+2. MCP/Skill (if listed in the MCP/Skill column in 10.1)
+3. Official URL (use `read_url_content` on the URL listed in 10.1)
+4. Web search (use `search_web` with query: "{technology} {version} {topic} site:{official domain}")
 ```
 
 ---
 
-## Instruções para o Agente (Dev e CodeReview)
+## Agent Instructions (Dev and CodeReview)
 
-Quando o agente precisar consultar documentação durante o desenvolvimento:
+When the agent needs to consult documentation during development:
 
-### 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"
+### Step 1: Read section 10 of the SDD
+Open `.specs/features/{feature}/sdd.md` and read section "10. Technical Documentation Sources"
 
-### 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}")`
+### Step 2: Follow the hierarchy
+1. **Local docs?** → `view_file` on the path listed in 10.2
+2. **MCP/Skill?** → Use the tool/skill configured in 10.1
+3. **Official URL?** → `read_url_content("{url-from-table-10.1}/specific-topic")`
+4. **None?** → `search_web("{technology} {version} {topic} site:{domain}")`
 
-### Passo 3: Validar a versão
+### Step 3: Validate the version
 > [!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.
+> Before using any documentation information, verify it matches the version listed in table 10.1. Documentation from the wrong version may generate incompatible code.
 
-### Exemplo prático de consulta:
+### Practical lookup example:
 
 ```
-Microtask: "Implementar server action de criação de usuário"
+Microtask: "Implement user creation server action"
 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")
+1. Local docs? → No docs about server actions
+2. MCP/Skill? → No Next.js MCP
+3. Official URL? → read_url_content("https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations")
+4. If URL doesn't cover → search_web("Next.js 15 server actions mutations site:nextjs.org")
 ```

package/sddk/skills/system-design-document/references/sdd-template.md

@@ -1,51 +1,51 @@
-# Template de System Design Document (SDD)
+# System Design Document (SDD) Template
 
-Use este template como base para gerar o documento SDD. Adapte as seções conforme a complexidade da feature.
+Use this template as a base to generate the SDD document. Adapt sections according to the feature's complexity.
 
 ---
 
-## Estrutura do Documento
+## Document Structure
 
 ```markdown
 # System Design Document (SDD)
-## {Nome da Feature}
+## {Feature Name}
 
-**Versão**: 1.0
-**Data**: {data de criação}
-**Projeto**: {nome do projeto}
-**Feature**: {nome da feature}
-**SRS Referência**: [srs.md](./srs.md)
+**Version**: 1.0
+**Date**: {creation date}
+**Project**: {project name}
+**Feature**: {feature name}
+**SRS Reference**: [srs.md](./srs.md)
 
 ---
 
-## 1. Visão Geral Técnica
+## 1. Technical Overview
 
-### 1.1 Resumo
-Breve descrição técnica do que será implementado e como.
+### 1.1 Summary
+Brief technical description of what will be implemented and how.
 
-### 1.2 Stack Tecnológica
+### 1.2 Technology Stack
 
-| Camada | Tecnologia | Justificativa |
+| Layer | Technology | Justification |
 |:---|:---|:---|
-| Linguagem | {ex: TypeScript} | {por que esta escolha} |
-| Framework | {ex: Next.js 14} | {por que esta escolha} |
-| Banco de dados | {ex: PostgreSQL} | {por que esta escolha} |
-| ORM/Query | {ex: Prisma} | {por que esta escolha} |
-| Autenticação | {ex: NextAuth.js} | {por que esta escolha} |
-| Estilização | {ex: Tailwind CSS v4} | {por que esta escolha} |
+| Language | {e.g.: TypeScript} | {why this choice} |
+| Framework | {e.g.: Next.js 14} | {why this choice} |
+| Database | {e.g.: PostgreSQL} | {why this choice} |
+| ORM/Query | {e.g.: Prisma} | {why this choice} |
+| Authentication | {e.g.: NextAuth.js} | {why this choice} |
+| Styling | {e.g.: Tailwind CSS v4} | {why this choice} |
 
-### 1.3 Decisões Arquiteturais
+### 1.3 Architectural Decisions
 
-| Decisão | Escolha | Alternativas Consideradas | Justificativa |
+| Decision | Choice | Alternatives Considered | Justification |
 |:---|:---|:---|:---|
-| Padrão | {ex: Clean Architecture} | MVC, Hexagonal | {razão} |
-| State Management | {ex: Zustand} | Redux, Context | {razão} |
+| Pattern | {e.g.: Clean Architecture} | MVC, Hexagonal | {reason} |
+| State Management | {e.g.: Zustand} | Redux, Context | {reason} |
 
 ---
 
-## 2. Arquitetura do Sistema
+## 2. System Architecture
 
-### 2.1 Diagrama de Arquitetura
+### 2.1 Architecture Diagram
 
 ```mermaid
 graph TB
@@ -61,46 +61,46 @@ graph TB
     C --> D
 ```
 
-### 2.2 Estrutura de Diretórios
+### 2.2 Directory Structure
 
 ```
 src/
 ├── app/                    # Routes / pages
-├── components/             # Componentes reutilizáveis
+├── components/             # Reusable components
 │   ├── ui/                 # Design system (atoms)
-│   └── features/           # Componentes de feature
-├── lib/                    # Utilitários e helpers
-├── services/               # Lógica de negócio
-├── repositories/           # Acesso a dados
+│   └── features/           # Feature components
+├── lib/                    # Utilities and helpers
+├── services/               # Business logic
+├── repositories/           # Data access
 ├── types/                  # TypeScript types/interfaces
-└── config/                 # Configurações
+└── config/                 # Configurations
 ```
 
-### 2.3 Camadas e Responsabilidades
+### 2.3 Layers and Responsibilities
 
-| Camada | Responsabilidade | Exemplo |
+| Layer | Responsibility | Example |
 |:---|:---|:---|
-| **Presentation** | UI, formulários, validação visual | Componentes React |
-| **Application** | Orquestração, use cases | Services |
-| **Domain** | Regras de negócio puras | Entidades, Value Objects |
-| **Infrastructure** | Acesso a dados, APIs externas | Repositories, API clients |
+| **Presentation** | UI, forms, visual validation | React Components |
+| **Application** | Orchestration, use cases | Services |
+| **Domain** | Pure business rules | Entities, Value Objects |
+| **Infrastructure** | Data access, external APIs | Repositories, API clients |
 
 ---
 
-## 3. Modelo de Dados
+## 3. Data Model
 
-### 3.1 Entidades
+### 3.1 Entities
 
-#### {NomeEntidade}
+#### {EntityName}
 
-| Campo | Tipo | Constraints | Descrição |
+| Field | Type | Constraints | Description |
 |:---|:---|:---|:---|
-| id | UUID | PK, auto-generated | Identificador único |
-| {campo} | {tipo} | {constraints} | {descrição} |
-| created_at | DateTime | NOT NULL, default NOW | Data de criação |
-| updated_at | DateTime | NOT NULL, auto-update | Última atualização |
+| id | UUID | PK, auto-generated | Unique identifier |
+| {field} | {type} | {constraints} | {description} |
+| created_at | DateTime | NOT NULL, default NOW | Creation date |
+| updated_at | DateTime | NOT NULL, auto-update | Last update |
 
-### 3.2 Relacionamentos
+### 3.2 Relationships
 
 ```mermaid
 erDiagram
@@ -110,23 +110,23 @@ erDiagram
 
 ### 3.3 Migrations
 
-Lista de migrations necessárias em ordem:
-1. `001_create_{table}.sql` — Criar tabela principal
-2. `002_create_{table}.sql` — Criar tabelas secundárias
+List of required migrations in order:
+1. `001_create_{table}.sql` — Create main table
+2. `002_create_{table}.sql` — Create secondary tables
 
 ---
 
-## 4. Design de API
+## 4. API Design
 
 ### 4.1 Endpoints
 
 #### `POST /api/{resource}`
-- **Descrição**: {o que faz}
-- **Auth**: {requer autenticação? qual role?}
+- **Description**: {what it does}
+- **Auth**: {requires authentication? which role?}
 - **Request Body**:
   ```json
   {
-    "field": "type — descrição"
+    "field": "type — description"
   }
   ```
 - **Response 200**:
@@ -135,125 +135,125 @@ Lista de migrations necessárias em ordem:
     "data": {}
   }
   ```
-- **Errors**: 400 (validação), 401 (não autenticado), 403 (não autorizado), 500 (erro interno)
+- **Errors**: 400 (validation), 401 (unauthenticated), 403 (unauthorized), 500 (internal error)
 
-### 4.2 Validações
+### 4.2 Validations
 
-| Endpoint | Campo | Regra |
+| Endpoint | Field | Rule |
 |:---|:---|:---|
-| POST /api/{resource} | {campo} | {regra de validação} |
+| POST /api/{resource} | {field} | {validation rule} |
 
 ---
 
-## 5. Design de Interface (Frontend)
+## 5. Interface Design (Frontend)
 
-### 5.1 Componentes
+### 5.1 Components
 
-| Componente | Tipo | Descrição |
+| Component | Type | Description |
 |:---|:---|:---|
-| `{ComponentName}` | Page | {descrição} |
-| `{ComponentName}` | Feature | {descrição} |
-| `{ComponentName}` | UI/Atom | {descrição} |
+| `{ComponentName}` | Page | {description} |
+| `{ComponentName}` | Feature | {description} |
+| `{ComponentName}` | UI/Atom | {description} |
 
-### 5.2 Estado e Fluxo de Dados
+### 5.2 State and Data Flow
 
-Descrever como o estado flui entre componentes:
-- Fonte de dados
-- Estado local vs global
+Describe how state flows between components:
+- Data source
+- Local vs global state
 - Cache strategy
 
 ### 5.3 Design Tokens
 
-| Token | Valor | Uso |
+| Token | Value | Usage |
 |:---|:---|:---|
-| `--color-primary` | {valor} | {onde usar} |
-| `--spacing-md` | {valor} | {onde usar} |
+| `--color-primary` | {value} | {where to use} |
+| `--spacing-md` | {value} | {where to use} |
 
 ---
 
-## 6. Integrações
+## 6. Integrations
 
-### 6.1 APIs Externas
+### 6.1 External APIs
 
-| Serviço | Propósito | Endpoint | Auth |
+| Service | Purpose | Endpoint | Auth |
 |:---|:---|:---|:---|
-| {nome} | {para quê} | {URL base} | {tipo de auth} |
+| {name} | {what for} | {base URL} | {auth type} |
 
-### 6.2 Eventos / Webhooks
+### 6.2 Events / Webhooks
 
-| Evento | Trigger | Payload |
+| Event | Trigger | Payload |
 |:---|:---|:---|
-| {nome} | {quando dispara} | {dados enviados} |
+| {name} | {when it fires} | {data sent} |
 
 ---
 
-## 7. Tratamento de Erros
+## 7. Error Handling
 
-### 7.1 Estratégia
+### 7.1 Strategy
 
-| Camada | Estratégia | Exemplo |
+| Layer | Strategy | Example |
 |:---|:---|:---|
-| Frontend | {ex: Error Boundary + toast} | {quando usar} |
-| API | {ex: HTTP status + error body padronizado} | {formato} |
-| Service | {ex: Custom exceptions + logging} | {tipos de erro} |
+| Frontend | {e.g.: Error Boundary + toast} | {when to use} |
+| API | {e.g.: HTTP status + standardized error body} | {format} |
+| Service | {e.g.: Custom exceptions + logging} | {error types} |
 
 ### 7.2 Error Codes
 
-| Código | Mensagem | Ação do Usuário |
+| Code | Message | User Action |
 |:---|:---|:---|
-| {code} | {mensagem} | {o que fazer} |
+| {code} | {message} | {what to do} |
 
 ---
 
-## 8. Segurança
+## 8. Security
 
-### 8.1 Autenticação
-Descrever mecanismo de autenticação.
+### 8.1 Authentication
+Describe the authentication mechanism.
 
-### 8.2 Autorização
-Descrever modelo de permissões (RBAC, ABAC, etc.).
+### 8.2 Authorization
+Describe the permissions model (RBAC, ABAC, etc.).
 
-### 8.3 Proteção de Dados
-Campos sensíveis, criptografia, LGPD/GDPR.
+### 8.3 Data Protection
+Sensitive fields, encryption, LGPD/GDPR.
 
 ---
 
-## 9. Referências ao SRS
+## 9. SRS References
 
-| Seção SDD | Requisito SRS | Referência |
+| SDD Section | SRS Requirement | Reference |
 |:---|:---|:---|
-| 3. Modelo de Dados | RF-001 | [SRS#3 RF-001](./srs.md#rf-001) |
+| 3. Data Model | FR-001 | [SRS#3 FR-001](./srs.md#fr-001) |
 
 ---
 
-## 10. Fontes de Documentação Técnica
+## 10. Technical Documentation Sources
 
-### 10.1 Configuração de Fontes
+### 10.1 Source Configuration
 
-| Tecnologia | Versão | Fonte Primária | URL Oficial | MCP/Skill |
+| Technology | Version | Primary Source | Official URL | MCP/Skill |
 |:---|:---|:---|:---|:---|
-| {tecnologia} | {versão} | {URL oficial / MCP / Skill / Docs local} | {URL} | {nome do MCP ou —} |
+| {technology} | {version} | {Official URL / MCP / Skill / Local docs} | {URL} | {MCP name or —} |
 
-### 10.2 Documentação Local do Projeto
+### 10.2 Local Project Documentation
 
-| Caminho | Conteúdo |
+| Path | Content |
 |:---|:---|
-| {caminho} | {descrição do conteúdo} |
+| {path} | {content description} |
 
-### 10.3 Regra de Consulta
+### 10.3 Lookup Rule
 
-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}")
+Priority order for documentation lookup during development:
+1. Local project documentation (paths listed in 10.2)
+2. MCP/Skill (if listed in the MCP/Skill column in 10.1)
+3. Official URL (use `read_url_content` on the URL listed in 10.1)
+4. Web search (use `search_web` with query: "{technology} {version} {topic} site:{official domain}")
 ```
 
-## Regras de Preenchimento
+## Filling Rules
 
-1. **Cada decisão arquitetural DEVE ter justificativa** — nunca apenas "porque sim"
-2. **Modelo de dados DEVE corresponder aos requisitos do SRS** — usar matriz de referência
-3. **Endpoints DEVEM cobrir todos os requisitos funcionais** do SRS
-4. **Componentes DEVEM ser granulares** — nunca um componente monolítico
-5. **Design tokens DEVEM ser definidos** — nunca usar valores hardcoded
-6. **Fontes de documentação DEVEM ser configuradas** para cada tecnologia da stack com versão pinada
+1. **Each architectural decision MUST have justification** — never just "because"
+2. **Data model MUST correspond to SRS requirements** — use reference matrix
+3. **Endpoints MUST cover all functional requirements** from the SRS
+4. **Components MUST be granular** — never a monolithic component
+5. **Design tokens MUST be defined** — never use hardcoded values
+6. **Documentation sources MUST be configured** for each technology in the stack with pinned version