sdd-toolkit 1.6.0 → 1.9.0

package/README.pt.md

@@ -1,135 +1,334 @@
-# sdd-toolkit (CLI de Especificação Universal)
-
-CLI tool para configurar automaticamente o ambiente de desenvolvimento e instalar agentes de IA (Auditor, Coder, etc.) para várias ferramentas modernas de IA.
-
-## Visão Geral
-
-**sdd-toolkit** é um "Gerenciador de Pacotes de Agentes de IA". Ele define uma equipe padrão de Desenvolvedores de IA e os instala diretamente no contexto de sua assistente de codificação de IA favorita (como Gemini, Roo Code, Kilo Code, OpenCode).
-
-A ideia principal é parar de criar prompts do zero e instalar um workflow comprovado e estruturado.
-
-## 🚀 Recursos Principais
-
-### 1. Workflow Inteligente e Ágil
-- **Fluxo Híbrido:** Suporta planejamento "Waterfall" (para novos projetos) e execução "Agile" (para hotfixes).
-- **Contexto Inteligente:** Os agentes escaneiam automaticamente seu `package.json`, `go.mod`, ou `requirements.txt` para entender sua stack. Não mais explicar "Eu uso React" toda vez.
-- **Memória Unificada:** Todo contexto é armazenado em uma pasta oculta `.sdd-toolkit/`, mantendo sua raiz limpa.
-
-### 2. "Comandos de Potência"
-Os agentes vêm equipados com modos de execução especiais acionados por comandos:
-- **`/sdd`**: Acesso a ajuda e lista de todos os agentes disponíveis.
-- **`/flow:debug`**: Cole um log de erro e o Coder entra no "Modo Cirúrgico" para corrigir imediatamente.
-- **`/flow:tdd`**: Força o ciclo Red-Green-Refactor para código de alta qualidade.
-- **`/flow:refactor`**: Aplica princípios de Clean Code a um arquivo existente.
-- **`/flow:gen-tests`**: Gera automaticamente testes unitários para seu código.
-- **`/flow:security`**: Escaneia seu código/plano em busca de vulnerabilidades (OWASP).
-- **`/flow:sync`**: Atualiza a documentação (`project.md`) para corresponder ao código real (Engenharia Reversa).
+# sdd-toolkit (CLI de Especificação Universal)
+
+![npm version](https://img.shields.io/npm/v/sdd-toolkit)
+![License: MIT](https://img.shields.io/npm/l/sdd-toolkit)
+![Downloads](https://img.shields.io/npm/dm/sdd-toolkit)
+
+CLI tool para configurar automaticamente o ambiente de desenvolvimento e instalar agentes de IA (Auditor, Coder, etc.) para várias ferramentas modernas de IA.
 
-### 3. Instalação de Agentes de IA
-Lê definições agnósticas (YAML) e as converte para formatos específicos:
+## Visão Geral
+
+**sdd-toolkit** é um "Gerenciador de Pacotes de Agentes de IA". Ele define uma equipe padrão de Desenvolvedores de IA e os instala diretamente no contexto de sua assistente de codificação de IA favorita (como Gemini, Roo Code, Kilo Code, OpenCode).
+
+A ideia principal é parar de criar prompts do zero e instalar um workflow comprovado e estruturado.
+
+## 📑 Índice
+
+- [Visão Geral](#visão-geral)
+- [Recursos Principais](#-recursos-principais)
+- [A Equipe](#-a-equipe-funções-dos-agentes)
+- [Instalação e Uso](#instalação-e-uso)
+- [Como Funciona](#como-funciona)
+- [Fluxo de Desenvolvimento](#fluxo-de-desenvolvimento)
+- [Comandos nas Ferramentas de IA](#comandos-nas-ferramentas-de-ia)
+- [Estrutura de Arquivos Gerados](#estrutura-de-arquivos-gerados)
+- [Exemplos de Uso](#exemplos-de-uso)
+- [Solução de Problemas](#solução-de-problemas)
+- [Perguntas Frequentes](#-perguntas-frequentes)
+- [Estrutura do Projeto](#estrutura-do-projeto)
+- [Licença](#licença)
+
+## 🚀 Recursos Principais
+
+### 1. Workflow Inteligente e Ágil
+- **Fluxo Híbrido:** Suporta planejamento "Waterfall" (para novos projetos) e execução "Agile" (para hotfixes).
+- **Contexto Inteligente:** Os agentes escaneiam automaticamente seu `package.json`, `go.mod`, ou `requirements.txt` para entender sua stack. Não mais explicar "Eu uso React" toda vez.
+- **Memória Unificada:** Todo contexto é armazenado em uma pasta oculta `.sdd-toolkit/`, mantendo sua raiz limpa.
+
+### 2. Suporte Multi-Idiomas
+O toolkit suporta Inglês, Português (Brasil) e Espanhol. Os agentes adaptam automaticamente suas respostas ao idioma preferido.
+
+### 3. Instalação de Agentes de IA
+Lê definições agnósticas (YAML) e as converte para formatos específicos:
 - **Gemini CLI:** Gera arquivos de configuração `.toml`.
--   **Roo Code / Cline:** Gera modos customizados (`_custom_modes.json`) e regras de contexto em `.roo/` ou `.cline/`.
--   **GitHub Copilot:** Gera instruções em `.github/copilot-instructions.md` e agentes em `.github/agents/`.
--   **Cursor:** Gera regras em `.cursor/rules/*.mdc`.
--   **Windsurf:** Gera regras em `.windsurfrules`.
--   **Trae:** Gera instruções em `.trae/instructions.md`.
--   **OpenCode:** Gera agentes em `.opencode/`.
--   **Kilo Code:** Gera prompts Markdown (`.kilo/prompts/*.md`).
+-   **Roo Code:** Gera agentes em `.roo/commands/*.md`.
+-   **Cline:** Gera modos customizados (`_custom_modes.json`) e regras de contexto em `.cline/`.
+-   **GitHub Copilot:** Gera instruções em `.github/prompts.md` e agentes em `.github/prompts/*.md`.
+-   **Cursor:** Gera regras em `.cursor/commands/*.mdc`.
+-   **Windsurf:** Gera workflows em `.windsurf/workflows/*.md`.
+-   **Trae:** Gera instruções em `.trae/instructions.md`.
+-   **OpenCode:** Gera agentes em `.opencode/commands/*.md`.
+-   **Kilo Code:** Gera prompts Markdown (`.kilocode/workflows/*.md`).
 
 ## 👥 A Equipe (Funções dos Agentes)
 
 O sistema instala uma equipe de agentes especializados:
 
-### 🏗️ Agentes Estratégicos
-- **@Arquitetos de Projeto:** Define o escopo e princípios.
-- **@Engenheiros de Requisitos:** Define a stack técnica (Auto-detectada).
-- **@Gerenciadores de Marcos:** Cria o roadmap.
-
-### ⚡ Agentes de Execução
-- **@Planejadores de Tarefas:** Quebra marcos em tarefas atômicas.
-- **@Gerenciadores de Recursos:** O ponto de entrada ágil. Trata solicitações como "Adicionar Login Google" e decide o melhor caminho (Hotfix vs Milestone).
-- **@Codificadores:** O desenvolvedor sênior. Suporta modos TDD, Debug, Refactor e Geração de Testes.
-
-### 🛡️ Agentes de Qualidade
-- **@Auditores:** Verifica consistência entre requisitos e tarefas.
-- **@QA Engineers:** Revisa código contra a especificação.
-- **@DevOps Engineers:** Trata Docker, CI/CD e Configs.
-- **@Gerenciadores de Releases:** Consolida logs e gerencia o changelog.
-
-## Instalação e Uso
-
-Você pode executar a ferramenta diretamente via `npx` sem instalação prévia:
-
-```bash
-npx sdd-toolkit
-```
+### 🏗️ Agentes Estratégicos
+- **@Arquiteto de Projeto:** Define o escopo e princípios.
+- **@Engenheiro de Requisitos:** Define a stack técnica (Auto-detectada).
 
-Ou instalar globalmente:
+### ⚡ Agentes de Execução
+- **@Gerente de Features:** Gerencia features, marcos e tarefas.
+- **@Codificador:** O desenvolvedor sênior. Implementa código seguindo princípios SOLID.
+
+### 🛡️ Agentes de Qualidade
+- **@QA Engineer:** Revisa código contra a especificação.
+- **@Gerente de Releases:** Consolida logs e gerencia o changelog.
 
-```bash
-npm install -g sdd-toolkit
-sdd-toolkit
-```
+## Instalação e Uso
+
+### Configuração Inicial
+Execute a ferramenta diretamente via `npx` sem instalação prévia:
+
+```bash
+npx sdd-toolkit
+```
+
+### Ver o Dashboard do Projeto
+Verifique o status atual do seu projeto:
+
+```bash
+sdd-toolkit view
+```
+
+### Atualizar Instalação Existente
+Atualize os agentes instalados sem reconfiguração:
+
+```bash
+sdd-toolkit upgrade
+```
+
+### Instalação Global
+Ou instale globalmente:
+
+```bash
+npm install -g sdd-toolkit
+sdd-toolkit
+```
 
 ## Como Funciona
 
 1.  **Inicialização:** O assistente detecta suas ferramentas e configura a pasta de contexto oculta `.sdd-toolkit/`.
-2.  **Construção de Agentes:** Lê os "Protocolos de Pensamento" (YAML) e os compila no formato nativo da sua ferramenta de IA.
-3.  **Execução:** Você interage com os agentes usando comandos simplificados (ex.: `/project`, `/coder`) ou os novos gatilhos `/flow:*`.
-
-## Fluxo Completo de Desenvolvimento
-
-O sdd-toolkit implementa um **fluxo de trabalho híbrido unificado** que se adapta às suas necessidades, combinando planejamento estruturado para novos projetos com execução ágil para correções rápidas. Ele garante rastreabilidade, justificativa e qualidade através de colaboração IA-humana.
-
-### Visão Geral do Fluxo Híbrido Unificado
-
-- **Iniciação Inteligente:** Comece com `/dev:start "Descrição"` para roteamento inteligente. O sistema verifica docs existentes e decide entre caminhos quick ou estruturados.
-- **Planejamento Condicional:** Se necessário, escala para planejamento completo (Arquitetos de Projeto → Engenheiros de Requisitos → Gerenciadores de Marcos → Planejadores de Tarefas).
-- **Execução Padronizada:** Codificadores implementam tarefas com logs, seguidos de validação unificada (QA e Auditores).
-- **Finalização:** Gerenciadores de Releases consolidam em changelog com confirmação humana.
-
-### Passos Detalhados do Fluxo
-
-#### 1. Iniciação (Inteligente)
-- Comando: `/start "Construir um sistema de login"`
-- Ação: Arquitetos de Projeto verificam `.sdd-toolkit/project.md` existente.
-  - Se nenhum: Entra no modo de entrevista para o básico.
-  - Se existe: Confirma prosseguir ou reiniciar.
-- Saída: Atualiza `project.md` com notas híbridas (ex.: pontos de aprovação).
-
-#### 2. Planejamento (Condicional)
-- Se hotfix: Gerenciadores de Recursos roteia diretamente para criação de tarefas.
-- Se projeto: Gerenciadores de Marcos gera roadmap com aprovação humana.
-- Comandos: `/requirements`, `/milestone`, `/tasks`.
-- Saída: `requirements.md`, `milestones.md`, `task.md`.
-
-#### 3. Execução (Padronizada)
-- Comando: `/coder`
-- Ação: Codificador lê contexto, implementa, registra logs em `executions/`, marca tarefas como concluídas.
-- Modos: `/flow:debug`, `/flow:refactor`, `/flow:tdd`, etc.
-- Saída: Mudanças no código + logs de execução.
-
-#### 4. Validação (Unificada)
-- Comando: `/review`
-- Ação: QA revisa código, Auditores verificam consistência. Pausa para entrada humana em ambiguidades.
-- Saída: Relatórios de revisão em `logs/reviews/`.
-
-#### 5. Finalização (Com Confirmação)
-- Comando: `/release` ou implícito após aprovação.
-- Ação: Gerenciadores de Releases atualiza `changelog.md` e arquiva logs após confirmação humana.
-- Saída: Changelog limpo e logs arquivados.
-
-### Interações dos Agentes
-Agentes compartilham contexto via arquivos `.sdd-toolkit/`, garantindo sem alucinações. Comandos de potência habilitam modos especializados. O fluxo promove justificativa (ex.: "Por que essa decisão?") e handoffs IA-humana para confiabilidade.
-
-Para exemplos, veja os guias de workflow gerados em `.sdd-toolkit/`.
+2.  **Construção de Agentes:** Lê as definições dos agentes (YAML) e as compila no formato nativo da sua ferramenta de IA.
+3.  **Execução:** Interaja com os agentes usando comandos simplificados (ex.: `/project`, `/coder`, `/feature`).
 
-## Estrutura do Projeto
-
--   `src/`: Código fonte da CLI.
--   `definitions/`: Definições YAML de agentes (agnósticas).
--   `templates/`: Modelos de documentação.
-
-## Licença
-
-MIT
+## Fluxo de Desenvolvimento
+
+O sdd-toolkit fornece um fluxo de trabalho estruturado com agentes especializados:
+
+### 1. Definir Projeto
+- Comando: `/project`
+- Cria `.sdd-toolkit/project.md` com o escopo e princípios do projeto.
+
+### 2. Definir Requisitos
+- Comando: `/requirements`
+- Analisa sua stack e cria `.sdd-toolkit/requirements.md`.
+
+### 3. Planejar Features
+- Comando: `/feature`
+- Cria `.sdd-toolkit/features/[nome].md` com marcos e tarefas.
+
+### 4. Implementar Código
+- Comando: `/coder [task-id]`
+- Implementa tarefas do plano de features e registra o trabalho.
+
+### 5. Revisar Código
+- Comando: `/review [task-id]`
+- QA Engineer revisa a implementação contra os requisitos.
+
+### 6. Release
+- Comando: `/log` ou `/dev:release`
+- Consolida logs no changelog e arquiva o trabalho concluído.
+
+## Comandos nas Ferramentas de IA
+
+Uma vez que os agentes estejam instalados, use estes comandos no seu assistente de codificação de IA:
+
+### Acessar Agentes
+- **`/sdd`** - Exibe os agentes disponíveis e ajuda
+- **`/sdd.project`** - Ativa o Arquiteto de Projeto
+- **`/sdd.requirements`** - Ativa o Engenheiro de Requisitos
+- **`/sdd.feature`** - Ativa o Gerente de Features
+- **`/sdd.coder`** - Ativa o Codificador
+- **`/sdd.review`** - Ativa o QA Engineer
+- **`/sdd.log`** - Ativa o Gerente de Releases
+
+### Comandos Especiais
+- **`/dev:review [Task_ID]`** - Aciona revisão de código para uma tarefa específica
+- **`/dev:release`** - Consolida logs e cria changelog
+
+## Estrutura de Arquivos Gerados
+
+Após executar `sdd-toolkit`, a seguinte estrutura é criada em seu projeto:
+
+```
+.sdd-toolkit/
+├── project.md              # Escopo e princípios do projeto
+├── requirements.md         # Requisitos técnicos e stack
+├── guidelines.md           # Diretrizes de desenvolvimento do projeto
+├── milestones.md           # Roadmap de desenvolvimento
+├── task.md                # Backlog de execução de tarefas
+├── features/               # Especificações individuais de features
+│   └── [feature-name].md
+├── logs/
+│   ├── executions/         # Logs de execução de tarefas
+│   ├── reviews/           # Relatórios de revisão de código
+│   └── archive/          # Trabalho concluído arquivado
+└── agents/               # Definições personalizadas de agentes (overrides opcionais)
+```
+
+## Estrutura do Projeto
+
+- `definitions/`: Definições YAML de agentes
+- `templates/`: Modelos de documentação
+- `src/`: Código fonte da CLI
+
+## Exemplos de Uso
+
+### Fluxo Completo: Nova Feature
+
+1. **Definir projeto:**
+    ```
+   /sdd.project
+    ```
+   Cria `.sdd-toolkit/project.md` com escopo e princípios.
+
+2. **Definir requisitos técnicos:**
+    ```
+   /sdd.requirements
+    ```
+   Analisa seu `package.json`/`go.mod` e cria `.sdd-toolkit/requirements.md`.
+
+3. **Planejar uma nova feature:**
+    ```
+   /sdd.feature
+    ```
+   Especifique sua feature (ex: "Adicionar autenticação de usuário"). Cria `.sdd-toolkit/features/auth.md`.
+
+4. **Implementar tarefas:**
+    ```
+   /sdd.coder MT01-task-1
+    ```
+   Codificador implementa a tarefa seguindo princípios SOLID e registra o trabalho.
+
+5. **Revisar implementação:**
+    ```
+   /sdd.review MT01-task-1
+    ```
+   QA Engineer valida a implementação contra os requisitos.
+
+6. **Release das mudanças:**
+    ```
+   /sdd.log
+    ```
+   Consolida logs no changelog e arquiva o trabalho concluído.
+
+### Correção Rápida de Bug
+
+1. **Usar Codificador diretamente:**
+    ```
+   /sdd.coder fixar-bug-login
+    ```
+   Codificador analisa, corrige e documenta a mudança.
+
+2. **Revisar correção:**
+    ```
+   /sdd.review fixar-bug-login
+    ```
+   Valida que a correção atende os requisitos.
+
+## Licença
+
+MIT
+
+## ❓ Solução de Problemas
+
+### Agentes não aparecem na sua ferramenta de IA
+
+**Problema:** Depois de executar `sdd-toolkit`, os agentes não aparecem no seu assistente de codificação de IA.
+
+**Soluções:**
+- **Roo Code/Cline:** Verifique se você configurou os Modos Personalizados nas configurações. Veja a mensagem de aviso após a instalação.
+- **Cursor:** Reinicie a IDE após a instalação.
+- **OpenCode:** Atualize o painel de comandos.
+- **Gemini CLI:** Verifique se a pasta `.gemini/commands/dev/` existe com arquivos `.toml`.
+
+### Erro de permissão ao executar sdd-toolkit
+
+**Problema:** Recebendo "Permissão negada" ou erro EACCES ao executar `npx sdd-toolkit`.
+
+**Soluções:**
+- **Opção 1:** Execute com permissões elevadas (não recomendado):
+  ```bash
+  sudo npx sdd-toolkit
+  ```
+- **Opção 2:** Corrija permissões do npm:
+  ```bash
+  npm config set prefix ~/.npm-global
+  export PATH=~/.npm-global/bin:$PATH
+  ```
+- **Opção 3:** Instale globalmente com sudo:
+  ```bash
+  sudo npm install -g sdd-toolkit
+  ```
+
+### Agentes respondendo no idioma errado
+
+**Problema:** Os agentes não estão respondendo no seu idioma preferido.
+
+**Solução:**
+- Execute `sdd-toolkit` novamente e certifique-se de selecionar o idioma correto durante a configuração (Inglês, Português ou Espanhol).
+- Ou edite manualmente o `LANGUAGE_RULES` nos arquivos dos seus agentes.
+
+### Perfil de stack não aplicando regras
+
+**Problema:** As regras do perfil de stack selecionado não estão sendo usadas pelos agentes.
+
+**Solução:**
+- O perfil de stack é aplicado apenas durante a instalação inicial ou upgrade. Execute:
+  ```bash
+  sdd-toolkit upgrade
+  ```
+  Certifique-se de selecionar o mesmo perfil de stack novamente.
+
+### Pasta `.sdd-toolkit/` não criada
+
+**Problema:** A estrutura de pastas ocultas não é criada após a instalação.
+
+**Soluções:**
+- Verifique se você está executando o comando a partir do diretório raiz do seu projeto (onde está o `package.json`).
+- Verifique as permissões de escrita no diretório.
+- Verifique mensagens de erro durante a instalação.
+
+## 🔎 Perguntas Frequentes
+
+**P: Posso usar múltiplos assistentes de IA simultaneamente?**
+
+R: Sim! Você pode instalar agentes para múltiplas ferramentas de IA no mesmo projeto. Cada ferramenta tem sua própria estrutura de pastas (`.roo/`, `.cline/`, `.cursor/`, etc.) e podem coexistir sem conflitos.
+
+**P: Como atualizo os agentes após a configuração inicial?**
+
+R: Execute `sdd-toolkit upgrade`. Isso atualizará todos os agentes instalados sem exigir que você reconfigure seu perfil de stack ou regras globais.
+
+**P: Posso personalizar as definições dos agentes?**
+
+R: Sim! Crie arquivos YAML personalizados na pasta `.sdd-toolkit/agents/`. O toolkit usará suas versões personalizadas em vez das padrão. Você pode copiar e modificar as definições padrão da pasta `definitions/` no toolkit.
+
+**P: O que acontece se eu executar `sdd-toolkit` múltiplas vezes?**
+
+R: A ferramenta é idempotente - executá-la novamente apenas atualizará ou regerará arquivos ausentes sem duplicar configurações existentes. Seus documentos de projeto existentes em `.sdd-toolkit/` serão preservados.
+
+**P: Posso usar isso com projetos que já têm código existente?**
+
+R: Sim! O agente "Engenheiro de Requisitos" pode analisar seu `package.json`, `go.mod` ou `requirements.txt` existente para detectar automaticamente sua stack. O "Arquiteto de Projeto" também pode formalizar projetos existentes em modo "híbrido".
+
+**P: Preciso commitar a pasta `.sdd-toolkit/` no meu repositório?**
+
+R: Sim, é recomendado. A pasta `.sdd-toolkit/` contém a documentação do seu projeto, especificações e configurações dos agentes. Commitá-la garante consistência em toda a equipe e preserva o contexto para sessões futuras.
+
+**P: Como removo o sdd-toolkit do meu projeto?**
+
+R: Simplesmente delete a pasta `.sdd-toolkit/` e quaisquer pastas específicas de ferramentas (`.roo/`, `.cline/`, `.cursor/`, etc.). Esses são todos arquivos gerados e não afetarão seu código fonte.
+
+**P: Minhas mudanças de código são rastreadas pelo sdd-toolkit?**
+
+R: Não, o sdd-toolkit apenas gerencia documentação e configurações de agentes de IA. Ele não rastreia mudanças de código, lê seus arquivos fonte, ou interfere com controle de versão.
+
+**P: Posso adicionar meus próprios perfis de stack?**
+
+R: Atualmente, os perfis de stack são codificados no toolkit. Para adicionar um perfil personalizado, você pode usar o recurso de "Regras Globais" durante a configuração para injetar suas próprias convenções, ou pode fazer um fork do repositório e adicionar seu perfil em `src/lib/profiles.js`.
+
+**P: Isso é adequado para projetos empresariais?**
+
+R: Sim, o sdd-toolkit é desenhado para escalar. A pasta `.sdd-toolkit/` pode ser commitada no seu repositório, garantindo que todos os membros da equipe usem as mesmas configurações de agentes e sigam os mesmos princípios de desenvolvimento definidos em `guidelines.md`.

package/definitions/{project.yaml → sdd-project.yaml}

@@ -5,14 +5,13 @@ systemPrompt: |
   # System Prompt — Project Architect 🏛️
 
   ## Identity
-  You are the **Project Architect** 🏛️, the guardian agent of the macro vision and functional scope. Your responsibility is to ensure the project's conceptual foundation is solid, logical, and free of ambiguities before any technical detailing. You act as a critical consultant, not just a text editor.
+  You are the **Project Architect** 🏛️, guardian agent of the macro vision and functional scope. Your responsibility is to ensure that the project's conceptual foundation is solid, logical, and free of ambiguities before any technical detailing. You act as a critical consultant, not just a text editor.
 
   ## Core Mission
   Define or formalize the **CONCEPTUAL SCOPE**, generating the file `.sdd-toolkit/project.md`. This document is the project's "Constitution": the single source of truth for requirements and implementation.
 
-  ----------
-
   ## Scenarios and Protocols
+
   ### 1️⃣ Scope Creation (Greenfield)
   - **Trigger:** Absence of `project.md`.
   - **Action:** Activate **Mode 1** immediately to extract the essence of the idea.
@@ -26,9 +25,8 @@ systemPrompt: |
   - **Protocol:** Request `tree` and manifest files (`package.json`, `go.mod`, etc.).
   - **Golden Rule:** The **truth of the code** precedes the user's desire. If there is a conflict, document the "Documentation Debt" in the Rationale.
 
-  ----------
-
   ## Modes of Operation
+
   ### Mode 1 — Strategic Interview (Deep Dive)
   If there are gaps, do not generate the file. Ask surgical questions:
   1. **North Star:** What is the user's "Aha! moment"? What defines success?
@@ -39,8 +37,6 @@ systemPrompt: |
   ### Mode 2 — Scope Generation
   Generate the content strictly following the YAML + Markdown structure below.
 
-  ----------
-
   ## Mandatory Structure: `.sdd-toolkit/project.md`
   ```markdown
   ---
@@ -80,7 +76,6 @@ systemPrompt: |
   - **Justifications:** Why this scope design?
   - **Discrepancy Analysis:** (For hybrid flows) What does the code do that the user didn't describe?
   - **Risk Zones:** Nebulous items requiring later technical validation.
-  ---
   ```
 
   ## Execution Rules (Hard Rules)
@@ -90,12 +85,13 @@ systemPrompt: |
 
   ## Closing and Handover Protocol
   After generating the file content, you must finish EXACTLY like this:
-  > "🏛️ **Project scope successfully documented.**
-  > 
+
+  > "🏛️ **Project scope successfully documented.**"
+  >
   > **Next Step:** Save the content above in `.sdd-toolkit/project.md`.
-  > 
+  >
   > **Handover:** The next agent to be triggered is the **Requirements Analyst**. You can use the command below to start the next phase:
-  > 
+  >
   > `> Activate Requirements Analyst: Read .sdd-toolkit/project.md and start detailing User Stories for [Module X].`"
 
 rules:
@@ -106,3 +102,27 @@ rules:
   - "VERIFY: Ensure saved file is always `.sdd-toolkit/project.md`."
   - "**HYBRID INITIATION:** Always check existing documents before starting; require user confirmation to overwrite."
   - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."
+
+  ## Examples
+
+  ### Example 1: Simple New Project
+  **Trigger:** User starts a new greenfield project (e.g., "Build a todo app")
+  **Action:** Ask for project name, scope, and boundaries
+  **Output:** `.sdd-toolkit/project.md` with clear scope including anti-requirements
+
+  ### Example 2: Tech Stack Detection
+  **Trigger:** Existing React project with `package.json`
+  **Action:** Auto-detect React ecosystem, verify Next.js presence
+  **Output:** Stack profile automatically applied in requirements
+
+  ## Troubleshooting
+
+  ### Issue: User provides vague project description
+  **Symptom:** Generated project.md lacks clarity or specific scope
+  **Solution:** Ask focused questions to extract concrete requirements
+  **Prevention:** Use "North Star", "Boundaries", "Ecosystem" questions from Mode 1
+
+  ### Issue: Project scope creep
+  **Symptom:** User keeps adding requirements outside defined boundaries
+  **Solution:** Enforce "Anti-Scope" section; suggest creating new features instead
+  **Prevention:** Quote "What will NOT do in this version" back to user before accepting

package/definitions/sdd.yaml

@@ -8,14 +8,13 @@ systemPrompt: |
   # Core Instructions
   You are the central hub for accessing SDD Toolkit agents. When activated via "/sdd", provide an overview of available agents and how to use them.
 
-  ## Available Agents
-  - **/project**: Project Architect 🏛️ - Defines project scope and vision.
-  - **/requirements**: Requirements Engineer 🔍 - Analyzes stack and technical requirements.
-  - **/tasks**: Task Planner 📋 - Creates detailed task breakdowns and milestones.
-  - **/feature**: Feature Manager ✨ - Manages feature development and integration.
-  - **/coder**: Coder 💻 - Implements code following SOLID principles.
-  - **/review**: Auditor 👀 - Reviews and validates code quality.
-  - **/log**: Logger 📝 - Maintains execution logs and documentation.
+## Available Agents
+- **/sdd.project**: Project Architect 🏛️ - Defines project scope and vision.
+- **/sdd.requirements**: Requirements Engineer 🔍 - Analyzes stack and technical requirements.
+- **/sdd.feature**: Feature Manager ✨ - Manages features, milestones, and tasks.
+- **/sdd.coder**: Coder 💻 - Implements code following SOLID principles.
+- **/sdd.review**: QA Engineer 🔍 - Reviews and validates code quality.
+- **/sdd.log**: Release Manager 📦 - Consolidates logs and manages changelog.
 
   ## Usage
   - Type "/sdd" to see this help.

package/package.json

@@ -1,41 +1,42 @@
-{
-    "name": "sdd-toolkit",
-    "version": "1.6.0",
-    "description": "Instalador automático dos agentes de desenvolvimento",
-    "main": "src/index.js",
-    "bin": {
-        "sdd-toolkit": "./src/index.js"
-    },
-    "scripts": {
-        "start": "node src/index.js",
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "dependencies": {
-        "@clack/prompts": "^0.7.0",
-        "js-yaml": "^4.1.0",
-        "picocolors": "^1.0.0",
-        "zod": "^4.2.1"
-    },
-    "author": "",
-    "license": "MIT",
-    "files": [
-        "src",
-        "definitions",
-        "templates",
-        "README.md"
-    ],
-    "keywords": [
-        "ai",
-        "agents",
-        "cli",
-        "dev-tools",
-        "llm",
-        "gemini",
-        "roo-code",
-        "cline"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/filipeoliveira93/agents.dev"
-    }
-}
+{
+    "name": "sdd-toolkit",
+    "version": "1.9.0",
+    "description": "Instalador automatico dos agentes de desenvolvimento",
+    "main": "src/index.js",
+    "bin": {
+        "sdd-toolkit": "./src/index.js"
+    },
+    "scripts": {
+        "start": "node src/index.js",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "dependencies": {
+        "@clack/prompts": "^0.7.0",
+        "js-yaml": "^4.1.0",
+        "picocolors": "^1.0.0",
+        "zod": "^4.2.1"
+    },
+    "author": "",
+    "license": "MIT",
+    "files": [
+        "src",
+        "definitions",
+        "templates",
+        "README.md",
+        "README.pt.md"
+    ],
+    "keywords": [
+        "ai",
+        "agents",
+        "cli",
+        "dev-tools",
+        "llm",
+        "gemini",
+        "roo-code",
+        "cline"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/filipeoliveira93/agents.dev"
+    }
+}