specforge-mcp 0.7.0 → 0.9.0

package/dist/index.js

@@ -27,6 +27,41 @@ import { SPECFORGE_VERSION } from './config/version.js';
 const server = new McpServer({
     name: 'specforge',
     version: SPECFORGE_VERSION,
+}, {
+    instructions: [
+        'You are SpecForge — a friendly assistant that helps people plan and organize software projects.',
+        '',
+        'CRITICAL UX RULES — follow these in EVERY interaction:',
+        '',
+        '1. ALWAYS explain technical terms in plain language. Your users may not be developers.',
+        '   - "spec" → "a detailed plan for a feature — like a blueprint before building a house"',
+        '   - "draft" → "a first version that is not finished yet — you can still change it"',
+        '   - "review" → "the plan is ready for someone to check before approving it"',
+        '   - "approved" → "the plan has been approved and is ready to be built"',
+        '   - "implementing" → "someone is actively building this feature right now"',
+        '   - "done" → "the feature is finished and matches what the plan described"',
+        '   - "drift" → "when the code no longer matches what the plan says — like building a house that does not match the blueprint"',
+        '   - "constitution" → "a set of rules your project always follows — like ground rules for quality"',
+        '   - "ADR" → "a record of an important technical decision — why you chose X over Y"',
+        '   - "schema" → "the structure of your database — what tables and fields store your data"',
+        '   - "UI contract" → "a description of how your screens work — what each component shows and does"',
+        '   - "acceptance criteria" → "a checklist of conditions that must be true for a feature to be considered done"',
+        '   - "coverage" → "how much of the plan has actually been built — shown as a percentage"',
+        '   - "audit" → "a health check of your code — finds problems and gives you a score"',
+        '   - "PII" → "personal data like names, emails, or phone numbers that need special protection"',
+        '   - "migration" → "moving your project from one technology to another"',
+        '   - "stack" → "the set of technologies your project uses (language, framework, database, etc.)"',
+        '   - "orchestration" → "coordinating multiple AI agents to work on different parts of your project at the same time"',
+        '   - "handoff" → "a package of instructions so an AI agent knows exactly what to build"',
+        '   - "readiness" → "whether a plan has enough detail to start building"',
+        '   - "reconcile" → "updating a plan to match changes that happened during building"',
+        '',
+        '2. Be conversational and warm. Guide the user step by step.',
+        '3. After every tool result, summarize what happened in simple terms.',
+        '4. When presenting lists or results, use plain language headers — not jargon.',
+        '5. If the user seems confused, offer to explain further. Never assume knowledge.',
+        "6. Adapt your language to the user's locale (English, Spanish, or Portuguese).",
+    ].join('\n'),
 });
 // ---------------------------------------------------------------------------
 // Register all resources and tools

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specforge-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "SpecForge — MCP Server for Spec Driven Development. Manages specs, estimations, reverse engineering, and auto-learning across any language/framework.",
   "type": "module",
   "main": "dist/index.js",

package/src/i18n/messages/en.json

@@ -65,7 +65,7 @@
   },
   "tools": {
     "set_locale": {
-      "description": "Change the active locale for messages and spec templates",
+      "description": "Change the language SpecForge uses to talk to you and to write your plans. For example, switch to Spanish or Portuguese.",
       "success": "Locale set to {locale}",
       "notImplemented": "set_locale is not yet implemented"
     },
@@ -75,205 +75,205 @@
       "notImplemented": "init_project is not yet implemented"
     },
     "init_constitution": {
-      "description": "Generate the project constitution — immutable architectural principles and quality rules",
+      "description": "Create a set of ground rules for your project — these are quality and architecture principles that every plan will follow automatically. Think of it as your project's 'golden rules' that never change.",
       "success": "Constitution initialized for project {projectId} with {count} principles",
       "notImplemented": "init_constitution is not yet implemented"
     },
     "clarify_requirements": {
-      "description": "ONLY use when the user request is extremely vague (1-2 words like 'auth' or 'payments'). For most feature requests, skip this and go directly to create_spec — SpecForge infers what it needs from project context",
+      "description": "ONLY use when the user gives an extremely vague request (1-2 words like 'auth' or 'payments'). For most feature requests, skip this and go directly to create_spec — SpecForge figures out what it needs from the project context.",
       "success": "Generated {count} clarification questions for topic: {topic}",
       "notImplemented": "clarify_requirements is not yet implemented"
     },
     "create_spec": {
-      "description": "Create a full SDD spec from a description. Call this directly — no need to run clarify_requirements first. IMPORTANT: Before calling this tool, explain to the user in simple terms: 'Based on what you described, I'm going to create a spec — think of it as a detailed plan for your feature with a checklist of what done looks like. This includes: a user story (who needs this and why), acceptance criteria (how we know it works), a technical sheet (architecture, files, risks), and diagrams. Everything stays local on your machine. Let me generate it now.' Keep it friendly and non-technical. After creation, summarize the key points: what will be built, estimated effort, and next steps.",
+      "description": "Create a full SDD spec from a description. Call this directly — no need to run clarify_requirements first. IMPORTANT — UX behavior: When the user describes something broad (e.g. 'build me a billing system', 'I want an e-commerce app'), DO NOT create a single spec. Instead: 1) Break it down into multiple specs (authentication, products, cart, payments, etc.). 2) Present the plan BEFORE creating anything: 'Based on what you told me, I am going to create X specs to cover everything you need: [list each spec with a one-line summary]. Each spec is a detailed plan with acceptance criteria — think of it as a checklist of what done looks like. Shall I go ahead?' 3) Wait for confirmation, then call create_spec once per feature. 4) After creating all specs, summarize: what was created, estimated total effort, and suggested order of implementation. For small/single features, explain briefly what the spec will contain and create it directly. Always be friendly and use plain language.",
       "success": "Spec {id} created: {title}",
       "notImplemented": "create_spec is not yet implemented"
     },
     "list_specs": {
-      "description": "List all specs for a project, optionally filtering by status",
+      "description": "Show all the plans (specs) in your project. You can filter by status — for example, only show plans that are still in draft, or only the ones already approved and ready to build.",
       "success": "Found {count} specs",
       "notImplemented": "list_specs is not yet implemented"
     },
     "update_status": {
-      "description": "Transition a spec through its lifecycle (draft → review → approved → implementing → done)",
+      "description": "Move a plan forward in its lifecycle. Plans go through these stages: draft (work in progress) → review (ready for someone to check) → approved (ready to build) → implementing (being built) → done (finished and verified).",
       "success": "Spec {specId} status updated to {status}",
       "notImplemented": "update_status is not yet implemented"
     },
     "estimate": {
-      "description": "Estimate effort, cost, and token usage for a spec using multi-agent analysis",
+      "description": "Calculate how much time, effort, and cost it will take to build a feature based on its plan. Gives you hours of development work, estimated AI token costs, and a confidence level based on similar past work.",
       "success": "Estimation complete for spec {specId} — {devHours}h dev, ${totalCostUsd} total",
       "notImplemented": "estimate is not yet implemented"
     },
     "reverse_engineer": {
-      "description": "Analyze existing code and generate an SDD spec from it",
+      "description": "Look at code that already exists and create a plan (spec) from it. Useful when you have working code but no documentation — this generates a blueprint of what the code does.",
       "success": "Reverse-engineered spec from {path}",
       "notImplemented": "reverse_engineer is not yet implemented"
     },
     "validate": {
-      "description": "Validate implementation against its spec — coverage, drift, and quality",
+      "description": "Check how much of a plan has actually been built. Compares the blueprint (spec) with the real code and tells you: what percentage is done, what files are missing, and whether the code matches the plan.",
       "success": "Validation complete: {score}% coverage",
       "notImplemented": "validate is not yet implemented"
     },
     "detect_drift": {
-      "description": "Detect drift between spec and implementation",
+      "description": "Check if the code has drifted away from the original plan. Drift means the code was changed but the plan was not updated — like building something different from the blueprint.",
       "success": "Drift analysis complete: {driftScore}% drift detected",
       "notImplemented": "detect_drift is not yet implemented"
     },
     "summarize_spec": {
-      "description": "Generate a concise summary of a spec",
+      "description": "Generate a short, easy-to-read summary of a plan. Useful when you need a quick overview without reading the full detailed spec.",
       "success": "Summary generated for spec {specId}",
       "notImplemented": "summarize_spec is not yet implemented"
     },
     "generate_checklist": {
-      "description": "Generate a quality checklist for a spec",
+      "description": "Create a quality checklist for a plan — a list of things to verify before considering the feature done. Covers code quality, testing, security, and more.",
       "success": "Checklist generated: {totalCount} items",
       "notImplemented": "generate_checklist is not yet implemented"
     },
     "reconcile_spec": {
-      "description": "Reconcile spec with implementation changes",
+      "description": "Update a plan to match what was actually built. When the code changes during development, this tool brings the plan back in sync with reality.",
       "success": "Spec {specId} reconciled with {count} changes",
       "notImplemented": "reconcile_spec is not yet implemented"
     },
     "learn_pattern": {
-      "description": "Teach the system a new pattern (architecture, convention, estimation, stack, quality)",
+      "description": "Teach SpecForge something new about your project — a coding convention, an architecture pattern, an estimation rule, or a quality standard. SpecForge remembers it and uses it in future plans.",
       "success": "Pattern learned: {type} — {pattern}",
       "notImplemented": "learn_pattern is not yet implemented"
     },
     "capture_learning": {
-      "description": "Capture a discovered pattern or lesson into the spec system with semantic deduplication",
+      "description": "Save a lesson or pattern you discovered while working. SpecForge checks if it already knows this (to avoid duplicates) and files it in the right place for future reference.",
       "success": "Pattern captured and routed to {specId}",
       "duplicate": "Pattern already covered in {specId} ({similarity}% similarity)",
       "lesson": "Lesson captured: {type}"
     },
     "audit": {
-      "description": "Audit code for SOLID, clean code, architecture, security, and quality issues",
+      "description": "Run a health check on your code. Analyzes it for clean code practices, architecture quality, security issues, and gives you a score out of 100 with specific findings to fix.",
       "success": "Audit complete: {score}/100 — {findingsCount} findings",
       "notImplemented": "audit is not yet implemented"
     },
     "consult_docs": {
-      "description": "Consult framework documentation for a specific topic",
+      "description": "Look up official documentation for your framework or library on a specific topic. Gets the answer without you having to leave your conversation.",
       "success": "Found docs for {framework}: {topic}",
       "notImplemented": "consult_docs is not yet implemented"
     },
     "discover_mcps": {
-      "description": "Discover MCP servers configured in the environment",
+      "description": "Find out what MCP servers (AI tool integrations) are set up in your environment. Shows you what tools your AI assistant can already use.",
       "success": "Discovered {count} MCP servers",
       "notImplemented": "discover_mcps is not yet implemented"
     },
     "suggest_mcps": {
-      "description": "Suggest MCP servers that could benefit the project",
+      "description": "Get recommendations for MCP servers (AI tool integrations) that could help your project. Based on your tech stack and patterns, suggests tools you might be missing.",
       "success": "Found {count} recommended MCP servers",
       "notImplemented": "suggest_mcps is not yet implemented"
     },
     "generate_adr": {
-      "description": "Generate Architecture Decision Records for a spec",
+      "description": "Create an Architecture Decision Record (ADR) — a document that records why an important technical decision was made. For example: 'We chose PostgreSQL over MongoDB because...' Keeps your team aligned on past choices.",
       "success": "ADR generated with {count} decisions",
       "notImplemented": "generate_adr is not yet implemented"
     },
     "design_schema": {
-      "description": "Design database schema from spec requirements",
+      "description": "Design the database structure for a feature based on its plan. Creates the tables, fields, relationships, and indexes your data needs.",
       "success": "Schema designed: {tableCount} tables, {indexCount} indexes",
       "notImplemented": "design_schema is not yet implemented"
     },
     "define_ui_contract": {
-      "description": "Define UI component contracts, data flow, and state management",
+      "description": "Define how your user interface components work — what data each screen needs, what actions users can take, and how information flows between components.",
       "success": "UI contract defined: {componentCount} components",
       "notImplemented": "define_ui_contract is not yet implemented"
     },
     "challenge_spec": {
-      "description": "Stress-test a spec for failures, concurrency, scale, and edge cases",
+      "description": "Stress-test a plan by simulating failures, high traffic, and edge cases. Finds weak spots before you start building — like a fire drill for your feature design.",
       "success": "Challenge complete: {scenarioCount} failure scenarios analyzed",
       "notImplemented": "challenge_spec is not yet implemented"
     },
     "generate_execution_plan": {
-      "description": "Generate a step-by-step execution plan for implementing a spec",
+      "description": "Create a step-by-step implementation guide for building a feature. Breaks the work into phases with clear tasks, so you know exactly what to do and in what order.",
       "success": "Execution plan generated: {phaseCount} phases, {stepCount} steps",
       "notImplemented": "generate_execution_plan is not yet implemented"
     },
     "suggest_stack": {
-      "description": "Suggest a technology stack based on project requirements",
+      "description": "Get a technology recommendation for your project. Based on what you are building, suggests the best combination of language, framework, database, and tools.",
       "success": "Stack recommended: {language}/{framework}",
       "notImplemented": "suggest_stack is not yet implemented"
     },
     "check_versions": {
-      "description": "Check dependency versions for updates, deprecations, and security issues",
+      "description": "Check if your project dependencies (libraries and packages) are up to date. Finds outdated versions, security vulnerabilities, and deprecated packages that need attention.",
       "success": "Checked {count} dependencies: {updatesAvailable} updates, {securityAlerts} security alerts",
       "notImplemented": "check_versions is not yet implemented"
     },
     "generate_skill": {
-      "description": "Generate an agent skill file for a specific platform",
+      "description": "Generate an AI agent skill file — a set of instructions that teaches an AI coding assistant how to perform a specific task in your project.",
       "success": "Skill '{name}' generated for {platform}",
       "notImplemented": "generate_skill is not yet implemented"
     },
     "detect_agent": {
-      "description": "Detect the AI coding agent platform in use",
+      "description": "Detect which AI coding assistant is being used in your project (Claude Code, Cursor, Copilot, Windsurf, etc.) so SpecForge can generate the right format of configuration files.",
       "success": "Detected agent: {platform} (confidence: {confidence}%)",
       "notImplemented": "detect_agent is not yet implemented"
     },
     "generate_sub_agent": {
-      "description": "Generate a sub-agent definition for multi-agent orchestration",
+      "description": "Create a specialized AI agent definition for a specific task. Used when you want multiple AI agents working on different parts of your project at the same time.",
       "success": "Sub-agent '{agentName}' generated for {framework}",
       "notImplemented": "generate_sub_agent is not yet implemented"
     },
     "generate_rules": {
-      "description": "Generate agent rules files (.cursorrules, CLAUDE.md, etc.)",
+      "description": "Generate configuration files for your AI coding assistant — like CLAUDE.md for Claude Code, .cursorrules for Cursor, etc. These files teach the AI your project's conventions.",
       "success": "Rules generated for {platform}: {rulesCount} rules",
       "notImplemented": "generate_rules is not yet implemented"
     },
     "generate_orchestration_script": {
-      "description": "Generate a 3-layer parallel automation script (worktrees + claude -p)",
+      "description": "Generate an automation script that coordinates multiple AI agents working in parallel on different features. Each agent works in its own isolated workspace to avoid conflicts.",
       "success": "Orchestration script generated for {specCount} specs",
       "notImplemented": "generate_orchestration_script is not yet implemented"
     },
     "suggest_tooling": {
-      "description": "Assess and suggest dev lifecycle tooling (CI/CD, testing, monitoring, etc.)",
+      "description": "Get recommendations for development tools across your entire workflow — CI/CD pipelines, testing frameworks, monitoring, code quality tools, and more. Gives you a maturity score.",
       "success": "Tooling assessment complete: {maturityScore}/100",
       "notImplemented": "suggest_tooling is not yet implemented"
     },
     "generate_tests": {
-      "description": "Generate test plan and test files from a spec",
+      "description": "Create a test plan and starter test files from a feature plan. Generates unit tests, integration tests, and end-to-end tests based on the acceptance criteria.",
       "success": "Test plan generated: {unitCount} unit, {integrationCount} integration, {e2eCount} e2e tests",
       "notImplemented": "generate_tests is not yet implemented"
     },
     "generate_docs": {
-      "description": "Generate documentation from specs and code",
+      "description": "Generate documentation from your plans and code — API references, README sections, architecture overviews, and more.",
       "success": "Generated {count} documents",
       "notImplemented": "generate_docs is not yet implemented"
     },
     "manage_context": {
-      "description": "Save, load, and manage persistent context notes across sessions",
+      "description": "Save and retrieve important notes that persist across sessions. Use it to remember decisions, constraints, or context that you want SpecForge to keep in mind.",
       "success": "Context {action}: {key}",
       "notImplemented": "manage_context is not yet implemented"
     },
     "manage_git": {
-      "description": "Git integration — branches, PRs, changelogs, hooks linked to specs",
+      "description": "Git integration for your project — create branches linked to plans, generate pull request descriptions, changelogs, and set up git hooks tied to your specs.",
       "success": "Git {action} completed",
       "notImplemented": "manage_git is not yet implemented"
     },
     "orchestrate": {
-      "description": "Multi-agent orchestration — register agents, lock resources, distribute tasks",
+      "description": "Coordinate multiple AI agents working on your project — assign tasks, lock files so agents do not conflict, and track what each agent is doing.",
       "success": "Orchestration {action} completed",
       "notImplemented": "orchestrate is not yet implemented"
     },
     "integrate_pm": {
-      "description": "Integrate with project management tools (Jira, Linear, GitHub Issues, etc.)",
+      "description": "Connect your plans to project management tools like Jira, Linear, GitHub Issues, Trello, or Notion. Creates tasks and tickets directly from your specs.",
       "success": "PM integration: {action} on {platform}",
       "notImplemented": "integrate_pm is not yet implemented"
     },
     "security_check": {
-      "description": "Analyze a spec against OWASP Top 10, scan code for insecure patterns, generate security score (A-F) and drift detection",
+      "description": "Run a security analysis on a feature plan — checks against common vulnerabilities (OWASP Top 10), scans for insecure code patterns, and gives you a security grade from A (excellent) to F (critical issues).",
       "success": "Security check complete: {specId} — grade {grade}",
       "notImplemented": "security_check is not yet implemented"
     },
     "data_governance": {
-      "description": "Detect PII in specs, generate retention policies, draft privacy notices, and audit compliance with GDPR/CCPA/LGPD",
+      "description": "Check your plans for personal data handling. Finds fields that contain personal information (names, emails, etc.), generates data retention policies, drafts privacy notices, and audits compliance with privacy laws like GDPR, CCPA, and LGPD.",
       "detectSuccess": "PII detection complete — {count} field(s) found, hasPII: {hasPII}",
       "retentionSuccess": "Retention policy generated for model: {model}",
       "privacyNoticeSuccess": "Privacy notice draft generated — {count} spec(s) with PII",
       "auditSuccess": "Privacy audit complete — {total} spec(s) reviewed, {nonCompliant} non-compliant"
     },
     "migrate_tech": {
-      "description": "Guide tech stack migration (language, framework, DB, services): analyze source codebase, map equivalences, generate migration plan, recommend transition strategy, validate functional parity, and plan DB migration",
+      "description": "Guide you through moving your project from one technology to another — for example, from Express to Fastify, or from MySQL to PostgreSQL. Analyzes your current code, maps equivalences, creates a step-by-step migration plan, and helps validate that everything still works.",
       "analyzeSuccess": "Source stack analysis complete — review implicit contracts and hot components before migrating",
       "mapSuccess": "Equivalence map generated — review manual mappings and differences before proceeding",
       "planSuccess": "Migration plan generated with ordered specs and circular dependency resolution",
@@ -293,15 +293,15 @@
       "statusSuccess": "Migration status report generated — update completed components as specs are finished"
     },
     "paradigm_report": {
-      "description": "Detect and report the programming paradigms used in a project",
+      "description": "Analyze your project and report what programming styles (paradigms) are used — object-oriented, functional, procedural, reactive, etc. Helps you understand the codebase patterns.",
       "success": "Paradigm report generated: {dominant} detected",
       "notFound": "Project not found. Run init_project first."
     },
     "check_readiness": {
-      "description": "Evaluate if a spec is ready for implementation by checking completeness, criteria quality, and dependency status"
+      "description": "Check if a plan has enough detail to start building. Verifies that the description is complete, acceptance criteria are clear, and all dependencies are met. Tells you if the plan is ready or what is missing."
     },
     "package_handoff": {
-      "description": "Generate a structured handoff package for an AI agent to implement a spec, including objective, criteria, file list, out-of-scope items, and constraints"
+      "description": "Create a complete instruction package so an AI agent can implement a feature. Includes the objective, acceptance criteria, file list, what is out of scope, and any constraints — everything the agent needs to get started."
     }
   },
   "resources": {

package/src/i18n/messages/es.json

@@ -65,7 +65,7 @@
   },
   "tools": {
     "set_locale": {
-      "description": "Cambiar el idioma activo para mensajes y plantillas de specs",
+      "description": "Cambiar el idioma que usa SpecForge para comunicarse contigo y para escribir tus planes. Por ejemplo, cambiar a inglés o portugués.",
       "success": "Idioma establecido a {locale}",
       "notImplemented": "set_locale aún no está implementado"
     },
@@ -75,205 +75,205 @@
       "notImplemented": "init_project aún no está implementado"
     },
     "init_constitution": {
-      "description": "Generar la constitución del proyecto — principios arquitectónicos inmutables y reglas de calidad",
+      "description": "Crear las reglas base de tu proyecto — son principios de calidad y arquitectura que todos los planes seguirán automáticamente. Piénsalo como las 'reglas de oro' de tu proyecto que nunca cambian.",
       "success": "Constitución inicializada para proyecto {projectId} con {count} principios",
       "notImplemented": "init_constitution aún no está implementado"
     },
     "clarify_requirements": {
-      "description": "SOLO usar cuando la petición del usuario sea extremadamente vaga (1-2 palabras como 'auth' o 'pagos'). Para la mayoría de features, saltar esto e ir directo a create_spec — SpecForge infiere lo que necesita del contexto del proyecto",
+      "description": "SOLO usar cuando el usuario da una petición extremadamente vaga (1-2 palabras como 'auth' o 'pagos'). Para la mayoría de features, saltar esto e ir directo a create_spec — SpecForge deduce lo que necesita del contexto del proyecto.",
       "success": "Se generaron {count} preguntas de clarificación para el tema: {topic}",
       "notImplemented": "clarify_requirements aún no está implementado"
     },
     "create_spec": {
-      "description": "Crear una spec SDD completa desde una descripción. Llamar directamente — no necesita ejecutar clarify_requirements primero. IMPORTANTE: Antes de llamar este tool, explícale al usuario de forma simple: 'Basándome en lo que me describiste, voy a crear una spec — piénsala como un plan detallado para tu feature con una lista de verificación de qué significa que esté terminada. Incluye: una historia de usuario (quién lo necesita y por qué), criterios de aceptación (cómo sabemos que funciona), una ficha técnica (arquitectura, archivos, riesgos) y diagramas. Todo se guarda local en tu máquina. Déjame generarla.' Sé amigable y no técnico. Después de crearla, resume los puntos clave: qué se va a construir, esfuerzo estimado y próximos pasos.",
+      "description": "Crear una spec SDD completa desde una descripción. Llamar directamente — no necesita ejecutar clarify_requirements primero. IMPORTANTE — Comportamiento UX: Cuando el usuario describe algo amplio (ej: 'hazme un sistema de facturación', 'quiero una app de e-commerce'), NO crees una sola spec. En su lugar: 1) Descompón en múltiples specs (autenticación, productos, carrito, pagos, etc.). 2) Presenta el plan ANTES de crear nada: 'Basándome en lo que me contaste, voy a crear X specs para cubrir todo lo que necesitas: [lista cada spec con un resumen de una línea]. Cada spec es un plan detallado con criterios de aceptación — piénsalo como una checklist de qué significa que esté terminado. ¿Le damos?' 3) Espera confirmación, luego llama create_spec una vez por feature. 4) Después de crear todas, resume: qué se creó, esfuerzo total estimado y orden sugerido de implementación. Para features pequeñas/individuales, explica brevemente qué contendrá la spec y créala directamente. Siempre sé amigable y usa lenguaje simple.",
       "success": "Spec {id} creada: {title}",
       "notImplemented": "create_spec aún no está implementado"
     },
     "list_specs": {
-      "description": "Listar todas las specs de un proyecto, opcionalmente filtrando por estado",
+      "description": "Mostrar todos los planes (specs) de tu proyecto. Puedes filtrar por estado — por ejemplo, solo mostrar planes que aún están en borrador, o solo los que ya fueron aprobados y listos para construir.",
       "success": "Se encontraron {count} specs",
       "notImplemented": "list_specs aún no está implementado"
     },
     "update_status": {
-      "description": "Transicionar una spec a través de su ciclo de vida (draft → review → approved → implementing → done)",
+      "description": "Mover un plan hacia adelante en su ciclo de vida. Los planes pasan por estas etapas: borrador (trabajo en progreso) → revisión (listo para que alguien lo revise) → aprobado (listo para construir) → implementando (se está construyendo) → terminado (completado y verificado).",
       "success": "Spec {specId} actualizada a estado {status}",
       "notImplemented": "update_status aún no está implementado"
     },
     "estimate": {
-      "description": "Estimar esfuerzo, costo y uso de tokens para una spec usando análisis multi-agente",
+      "description": "Calcular cuánto tiempo, esfuerzo y costo tomará construir una feature basándose en su plan. Te da horas de desarrollo, costos estimados de tokens de IA, y un nivel de confianza basado en trabajos similares anteriores.",
       "success": "Estimación completa para spec {specId} — {devHours}h dev, ${totalCostUsd} total",
       "notImplemented": "estimate aún no está implementado"
     },
     "reverse_engineer": {
-      "description": "Analizar código existente y generar una spec SDD desde él",
+      "description": "Mirar código que ya existe y crear un plan (spec) a partir de él. Útil cuando tienes código funcionando pero sin documentación — esto genera un plano de lo que hace el código.",
       "success": "Spec generada por ingeniería inversa desde {path}",
       "notImplemented": "reverse_engineer aún no está implementado"
     },
     "validate": {
-      "description": "Validar implementación contra su spec — cobertura, drift y calidad",
+      "description": "Verificar cuánto de un plan se ha construido realmente. Compara el plano (spec) con el código real y te dice: qué porcentaje está hecho, qué archivos faltan, y si el código coincide con el plan.",
       "success": "Validación completa: {score}% de cobertura",
       "notImplemented": "validate aún no está implementado"
     },
     "detect_drift": {
-      "description": "Detectar drift entre spec e implementación",
+      "description": "Revisar si el código se ha alejado del plan original. El drift significa que el código cambió pero el plan no se actualizó — como construir algo diferente al plano.",
       "success": "Análisis de drift completo: {driftScore}% de drift detectado",
       "notImplemented": "detect_drift aún no está implementado"
     },
     "summarize_spec": {
-      "description": "Generar un resumen conciso de una spec",
+      "description": "Generar un resumen corto y fácil de leer de un plan. Útil cuando necesitas una vista rápida sin leer la spec completa y detallada.",
       "success": "Resumen generado para spec {specId}",
       "notImplemented": "summarize_spec aún no está implementado"
     },
     "generate_checklist": {
-      "description": "Generar un checklist de calidad para una spec",
+      "description": "Crear un checklist de calidad para un plan — una lista de cosas que verificar antes de dar una feature por terminada. Cubre calidad de código, testing, seguridad y más.",
       "success": "Checklist generado: {totalCount} items",
       "notImplemented": "generate_checklist aún no está implementado"
     },
     "reconcile_spec": {
-      "description": "Reconciliar spec con cambios de implementación",
+      "description": "Actualizar un plan para que coincida con lo que realmente se construyó. Cuando el código cambia durante el desarrollo, esta herramienta sincroniza el plan con la realidad.",
       "success": "Spec {specId} reconciliada con {count} cambios",
       "notImplemented": "reconcile_spec aún no está implementado"
     },
     "learn_pattern": {
-      "description": "Enseñar al sistema un nuevo patrón (arquitectura, convención, estimación, stack, calidad)",
+      "description": "Enseñarle algo nuevo a SpecForge sobre tu proyecto — una convención de código, un patrón de arquitectura, una regla de estimación o un estándar de calidad. SpecForge lo recuerda y lo usa en futuros planes.",
       "success": "Patrón aprendido: {type} — {pattern}",
       "notImplemented": "learn_pattern aún no está implementado"
     },
     "capture_learning": {
-      "description": "Capturar un patrón o lección descubierta en el sistema de specs con deduplicación semántica",
+      "description": "Guardar una lección o patrón que descubriste mientras trabajabas. SpecForge verifica si ya lo sabe (para evitar duplicados) y lo archiva en el lugar correcto para referencia futura.",
       "success": "Patrón capturado y enrutado a {specId}",
       "duplicate": "Patrón ya cubierto en {specId} ({similarity}% similitud)",
       "lesson": "Lección capturada: {type}"
     },
     "audit": {
-      "description": "Auditar código por SOLID, código limpio, arquitectura, seguridad y calidad",
+      "description": "Ejecutar un chequeo de salud en tu código. Lo analiza por prácticas de código limpio, calidad de arquitectura, problemas de seguridad, y te da una puntuación sobre 100 con hallazgos específicos para corregir.",
       "success": "Auditoría completa: {score}/100 — {findingsCount} hallazgos",
       "notImplemented": "audit aún no está implementado"
     },
     "consult_docs": {
-      "description": "Consultar documentación del framework para un tema específico",
+      "description": "Buscar documentación oficial de tu framework o librería sobre un tema específico. Obtiene la respuesta sin que tengas que salir de tu conversación.",
       "success": "Documentación encontrada para {framework}: {topic}",
       "notImplemented": "consult_docs aún no está implementado"
     },
     "discover_mcps": {
-      "description": "Descubrir MCP servers configurados en el entorno",
+      "description": "Descubrir qué MCP servers (integraciones de herramientas de IA) están configurados en tu entorno. Te muestra qué herramientas puede usar tu asistente de IA.",
       "success": "Se descubrieron {count} MCP servers",
       "notImplemented": "discover_mcps aún no está implementado"
     },
     "suggest_mcps": {
-      "description": "Sugerir MCP servers que podrían beneficiar al proyecto",
+      "description": "Obtener recomendaciones de MCP servers (integraciones de herramientas de IA) que podrían ayudar a tu proyecto. Basándose en tu stack tecnológico y patrones, sugiere herramientas que podrías estar necesitando.",
       "success": "Se encontraron {count} MCP servers recomendados",
       "notImplemented": "suggest_mcps aún no está implementado"
     },
     "generate_adr": {
-      "description": "Generar Architecture Decision Records para una spec",
+      "description": "Crear un Registro de Decisión Arquitectónica (ADR) — un documento que registra por qué se tomó una decisión técnica importante. Por ejemplo: 'Elegimos PostgreSQL sobre MongoDB porque...' Mantiene a tu equipo alineado sobre decisiones pasadas.",
       "success": "ADR generado con {count} decisiones",
       "notImplemented": "generate_adr aún no está implementado"
     },
     "design_schema": {
-      "description": "Diseñar schema de base de datos desde requisitos de la spec",
+      "description": "Diseñar la estructura de base de datos para una feature basándose en su plan. Crea las tablas, campos, relaciones e índices que tus datos necesitan.",
       "success": "Schema diseñado: {tableCount} tablas, {indexCount} índices",
       "notImplemented": "design_schema aún no está implementado"
     },
     "define_ui_contract": {
-      "description": "Definir contratos de componentes UI, flujo de datos y manejo de estado",
+      "description": "Definir cómo funcionan tus componentes de interfaz de usuario — qué datos necesita cada pantalla, qué acciones pueden tomar los usuarios, y cómo fluye la información entre componentes.",
       "success": "Contrato UI definido: {componentCount} componentes",
       "notImplemented": "define_ui_contract aún no está implementado"
     },
     "challenge_spec": {
-      "description": "Probar una spec ante fallos, concurrencia, escala y casos borde",
+      "description": "Poner a prueba un plan simulando fallos, alto tráfico y casos extremos. Encuentra puntos débiles antes de empezar a construir — como un simulacro de incendio para el diseño de tu feature.",
       "success": "Challenge completo: {scenarioCount} escenarios de fallo analizados",
       "notImplemented": "challenge_spec aún no está implementado"
     },
     "generate_execution_plan": {
-      "description": "Generar un plan de ejecución paso a paso para implementar una spec",
+      "description": "Crear una guía de implementación paso a paso para construir una feature. Divide el trabajo en fases con tareas claras, para que sepas exactamente qué hacer y en qué orden.",
       "success": "Plan de ejecución generado: {phaseCount} fases, {stepCount} pasos",
       "notImplemented": "generate_execution_plan aún no está implementado"
     },
     "suggest_stack": {
-      "description": "Sugerir un stack tecnológico basado en requisitos del proyecto",
+      "description": "Obtener una recomendación tecnológica para tu proyecto. Basándose en lo que estás construyendo, sugiere la mejor combinación de lenguaje, framework, base de datos y herramientas.",
       "success": "Stack recomendado: {language}/{framework}",
       "notImplemented": "suggest_stack aún no está implementado"
     },
     "check_versions": {
-      "description": "Verificar versiones de dependencias para actualizaciones, deprecaciones y problemas de seguridad",
+      "description": "Verificar si las dependencias de tu proyecto (librerías y paquetes) están actualizadas. Encuentra versiones desactualizadas, vulnerabilidades de seguridad y paquetes deprecados que necesitan atención.",
       "success": "Se verificaron {count} dependencias: {updatesAvailable} actualizaciones, {securityAlerts} alertas de seguridad",
       "notImplemented": "check_versions aún no está implementado"
     },
     "generate_skill": {
-      "description": "Generar un archivo de skill de agente para una plataforma específica",
+      "description": "Generar un archivo de skill de agente IA — un conjunto de instrucciones que le enseña a un asistente de código IA cómo realizar una tarea específica en tu proyecto.",
       "success": "Skill '{name}' generado para {platform}",
       "notImplemented": "generate_skill aún no está implementado"
     },
     "detect_agent": {
-      "description": "Detectar la plataforma de agente de IA en uso",
+      "description": "Detectar qué asistente de código IA se está usando en tu proyecto (Claude Code, Cursor, Copilot, Windsurf, etc.) para que SpecForge genere el formato correcto de archivos de configuración.",
       "success": "Agente detectado: {platform} (confianza: {confidence}%)",
       "notImplemented": "detect_agent aún no está implementado"
     },
     "generate_sub_agent": {
-      "description": "Generar una definición de sub-agente para orquestación multi-agente",
+      "description": "Crear una definición de agente IA especializado para una tarea específica. Se usa cuando quieres que múltiples agentes de IA trabajen en diferentes partes de tu proyecto al mismo tiempo.",
       "success": "Sub-agente '{agentName}' generado para {framework}",
       "notImplemented": "generate_sub_agent aún no está implementado"
     },
     "generate_rules": {
-      "description": "Generar archivos de reglas de agente (.cursorrules, CLAUDE.md, etc.)",
+      "description": "Generar archivos de configuración para tu asistente de código IA — como CLAUDE.md para Claude Code, .cursorrules para Cursor, etc. Estos archivos le enseñan a la IA las convenciones de tu proyecto.",
       "success": "Reglas generadas para {platform}: {rulesCount} reglas",
       "notImplemented": "generate_rules aún no está implementado"
     },
     "generate_orchestration_script": {
-      "description": "Generar script de automatización paralela en 3 capas (worktrees + claude -p)",
+      "description": "Generar un script de automatización que coordina múltiples agentes de IA trabajando en paralelo en diferentes features. Cada agente trabaja en su propio espacio aislado para evitar conflictos.",
       "success": "Script de orquestación generado para {specCount} specs",
       "notImplemented": "generate_orchestration_script aún no está implementado"
     },
     "suggest_tooling": {
-      "description": "Evaluar y sugerir herramientas del ciclo de desarrollo (CI/CD, testing, monitoreo, etc.)",
+      "description": "Obtener recomendaciones de herramientas de desarrollo para todo tu flujo de trabajo — pipelines CI/CD, frameworks de testing, monitoreo, herramientas de calidad de código y más. Te da una puntuación de madurez.",
       "success": "Evaluación de herramientas completa: {maturityScore}/100",
       "notImplemented": "suggest_tooling aún no está implementado"
     },
     "generate_tests": {
-      "description": "Generar plan de tests y archivos de test desde una spec",
+      "description": "Crear un plan de tests y archivos de test iniciales desde un plan de feature. Genera tests unitarios, de integración y end-to-end basados en los criterios de aceptación.",
       "success": "Plan de tests generado: {unitCount} unitarios, {integrationCount} integración, {e2eCount} e2e",
       "notImplemented": "generate_tests aún no está implementado"
     },
     "generate_docs": {
-      "description": "Generar documentación desde specs y código",
+      "description": "Generar documentación desde tus planes y código — referencias de API, secciones de README, resúmenes de arquitectura y más.",
       "success": "Se generaron {count} documentos",
       "notImplemented": "generate_docs aún no está implementado"
     },
     "manage_context": {
-      "description": "Guardar, cargar y gestionar notas de contexto persistentes entre sesiones",
+      "description": "Guardar y recuperar notas importantes que persisten entre sesiones. Úsalo para recordar decisiones, restricciones o contexto que quieras que SpecForge tenga en mente.",
       "success": "Contexto {action}: {key}",
       "notImplemented": "manage_context aún no está implementado"
     },
     "manage_git": {
-      "description": "Integración Git — branches, PRs, changelogs, hooks vinculados a specs",
+      "description": "Integración Git para tu proyecto — crear branches vinculados a planes, generar descripciones de pull requests, changelogs y configurar git hooks ligados a tus specs.",
       "success": "Git {action} completado",
       "notImplemented": "manage_git aún no está implementado"
     },
     "orchestrate": {
-      "description": "Orquestación multi-agente — registrar agentes, bloquear recursos, distribuir tareas",
+      "description": "Coordinar múltiples agentes de IA trabajando en tu proyecto — asignar tareas, bloquear archivos para que los agentes no entren en conflicto, y seguir qué está haciendo cada agente.",
       "success": "Orquestación {action} completada",
       "notImplemented": "orchestrate aún no está implementado"
     },
     "integrate_pm": {
-      "description": "Integrar con herramientas de gestión de proyectos (Jira, Linear, GitHub Issues, etc.)",
+      "description": "Conectar tus planes con herramientas de gestión de proyectos como Jira, Linear, GitHub Issues, Trello o Notion. Crea tareas y tickets directamente desde tus specs.",
       "success": "Integración PM: {action} en {platform}",
       "notImplemented": "integrate_pm aún no está implementado"
     },
     "security_check": {
-      "description": "Analizar un spec contra OWASP Top 10, escanear código en busca de patrones inseguros, generar puntuación de seguridad (A-F) y detección de drift",
+      "description": "Ejecutar un análisis de seguridad en un plan de feature — verifica contra vulnerabilidades comunes (OWASP Top 10), escanea patrones de código inseguros, y te da una calificación de seguridad de A (excelente) a F (problemas críticos).",
       "success": "Verificación de seguridad completa: {specId} — grado {grade}",
       "notImplemented": "security_check aún no está implementado"
     },
     "data_governance": {
-      "description": "Detectar PII en specs, generar políticas de retención, redactar avisos de privacidad y auditar cumplimiento con GDPR/CCPA/LGPD",
+      "description": "Revisar tus planes por manejo de datos personales. Encuentra campos que contienen información personal (nombres, emails, etc.), genera políticas de retención de datos, redacta avisos de privacidad y audita cumplimiento con leyes de privacidad como GDPR, CCPA y LGPD.",
       "detectSuccess": "Detección de PII completada — {count} campo(s) encontrados, hasPII: {hasPII}",
       "retentionSuccess": "Política de retención generada para el modelo: {model}",
       "privacyNoticeSuccess": "Borrador de aviso de privacidad generado — {count} spec(s) con PII",
       "auditSuccess": "Auditoría de privacidad completada — {total} spec(s) revisados, {nonCompliant} no conformes"
     },
     "migrate_tech": {
-      "description": "Guiar la migración de stack tecnológico (lenguaje, framework, DB, servicios): analizar codebase origen, mapear equivalencias, generar plan de migración, recomendar estrategia de transición, validar paridad funcional y planificar migración de BD",
+      "description": "Guiarte a través de mover tu proyecto de una tecnología a otra — por ejemplo, de Express a Fastify, o de MySQL a PostgreSQL. Analiza tu código actual, mapea equivalencias, crea un plan de migración paso a paso y ayuda a validar que todo siga funcionando.",
       "analyzeSuccess": "Análisis del stack origen completado — revisar contratos implícitos y componentes calientes antes de migrar",
       "mapSuccess": "Mapa de equivalencias generado — revisar mapeos manuales y diferencias antes de continuar",
       "planSuccess": "Plan de migración generado con specs ordenados y resolución de dependencias circulares",
@@ -282,26 +282,26 @@
       "analyzeDbSuccess": "Schema de base de datos analizado — revisar schema, ORM y volumen estimado de datos",
       "mapDbSuccess": "Mapeo de tipos de BD generado — todos los warnings de data loss deben revisarse antes de migrar",
       "planDbSuccess": "Plan de migración de BD generado con enfoque por fases y estrategia de rollback",
-      "analyzeServicesSuccess": "External services analysis complete — review critical services and migration priorities",
-      "mapServicesSuccess": "Service equivalence map generated — review adapters and behavior differences",
-      "planServicesSuccess": "Service migration plan generated — stateless services scheduled first",
-      "validateServiceSuccess": "Service validation checklist generated — fill in expected values from your baseline",
-      "rollbackPlanSuccess": "Rollback plan generated — review irreversible steps and checkpoint conditions",
-      "checkpointSuccess": "Migration checkpoint recorded — use this ID to rollback to this state if needed",
-      "rollbackSuccess": "Rollback execution plan generated — confirm each manual step before proceeding",
-      "featureFlagsSuccess": "Feature flag spec generated — configure your provider and set expiration date",
-      "statusSuccess": "Migration status report generated — update completed components as specs are finished"
+      "analyzeServicesSuccess": "Análisis de servicios externos completado — revisar servicios críticos y prioridades de migración",
+      "mapServicesSuccess": "Mapa de equivalencia de servicios generado — revisar adaptadores y diferencias de comportamiento",
+      "planServicesSuccess": "Plan de migración de servicios generado — servicios sin estado programados primero",
+      "validateServiceSuccess": "Checklist de validación de servicios generado — completar valores esperados desde tu baseline",
+      "rollbackPlanSuccess": "Plan de rollback generado — revisar pasos irreversibles y condiciones de checkpoint",
+      "checkpointSuccess": "Checkpoint de migración registrado — usa este ID para hacer rollback a este estado si es necesario",
+      "rollbackSuccess": "Plan de ejecución de rollback generado — confirmar cada paso manual antes de proceder",
+      "featureFlagsSuccess": "Spec de feature flags generada — configura tu proveedor y establece fecha de expiración",
+      "statusSuccess": "Reporte de estado de migración generado — actualizar componentes completados a medida que se terminan los specs"
     },
     "paradigm_report": {
-      "description": "Detectar y reportar los paradigmas de programación usados en un proyecto",
+      "description": "Analizar tu proyecto y reportar qué estilos de programación (paradigmas) se usan — orientado a objetos, funcional, procedural, reactivo, etc. Te ayuda a entender los patrones del código.",
       "success": "Reporte de paradigmas generado: {dominant} detectado",
       "notFound": "Proyecto no encontrado. Ejecuta init_project primero."
     },
     "check_readiness": {
-      "description": "Evaluar si una spec está lista para implementar verificando completeness, calidad de criterios y estado de dependencias"
+      "description": "Verificar si un plan tiene suficiente detalle para empezar a construir. Verifica que la descripción esté completa, los criterios de aceptación sean claros y todas las dependencias estén cumplidas. Te dice si el plan está listo o qué falta."
     },
     "package_handoff": {
-      "description": "Generar un paquete de handoff estructurado para que un agente AI implemente una spec, incluyendo objetivo, criterios, archivos, fuera de scope y restricciones"
+      "description": "Crear un paquete completo de instrucciones para que un agente de IA implemente una feature. Incluye el objetivo, criterios de aceptación, lista de archivos, qué está fuera de scope y cualquier restricción — todo lo que el agente necesita para empezar."
     }
   },
   "resources": {

package/src/i18n/messages/pt.json

@@ -65,7 +65,7 @@
   },
   "tools": {
     "set_locale": {
-      "description": "Alterar o idioma ativo para mensagens e modelos de specs",
+      "description": "Mudar o idioma que o SpecForge usa para se comunicar com você e para escrever seus planos. Por exemplo, trocar para inglês ou espanhol.",
       "success": "Idioma definido para {locale}",
       "notImplemented": "set_locale ainda não está implementado"
     },
@@ -75,205 +75,205 @@
       "notImplemented": "init_project ainda não está implementado"
     },
     "init_constitution": {
-      "description": "Gerar a constituição do projeto — princípios arquiteturais imutáveis e regras de qualidade",
+      "description": "Criar as regras base do seu projeto — são princípios de qualidade e arquitetura que todos os planos vão seguir automaticamente. Pense nisso como as 'regras de ouro' do seu projeto que nunca mudam.",
       "success": "Constituição inicializada para projeto {projectId} com {count} princípios",
       "notImplemented": "init_constitution ainda não está implementado"
     },
     "clarify_requirements": {
-      "description": "APENAS usar quando o pedido do usuário for extremamente vago (1-2 palavras como 'auth' ou 'pagamentos'). Para a maioria das features, pular e ir direto para create_spec — SpecForge infere o que precisa do contexto do projeto",
+      "description": "APENAS usar quando o pedido do usuário for extremamente vago (1-2 palavras como 'auth' ou 'pagamentos'). Para a maioria das features, pule e vá direto para create_spec — o SpecForge descobre o que precisa do contexto do projeto.",
       "success": "Geradas {count} perguntas de clarificação para o tópico: {topic}",
       "notImplemented": "clarify_requirements ainda não está implementado"
     },
     "create_spec": {
-      "description": "Criar uma spec SDD completa a partir de uma descrição. Chamar diretamente — não precisa executar clarify_requirements antes. IMPORTANTE: Antes de chamar este tool, explique ao usuário de forma simples: 'Com base no que você descreveu, vou criar uma spec — pense nela como um plano detalhado para sua feature com uma checklist do que significa estar pronta. Inclui: uma história de usuário (quem precisa e por quê), critérios de aceitação (como sabemos que funciona), uma ficha técnica (arquitetura, arquivos, riscos) e diagramas. Tudo fica salvo local na sua máquina. Deixa eu gerar agora.' Seja amigável e não técnico. Depois de criar, resuma os pontos-chave: o que será construído, esforço estimado e próximos passos.",
+      "description": "Criar uma spec SDD completa a partir de uma descrição. Chamar diretamente — não precisa executar clarify_requirements antes. IMPORTANTE — Comportamento UX: Quando o usuário descreve algo amplo (ex: 'me faz um sistema de faturamento', 'quero um app de e-commerce'), NÃO crie uma única spec. Em vez disso: 1) Decomponha em múltiplas specs (autenticação, produtos, carrinho, pagamentos, etc.). 2) Apresente o plano ANTES de criar: 'Com base no que você me contou, vou criar X specs para cobrir tudo que precisa: [lista cada spec com resumo de uma linha]. Cada spec é um plano detalhado com critérios de aceitação — pense como uma checklist do que significa estar pronto. Posso ir em frente?' 3) Espere confirmação, depois chame create_spec uma vez por feature. 4) Após criar todas, resuma: o que foi criado, esforço total estimado e ordem sugerida de implementação. Para features pequenas/individuais, explique brevemente e crie direto. Sempre seja amigável e use linguagem simples.",
       "success": "Spec {id} criada: {title}",
       "notImplemented": "create_spec ainda não está implementado"
     },
     "list_specs": {
-      "description": "Listar todas as specs de um projeto, opcionalmente filtrando por status",
+      "description": "Mostrar todos os planos (specs) do seu projeto. Você pode filtrar por status — por exemplo, mostrar só planos que ainda estão em rascunho, ou só os que já foram aprovados e estão prontos para construir.",
       "success": "Encontradas {count} specs",
       "notImplemented": "list_specs ainda não está implementado"
     },
     "update_status": {
-      "description": "Transicionar uma spec pelo seu ciclo de vida (draft → review → approved → implementing → done)",
+      "description": "Mover um plano adiante no seu ciclo de vida. Os planos passam por estas etapas: rascunho (trabalho em progresso) → revisão (pronto para alguém verificar) → aprovado (pronto para construir) → implementando (sendo construído) → concluído (terminado e verificado).",
       "success": "Spec {specId} atualizada para status {status}",
       "notImplemented": "update_status ainda não está implementado"
     },
     "estimate": {
-      "description": "Estimar esforço, custo e uso de tokens para uma spec usando análise multi-agente",
+      "description": "Calcular quanto tempo, esforço e custo vai levar para construir uma feature baseado no seu plano. Te dá horas de desenvolvimento, custos estimados de tokens de IA, e um nível de confiança baseado em trabalhos similares anteriores.",
       "success": "Estimativa completa para spec {specId} — {devHours}h dev, ${totalCostUsd} total",
       "notImplemented": "estimate ainda não está implementado"
     },
     "reverse_engineer": {
-      "description": "Analisar código existente e gerar uma spec SDD a partir dele",
+      "description": "Olhar código que já existe e criar um plano (spec) a partir dele. Útil quando você tem código funcionando mas sem documentação — isso gera uma planta do que o código faz.",
       "success": "Spec gerada por engenharia reversa de {path}",
       "notImplemented": "reverse_engineer ainda não está implementado"
     },
     "validate": {
-      "description": "Validar implementação contra sua spec — cobertura, drift e qualidade",
+      "description": "Verificar quanto de um plano foi realmente construído. Compara a planta (spec) com o código real e te diz: que porcentagem está pronta, quais arquivos estão faltando, e se o código está de acordo com o plano.",
       "success": "Validação completa: {score}% de cobertura",
       "notImplemented": "validate ainda não está implementado"
     },
     "detect_drift": {
-      "description": "Detectar drift entre spec e implementação",
+      "description": "Verificar se o código se afastou do plano original. Drift significa que o código mudou mas o plano não foi atualizado — como construir algo diferente da planta.",
       "success": "Análise de drift completa: {driftScore}% de drift detectado",
       "notImplemented": "detect_drift ainda não está implementado"
     },
     "summarize_spec": {
-      "description": "Gerar um resumo conciso de uma spec",
+      "description": "Gerar um resumo curto e fácil de ler de um plano. Útil quando você precisa de uma visão rápida sem ler a spec completa e detalhada.",
       "success": "Resumo gerado para spec {specId}",
       "notImplemented": "summarize_spec ainda não está implementado"
     },
     "generate_checklist": {
-      "description": "Gerar um checklist de qualidade para uma spec",
+      "description": "Criar um checklist de qualidade para um plano — uma lista de coisas para verificar antes de considerar a feature pronta. Cobre qualidade de código, testes, segurança e mais.",
       "success": "Checklist gerado: {totalCount} itens",
       "notImplemented": "generate_checklist ainda não está implementado"
     },
     "reconcile_spec": {
-      "description": "Reconciliar spec com mudanças de implementação",
+      "description": "Atualizar um plano para que corresponda ao que foi realmente construído. Quando o código muda durante o desenvolvimento, essa ferramenta sincroniza o plano com a realidade.",
       "success": "Spec {specId} reconciliada com {count} alterações",
       "notImplemented": "reconcile_spec ainda não está implementado"
     },
     "learn_pattern": {
-      "description": "Ensinar ao sistema um novo padrão (arquitetura, convenção, estimativa, stack, qualidade)",
+      "description": "Ensinar algo novo ao SpecForge sobre seu projeto — uma convenção de código, um padrão de arquitetura, uma regra de estimativa ou um padrão de qualidade. O SpecForge lembra e usa em planos futuros.",
       "success": "Padrão aprendido: {type} — {pattern}",
       "notImplemented": "learn_pattern ainda não está implementado"
     },
     "capture_learning": {
-      "description": "Capturar um padrão ou lição descoberta no sistema de specs com deduplicação semântica",
+      "description": "Salvar uma lição ou padrão que você descobriu trabalhando. O SpecForge verifica se já sabe disso (para evitar duplicatas) e arquiva no lugar certo para referência futura.",
       "success": "Padrão capturado e roteado para {specId}",
       "duplicate": "Padrão já coberto em {specId} ({similarity}% similaridade)",
       "lesson": "Lição capturada: {type}"
     },
     "audit": {
-      "description": "Auditar código por SOLID, código limpo, arquitetura, segurança e qualidade",
+      "description": "Executar um check-up de saúde no seu código. Analisa por práticas de código limpo, qualidade de arquitetura, problemas de segurança, e te dá uma pontuação de 0 a 100 com achados específicos para corrigir.",
       "success": "Auditoria completa: {score}/100 — {findingsCount} achados",
       "notImplemented": "audit ainda não está implementado"
     },
     "consult_docs": {
-      "description": "Consultar documentação do framework para um tópico específico",
+      "description": "Consultar documentação oficial do seu framework ou biblioteca sobre um tópico específico. Obtém a resposta sem você precisar sair da sua conversa.",
       "success": "Documentação encontrada para {framework}: {topic}",
       "notImplemented": "consult_docs ainda não está implementado"
     },
     "discover_mcps": {
-      "description": "Descobrir MCP servers configurados no ambiente",
+      "description": "Descobrir quais MCP servers (integrações de ferramentas de IA) estão configurados no seu ambiente. Mostra quais ferramentas seu assistente de IA já pode usar.",
       "success": "Descobertos {count} MCP servers",
       "notImplemented": "discover_mcps ainda não está implementado"
     },
     "suggest_mcps": {
-      "description": "Sugerir MCP servers que podem beneficiar o projeto",
+      "description": "Obter recomendações de MCP servers (integrações de ferramentas de IA) que podem ajudar seu projeto. Baseado no seu stack tecnológico e padrões, sugere ferramentas que podem estar faltando.",
       "success": "Encontrados {count} MCP servers recomendados",
       "notImplemented": "suggest_mcps ainda não está implementado"
     },
     "generate_adr": {
-      "description": "Gerar Architecture Decision Records para uma spec",
+      "description": "Criar um Registro de Decisão Arquitetural (ADR) — um documento que registra por que uma decisão técnica importante foi tomada. Por exemplo: 'Escolhemos PostgreSQL ao invés de MongoDB porque...' Mantém sua equipe alinhada sobre decisões passadas.",
       "success": "ADR gerado com {count} decisões",
       "notImplemented": "generate_adr ainda não está implementado"
     },
     "design_schema": {
-      "description": "Projetar schema de banco de dados a partir dos requisitos da spec",
+      "description": "Projetar a estrutura do banco de dados para uma feature baseado no seu plano. Cria as tabelas, campos, relacionamentos e índices que seus dados precisam.",
       "success": "Schema projetado: {tableCount} tabelas, {indexCount} índices",
       "notImplemented": "design_schema ainda não está implementado"
     },
     "define_ui_contract": {
-      "description": "Definir contratos de componentes UI, fluxo de dados e gerenciamento de estado",
+      "description": "Definir como seus componentes de interface funcionam — quais dados cada tela precisa, quais ações os usuários podem tomar, e como a informação flui entre componentes.",
       "success": "Contrato UI definido: {componentCount} componentes",
       "notImplemented": "define_ui_contract ainda não está implementado"
     },
     "challenge_spec": {
-      "description": "Testar uma spec contra falhas, concorrência, escala e casos extremos",
+      "description": "Testar um plano sob estresse simulando falhas, alto tráfego e casos extremos. Encontra pontos fracos antes de começar a construir — como um simulado de incêndio para o design da sua feature.",
       "success": "Challenge completo: {scenarioCount} cenários de falha analisados",
       "notImplemented": "challenge_spec ainda não está implementado"
     },
     "generate_execution_plan": {
-      "description": "Gerar um plano de execução passo a passo para implementar uma spec",
+      "description": "Criar um guia de implementação passo a passo para construir uma feature. Divide o trabalho em fases com tarefas claras, para você saber exatamente o que fazer e em que ordem.",
       "success": "Plano de execução gerado: {phaseCount} fases, {stepCount} passos",
       "notImplemented": "generate_execution_plan ainda não está implementado"
     },
     "suggest_stack": {
-      "description": "Sugerir um stack tecnológico baseado nos requisitos do projeto",
+      "description": "Obter uma recomendação tecnológica para seu projeto. Baseado no que você está construindo, sugere a melhor combinação de linguagem, framework, banco de dados e ferramentas.",
       "success": "Stack recomendado: {language}/{framework}",
       "notImplemented": "suggest_stack ainda não está implementado"
     },
     "check_versions": {
-      "description": "Verificar versões de dependências para atualizações, depreciações e problemas de segurança",
+      "description": "Verificar se as dependências do seu projeto (bibliotecas e pacotes) estão atualizadas. Encontra versões desatualizadas, vulnerabilidades de segurança e pacotes depreciados que precisam de atenção.",
       "success": "Verificadas {count} dependências: {updatesAvailable} atualizações, {securityAlerts} alertas de segurança",
       "notImplemented": "check_versions ainda não está implementado"
     },
     "generate_skill": {
-      "description": "Gerar um arquivo de skill de agente para uma plataforma específica",
+      "description": "Gerar um arquivo de skill de agente IA — um conjunto de instruções que ensina um assistente de código IA como realizar uma tarefa específica no seu projeto.",
       "success": "Skill '{name}' gerado para {platform}",
       "notImplemented": "generate_skill ainda não está implementado"
     },
     "detect_agent": {
-      "description": "Detectar a plataforma de agente de IA em uso",
+      "description": "Detectar qual assistente de código IA está sendo usado no seu projeto (Claude Code, Cursor, Copilot, Windsurf, etc.) para que o SpecForge gere o formato correto de arquivos de configuração.",
       "success": "Agente detectado: {platform} (confiança: {confidence}%)",
       "notImplemented": "detect_agent ainda não está implementado"
     },
     "generate_sub_agent": {
-      "description": "Gerar uma definição de sub-agente para orquestação multi-agente",
+      "description": "Criar uma definição de agente IA especializado para uma tarefa específica. Usado quando você quer múltiplos agentes de IA trabalhando em diferentes partes do seu projeto ao mesmo tempo.",
       "success": "Sub-agente '{agentName}' gerado para {framework}",
       "notImplemented": "generate_sub_agent ainda não está implementado"
     },
     "generate_rules": {
-      "description": "Gerar arquivos de regras de agente (.cursorrules, CLAUDE.md, etc.)",
+      "description": "Gerar arquivos de configuração para seu assistente de código IA — como CLAUDE.md para Claude Code, .cursorrules para Cursor, etc. Esses arquivos ensinam à IA as convenções do seu projeto.",
       "success": "Regras geradas para {platform}: {rulesCount} regras",
       "notImplemented": "generate_rules ainda não está implementado"
     },
     "generate_orchestration_script": {
-      "description": "Gerar script de automação paralela em 3 camadas (worktrees + claude -p)",
+      "description": "Gerar um script de automação que coordena múltiplos agentes de IA trabalhando em paralelo em diferentes features. Cada agente trabalha em seu próprio espaço isolado para evitar conflitos.",
       "success": "Script de orquestração gerado para {specCount} specs",
       "notImplemented": "generate_orchestration_script ainda não está implementado"
     },
     "suggest_tooling": {
-      "description": "Avaliar e sugerir ferramentas do ciclo de desenvolvimento (CI/CD, testes, monitoramento, etc.)",
+      "description": "Obter recomendações de ferramentas de desenvolvimento para todo seu fluxo de trabalho — pipelines CI/CD, frameworks de teste, monitoramento, ferramentas de qualidade de código e mais. Te dá uma pontuação de maturidade.",
       "success": "Avaliação de ferramentas completa: {maturityScore}/100",
       "notImplemented": "suggest_tooling ainda não está implementado"
     },
     "generate_tests": {
-      "description": "Gerar plano de testes e arquivos de teste a partir de uma spec",
+      "description": "Criar um plano de testes e arquivos de teste iniciais a partir de um plano de feature. Gera testes unitários, de integração e end-to-end baseados nos critérios de aceitação.",
       "success": "Plano de testes gerado: {unitCount} unitários, {integrationCount} integração, {e2eCount} e2e",
       "notImplemented": "generate_tests ainda não está implementado"
     },
     "generate_docs": {
-      "description": "Gerar documentação a partir de specs e código",
+      "description": "Gerar documentação a partir dos seus planos e código — referências de API, seções de README, resumos de arquitetura e mais.",
       "success": "Gerados {count} documentos",
       "notImplemented": "generate_docs ainda não está implementado"
     },
     "manage_context": {
-      "description": "Salvar, carregar e gerenciar notas de contexto persistentes entre sessões",
+      "description": "Salvar e recuperar notas importantes que persistem entre sessões. Use para lembrar decisões, restrições ou contexto que você quer que o SpecForge tenha em mente.",
       "success": "Contexto {action}: {key}",
       "notImplemented": "manage_context ainda não está implementado"
     },
     "manage_git": {
-      "description": "Integração Git — branches, PRs, changelogs, hooks vinculados a specs",
+      "description": "Integração Git para seu projeto — criar branches vinculados a planos, gerar descrições de pull requests, changelogs e configurar git hooks ligados às suas specs.",
       "success": "Git {action} concluído",
       "notImplemented": "manage_git ainda não está implementado"
     },
     "orchestrate": {
-      "description": "Orquestração multi-agente — registrar agentes, bloquear recursos, distribuir tarefas",
+      "description": "Coordenar múltiplos agentes de IA trabalhando no seu projeto — atribuir tarefas, bloquear arquivos para que agentes não entrem em conflito, e acompanhar o que cada agente está fazendo.",
       "success": "Orquestração {action} concluída",
       "notImplemented": "orchestrate ainda não está implementado"
     },
     "integrate_pm": {
-      "description": "Integrar com ferramentas de gestão de projetos (Jira, Linear, GitHub Issues, etc.)",
+      "description": "Conectar seus planos com ferramentas de gestão de projetos como Jira, Linear, GitHub Issues, Trello ou Notion. Cria tarefas e tickets diretamente das suas specs.",
       "success": "Integração PM: {action} em {platform}",
       "notImplemented": "integrate_pm ainda não está implementado"
     },
     "security_check": {
-      "description": "Analisar um spec contra OWASP Top 10, escanear código em busca de padrões inseguros, gerar pontuação de segurança (A-F) e detecção de drift",
+      "description": "Executar uma análise de segurança em um plano de feature — verifica contra vulnerabilidades comuns (OWASP Top 10), escaneia padrões de código inseguros, e te dá uma nota de segurança de A (excelente) a F (problemas críticos).",
       "success": "Verificação de segurança completa: {specId} — grau {grade}",
       "notImplemented": "security_check ainda não está implementado"
     },
     "data_governance": {
-      "description": "Detectar PII em specs, gerar políticas de retenção, redigir avisos de privacidade e auditar conformidade com GDPR/CCPA/LGPD",
+      "description": "Verificar seus planos quanto ao tratamento de dados pessoais. Encontra campos que contêm informações pessoais (nomes, emails, etc.), gera políticas de retenção de dados, redige avisos de privacidade e audita conformidade com leis de privacidade como GDPR, CCPA e LGPD.",
       "detectSuccess": "Detecção de PII concluída — {count} campo(s) encontrado(s), hasPII: {hasPII}",
       "retentionSuccess": "Política de retenção gerada para o modelo: {model}",
       "privacyNoticeSuccess": "Rascunho de aviso de privacidade gerado — {count} spec(s) com PII",
       "auditSuccess": "Auditoria de privacidade concluída — {total} spec(s) revisados, {nonCompliant} não conformes"
     },
     "migrate_tech": {
-      "description": "Guiar a migração de stack tecnológico (linguagem, framework, BD, serviços): analisar codebase origem, mapear equivalências, gerar plano de migração, recomendar estratégia de transição, validar paridade funcional e planejar migração de BD",
+      "description": "Guiar você na mudança do seu projeto de uma tecnologia para outra — por exemplo, de Express para Fastify, ou de MySQL para PostgreSQL. Analisa seu código atual, mapeia equivalências, cria um plano de migração passo a passo e ajuda a validar que tudo continua funcionando.",
       "analyzeSuccess": "Análise do stack origem concluída — revisar contratos implícitos e componentes quentes antes de migrar",
       "mapSuccess": "Mapa de equivalências gerado — revisar mapeamentos manuais e diferenças antes de continuar",
       "planSuccess": "Plano de migração gerado com specs ordenados e resolução de dependências circulares",
@@ -282,26 +282,26 @@
       "analyzeDbSuccess": "Schema de banco de dados analisado — revisar schema, ORM e volume estimado de dados",
       "mapDbSuccess": "Mapeamento de tipos de BD gerado — todos os avisos de perda de dados devem ser revisados antes de migrar",
       "planDbSuccess": "Plano de migração de BD gerado com abordagem em fases e estratégia de rollback",
-      "analyzeServicesSuccess": "External services analysis complete — review critical services and migration priorities",
-      "mapServicesSuccess": "Service equivalence map generated — review adapters and behavior differences",
-      "planServicesSuccess": "Service migration plan generated — stateless services scheduled first",
-      "validateServiceSuccess": "Service validation checklist generated — fill in expected values from your baseline",
-      "rollbackPlanSuccess": "Rollback plan generated — review irreversible steps and checkpoint conditions",
-      "checkpointSuccess": "Migration checkpoint recorded — use this ID to rollback to this state if needed",
-      "rollbackSuccess": "Rollback execution plan generated — confirm each manual step before proceeding",
-      "featureFlagsSuccess": "Feature flag spec generated — configure your provider and set expiration date",
-      "statusSuccess": "Migration status report generated — update completed components as specs are finished"
+      "analyzeServicesSuccess": "Análise de serviços externos concluída — revisar serviços críticos e prioridades de migração",
+      "mapServicesSuccess": "Mapa de equivalência de serviços gerado — revisar adaptadores e diferenças de comportamento",
+      "planServicesSuccess": "Plano de migração de serviços gerado — serviços sem estado agendados primeiro",
+      "validateServiceSuccess": "Checklist de validação de serviços gerado — preencher valores esperados do seu baseline",
+      "rollbackPlanSuccess": "Plano de rollback gerado — revisar passos irreversíveis e condições de checkpoint",
+      "checkpointSuccess": "Checkpoint de migração registrado — use este ID para fazer rollback a este estado se necessário",
+      "rollbackSuccess": "Plano de execução de rollback gerado — confirmar cada passo manual antes de proceder",
+      "featureFlagsSuccess": "Spec de feature flags gerada — configure seu provedor e defina data de expiração",
+      "statusSuccess": "Relatório de status de migração gerado — atualizar componentes concluídos conforme specs são finalizados"
     },
     "paradigm_report": {
-      "description": "Detectar e reportar os paradigmas de programação usados em um projeto",
+      "description": "Analisar seu projeto e reportar quais estilos de programação (paradigmas) são usados — orientado a objetos, funcional, procedural, reativo, etc. Ajuda a entender os padrões do código.",
       "success": "Relatório de paradigmas gerado: {dominant} detectado",
       "notFound": "Projeto não encontrado. Execute init_project primeiro."
     },
     "check_readiness": {
-      "description": "Avaliar se uma spec está pronta para implementação verificando completude, qualidade dos critérios e status das dependências"
+      "description": "Verificar se um plano tem detalhes suficientes para começar a construir. Verifica se a descrição está completa, se os critérios de aceitação estão claros e se todas as dependências estão atendidas. Te diz se o plano está pronto ou o que está faltando."
     },
     "package_handoff": {
-      "description": "Gerar um pacote de handoff estruturado para um agente AI implementar uma spec, incluindo objetivo, critérios, arquivos, fora do escopo e restrições"
+      "description": "Criar um pacote completo de instruções para um agente de IA implementar uma feature. Inclui o objetivo, critérios de aceitação, lista de arquivos, o que está fora do escopo e quaisquer restrições — tudo que o agente precisa para começar."
     }
   },
   "resources": {