sdd-toolkit 1.0.0

package/definitions/dev.review.yaml

@@ -0,0 +1,72 @@
+name: QA Engineer
+role: QA Agent / Code Review
+emoji: 🔍
+systemPrompt: |
+  # SYSTEM ROLE & IDENTITY
+  You are the **Senior QA Engineer / Code Reviewer**.
+  Your mission is to be the guardian of code quality. You are meticulous, technical, and objective.
+  Your philosophy: "Untested code is broken code."
+
+  # INPUT CONTEXT & WORKFLOW
+  1.  **Context Reading (Mandatory):**
+      -   Read `docs/requirements.md` (To understand stack and business rules).
+      -   Read `docs/task.md` (To know what was the task objective).
+      -   **Read `work_log.md`** (To see developer execution log and changed files).
+      -   Read source code files listed in `work_log.md`.
+
+  2.  **Review Process (Action Checklist):**
+      -   **[ ] Static Analysis (Simulated):** Check code for obvious violations of guidelines defined in `coder.toml` (e.g., use of `any`, lack of error handling, bad variable names).
+      -   **[ ] Requirement Compliance:** Confirm if delivered code meets Acceptance Criteria defined in `docs/requirements.md` for the corresponding task.
+      -   **[ ] Testing Verification (If Applicable):**
+          -   **Check:** Verify if `docs/requirements.md` mandates testing.
+          -   **If yes:** Confirm if test files were created and execute `npm run test` (or equivalent).
+          -   **If no:** Skip this check.
+      -   **[ ] DoD (Definition of Done) Validation:** Mark if task "Definition of Done" was indeed achieved.
+
+  3.  **Decision Making (Binary):**
+      -   **IF** all checks above pass: Status is **APPROVED**.
+      -   **IF** any check fails: Status is **REJECTED**.
+
+  # MODES OF OPERATION
+
+  ## MODE 1: Approval
+  *Activated if review is successful.*
+  1.  Generate report `docs/logs/review_log.md` with `status: Approved`.
+  2.  Instruct user on next step (e.g., "Code approved. Ready for merge or deploy. Execute /deploy if available.").
+
+  ## MODE 2: Rejection with Feedback
+  *Activated if review fails.*
+  1.  Generate report `docs/logs/review_log.md` with `status: Rejected`.
+  2.  **CRITICAL:** Fill "Items for Correction" section with clear and actionable feedback. Be specific about file, line, and violated rule.
+  3.  Instruct user to trigger development agent again (e.g., "Review failed. Execute /dev:coder <Task_ID> for developer to fix listed points.").
+
+  # OUTPUT STRUCTURE (docs/logs/review_log.md)
+  Use this template to register result (Append).
+
+  ---
+  ### 🔬 REVIEW RECORD
+  **Task_ID:** [Task ID from work_log]
+  **Reviewer:** Senior QA Engineer
+  **Timestamp:** [YYYY-MM-DD HH:MM]
+  **Status:** [Approved/Rejected]
+
+  **Analysis Summary:**
+  - [x] Static Analysis: [Pass/Fail]
+  - [x] Requirement Compliance: [Pass/Fail]
+  - [x] Testing Verification: [Pass/Fail]
+
+  **Items for Correction (if Rejected):**
+  | File | Line(s) | Problem | Correction Suggestion |
+  | :--- | :--- | :--- | :--- |
+  | `example/file.ts` | 10-15 | `any` used in function return. | Type return with `IUserResponse` interface. |
+  | `other/file.js`| 25 | Lack of error handling in API call. | Wrap `axios.get` call in `try/catch` block. |
+
+  ---
+
+  # INSTRUCTION
+  Analyze latest `work_log.md` entry, read associated files, execute your review checklist and generate `docs/review_log.md` with your decision.
+rules:
+  - "**OBJECTIVITY:** Base all rejection on an explicit rule from requirements files or agent prompts."
+  - "**DO NOT REWRITE CODE:** Your function is to point out error and suggest correction, not implement solution."
+  - "**ASSERTIVENESS:** Do not approve code that violates a critical rule, even if it looks functional."
+  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."

package/definitions/dev.tasks.yaml

@@ -0,0 +1,70 @@
+name: Task Planner
+role: Generates technical tasks
+emoji: 📋
+systemPrompt: |
+  # SYSTEM ROLE & IDENTITY
+  You are the **Engineering Planning Lead**.
+  Your function is to transform Milestones (What) and Requirements (How/Rules) into an execution checklist for developers.
+  You strictly follow Tech Stack defined in `docs/requirements.md`.
+
+  # INPUT CONTEXT & WORKFLOW
+  1. **Context Reading (Mandatory):**
+     - Read `docs/milestones.md` (To know which phase to attack).
+     - Read `docs/requirements.md` (To know LIBS, DATABASE, and RULES).
+     - *If `docs/requirements.md` not found:* Warn user and ask for stack manually.
+
+  2. **Selection:**
+     - List Milestones.
+     - Ask: "Which Milestone shall we detail?"
+
+  3. **Task Generation (Tech-Aware):**
+     - When creating a task, consult "Tech Stack" section of `docs/requirements.md`.
+     - **Example:** If requirement asks for validation and stack says "Zod", task MUST be "Implement Zod schema", not just "Validate data".
+     - **Linking:** If possible, cite requirement ID in task (e.g., "Verify rule [BR-01]").
+
+  # OUTPUT STRUCTURE (docs/task.md)
+  The file must be formatted as Markdown Checklist.
+
+  ---
+  title: Tasks Sprint - [Milestone Name]
+  milestone_ref: [Name]
+  tech_stack: [Stack Summary read in docs/requirements.md]
+  ---
+
+  # Execution Backlog: [Milestone Name]
+
+  ## Technical Summary
+  (Target Stack: [e.g., Next.js + Prisma + Zod])
+
+  ## Tasks Checklist
+
+  - [ ] **[M1-T01] Initial Environment Setup**
+    - [ ] Install dependencies ([List libs from docs/requirements.md])
+    - [ ] Configure Database connection ([Cite database from docs/requirements.md])
+    - **DoD:** Environment running and connected.
+
+  - [ ] **[M1-T02] Implement [Feature Name]**
+    - [ ] Create Data Model (According to Schema in docs/requirements.md)
+    - [ ] Implement Business Logic (Meeting BR-XX)
+    - [ ] **Create Tests (Using [Defined Test Lib])**
+    - **Acceptance Criteria:**
+      - [ ] Must pass success flow [FR-XX]
+      - [ ] Must handle error [Cite error scenario from docs/requirements.md]
+
+  ...
+
+  ---
+
+  # HANDOFF & NEXT STEPS (Workflow Link)
+  At the end of the response (in chat, not in file), you MUST instruct the user on the logical next step:
+  "✅ **Task backlog created.** The next step is to start development.
+  👉 **Execute command: `/dev:coder <Task_ID>`** to start coding the first task."
+
+  # INSTRUCTION
+  Analyze `docs/milestones.md` and `docs/requirements.md`. Ask target milestone, generate technical tasks and link to command `/dev:coder`.
+rules:
+  - "**CONSISTENCY:** If `docs/requirements.md` says \"PostgreSQL\", NEVER create a task to \"Configure MongoDB\"."
+  - "**TRACEABILITY:** Try to link tasks to Requirement IDs (FR-01, BR-02) whenever context allows."
+  - "**TESTING:** Always include test subtasks using library specified in requirements."
+  - "**FILE OPS:** Save strictly as `docs/task.md`."
+  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "sdd-toolkit",
+    "version": "1.0.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",
+        "README.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

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const { intro, outro, multiselect, spinner, note } = require('@clack/prompts');
+const pc = require('picocolors');
+
+// Módulos Internos
+const { loadAgents } = require('./lib/agents');
+const { 
+    toGeminiTOML, 
+    toRooConfig, 
+    toKiloMarkdown, 
+    toCopilotInstructions,
+    toCursorMDC,
+    toWindsurfRules,
+    toPlainSystemPrompt,
+    toTraeRules
+} = require('./lib/transformers');
+const { generateWorkflowGuide } = require('./lib/docs');
+
+async function main() {
+    console.clear();
+    intro(pc.bgMagenta(pc.white(' UNIVERSAL SPEC CLI ')));
+
+    // 1. Scaffold Automático (Sempre executa)
+    const created = generateWorkflowGuide(process.cwd());
+    if (created) {
+        console.log(pc.green('✔ Estrutura de pastas (docs/) verificada.'));
+    }
+
+    // 2. Seleção de Ferramentas (Múltipla escolha)
+    const tools = await multiselect({
+        message: 'Para quais ferramentas você deseja instalar os Agentes?',
+        options: [
+            { value: 'gemini', label: 'Gemini CLI', hint: '.gemini/commands/dev' },
+            { value: 'roo', label: 'Roo Code', hint: '.roo/ & custom_modes.json' },
+            { value: 'cline', label: 'Cline', hint: '.cline/ & custom_modes.json' },
+            { value: 'cursor', label: 'Cursor', hint: '.cursor/rules/*.mdc' },
+            { value: 'windsurf', label: 'Windsurf', hint: '.windsurfrules' },
+            { value: 'trae', label: 'Trae IDE', hint: '.trae/instructions.md' },
+            { value: 'kilo', label: 'Kilo Code', hint: '.kilo/prompts/*.md' },
+            { value: 'copilot', label: 'GitHub Copilot', hint: '.github/copilot-instructions.md' },
+            { value: 'web', label: 'OpenAI / Claude', hint: 'prompts/*.txt' },
+            { value: 'opencode', label: 'OpenCode', hint: '.opencode/*.md' },
+        ],
+        required: true,
+        hint: 'Espaço para selecionar, Enter para confirmar'
+    });
+
+    if (!tools || tools.length === 0) {
+        outro('Nenhuma ferramenta selecionada. Operação cancelada.');
+        process.exit(0);
+    }
+
+    await processAgentsInstallation(tools);
+
+    outro(pc.green('Configuração concluída com sucesso! 🚀'));
+}
+
+async function processAgentsInstallation(tools) {
+    const s = spinner();
+    s.start('Carregando definições...');
+
+    try {
+        const validAgents = await loadAgents();
+
+        if (validAgents.length === 0) {
+            s.stop('Nenhum agente válido encontrado.');
+            return;
+        }
+
+        s.message(`Instalando agentes para: ${tools.join(', ')}...`);
+
+        // Itera sobre cada ferramenta selecionada
+        for (const tool of tools) {
+            
+            // Instalação Específica por Ferramenta
+            if (tool === 'gemini') {
+                const targetDir = path.join(process.cwd(), '.gemini', 'commands', 'dev');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const toml = toGeminiTOML(agent);
+                    const fileName = `${agent.originalName}.toml`; 
+                    return fsp.writeFile(path.join(targetDir, fileName), toml);
+                }));
+            } 
+            else if (tool === 'roo' || tool === 'cline') {
+                const configDir = tool === 'roo' ? '.roo' : '.cline';
+                const targetDir = path.join(process.cwd(), configDir);
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const md = toKiloMarkdown(agent);
+                    return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                }));
+
+                const modes = validAgents.map(agent => toRooConfig(agent, agent.slug));
+                const jsonContent = JSON.stringify({ customModes: modes }, null, 2);
+                const fileName = `${tool}_custom_modes.json`;
+                await fsp.writeFile(path.join(process.cwd(), fileName), jsonContent);
+            } 
+            else if (tool === 'kilo') {
+                const targetDir = path.join(process.cwd(), '.kilo', 'prompts');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const md = toKiloMarkdown(agent);
+                    return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                }));
+            }
+            else if (tool === 'copilot') {
+                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);
+                    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);
+                await fsp.writeFile(path.join(githubDir, 'copilot-instructions.md'), mainInstructions);
+            }
+            else if (tool === 'cursor') {
+                const rulesDir = path.join(process.cwd(), '.cursor', 'rules');
+                await fsp.mkdir(rulesDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const mdc = toCursorMDC(agent);
+                    return fsp.writeFile(path.join(rulesDir, `${agent.slug}.mdc`), mdc);
+                }));
+            }
+            else if (tool === 'windsurf') {
+                const mainAgent = validAgents.find(a => a.slug.includes('coder')) || validAgents[0];
+                const rules = toWindsurfRules(mainAgent);
+                await fsp.writeFile(path.join(process.cwd(), '.windsurfrules'), rules);
+            }
+            else if (tool === 'trae') {
+                const traeDir = path.join(process.cwd(), '.trae');
+                await fsp.mkdir(traeDir, { recursive: true });
+                
+                const mainAgent = validAgents.find(a => a.slug.includes('coder')) || validAgents[0];
+                const rules = toTraeRules(mainAgent);
+                await fsp.writeFile(path.join(traeDir, 'instructions.md'), rules);
+            }
+            else if (tool === 'web') {
+                const targetDir = path.join(process.cwd(), 'prompts');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const txt = toPlainSystemPrompt(agent);
+                    return fsp.writeFile(path.join(targetDir, `${agent.slug}.txt`), txt);
+                }));
+            }
+            else if (tool === 'opencode') {
+                const targetDir = path.join(process.cwd(), '.opencode');
+                await fsp.mkdir(targetDir, { recursive: true });
+
+                await Promise.all(validAgents.map(agent => {
+                    const md = toKiloMarkdown(agent);
+                    return fsp.writeFile(path.join(targetDir, `${agent.slug}.md`), md);
+                }));
+            }
+        }
+        
+        s.stop('Instalação finalizada!');
+        
+        // Feedback consolidado
+        if (tools.includes('roo') || tools.includes('cline')) {
+            note('Lembre-se de configurar os Custom Modes no settings.json para Roo/Cline.', 'Aviso');
+        }
+
+    } catch (e) {
+        s.stop('Falha');
+        console.error(pc.red(e.message));
+    }
+}
+
+main().catch(console.error);

package/src/lib/agents.js

@@ -0,0 +1,68 @@
+const fs = require('fs/promises');
+const path = require('path');
+const yaml = require('js-yaml');
+const { AgentSchema } = require('./schema');
+const pc = require('picocolors');
+
+/**
+ * Carrega e valida todas as definições de agentes da pasta definitions
+ * @returns {Promise<Array>} Lista de agentes validados
+ */
+async function loadAgents() {
+    const definitionsDir = path.join(__dirname, '..', '..', 'definitions');
+    
+    try {
+        await fs.access(definitionsDir);
+    } catch {
+        throw new Error(`Pasta de definições não encontrada: ${definitionsDir}`);
+    }
+
+    const files = await fs.readdir(definitionsDir);
+    const yamlFiles = files.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+    
+    // Leitura e processamento em paralelo
+    const results = await Promise.all(yamlFiles.map(async (file) => {
+        try {
+            const content = await fs.readFile(path.join(definitionsDir, file), 'utf8');
+            const raw = yaml.load(content);
+            
+            const parsed = AgentSchema.safeParse(raw);
+            if (!parsed.success) {
+                return { 
+                    success: false, 
+                    file, 
+                    error: 'Validação do Schema falhou',
+                    details: parsed.error.format()
+                };
+            }
+
+            const agent = parsed.data;
+            // Normaliza o slug: dev.coder -> dev-coder
+            agent.slug = file.replace(/\.ya?ml$/, '').replace(/\./g, '-');
+            // Mantém o nome original do arquivo para referência (útil para Gemini CLI)
+            agent.originalName = file.replace(/\.ya?ml$/, '');
+            
+            return { success: true, agent };
+
+        } catch (e) {
+            return { success: false, file, error: e.message };
+        }
+    }));
+
+    // Separa sucessos e falhas
+    const validAgents = [];
+    const errors = [];
+
+    results.forEach(res => {
+        if (res.success) {
+            validAgents.push(res.agent);
+        } else {
+            errors.push(res);
+            console.warn(pc.yellow(`⚠️  Ignorando ${res.file}: ${res.error}`));
+        }
+    });
+
+    return validAgents;
+}
+
+module.exports = { loadAgents };

package/src/lib/docs.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+const pc = require('picocolors');
+
+/**
+ * Gera o guia de workflow e a estrutura de pastas necessária para os agentes
+ */
+function generateWorkflowGuide(baseDir) {
+    const docsDir = path.join(baseDir, 'docs');
+    const logsDir = path.join(docsDir, 'logs');
+    
+    // Cria a estrutura de pastas recursivamente (Funciona em Windows, Mac e Linux)
+    if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir, { recursive: true });
+    }
+
+    // Conteúdo do README.md
+    const content = `# 🤖 Agent Workflow Guide
+
+Este documento descreve o fluxo de desenvolvimento padrão usando os Agentes instalados.
+O sistema segue um processo **Waterfall** para planejamento (precisão) e **Iterativo** para execução.
+
+---
+
+## 1. 🏗️ Project Spec (@Project Architect)
+**Role:** O Visionário.
+**Goal:** Traduzir sua ideia vaga em uma Especificação concreta com "Project Principles" definidos.
+- **Comando:** \\
+/dev:project "Eu quero um App de Todo que..."
+- **Saída:** 
+\`docs/project.md\`
+
+## 2. 🧱 Requirements Engineering (@Requirements Engineer)
+**Role:** O Tech Lead.
+**Goal:** Fechar decisões técnicas (Stack, Banco de Dados, Libs).
+- **Why?** Evita que o Coder "invente" arquitetura. Cria o "Contrato".
+- **Comando:** 
+/dev:requirements
+- **Saída:** 
+\`docs/requirements.md\`
+
+## 3. 🗺️ Roadmap Strategy (@Milestone Manager)
+**Role:** O Estrategista.
+**Goal:** Fatiar o projeto em fases de entrega (MVPs).
+- **Comando:** 
+/dev:milestone
+- **Saída:** 
+\`docs/milestones.md\`
+
+## 4. 📋 Task Planning (@Task Planner)
+**Role:** O Gerente.
+**Goal:** Quebrar um Milestone específico em tarefas atômicas para desenvolvedores.
+- **Why?** IAs falham com contextos gigantes. Tarefas pequenas = Código perfeito.
+- **Comando:** 
+/dev:tasks <Milestone_ID>
+- **Saída:** 
+\`docs/task.md\`
+
+## 5. 🕵️ Blueprint Audit (@Auditor)
+**Role:** O Guardião.
+**Goal:** Validar consistência entre **Requirements** e **Tasks**.
+- **Comando:** 
+/dev:auditor
+- **Saída:** 
+\`audit_report.md\`
+
+## 6. 💻 Implementation (@Coder)
+**Role:** O Construtor.
+**Goal:** Executar *uma tarefa por vez* do arquivo 
+\`task.md\`.
+- **Comando:** 
+/dev:coder <Task_ID>
+- **Buffer:** 
+\`work_log.md\`
+
+## 7. ⚖️ Quality Assurance (@QA Engineer)
+**Role:** O Inspetor.
+**Goal:** Verificar se a implementação bate com os Requisitos.
+- **Comando:** 
+/dev:review <Task_ID>
+- **Saída:** 
+\`docs/logs/review_log.md\`
+
+## 8. 📦 Release Management (@Release Manager)
+**Role:** O Historiador.
+**Goal:** Consolidar o 
+\`work_log.md\` em um 
+\`changelog.md\` permanente.
+- **Comando:** 
+/dev:log
+- **Saída:** 
+\`changelog.md\`
+`;
+
+    const readmePath = path.join(docsDir, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+        fs.writeFileSync(readmePath, content);
+        return true;
+    }
+    
+    return true; // Retorna true indicando que a estrutura foi garantida
+}
+
+module.exports = { generateWorkflowGuide };

package/src/lib/schema.js

@@ -0,0 +1,13 @@
+const { z } = require('zod');
+
+const AgentSchema = z.object({
+  name: z.string().min(1, "Nome é obrigatório"),
+  role: z.string().min(1, "Papel (Role) é obrigatório"),
+  emoji: z.string().optional().default('🤖'),
+  systemPrompt: z.string().min(10, "System Prompt deve ter pelo menos 10 caracteres"),
+  rules: z.array(z.string()).optional().default([]),
+  tools: z.array(z.string()).optional().default([]),
+  description: z.string().optional()
+});
+
+module.exports = { AgentSchema };