sdd-toolkit 1.0.0 → 1.5.0

package/src/lib/profiles.js

@@ -0,0 +1,186 @@
+/**
+ * Technical Stack Profiles
+ * Defines additional rules to be injected into agents
+ */
+
+const STACK_PROFILES = {
+    // --- GENERIC ---
+    'generic': {
+        label: '🌐 Generic / None',
+        rules: []
+    },
+
+    // --- FRONTEND ---
+    'frontend-react': {
+        label: '🎨 Frontend: React + Tailwind',
+        rules: [
+            "Prefer Functional Components with Hooks.",
+            "Use Tailwind CSS for styling. Avoid inline styles.",
+            "Ensure accessibility (a11y) standards are met.",
+            "Use strict type checking if TypeScript is enabled.",
+            "Prefer React Query or SWR for data fetching."
+        ]
+    },
+    'frontend-next': {
+        label: '🎨 Frontend: Next.js (App Router)',
+        rules: [
+            "Use App Router directory structure.",
+            "Prefer Server Components by default; use 'use client' only when necessary.",
+            "Optimize images using next/image.",
+            "Use Server Actions for mutations."
+        ]
+    },
+    'frontend-vue': {
+        label: '🎨 Frontend: Vue.js 3 + Pinia',
+        rules: [
+            "Use Composition API with <script setup>.",
+            "Use Pinia for state management.",
+            "Prefer Tailwind CSS or Scoped CSS.",
+            "Follow the Vue Style Guide Priority A rules."
+        ]
+    },
+    'frontend-angular': {
+        label: '🎨 Frontend: Angular',
+        rules: [
+            "Use Standalone Components.",
+            "Prefer Signals over RxJS for synchronous state.",
+            "Strictly follow the Angular Style Guide.",
+            "Use Dependency Injection patterns."
+        ]
+    },
+    'frontend-svelte': {
+        label: '🎨 Frontend: SvelteKit',
+        rules: [
+            "Use Svelte 5 Runes syntax if available.",
+            "Leverage SvelteKit's load functions for server-side data.",
+            "Keep stores simple and derived."
+        ]
+    },
+
+    // --- BACKEND ---
+    'backend-node': {
+        label: '⚙️ Backend: Node.js (Express)',
+        rules: [
+            "Prefer Async/Await over raw Promises.",
+            "Follow Error Handling best practices (don't ignore errors).",
+            "Use Environment Variables for configuration.",
+            "Adhere to RESTful API standards."
+        ]
+    },
+    'backend-nest': {
+        label: '⚙️ Backend: NestJS',
+        rules: [
+            "Use Dependency Injection strictly.",
+            "Follow the module structure.",
+            "Use DTOs with ValidationPipe for all inputs.",
+            "Prefer TypeORM or Prisma for database interaction."
+        ]
+    },
+    'backend-python-fastapi': {
+        label: '⚙️ Backend: Python (FastAPI)',
+        rules: [
+            "Use Pydantic models for data validation.",
+            "Use Type Hints for function arguments and return values.",
+            "Implement async/await for I/O bound operations.",
+            "Follow PEP 8 style guidelines."
+        ]
+    },
+    'backend-python-django': {
+        label: '⚙️ Backend: Python (Django)',
+        rules: [
+            "Use Class-Based Views (CBVs) where appropriate.",
+            "Follow the 'Fat Models, Thin Views' philosophy.",
+            "Use Django ORM optimizations (select_related, prefetch_related).",
+            "Keep settings separated for dev/prod."
+        ]
+    },
+    'backend-java-spring': {
+        label: '⚙️ Backend: Java (Spring Boot)',
+        rules: [
+            "Use constructor injection over @Autowired.",
+            "Follow Google Java Style Guide.",
+            "Use Lombok to reduce boilerplate code.",
+            "Handle exceptions with @ControllerAdvice."
+        ]
+    },
+    'backend-csharp': {
+        label: '⚙️ Backend: C# (.NET Core)',
+        rules: [
+            "Follow Microsoft's C# Coding Conventions.",
+            "Use Async/Await all the way down.",
+            "Prefer LINQ for collection manipulation.",
+            "Use Dependency Injection via IServiceCollection."
+        ]
+    },
+    'backend-go': {
+        label: '⚙️ Backend: Go (Golang)',
+        rules: [
+            "Handle errors explicitly (if err != nil).",
+            "Follow strict formatting (gofmt).",
+            "Prefer standard library over external dependencies when possible.",
+            "Use context for cancellation and timeouts."
+        ]
+    },
+
+    // --- MOBILE ---
+    'mobile-react-native': {
+        label: '📱 Mobile: React Native',
+        rules: [
+            "Use Functional Components and Hooks.",
+            "Avoid bridge passing heavy data.",
+            "Optimize lists with FlatList or FlashList.",
+            "Style using StyleSheet objects or styled-components."
+        ]
+    },
+    'mobile-flutter': {
+        label: '📱 Mobile: Flutter',
+        rules: [
+            "Use const constructors whenever possible.",
+            "Prefer Composition over Inheritance.",
+            "Manage state with Riverpod or BLoC.",
+            "Follow Effective Dart guidelines."
+        ]
+    },
+    'mobile-ios': {
+        label: '📱 Mobile: iOS (SwiftUI)',
+        rules: [
+            "Use MVVM pattern.",
+            "Prefer Structs over Classes for data models.",
+            "Use strict concurrency checking.",
+            "Follow Apple's Human Interface Guidelines."
+        ]
+    },
+    'mobile-android': {
+        label: '📱 Mobile: Android (Kotlin Compose)',
+        rules: [
+            "Use Jetpack Compose for UI.",
+            "Follow Material Design 3 guidelines.",
+            "Use Coroutines and Flow for async work.",
+            "Implement Hilt for Dependency Injection."
+        ]
+    },
+
+    // --- DATA & AI ---
+    'data-python': {
+        label: '📊 Data Science: Python',
+        rules: [
+            "Use Pandas vectorization over loops.",
+            "Document notebooks with Markdown cells explaining logic.",
+            "Use Type Hints even in scripts.",
+            "Prefer Polars for large datasets if possible."
+        ]
+    },
+
+    // --- INFRASTRUCTURE ---
+    'infra-terraform': {
+        label: '☁️ Infra: Terraform',
+        rules: [
+            "Use modules for reusable resources.",
+            "Keep state remote and locked.",
+            "Format code with `terraform fmt`.",
+            "Avoid hardcoding values; use variables."
+        ]
+    }
+};
+
+module.exports = { STACK_PROFILES };

package/src/lib/schema.js

@@ -1,13 +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 };
+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 };

package/src/lib/transformers.js

@@ -1,7 +1,32 @@
+const { TRANSLATIONS } = require('./messages');
+
+/**
+ * Returns the language rule based on the locale
+ * @param {string} locale - 'en', 'pt-br', 'es', etc.
+ */
+function getLanguageRule(locale = 'en') {
+    const normalized = locale.toLowerCase().replace('-', '_');
+    
+    // Mapping locale slug to property key in messages
+    const keyMap = {
+        'en': 'EN',
+        'pt_br': 'PT_BR',
+        'es': 'ES'
+    };
+
+    const ruleKey = keyMap[normalized] || 'EN';
+    
+    // Get dictionary for the target locale or fallback to EN
+    const dict = TRANSLATIONS[normalized] || TRANSLATIONS['en'];
+    
+    return dict.LANGUAGE_RULES[ruleKey];
+}
+
 /**
  * Converte definição do agente para TOML do Gemini CLI
  */
-function toGeminiTOML(agent) {
+function toGeminiTOML(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
     // Escapa aspas duplas na descrição
     const description = (agent.description || agent.role).replace(/"/g, '\\"');
     
@@ -15,25 +40,27 @@ function toGeminiTOML(agent) {
         '\n'
     ];
 
-    if (agent.rules && agent.rules.length > 0) {
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    if (allRules.length > 0) {
         parts.push(`# Rules & Guidelines`);
-        agent.rules.forEach(rule => parts.push(`- ${rule}`));
+        allRules.forEach(rule => parts.push(`- ${rule}`));
         parts.push('\n');
     }
 
     const fullPrompt = parts.join('\n');
     
     // Escapa aspas triplas para o bloco multilinha TOML
-    const escapedPrompt = fullPrompt.replace(/"""/g, '\\"\\\"\\"');
+    const escapedPrompt = fullPrompt.replace(/"""/g, '\\"\\\"\\\"');
     
     // Monta o TOML final
     let toml = `description = "${description}"\n`;
     toml += `prompt = """\n${escapedPrompt}\n"""\n`;
     
     // Mantém rules como array separado se a ferramenta suportar (Gemini CLI suporta)
-    if (agent.rules && agent.rules.length > 0) {
+    if (allRules.length > 0) {
         toml += 'rules = [\n';
-        agent.rules.forEach(rule => {
+        allRules.forEach(rule => {
             const escaped = rule.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
             toml += `  "${escaped}",\n`;
         });
@@ -46,15 +73,18 @@ function toGeminiTOML(agent) {
 /**
  * Converte para configuração de Custom Mode do Roo Code / Cline (JSON)
  */
-function toRooConfig(agent, slug) {
+function toRooConfig(agent, slug, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
     const promptParts = [
         `# ${agent.name} (${agent.role})`,
         `\n${agent.systemPrompt.trim()}\n`
     ];
 
-    if (agent.rules && agent.rules.length > 0) {
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    if (allRules.length > 0) {
         promptParts.push(`## Rules & Guidelines`);
-        agent.rules.forEach(rule => promptParts.push(`- ${rule}`));
+        allRules.forEach(rule => promptParts.push(`- ${rule}`));
     }
 
     return {
@@ -68,7 +98,8 @@ function toRooConfig(agent, slug) {
 /**
  * Converte para Markdown do Kilo Code
  */
-function toKiloMarkdown(agent) {
+function toKiloMarkdown(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
     const parts = [
         `<!--- Kilo Code Agent Config --->`,
         `# ${agent.name} ${agent.emoji}`,
@@ -78,9 +109,11 @@ function toKiloMarkdown(agent) {
         '\n'
     ];
 
-    if (agent.rules && agent.rules.length > 0) {
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    if (allRules.length > 0) {
         parts.push(`## Constraints`);
-        agent.rules.forEach(rule => parts.push(`- ${rule}`));
+        allRules.forEach(rule => parts.push(`- ${rule}`));
     }
 
     return parts.join('\n');
@@ -89,7 +122,8 @@ function toKiloMarkdown(agent) {
 /**
  * Converte para Instruções do GitHub Copilot (.github/copilot-instructions.md)
  */
-function toCopilotInstructions(agent) {
+function toCopilotInstructions(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
     const parts = [
         `<!-- GitHub Copilot Instructions for ${agent.name} -->`,
         `# Identity and Role`,
@@ -100,15 +134,16 @@ function toCopilotInstructions(agent) {
         '\n'
     ];
 
-    if (agent.rules && agent.rules.length > 0) {
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    if (allRules.length > 0) {
         parts.push(`## Rules & Guidelines`);
-        agent.rules.forEach(rule => parts.push(`- ${rule}`));
+        allRules.forEach(rule => parts.push(`- ${rule}`));
     }
     
     // Adiciona uma seção de estilo de resposta para garantir conformidade
     parts.push(`\n## Response Style`);
     parts.push(`- Be concise and objective.`);
-    parts.push(`- Use Portuguese (Brazil) unless told otherwise.`);
     parts.push(`- Follow the project conventions defined in the workspace.`);
 
     return parts.join('\n');
@@ -118,7 +153,8 @@ function toCopilotInstructions(agent) {
  * Converte para Cursor Rules (.mdc)
  * Inclui Frontmatter para Contexto
  */
-function toCursorMDC(agent) {
+function toCursorMDC(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
     // Tenta inferir globs baseados no papel do agente
     let globs = "*";
     const roleLower = agent.slug.toLowerCase();
@@ -127,7 +163,9 @@ function toCursorMDC(agent) {
     if (roleLower.includes('css') || roleLower.includes('style')) globs = "*.css, *.scss, *.tailwind";
     if (roleLower.includes('sql') || roleLower.includes('db')) globs = "*.sql, *.prisma, *.schema";
 
-    return `---
+    const allRules = [languageRule, ...(agent.rules || [])];
+
+    return `--- 
 description: ${agent.description || agent.role}
 globs: ${globs}
 ---
@@ -138,14 +176,17 @@ Role: ${agent.role}
 ## Instructions
 ${agent.systemPrompt.trim()}
 
-${agent.rules && agent.rules.length > 0 ? '## Rules\n' + agent.rules.map(r => `- ${r}`).join('\n') : ''}
+${allRules.length > 0 ? '## Rules\n' + allRules.map(r => `- ${r}`).join('\n') : ''}
 `;
 }
 
 /**
  * Converte para Windsurf (.windsurfrules)
  */
-function toWindsurfRules(agent) {
+function toWindsurfRules(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
+    const allRules = [languageRule, ...(agent.rules || [])];
+
     return `# ${agent.name} ${agent.emoji} Rules
 
 Role: ${agent.role}
@@ -153,28 +194,34 @@ Role: ${agent.role}
 ## Core Logic
 ${agent.systemPrompt.trim()}
 
-${agent.rules && agent.rules.length > 0 ? '## Guidelines\n' + agent.rules.map(r => `- ${r}`).join('\n') : ''}
+${allRules.length > 0 ? '## Guidelines\n' + allRules.map(r => `- ${r}`).join('\n') : ''}
 `;
 }
 
 /**
  * Converte para System Prompt Puro (OpenAI/Claude/Web)
  */
-function toPlainSystemPrompt(agent) {
+function toPlainSystemPrompt(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
+    const allRules = [languageRule, ...(agent.rules || [])];
+    
     return `You are ${agent.name} ${agent.emoji}
 Role: ${agent.role}
 
 [SYSTEM INSTRUCTIONS]
 ${agent.systemPrompt.trim()}
 
-${agent.rules && agent.rules.length > 0 ? '[GUIDELINES]\n' + agent.rules.map(r => `- ${r}`).join('\n') : ''}
+${allRules.length > 0 ? '[GUIDELINES]\n' + allRules.map(r => `- ${r}`).join('\n') : ''}
 `;
 }
 
 /**
  * Converte para Trae Instructions
  */
-function toTraeRules(agent) {
+function toTraeRules(agent, options = {}) {
+    const languageRule = getLanguageRule(options.locale);
+    const allRules = [languageRule, ...(agent.rules || [])];
+
     return `<!-- Trae Workspace Rules -->
 # ${agent.name} ${agent.emoji}
 
@@ -183,7 +230,7 @@ function toTraeRules(agent) {
 ## Context & Instructions
 ${agent.systemPrompt.trim()}
 
-${agent.rules && agent.rules.length > 0 ? '## Constraints\n' + agent.rules.map(r => `- ${r}`).join('\n') : ''}
+${allRules.length > 0 ? '## Constraints\n' + allRules.map(r => `- ${r}`).join('\n') : ''}
 `;
 }
 
@@ -196,4 +243,4 @@ module.exports = {
     toWindsurfRules,
     toPlainSystemPrompt,
     toTraeRules
-};
+};

package/src/scripts/archive.js

@@ -0,0 +1,56 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const docsDir = path.join(process.cwd(), 'docs');
+const archiveDir = path.join(docsDir, 'archive');
+
+// Files to archive (Ephemeral context)
+const filesToArchive = ['spec.md', 'plan.md', 'audit_report.md'];
+
+// Files to keep (Long-term context)
+// - guidelines.md (Laws)
+// - context.md (Project Reality)
+// - work_log.md (History)
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+
+console.log('📦 SDD SESSION ARCHIVER');
+console.log('This will move current Spec, Plan, and Audit reports to docs/archive/.');
+console.log('Your Work Log and Context will remain untouched.\n');
+
+// Check if there is anything to archive
+const existingFiles = filesToArchive.filter(f => fs.existsSync(path.join(docsDir, f)));
+
+if (existingFiles.length === 0) {
+    console.log('❌ No active session files found (spec.md, plan.md, etc). Nothing to archive.');
+    process.exit(0);
+}
+
+rl.question('Enter a name for this feature/session (e.g., "auth-system"): ', (name) => {
+    const safeName = (name || 'untitled').replace(/[^a-z0-9-_]/gi, '-').toLowerCase();
+    const timestamp = new Date().toISOString().split('T')[0];
+    const folderName = `${timestamp}_${safeName}`;
+    const targetDir = path.join(archiveDir, folderName);
+
+    if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    console.log(`\nMoving files to: docs/archive/${folderName}/
+`);
+
+    existingFiles.forEach(file => {
+        const srcPath = path.join(docsDir, file);
+        const destPath = path.join(targetDir, file);
+        fs.renameSync(srcPath, destPath);
+        console.log(`✔ Archived: ${file}`);
+    });
+
+    console.log('\n✅ Session archived successfully!');
+    console.log('You are ready to start a new feature with /dev.spec');
+    rl.close();
+});

package/src/scripts/reset.js

@@ -0,0 +1,19 @@
+const fs = require('fs');
+const path = require('path');
+
+const docsDir = path.join(process.cwd(), 'docs');
+
+console.log('⚠️  WARNING: This will wipe all documentation (Spec, Plan, Context).');
+console.log('Your source code (src/) will NOT be touched.');
+console.log('Are you sure? (Run with --force to execute)');
+
+if (process.argv.includes('--force')) {
+    ['spec.md', 'plan.md', 'context.md', 'audit_report.md'].forEach(file => {
+        const p = path.join(docsDir, file);
+        if (fs.existsSync(p)) {
+            fs.unlinkSync(p);
+            console.log(`Deleted: docs/${file}`);
+        }
+    });
+    console.log('✅ Wipe complete. You can start fresh with /dev.explore');
+}

package/src/scripts/status.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+const path = require('path');
+
+// Tenta carregar picocolors se estiver disponível no projeto do usuário, senão usa fallback
+let pc = { 
+    green: s => s, 
+    blue: s => s, 
+    yellow: s => s, 
+    red: s => s, 
+    bold: s => s, 
+    bgBlue: s => s 
+};
+try { pc = require('picocolors'); } catch (e) {}
+
+const docsDir = path.join(process.cwd(), 'docs');
+
+function checkFile(name) {
+    const p = path.join(docsDir, name);
+    if (fs.existsSync(p)) {
+        const stats = fs.statSync(p);
+        return { exists: true, size: stats.size, mtime: stats.mtime };
+    }
+    return { exists: false };
+}
+
+console.clear();
+console.log(pc.bgBlue(pc.bold(' 📊 SDD PROJECT STATUS ')));
+console.log('');
+
+// 1. Spec Status
+const spec = checkFile('spec.md');
+if (spec.exists && spec.size > 100) {
+    console.log(`${pc.green('✔ Spec Defined')} (Last update: ${spec.mtime.toLocaleString()})`);
+} else {
+    console.log(`${pc.red('✖ Spec Missing')} (Run /dev.spec)`);
+}
+
+// 2. Plan Status
+const plan = checkFile('plan.md');
+if (plan.exists && plan.size > 100) {
+    console.log(`${pc.green('✔ Plan Active')} (Last update: ${plan.mtime.toLocaleString()})`);
+    
+    // Tenta ler progresso simples
+    try {
+        const content = fs.readFileSync(path.join(docsDir, 'plan.md'), 'utf-8');
+        const total = (content.match(/- \[ \]/g) || []).length + (content.match(/- \[x\]/g) || []).length;
+        const done = (content.match(/- \[x\]/g) || []).length;
+        if (total > 0) {
+            const percent = Math.round((done / total) * 100);
+            console.log(`   Progress: [${'#'.repeat(Math.floor(percent/10))}${'-'.repeat(10 - Math.floor(percent/10))}] ${percent}% (${done}/${total} tasks)`);
+        }
+    } catch (e) {}
+} else {
+    console.log(`${pc.yellow('⚠ Plan Missing')} (Run /dev.plan)`);
+}
+
+console.log('');
+console.log('Use /dev.build to continue work.');

package/templates/guidelines.md

@@ -0,0 +1,9 @@
+# 📜 Project Guidelines
+
+## 🏗️ Architecture Patterns
+
+## 💻 Code Conventions
+
+## 🛠️ Tech Stack & Versions
+
+## 🛡️ Security & Performance

package/templates/milestones.md

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

package/templates/project.md

@@ -0,0 +1,28 @@
+---
+title: 
+version: 
+status: 
+last_updated: 
+---
+
+# 
+
+## 1. Overview
+
+## 2. Business Objectives
+
+## 3. Actors and Personas
+
+## 4. Modules and Features Structure
+
+## 5. User Journey (Flow)
+
+## 6. Business Rules
+
+## 7. External Integrations
+
+## 8. Non-Functional Requirements & Constraints
+
+## 9. Data Definitions
+
+## 10. Project Principles (Constitution)

package/templates/requirements.md

@@ -0,0 +1,15 @@
+---
+title: Requirements and Architecture Specification
+scope: 
+last_updated: 
+---
+
+# Requirements and Stack Catalog
+
+## 1. Tech Stack and Standards (Tech Constraints)
+
+## 2. Functional Requirements (FR)
+
+## 3. Non-Functional Requirements (NFR)
+
+## 4. Data Model (Schema Draft)

package/templates/task.md

@@ -0,0 +1,11 @@
+---
+title: Tasks Sprint - 
+milestone_ref: 
+tech_stack: 
+---
+
+# Execution Backlog: 
+
+## Technical Summary
+
+## Tasks Checklist