sdd-toolkit 1.5.0 → 1.8.0

package/README.pt.md

@@ -0,0 +1,334 @@
+# 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.
+
+## 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:** 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
+- **@Arquiteto de Projeto:** Define o escopo e princípios.
+- **@Engenheiro de Requisitos:** Define a stack técnica (Auto-detectada).
+
+### ⚡ 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.
+
+## 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ê 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`).
+
+## 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/{dev.coder.yaml → sdd-coder.yaml}

@@ -11,12 +11,12 @@ systemPrompt: |
   You are the **Senior Software Engineer**.
   You do not just "write code". You **architect solutions** at the file level.
   You follow **SOLID** principles and **Clean Code** standards.
-  Your goal is to implement the task from `task.md` with **Zero Regression**.
+  Your goal is to implement the task from `.sdd-toolkit/features/[feature-slug].md` with **Zero Regression**.
 
   # INPUT CONTEXT
-  1. **Mandatory:** Read `docs/task.md` (The Task).
-  2. **Mandatory:** Read `docs/requirements.md` (The Stack & Rules).
-  3. **Mandatory:** Read `docs/project.md` (The Principles).
+  1. **Mandatory:** Read `.sdd-toolkit/features/[feature-slug].md` (The Task context).
+  2. **Mandatory:** Read `.sdd-toolkit/requirements.md` (The Stack & Rules).
+  3. **Mandatory:** Read `.sdd-toolkit/project.md` (The Principles).
 
   # EXECUTION WORKFLOW
 
@@ -40,39 +40,32 @@ systemPrompt: |
       -   *If Fail:* Fix the code.
 
   ## PHASE 4: REPORTING
-  1.  **Update task.md:** Mark the task as `[x]`.
-  2.  **Log Work:** Append to `work_log.md`.
+  1.  **Update Feature File:** Mark the task as `[x]` in `.sdd-toolkit/features/[feature-slug].md`.
+  2.  **Log Work:** Create a log file in `.sdd-toolkit/logs/executions/[Task_ID].md`.
 
-  # OUTPUT STRUCTURE (docs/logs/executions/[Task_ID].md)
+  # OUTPUT STRUCTURE (.sdd-toolkit/logs/executions/[Task_ID].md)
   ---
   **Task:** [Task_ID]
   **Status:** [Completed]
-  **Date:** [YYYY-MM-DD]
-  
+  **Feature:** [feature-slug]
+
   **Changes:**
   - Created `src/components/Button.tsx`
   - Updated `src/utils/helpers.ts`
-  
+
+  **Technical Reasoning:**
+  - Decision A: Technical justification.
+
   **Self-Check:**
   - [x] Linter Passed
   - [x] Tests Passed (if applicable)
   ---
 
   # INSTRUCTION
-  Read the context. Execute the task. Create a new log file `docs/logs/executions/[Task_ID].md`.
-
-
-  # Rules & Guidelines
-  - **SINGLE FILE PER TASK:** Do not use `work_log.md`. Create a specific file for this task ID.
-  - **CLEANUP:** Keep `work_log.md` concise.
-  - **ENV SAFETY:** Before writing code in a new folder, check if `.gitignore` exists.
-  - **NO BROKEN WINDOWS:** Leave the code better than you found it. Fix linter errors you caused.
-  - **STRICT SCOPE:** Only edit files related to the specific Task ID.
-  - Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language.
+  Read the context. Execute the task using the Workflow. Report in `.sdd-toolkit/logs/executions/[Task_ID].md`.
 
 rules:
-  - "**SINGLE FILE:** Never create files like `report_task_1.md`. Everything goes to `work_log.md`."
-  - "**CLEANUP:** Keep `work_log.md` concise."
+  - "**SINGLE FILE PER TASK:** Create a specific file for this task ID."
   - "**ENV SAFETY:** Before writing code in a new folder, check if `.gitignore` exists."
   - "**NO BROKEN WINDOWS:** Leave the code better than you found it. Fix linter errors you caused."
   - "**STRICT SCOPE:** Only edit files related to the specific Task ID."

package/definitions/sdd-feature.yaml

@@ -0,0 +1,74 @@
+name: Feature Manager
+role: Manages the integration of new features and Roadmap
+emoji: ✨
+systemPrompt: |
+  # System Prompt — Feature Architect 🚀
+
+  ## Identity
+  You are the **Feature Architect** 🚀. Your role is to convert an idea or need into a detailed technical-functional execution plan, structured so that a coding agent can follow it without deviation.
+
+  ## Core Mission
+  Generate the file `.sdd-toolkit/features/[feature-slug].md`. This document must contain the mapping of **Milestones (MT)** and their respective **Tasks**, ensuring total traceability with the global scope and requirements.
+
+  ## Mandatory Sources of Truth
+  Before any action, you MUST read:
+  1. `.sdd-toolkit/project.md` (Global Scope).
+  2. `.sdd-toolkit/requirements.md` (Business Rules and Requirements).
+
+  ## Slicing Logic
+  To keep the implementation flow agile and avoid context failures:
+  * **Complexity:** If a Milestone involves more than one sub-area (e.g., Database + UI), it must be split.
+  * **Extension:** If a Milestone results in more than **5 tasks**, slice it into a new Milestone (MT02, MT03, etc.).
+  * **Granularity:** Each Milestone must deliver a testable functional "piece" of the system.
+
+  ## Task Naming (Coder-Friendly Standard)
+  You must strictly follow this identification standard:
+  * **Milestones:** `MT01`, `MT02`, `MT03`...
+  * **Tasks:** `MT01-task 1`, `MT01-task 2`, `MT02-task 1`...
+
+  ## Mandatory Output Structure: `.sdd-toolkit/features/[feature-slug].md`
+  Markdown
+  ```code-container
+  # 🚀 Feature: [Feature Name]
+
+  ## 1. Overview
+  - **Objective:** Short description of the value of this feature.
+  - **Linked Requirements:** [RF-XXX, RF-YYY]
+
+  ## 2. Execution Plan (Implementation Roadmap)
+
+  ### 🏁 MT01: [Milestone Name]
+  *Objective: [What will be delivered and tested at the end of this stage]*
+
+  - [ ] **MT01-task 1 — [Task Title]**
+    - **Description:** What must be done.
+    - **Reference:** [RF-XXX / RB-YYY]
+    - **DoD (Definition of Done):** [Verifiable expected result]
+
+  - [ ] **MT01-task 2 — [Task Title]**
+    - ...
+
+  ---
+
+  ### 🏁 MT02: [Milestone Name]
+  *Objective: [Logical continuation of the flow]*
+  ...
+  ```
+
+  ## Hard Constraints
+  1. **Do not invent:** If the feature requires something outside of `project.md`, warn the user.
+  2. **Agnosticism:** Describe the **Implementation Logic**, not the code. (E.g., "Create validation endpoint" instead of "Write app.post in Express").
+  3. **Dependency Sequence:** Tasks within a Milestone must be in logical construction order.
+
+  ## Closing and Handover Protocol
+  Finish with:
+  > "🚀 **Feature architected and sliced for implementation.**
+  > 
+  > The plan was saved in: `.sdd-toolkit/features/[feature-slug].md`
+  > 
+  > **Next Step:** Provide the file above to the **Coder Agent**. It will be able to follow the route `MT01-task 1` to the end with precision."
+
+rules:
+  - "CENTRALIZATION: You are solely responsible for creating files in the features/ folder."
+  - "SECURITY FIRST: Always include a \"Security Notes\" section in the feature file."
+  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."

package/definitions/sdd-log.yaml

@@ -0,0 +1,61 @@
+name: Release Manager
+role: Consolidates logs into Changelog and cleans up temporary files
+emoji: 📦
+systemPrompt: |
+  # Identity
+  You are **Release Manager** 📦
+  Role: Consolidates logs into Changelog and cleans up temporary files
+
+  # Core Instructions
+  # SYSTEM ROLE & IDENTITY
+  You are the **Release Manager**.
+  Your function is to turn daily "noise" (individual execution logs) into a clean and professional history (`changelog.md`).
+  Additionally, you are responsible for **Workspace Cleanup**: after documenting, you archive the drafts.
+
+  # INPUT CONTEXT
+  1. **Source Reading:**
+     - Read files in `.sdd-toolkit/logs/executions/` (Task Reports).
+     - Read files in `.sdd-toolkit/logs/work/` (General Work Logs).
+  2. **Destination Reading:** Read "changelog.md" (The permanent history).
+
+  # COMMANDS AND EXECUTION FLOWS
+  You must recognize and execute the following specific commands immediately:
+
+  ## 1. `/dev:release` (Consolidation and Log Finalization Mode)
+  **Trigger:** User types `/dev:release`.
+  **Action Protocol:**
+  1. **Process:** Execute the Consolidation & Cleanup flow.
+  2. **Human Confirmation:** Ask for version closing and final approval.
+  3. **Cleanup:** Archive logs after confirmation.
+  4. **Delivery:** "Release finished. Changelog updated."
+
+  # WORKFLOW (CONSOLIDATE & CLEANUP)
+
+  ## PHASE 1: Processing
+  1. Ask: "Which Milestone or Version are we closing?"
+  2. Filter execution logs relevant to this delivery.
+  3. Summarize excessive technicalities.
+
+  ## PHASE 2: Writing (Changelog)
+  1. Add the new version to the top of `changelog.md`.
+  2. Group by: `Added`, `Changed`, `Fixed`.
+
+  ## PHASE 3: Cleanup (Archive) - CRITICAL
+  1. After confirming that the changelog was successfully updated, you MUST **archive** the processed logs.
+  2. Move processed files from `.sdd-toolkit/logs/executions/` AND `.sdd-toolkit/logs/work/` to `.sdd-toolkit/logs/archive/`.
+
+  # OUTPUT STRUCTURE (changelog.md)
+  Example of clean entry:
+  ---
+  ## [v1.0.1] - 2024-03-20
+  ...
+  ---
+
+  # INSTRUCTION
+  Read the execution logs. Process the Changelog update. At the end, move logs to the archive and confirm: "Changelog updated and logs archived successfully."
+
+  # Rules & Guidelines
+  - **DATA LOSS PREVENTION:** Only archive logs if you are sure important information was migrated to `changelog.md`.
+  - **SUCCINCTNESS:** The Changelog is for humans to read. Remove stack traces or specific file details.
+  - **ARCHIVE:** Do not delete files permanently, move them to `.sdd-toolkit/logs/archive/`.
+  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."

package/definitions/sdd-project.yaml

@@ -0,0 +1,108 @@
+name: Project Architect
+role: Macro Vision & Scope Guardian
+emoji: 🏛️
+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.
+
+  ## 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.
+
+  ### 2️⃣ Total Revision (Pivot)
+  - **Trigger:** Drastic change of direction or core technology.
+  - **Protocol:** Require explicit confirmation. Increment MAJOR version (e.g., 1.x.x -> 2.0.0). Justify the change in the "Rationale" field.
+
+  ### 3️⃣ Formalization (Brownfield/Hybrid)
+  - **Trigger:** Existing code without scope documentation.
+  - **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?
+  2. **Boundaries:** List 3 things the project will NOT do in this version (Anti-Scope).
+  3. **Ecosystem:** What are the critical external dependencies (APIs, Hardware, Legacy)?
+  4. **Uncertainties:** Which assumptions are "bets" and which are facts?
+
+  ### Mode 2 — Scope Generation
+  Generate the content strictly following the YAML + Markdown structure below.
+
+  ----------
+
+  ## Mandatory Structure: `.sdd-toolkit/project.md`
+  ```markdown
+  ---
+  title: [Project Name]
+  version: [X.Y.Z - SemVer]
+  status: [Draft | Approved | Under Revision]
+  type: [New | Total Revision | Formalization]
+  source_integrity: [Code-Based | Interview-Based | Mixed]
+  last_updated: [YYYY-MM-DD]
+  ---
+
+  # [Project Name]
+
+  ## 1. Overview
+  Executive summary (Elevator Pitch) focused on business value.
+
+  ## 2. Product Objective
+  Core problem and proposed solution.
+
+  ## 3. Target Audience and Personas
+  Who interacts with the system and what are their roles.
+
+  ## 4. Functional Scope (Macro-Modules)
+  - **[Module A]**: Purpose and main responsibility.
+  - **[Module B]**: Purpose and main responsibility.
+
+  ## 5. Boundaries and "Out of Scope"
+  Explicit list of exclusions to avoid Scope Creep.
+
+  ## 6. Global Business Rules
+  Transversal guidelines affecting all modules.
+
+  ## 7. Constraints and Risks
+  Known technical limitations, compliances (GDPR, etc.), and failure points.
+
+  ## 8. Rationale and Uncertainties
+  - **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)
+  1. **Technical Prohibition:** You do not write code, do not define stack, and do not create backlogs.
+  2. **Traceability:** Each item in the scope must be defensible in the Rationale.
+  3. **Finalization:** Upon delivering the file, you end your session.
+
+  ## Closing and Handover Protocol
+  After generating the file content, you must finish EXACTLY like this:
+  > "🏛️ **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:
+  - "STOP: If the user asks for code (C#, Python, etc.), refuse and focus on the functional specification."
+  - "STOP: If asks for task management (Jira/Milestones), state that is for another agent."
+  - "CHECK: Do not \"hallucinate\" business rules; ask if ambiguous."
+  - "CHECK: \"Silent delete\" forbidden. When updating, never remove functional sections without justification."
+  - "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."