sdd-toolkit 1.6.0 → 1.8.0

package/README.md

@@ -1,5 +1,9 @@
 # sdd-toolkit (Universal Spec CLI)
 
+![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 to automatically set up the development environment and install AI agents (Auditor, Coder, etc.) for various modern AI tools.
 
 ## Overview
@@ -8,6 +12,22 @@ CLI tool to automatically set up the development environment and install AI agen
 
 The main idea is to stop creating prompts from scratch and install a proven, structured workflow.
 
+## 📑 Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#-key-features)
+- [The Squad](#-the-squad-agent-roles)
+- [Installation and Usage](#installation-and-usage)
+- [How it Works](#how-it-works)
+- [Development Workflow](#development-workflow)
+- [AI Tool Commands](#ai-tool-commands)
+- [Generated Files Structure](#generated-files-structure)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#-frequently-asked-questions)
+- [Project Structure](#project-structure)
+- [License](#license)
+
 ## 🚀 Key Features
 
 ### 1. Smart & Agile Workflow
@@ -15,26 +35,20 @@ The main idea is to stop creating prompts from scratch and install a proven, str
 - **Smart Context:** Agents automatically scan your `package.json`, `go.mod`, or `requirements.txt` to understand your stack. No more explaining "I use React" every time.
 - **Unified Memory:** All context is stored in a hidden `.sdd-toolkit/` folder, keeping your root directory clean.
 
-### 2. "Power Commands"
-Agents come equipped with special execution modes triggered by commands:
-- **`/sdd`**: Access help and list all available agents.
-- **`/flow:debug`**: Paste an error log, and the Coder enters "Surgical Mode" to fix it immediately.
-- **`/flow:tdd`**: Forces the Red-Green-Refactor cycle for high-quality code.
-- **`/flow:refactor`**: Applies Clean Code principles to an existing file.
-- **`/flow:gen-tests`**: Automatically generates unit tests for your code.
-- **`/flow:security`**: Scans your code/plan for vulnerabilities (OWASP).
-- **`/flow:sync`**: Updates the documentation (`project.md`) to match the actual code (Reverse Engineering).
+### 2. Multi-Language Support
+The toolkit supports English, Portuguese (Brazil), and Spanish. Agents automatically adapt their responses to your preferred language.
 
 ### 3. AI Agent Installation
 Reads agnostic definitions (YAML) and converts them to specific formats:
 - **Gemini CLI:** Generates `.toml` configuration files.
--   **Roo Code / Cline:** Generates custom modes (`_custom_modes.json`) and context rules in `.roo/` or `.cline/`.
--   **GitHub Copilot:** Generates instructions in `.github/copilot-instructions.md` and agents in `.github/agents/`.
--   **Cursor:** Generates rules in `.cursor/rules/*.mdc`.
--   **Windsurf:** Generates rules in `.windsurfrules`.
+-   **Roo Code:** Generates agents in `.roo/commands/*.md`.
+-   **Cline:** Generates custom modes (`_custom_modes.json`) and context rules in `.cline/`.
+-   **GitHub Copilot:** Generates instructions in `.github/prompts.md` and agents in `.github/prompts/*.md`.
+-   **Cursor:** Generates rules in `.cursor/commands/*.mdc`.
+-   **Windsurf:** Generates workflows in `.windsurf/workflows/*.md`.
 -   **Trae:** Generates instructions in `.trae/instructions.md`.
--   **OpenCode:** Generates agents in `.opencode/`.
--   **Kilo Code:** Generates Markdown prompts (`.kilo/prompts/*.md`).
+-   **OpenCode:** Generates agents in `.opencode/commands/*.md`.
+-   **Kilo Code:** Generates Markdown prompts (`.kilocode/workflows/*.md`).
 
 ## 👥 The Squad (Agent Roles)
 
@@ -43,27 +57,40 @@ The system installs a team of specialized agents:
 ### 🏗️ Strategic Agents
 - **@Project Architect:** Defines the scope and principles.
 - **@Requirements Engineer:** Defines the tech stack (Auto-detected).
-- **@Milestone Manager:** Creates the roadmap.
 
 ### ⚡ Execution Agents
-- **@Task Planner:** Breaks down milestones into atomic tasks.
-- **@Feature Manager:** The agile entry point. Handles requests like "Add Google Login" and decides the best path (Hotfix vs Milestone).
-- **@Coder:** The senior developer. Supports TDD, Debug, Refactor, and Test Generation modes.
+- **@Feature Manager:** Manages features, milestones, and tasks.
+- **@Coder:** The senior developer. Implements code following SOLID principles.
 
 ### 🛡️ Quality Agents
-- **@QA Engineer:** Reviews code against the spec (Auditor role).
-- **@DevOps Engineer:** Handles Docker, CI/CD, and Configs.
+- **@QA Engineer:** Reviews code against the spec.
 - **@Release Manager:** Consolidates logs and manages the changelog.
 - **@SDD Helper:** Provides access to all agents and help.
 
 ## Installation and Usage
 
-You can run the tool directly via `npx` without prior installation:
+### Initial Setup
+Run the tool directly via `npx` without prior installation:
 
 ```bash
 npx sdd-toolkit
 ```
 
+### View Project Dashboard
+Check your current project status:
+
+```bash
+sdd-toolkit view
+```
+
+### Upgrade Existing Installation
+Update installed agents without reconfiguration:
+
+```bash
+sdd-toolkit upgrade
+```
+
+### Global Installation
 Or install globally:
 
 ```bash
@@ -74,61 +101,133 @@ sdd-toolkit
 ## How it Works
 
 1.  **Initialization:** The wizard detects your tools and sets up the hidden `.sdd-toolkit/` context folder.
-2.  **Agent Building:** It reads the "Thinking Protocols" (YAML) and compiles them into your AI tool's native format.
-3.  **Execution:** You interact with the agents using simplified commands (e.g., `/project`, `/coder`) or the new `/flow:*` triggers.
+2.  **Agent Building:** Reads the agent definitions (YAML) and compiles them into your AI tool's native format.
+3.  **Execution:** Interact with agents using simplified commands (e.g., `/project`, `/coder`, `/feature`).
+
+## Development Workflow
+
+The sdd-toolkit provides a structured workflow with specialized agents:
+
+### 1. Define Project
+- Command: `/project`
+- Creates `.sdd-toolkit/project.md` with project scope and principles.
 
-## Complete Development Flow
+### 2. Define Requirements
+- Command: `/requirements`
+- Analyzes your stack and creates `.sdd-toolkit/requirements.md`.
 
-The sdd-toolkit implements a **unified hybrid workflow** that adapts to your needs, combining structured planning for new projects with agile execution for quick fixes. It ensures traceability, justification, and quality through AI-human collaboration.
+### 3. Plan Features
+- Command: `/feature`
+- Creates `.sdd-toolkit/features/[name].md` with milestones and tasks.
 
-### Unified Hybrid Workflow Overview
+### 4. Implement Code
+- Command: `/coder [task-id]`
+- Implements tasks from feature plan and logs work.
 
-- **Adaptive Initiation:** Start with `/start "Descrição"` for intelligent routing. The system checks existing docs and decides between quick or structured paths.
-- **Conditional Planning:** If needed, escalates to full planning (Project Architect → Requirements Engineer → Milestone Manager → Task Planner).
-- **Standardized Execution:** Coders implement tasks with logs, followed by unified validation (QA and Auditor).
-- **Finalization:** Release Manager consolidates into changelog with human confirmation.
+### 5. Review Code
+- Command: `/review [task-id]`
+- QA Engineer reviews implementation against requirements.
 
-### Detailed Flow Steps
+### 6. Release
+- Command: `/log` or `/dev:release`
+- Consolidates logs into changelog and archives completed work.
 
-#### 1. Initiation (Inteligente)
-- Command: `/start "Build a login system"`
-- Action: Project Architect checks for existing `.sdd-toolkit/project.md`.
-  - If none: Enters interview mode for basics.
-  - If exists: Confirms proceed or restart.
-- Output: Updates `project.md` with hybrid notes (e.g., approval points).
+## AI Tool Commands
 
-#### 2. Planning (Condicional)
-- If hotfix: Feature Manager routes directly to task creation.
-- If project: Milestone Manager generates roadmap with human approval.
-- Commands: `/requirements`, `/milestone`, `/tasks`.
-- Output: `requirements.md`, `milestones.md`, `task.md`.
+Once agents are installed, use these commands in your AI coding assistant:
 
-#### 3. Execution (Padronizada)
-- Command: `/coder`
-- Action: Coder reads context, implements, logs in `executions/`, marks tasks as done.
-- Modes: `/flow:debug`, `/flow:refactor`, `/flow:tdd`, etc.
-- Output: Code changes + execution logs.
+### Access Agents
+- **`/sdd`** - Display available agents and help
+- **`/sdd.project`** - Activate Project Architect
+- **`/sdd.requirements`** - Activate Requirements Engineer
+- **`/sdd.feature`** - Activate Feature Manager
+- **`/sdd.coder`** - Activate Coder
+- **`/sdd.review`** - Activate QA Engineer
+- **`/sdd.log`** - Activate Release Manager
 
-#### 4. Validation (Unificada)
-- Commands: `/review`
-- Action: QA Engineer reviews code against the spec. Pauses for human input on ambiguities.
-- Output: Review reports in `logs/reviews/`.
+### Special Commands
+- **`/dev:review [Task_ID]`** - Trigger code review for a specific task
+- **`/dev:release`** - Consolidate logs and create changelog
 
-#### 5. Finalization (Com Confirmação)
-- Command: `/release` or implicit after approval.
-- Action: Release Manager updates `changelog.md` and archives logs after human confirmation.
-- Output: Clean changelog and archived logs.
+## Generated Files Structure
 
-### Agent Interactions
-Agents share context via `.sdd-toolkit/` files, ensuring no hallucinations. Power commands enable specialized modes. The flow promotes justification (e.g., "Why this decision?") and human-AI handoffs for reliability.
+After running `sdd-toolkit`, the following structure is created in your project:
 
-For examples, see the workflow guides generated in `.sdd-toolkit/`.
+```
+.sdd-toolkit/
+├── project.md              # Project scope and principles
+├── requirements.md         # Technical requirements and stack
+├── guidelines.md           # Project development guidelines
+├── milestones.md           # Development roadmap
+├── task.md                # Task execution backlog
+├── features/               # Individual feature specifications
+│   └── [feature-name].md
+├── logs/
+│   ├── executions/         # Task execution logs
+│   ├── reviews/           # Code review reports
+│   └── archive/          # Archived completed work
+└── agents/               # Custom agent definitions (optional overrides)
+```
 
 ## Project Structure
 
--   `src/`: CLI source code.
--   `definitions/`: YAML agent definitions (agnostic).
--   `templates/`: Documentation templates.
+- `definitions/`: YAML agent definitions
+- `templates/`: Documentation templates
+- `src/`: CLI source code
+
+## Usage Examples
+
+### Complete Workflow: New Feature
+
+1. **Define project:**
+   ```
+   /sdd.project
+   ```
+   Creates `.sdd-toolkit/project.md` with scope and principles.
+
+2. **Define technical requirements:**
+   ```
+   /sdd.requirements
+   ```
+   Analyzes your `package.json`/`go.mod` and creates `.sdd-toolkit/requirements.md`.
+
+3. **Plan a new feature:**
+   ```
+   /sdd.feature
+   ```
+   Specify your feature (e.g., "Add user authentication"). Creates `.sdd-toolkit/features/auth.md`.
+
+4. **Implement tasks:**
+   ```
+   /sdd.coder MT01-task-1
+   ```
+   Coder implements task following SOLID principles and logs work.
+
+5. **Review implementation:**
+   ```
+   /sdd.review MT01-task-1
+   ```
+   QA Engineer validates implementation against requirements.
+
+6. **Release changes:**
+   ```
+   /sdd.log
+   ```
+   Consolidates logs into changelog and archives completed work.
+
+### Quick Bug Fix
+
+1. **Use Coder directly:**
+    ```
+   /sdd.coder fix-login-bug
+    ```
+   Coder analyzes, fixes, and documents change.
+
+2. **Review fix:**
+    ```
+   /sdd.review fix-login-bug
+    ```
+   Validates that fix meets requirements.
 
 ## License
 
@@ -137,3 +236,104 @@ MIT
 ---
 
 **Nota:** Uma versão em português deste README está disponível em [README.pt.md](README.pt.md).
+
+## Troubleshooting
+
+### Agents not appearing in your AI tool
+
+**Problem:** After running `sdd-toolkit`, agents don't appear in your AI coding assistant.
+
+**Solutions:**
+- **Roo Code/Cline:** Check if you've configured Custom Modes in your settings. See the warning message after installation.
+- **Cursor:** Restart the IDE after installation.
+- **OpenCode:** Refresh the command palette.
+- **Gemini CLI:** Verify `.gemini/commands/dev/` folder exists with `.toml` files.
+
+### Permission denied when running sdd-toolkit
+
+**Problem:** Getting "Permission denied" or EACCES error when running `npx sdd-toolkit`.
+
+**Solutions:**
+- **Option 1:** Run with elevated permissions (not recommended):
+  ```bash
+  sudo npx sdd-toolkit
+  ```
+- **Option 2:** Fix npm permissions:
+  ```bash
+  npm config set prefix ~/.npm-global
+  export PATH=~/.npm-global/bin:$PATH
+  ```
+- **Option 3:** Install globally with sudo:
+  ```bash
+  sudo npm install -g sdd-toolkit
+  ```
+
+### Agents responding in wrong language
+
+**Problem:** Agents are not responding in your preferred language.
+
+**Solution:**
+- Re-run `sdd-toolkit` and ensure you select the correct language during setup (English, Portuguese, or Spanish).
+- Or manually edit the `LANGUAGE_RULES` in your agent files.
+
+### Stack profile not applying rules
+
+**Problem:** Selected stack profile rules are not being used by agents.
+
+**Solution:**
+- The stack profile is only applied during initial installation or upgrade. Run:
+  ```bash
+  sdd-toolkit upgrade
+  ```
+  Ensure you select the same stack profile again.
+
+### `.sdd-toolkit/` folder not created
+
+**Problem:** The hidden folder structure is not created after installation.
+
+**Solutions:**
+- Check that you're running the command from your project's root directory (where `package.json` is located).
+- Verify write permissions in the directory.
+- Check for error messages during installation.
+
+## ❓ Frequently Asked Questions
+
+**Q: Can I use multiple AI assistants simultaneously?**
+
+A: Yes! You can install agents for multiple AI tools in the same project. Each tool has its own folder structure (`.roo/`, `.cline/`, `.cursor/`, etc.) and they can coexist without conflicts.
+
+**Q: How do I update agents after initial setup?**
+
+A: Run `sdd-toolkit upgrade`. This will update all installed agents without requiring you to reconfigure your stack profile or global rules.
+
+**Q: Can I customize agent definitions?**
+
+A: Yes! Create custom YAML files in `.sdd-toolkit/agents/` folder. The toolkit will use your custom versions instead of the default ones. You can copy and modify the default definitions from the `definitions/` folder in the toolkit.
+
+**Q: What happens if I run `sdd-toolkit` multiple times?**
+
+A: The tool is idempotent - running it again will only update or regenerate missing files without duplicating existing configurations. Your existing project docs in `.sdd-toolkit/` will be preserved.
+
+**Q: Can I use this with projects that already have existing code?**
+
+A: Yes! The "Requirements Engineer" agent can analyze your existing `package.json`, `go.mod`, or `requirements.txt` to auto-detect your stack. The "Project Architect" can also formalize existing projects in "hybrid" mode.
+
+**Q: Do I need to commit `.sdd-toolkit/` to my repository?**
+
+A: Yes, it's recommended. The `.sdd-toolkit/` folder contains your project documentation, specifications, and agent configurations. Committing them ensures consistency across your team and preserves context for future sessions.
+
+**Q: How do I remove sdd-toolkit from my project?**
+
+A: Simply delete the `.sdd-toolkit/` folder and any tool-specific folders (`.roo/`, `.cline/`, `.cursor/`, etc.). These are all generated files and won't affect your source code.
+
+**Q: Are my code changes tracked by sdd-toolkit?**
+
+A: No, sdd-toolkit only manages documentation and AI agent configurations. It does not track code changes, read your source files, or interfere with version control.
+
+**Q: Can I add my own stack profiles?**
+
+A: Currently, stack profiles are hardcoded in the toolkit. To add a custom profile, you can use the "Global Rules" feature during setup to inject your own conventions, or you can fork the repository and add your profile to `src/lib/profiles.js`.
+
+**Q: Is this suitable for enterprise projects?**
+
+A: Yes, sdd-toolkit is designed to scale. The `.sdd-toolkit/` folder can be committed to your repository, ensuring all team members use the same agent configurations and follow the same development principles defined in `guidelines.md`.

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/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.8.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"
+    }
+}

package/src/index.js

@@ -71,8 +71,9 @@ async function main() {
         if (fs.existsSync(path.join(process.cwd(), '.windsurf'))) tools.push('windsurf');
         if (fs.existsSync(path.join(process.cwd(), '.claude'))) tools.push('claude');
         if (fs.existsSync(path.join(process.cwd(), '.trae'))) tools.push('trae');
-        if (fs.existsSync(path.join(process.cwd(), '.kilo'))) tools.push('kilo');
-        if (fs.existsSync(path.join(process.cwd(), '.github'))) tools.push('copilot');
+        if (fs.existsSync(path.join(process.cwd(), '.kilocode'))) tools.push('kilo');
+        if (fs.existsSync(path.join(process.cwd(), '.github'))) tools.push('copilot');
+        if (fs.existsSync(path.join(process.cwd(), '.roo'))) tools.push('roo');
         if (fs.existsSync(path.join(process.cwd(), '.opencode'))) tools.push('opencode');
         if (fs.existsSync(path.join(process.cwd(), 'prompts'))) tools.push('web');
 
@@ -135,16 +136,16 @@ async function main() {
         message: t('SETUP.TOOL_SELECT'),
         options: [
             { value: 'gemini', label: t('TOOLS.GEMINI'), hint: '.gemini/commands/dev' },
-            { value: 'roo', label: t('TOOLS.ROO'), hint: '.roo/ & custom_modes.json' },
+            { value: 'roo', label: t('TOOLS.ROO'), hint: '.roo/commands/*.md' },
             { value: 'cline', label: t('TOOLS.CLINE'), hint: '.cline/ & custom_modes.json' },
-            { value: 'cursor', label: t('TOOLS.CURSOR'), hint: '.cursor/rules/*.mdc' },
+            { value: 'cursor', label: t('TOOLS.CURSOR'), hint: '.cursor/commands/*.mdc' },
             { value: 'windsurf', label: t('TOOLS.WINDSURF'), hint: '.windsurf/workflows/*.md' },
-            { value: 'claude', label: 'Claude Code', hint: '.claude/commands/openspec/*.md' },
+            { value: 'claude', label: 'Claude Code', hint: '.claude/commands/agents/*.md' },
             { value: 'trae', label: t('TOOLS.TRAE'), hint: '.trae/instructions.md' },
-            { value: 'kilo', label: t('TOOLS.KILO'), hint: '.kilo/prompts/*.md' },
-            { value: 'copilot', label: t('TOOLS.COPILOT'), hint: '.github/copilot-instructions.md' },
+            { value: 'kilo', label: t('TOOLS.KILO'), hint: '.kilocode/workflows/*.md' },
+            { value: 'copilot', label: t('TOOLS.COPILOT'), hint: '.github/prompts/*.md' },
             { value: 'web', label: t('TOOLS.WEB'), hint: 'prompts/*.txt' },
-            { value: 'opencode', label: t('TOOLS.OPENCODE'), hint: '.opencode/*.md' }
+            { value: 'opencode', label: t('TOOLS.OPENCODE'), hint: '.opencode/commands/*.md' }
         ],
         required: true,
         hint: t('SETUP.TOOL_HINT')
@@ -192,21 +193,17 @@ async function processAgentsInstallation(tools, options) {
                     })
                 );
             },
-            roo: async (validAgents, options) => {
-                const targetDir = path.join(process.cwd(), '.roo');
-                await fsp.mkdir(targetDir, { recursive: true });
-
-                await Promise.all(
-                    validAgents.map((agent) => {
-                        const md = toKiloMarkdown(agent, options);
-                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
-                    })
-                );
-
-                const modes = validAgents.map((agent) => toRooConfig(agent, agent.slug, options));
-                const jsonContent = JSON.stringify({ customModes: modes }, null, 2);
-                await fsp.writeFile(path.join(process.cwd(), 'roo_custom_modes.json'), jsonContent);
-            },
+            roo: async (validAgents, options) => {
+                const targetDir = path.join(process.cwd(), '.roo', 'commands');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(
+                    validAgents.map((agent) => {
+                        const md = toOpenCodeAgent(agent, options);
+                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                    })
+                );
+            },
             cline: async (validAgents, options) => {
                 const targetDir = path.join(process.cwd(), '.cline');
                 await fsp.mkdir(targetDir, { recursive: true });
@@ -233,31 +230,31 @@ async function processAgentsInstallation(tools, options) {
                     })
                 );
             },
-            claude: async (validAgents, options) => {
-                const targetDir = path.join(process.cwd(), '.claude', 'commands', 'openspec');
-                await fsp.mkdir(targetDir, { recursive: true });
-
-                await Promise.all(
-                    validAgents.map((agent) => {
-                        const md = toClaudeCommand(agent, options);
-                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
-                    })
-                );
-            },
-            cursor: async (validAgents, options) => {
-                const rulesDir = path.join(process.cwd(), '.cursor', 'rules');
-                await fsp.mkdir(rulesDir, { recursive: true });
-
-                await Promise.all(
-                    validAgents.map((agent) => {
-                        const mdc = toCursorMDC(agent, options);
-                        return fsp.writeFile(path.join(rulesDir, `${agent.slug}.mdc`), mdc);
-                    })
-                );
-            },
-            kilo: async (validAgents, options) => {
-                const targetDir = path.join(process.cwd(), '.kilo', 'prompts');
-                await fsp.mkdir(targetDir, { recursive: true });
+            claude: async (validAgents, options) => {
+                const targetDir = path.join(process.cwd(), '.claude', 'commands', 'agents');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(
+                    validAgents.map((agent) => {
+                        const md = toClaudeCommand(agent, options);
+                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                    })
+                );
+            },
+            cursor: async (validAgents, options) => {
+                const commandsDir = path.join(process.cwd(), '.cursor', 'commands');
+                await fsp.mkdir(commandsDir, { recursive: true });
+
+                await Promise.all(
+                    validAgents.map((agent) => {
+                        const mdc = toCursorMDC(agent, options);
+                        return fsp.writeFile(path.join(commandsDir, `${agent.slug}.mdc`), mdc);
+                    })
+                );
+            },
+            kilo: async (validAgents, options) => {
+                const targetDir = path.join(process.cwd(), '.kilocode', 'workflows');
+                await fsp.mkdir(targetDir, { recursive: true });
 
                 await Promise.all(
                     validAgents.map((agent) => {
@@ -266,22 +263,22 @@ async function processAgentsInstallation(tools, options) {
                     })
                 );
             },
-            copilot: async (validAgents, options) => {
-                const githubDir = path.join(process.cwd(), '.github');
-                const agentsDir = path.join(githubDir, 'agents');
-                await fsp.mkdir(agentsDir, { recursive: true });
-
-                await Promise.all(
-                    validAgents.map((agent) => {
-                        const md = toCopilotInstructions(agent, options);
-                        return fsp.writeFile(path.join(agentsDir, `${agent.slug}.md`), md);
-                    })
-                );
-
-                const mainAgent = validAgents.find((a) => a.slug.includes('coder')) || validAgents[0];
-                const mainInstructions = toCopilotInstructions(mainAgent, options);
-                await fsp.writeFile(path.join(githubDir, 'copilot-instructions.md'), mainInstructions);
-            },
+            copilot: async (validAgents, options) => {
+                const githubDir = path.join(process.cwd(), '.github');
+                const promptsDir = path.join(githubDir, 'prompts');
+                await fsp.mkdir(promptsDir, { recursive: true });
+
+                await Promise.all(
+                    validAgents.map((agent) => {
+                        const md = toCopilotInstructions(agent, options);
+                        return fsp.writeFile(path.join(promptsDir, `${agent.slug}.md`), md);
+                    })
+                );
+
+                const mainAgent = validAgents.find((a) => a.slug.includes('coder')) || validAgents[0];
+                const mainInstructions = toCopilotInstructions(mainAgent, options);
+                await fsp.writeFile(path.join(githubDir, 'prompts.md'), mainInstructions);
+            },
             trae: async (validAgents, options) => {
                 const traeDir = path.join(process.cwd(), '.trae');
                 await fsp.mkdir(traeDir, { recursive: true });
@@ -301,17 +298,51 @@ async function processAgentsInstallation(tools, options) {
                     })
                 );
             },
-            opencode: async (validAgents, options) => {
-                const targetDir = path.join(process.cwd(), '.opencode', 'agent');
-                await fsp.mkdir(targetDir, { recursive: true });
-
-                await Promise.all(
-                    validAgents.map((agent) => {
-                        const md = toOpenCodeAgent(agent, options);
-                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
-                    })
-                );
-            }
+            opencode: async (validAgents, options) => {
+                const targetDir = path.join(process.cwd(), '.opencode', 'commands');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(
+                    validAgents.map((agent) => {
+                        const md = toOpenCodeAgent(agent, options);
+                        return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                    })
+                );
+
+                // Generate AGENTS.md with interaction rules and agent location
+                const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
+                let agentsMdContent = `# Interaction Rules
+
+- Always respond to the user in the language they initially interact in; if they interact in English, respond in English, if they interact in Portuguese, respond in Portuguese.
+- If possible, display reasoning in the user's language as well.
+- Be didactic when explaining things, focus on providing complete responses and not just summaries.
+- Whenever possible, provide examples to illustrate concepts.
+
+# Allowed Commands
+
+- Never execute rm or rm -rf commands without confirming with the user.
+- Whenever possible, use more specific commands instead of generic ones.
+- Be cautious when using commands that may affect critical systems, such as shutdown or reboot.
+- For commands that may affect files or directories, always confirm with the user before executing.
+- Never execute commands that require administrative privileges (sudo, admin) without explicit permission from the user.
+- Avoid running background processes or daemons unless explicitly requested.
+- Be cautious when using commands that alter network settings, firewall configurations, or external connections.
+- Always quote file paths that contain spaces to avoid interpretation errors.
+- For package installation commands (npm install, pip install, etc.), confirm that the user has control over dependencies and versions.
+- Avoid irreversible git operations (such as force push or reset --hard) without confirmation.
+
+# Agent Location
+
+Custom agents are located in .opencode/commands/`;
+
+                let userRules = '';
+                if (options.globalRules && options.globalRules.trim()) {
+                    userRules = '\n\n# User Specified Rules\n\n' + options.globalRules.split('\n').filter(line => line.trim()).map(line => '- ' + line.trim()).join('\n');
+                }
+                agentsMdContent += userRules;
+
+                await fsp.writeFile(agentsMdPath, agentsMdContent);
+            }
         };
 
         for (const tool of tools) {

package/src/lib/transformers.js

@@ -199,18 +199,18 @@ ${allRules.length > 0 ? '## Guidelines\n' + allRules.map(r => `- ${r}`).join('\n
 `;
 }
 
-/**
- * Converte para Claude Code Command (.claude/commands/openspec/*.md)
- */
-function toClaudeCommand(agent, options = {}) {
-    const languageRule = getLanguageRule(options.locale);
-    const allRules = [languageRule, ...(agent.rules || [])];
-
-    return `--- 
-name: OpenSpec: ${agent.name}
-description: ${agent.description || agent.role}
-category: OpenSpec
----
+/**
+ * Converte para Claude Code Command (.claude/commands/agents/*.md)
+ */
+function toClaudeCommand(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    return `---
+name: Agent: ${agent.name}
+description: ${agent.description || agent.role}
+category: Agents
+---
 # ${agent.name} ${agent.emoji}
 
 Role: ${agent.role}

package/templates/milestones.md

@@ -1,14 +0,0 @@
----
-title: Development Roadmap
-source_spec: .sdd-toolkit/project.md
-last_updated: 
-status: 
----
-
-# Strategic Roadmap
-
-## 1. Strategy Summary
-
-## 2. Milestones Detail
-
-## 3. Risk Matrix