refacil-sdd-ai 5.0.0 → 5.0.1

package/README.md

@@ -29,8 +29,8 @@ refacil-sdd-ai init
 #    whose folder already exists. Use --all to install for all three without prompting.
 #    Copies skills and sub-agents to the selected IDEs, configures hooks,
 #    and creates/updates .claudeignore, .cursorignore and .opencodeignore.
-#    Also prompts for global branch config (baseBranch, protectedBranches) pre-filled
-#    from ~/.refacil-sdd-ai/config.yaml. Skipped with --yes or --defaults.
+#    Also prompts for global branch config (baseBranch, protectedBranches, artifactLanguage)
+#    pre-filled from ~/.refacil-sdd-ai/config.yaml. Skipped with --yes or --defaults.
 
 # 3. Restart your IDE session
 #    (new skills are not detected until you restart)
@@ -102,11 +102,43 @@ Native CLI for **`refacil-sdd/`** (no separate OpenSpec skill layer). Used by sk
 | `refacil-sdd-ai sdd tasks-update <name>` | Mark a task done (`--task N --done`) |
 | `refacil-sdd-ai sdd archive <name>` | Move a regular change to `refacil-sdd/changes/archive/` |
 | `refacil-sdd-ai sdd validate-name <name>` | Validate change folder name (must start with a letter) |
-| `refacil-sdd-ai sdd config [--json]` | Show effective branch configuration (protectedBranches, baseBranch) after cascade: project `refacil-sdd/config.yaml` → global `~/.refacil-sdd-ai/config.yaml` → built-in defaults |
-| `refacil-sdd-ai sdd write-config [--global] [--base-branch <v>] [--protected-branches <csv>]` | Write or merge branch config into `refacil-sdd/config.yaml` (project) or `~/.refacil-sdd-ai/config.yaml` (`--global`). Performs a semantic no-op check — skips rewrite if values are already set. Directory is auto-created if absent. |
+| `refacil-sdd-ai sdd config [--json]` | Show effective configuration (protectedBranches, baseBranch, artifactLanguage) after cascade: project `refacil-sdd/config.yaml` → global `~/.refacil-sdd-ai/config.yaml` → built-in defaults. `--json` also includes a `sources` field indicating the resolution level for each value (`project`, `global`, or `default`). |
+| `refacil-sdd-ai sdd write-config [--global] [--base-branch <v>] [--protected-branches <csv>] [--artifact-language <lang>]` | Write or merge config into `refacil-sdd/config.yaml` (project) or `~/.refacil-sdd-ai/config.yaml` (`--global`). Performs a semantic no-op check — skips rewrite if values are already set. Directory is auto-created if absent. |
 
 Run **`refacil-sdd-ai help`** for the full list including `bus` and `compact` subcommands.
 
+### Artifact Language
+
+By default, `/refacil:propose` generates proposal, specs, design, and tasks in **English**. Set `artifactLanguage` to have the artifacts produced in your team's preferred language so developers can review them in their natural language.
+
+**Supported values**: `english` (default) · `spanish`
+
+**Configure globally** — applies to all repos for this user:
+
+```bash
+refacil-sdd-ai sdd write-config --global --artifact-language spanish
+```
+
+**Configure per project** — overrides the global value (commit `refacil-sdd/config.yaml` for team-wide effect):
+
+```bash
+refacil-sdd-ai sdd write-config --artifact-language spanish
+```
+
+**Check the active value**:
+
+```bash
+refacil-sdd-ai sdd config
+# artifactLanguage [global]: spanish
+
+refacil-sdd-ai sdd config --json
+# { ..., "artifactLanguage": "spanish", "sources": { "artifactLanguage": "global" } }
+```
+
+**Cascade**: project `refacil-sdd/config.yaml` → global `~/.refacil-sdd-ai/config.yaml` → default `english`.
+
+`refacil-sdd-ai init` also prompts for this preference and writes to the global config. Skip with `--yes` to keep the current value.
+
 ### Command rewrite control (`compact-bash`)
 
 | Command | Description |
@@ -380,7 +412,7 @@ Defined in `skills/prereqs/METHODOLOGY-CONTRACT.md`:
 - **Multi-stack tests**: detects the real test command (does not hardcode `npm test`).
 - **`AGENTS.md` by profile** (`sdd` vs `agents`): the methodology respects both.
 - **Output mode**: concise by default, detailed on demand.
-- **Language policy**: internal agent and skill instructions are in **English**. Responses to the user are in the **user's language** (default: Spanish). SDD artifacts are in the **team's agreed language**.
+- **Language policy**: internal agent and skill instructions are in **English**. Responses to the user are in the **user's language** (default: Spanish). SDD artifact language (proposal, specs, design, tasks) defaults to **English** and is configurable via `artifactLanguage` — see [Artifact Language](#artifact-language).
 
 ---
 

package/agents/proposer.md

@@ -153,6 +153,18 @@ Effort estimate: **S** (< 1h), **M** (1-4h), **L** (> 4h).
 
 ### Step 1: Explore the codebase
 
+#### Step 1a: Language resolution (run FIRST, before any exploration)
+
+Run: `refacil-sdd-ai sdd config --json`
+
+Read the `artifactLanguage` field from the JSON output. Prepend the following instruction to your working context for this session:
+
+> Generate ALL artifact content (proposal.md, specs.md, design.md, tasks.md) in **<artifactLanguage>** language. This applies to all prose, comments, labels, and descriptions inside the artifact files.
+
+Fallback rule: if the command fails, produces invalid JSON, or returns an unknown/missing `artifactLanguage` value, use `english` and continue without interruption.
+
+#### Step 1b: Codebase exploration
+
 Before generating artifacts, explore the project so that `design.md` is realistic and not invented:
 - Read `AGENTS.md` to understand the current architecture.
 - Identify files and modules relevant to the described change.

package/bin/cli.js

@@ -416,19 +416,22 @@ async function promptBranchConfig() {
   if (skipFlags.some((f) => process.argv.includes(f))) return;
   if (!process.stdout.isTTY) return;
 
-  const { readConfigFile, DEFAULT_PROTECTED_BRANCHES, DEFAULT_BASE_BRANCH } = require('../lib/config');
+  const { readConfigFile, DEFAULT_PROTECTED_BRANCHES, DEFAULT_BASE_BRANCH, SUPPORTED_LANGUAGES, DEFAULT_ARTIFACT_LANGUAGE } = require('../lib/config');
   const globalConfigPath = path.join(os.homedir(), '.refacil-sdd-ai', 'config.yaml');
   const globalConfig = readConfigFile(globalConfigPath) || {};
   const currentBaseBranch = (typeof globalConfig.baseBranch === 'string' && globalConfig.baseBranch.trim()) ? globalConfig.baseBranch.trim() : DEFAULT_BASE_BRANCH;
   const currentProtected = (Array.isArray(globalConfig.protectedBranches) && globalConfig.protectedBranches.length > 0) ? globalConfig.protectedBranches : DEFAULT_PROTECTED_BRANCHES;
+  const currentArtifactLanguage = (typeof globalConfig.artifactLanguage === 'string' && SUPPORTED_LANGUAGES.includes(globalConfig.artifactLanguage.trim())) ? globalConfig.artifactLanguage.trim() : DEFAULT_ARTIFACT_LANGUAGE;
 
   console.log('\n  Branch configuration (global, stored in ~/.refacil-sdd-ai/config.yaml)');
   console.log(`  Current base branch:        ${currentBaseBranch}`);
   console.log(`  Current protected branches: ${currentProtected.join(', ')}`);
+  console.log(`  Current artifact language:  ${currentArtifactLanguage}`);
   console.log('  Press Enter to keep current values, or type new ones.\n');
 
   let baseBranch;
   let protectedBranches;
+  let artifactLanguage;
 
   try {
     const clack = require('@clack/prompts');
@@ -455,8 +458,20 @@ async function promptBranchConfig() {
     }
     protectedBranches = parseBranchList((pbResult && pbResult.trim()) ? pbResult.trim() : currentProtected.join(', '), currentProtected);
 
+    const alResult = await clack.text({
+      message: `Artifact language — ${SUPPORTED_LANGUAGES.join(' | ')} (current: ${currentArtifactLanguage}):`,
+      placeholder: currentArtifactLanguage,
+      validate: () => undefined,
+    });
+    if (clack.isCancel(alResult)) {
+      console.log('  Branch config prompt cancelled. Keeping existing values.\n');
+      return;
+    }
+    const alRaw = (alResult && alResult.trim()) ? alResult.trim() : currentArtifactLanguage;
+    artifactLanguage = SUPPORTED_LANGUAGES.includes(alRaw) ? alRaw : currentArtifactLanguage;
+
     const confirm = await clack.confirm({
-      message: `Save global config — base: "${baseBranch}", protected: [${protectedBranches.join(', ')}]?`,
+      message: `Save global config — base: "${baseBranch}", protected: [${protectedBranches.join(', ')}], language: ${artifactLanguage}?`,
       initialValue: true,
     });
     if (clack.isCancel(confirm) || !confirm) {
@@ -475,7 +490,11 @@ async function promptBranchConfig() {
     const pbAnswer = await ask(`  Protected branches [${currentProtected.join(', ')}]: `);
     protectedBranches = parseBranchList((pbAnswer && pbAnswer.trim()) ? pbAnswer.trim() : currentProtected.join(', '), currentProtected);
 
-    const confirmAnswer = await ask(`  Save global config — base: "${baseBranch}", protected: [${protectedBranches.join(', ')}]? (Y/n): `);
+    const alAnswer = await ask(`  Artifact language [${currentArtifactLanguage}] (${SUPPORTED_LANGUAGES.join('/')}): `);
+    const alRaw = (alAnswer && alAnswer.trim()) ? alAnswer.trim() : currentArtifactLanguage;
+    artifactLanguage = SUPPORTED_LANGUAGES.includes(alRaw) ? alRaw : currentArtifactLanguage;
+
+    const confirmAnswer = await ask(`  Save global config — base: "${baseBranch}", protected: [${protectedBranches.join(', ')}], language: ${artifactLanguage}? (Y/n): `);
     rl.close();
     if (confirmAnswer.trim().toLowerCase() === 'n') {
       console.log('  Branch config not saved.\n');
@@ -483,19 +502,22 @@ async function promptBranchConfig() {
     }
   }
 
-  // Fix 2: pre-check to avoid process.exit(0) from cmdWriteConfig no-op path when called programmatically
+  // Pre-check to avoid process.exit(0) from cmdWriteConfig no-op path when called programmatically
   const valuesUnchanged = baseBranch === currentBaseBranch &&
-    JSON.stringify(protectedBranches.slice().sort()) === JSON.stringify(currentProtected.slice().sort());
+    JSON.stringify(protectedBranches.slice().sort()) === JSON.stringify(currentProtected.slice().sort()) &&
+    artifactLanguage === currentArtifactLanguage;
   if (valuesUnchanged) {
     console.log('  Branch config unchanged. Keeping existing values.\n');
     return;
   }
 
   // Build argv-style array and call cmdWriteConfig directly
+  // Only write artifactLanguage if user chose a non-default value
   const writeArgv = [
     '--global',
     '--base-branch', baseBranch,
     '--protected-branches', protectedBranches.join(','),
+    '--artifact-language', artifactLanguage,
   ];
   try {
     cmdWriteConfig(writeArgv, projectRoot);
@@ -798,6 +820,7 @@ function help() {
                       [--global]                    Write to ~/.refacil-sdd-ai/config.yaml (global level)
                       [--base-branch <branch>]      Base branch for new changes
                       [--protected-branches <csv>]  Protected branches (comma-separated)
+                      [--artifact-language <lang>]  Artifact language: english (default) or spanish
     clean         Remove skills and SDD-AI hooks from all detected IDEs
                   (.claude/settings.json, .cursor/hooks.json, .opencode/plugins/)
     help          Show this help

package/lib/commands/sdd.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { loadBranchConfigWithSources, parseYaml, readConfigFile } = require('../config');
+const { loadBranchConfigWithSources, parseYaml, readConfigFile, SUPPORTED_LANGUAGES } = require('../config');
 
 function findProjectRoot() {
   let dir = process.cwd();
@@ -634,13 +634,14 @@ function cmdConfig(argv, projectRoot) {
   const args = parseArgs(argv);
   const wantJson = args.json === true;
 
-  const { protectedBranches, baseBranch, sources } = loadBranchConfigWithSources(projectRoot);
+  const { protectedBranches, baseBranch, artifactLanguage, sources } = loadBranchConfigWithSources(projectRoot);
 
   if (wantJson) {
-    process.stdout.write(JSON.stringify({ protectedBranches, baseBranch }) + '\n');
+    process.stdout.write(JSON.stringify({ protectedBranches, baseBranch, artifactLanguage, sources }) + '\n');
   } else {
     console.log(`protectedBranches [${sources.protectedBranches}]: ${protectedBranches.join(', ')}`);
     console.log(`baseBranch [${sources.baseBranch}]: ${baseBranch}`);
+    console.log(`artifactLanguage [${sources.artifactLanguage}]: ${artifactLanguage}`);
   }
 }
 
@@ -651,11 +652,12 @@ function cmdWriteConfig(argv, projectRoot) {
   const isGlobal = args.global === true;
   const rawBaseBranch = args['base-branch'];
   const rawProtectedBranches = args['protected-branches'];
+  const rawArtifactLanguage = args['artifact-language'];
 
   // CR-03: no flags provided
-  if (rawBaseBranch === undefined && rawProtectedBranches === undefined) {
-    console.error('Uso: refacil-sdd-ai sdd write-config [--global] [--base-branch <branch>] [--protected-branches <csv>]');
-    console.error('Debe especificar al menos --base-branch o --protected-branches.');
+  if (rawBaseBranch === undefined && rawProtectedBranches === undefined && rawArtifactLanguage === undefined) {
+    console.error('Uso: refacil-sdd-ai sdd write-config [--global] [--base-branch <branch>] [--protected-branches <csv>] [--artifact-language <language>]');
+    console.error('Debe especificar al menos --base-branch, --protected-branches o --artifact-language.');
     process.exit(1);
   }
 
@@ -675,6 +677,18 @@ function cmdWriteConfig(argv, projectRoot) {
     }
   }
 
+  // --artifact-language: must be non-empty and in SUPPORTED_LANGUAGES
+  if (rawArtifactLanguage !== undefined) {
+    if (typeof rawArtifactLanguage !== 'string' || rawArtifactLanguage.trim() === '') {
+      console.error('Error: --artifact-language no puede estar vacío.');
+      process.exit(1);
+    }
+    if (!SUPPORTED_LANGUAGES.includes(rawArtifactLanguage.trim())) {
+      console.error(`Error: --artifact-language "${rawArtifactLanguage.trim()}" no es un lenguaje soportado. Valores válidos: ${SUPPORTED_LANGUAGES.join(', ')}.`);
+      process.exit(1);
+    }
+  }
+
   const targetPath = isGlobal
     ? path.join(os.homedir(), '.refacil-sdd-ai', 'config.yaml')
     : path.join(projectRoot, 'refacil-sdd', 'config.yaml');
@@ -690,13 +704,17 @@ function cmdWriteConfig(argv, projectRoot) {
   if (protectedBranchesList !== undefined) {
     merged.protectedBranches = protectedBranchesList;
   }
+  if (rawArtifactLanguage !== undefined) {
+    merged.artifactLanguage = rawArtifactLanguage.trim();
+  }
 
   // CA-03: no-op when all provided keys already match existing config (semantic comparison)
   const isNoOp = Object.keys(existing).length > 0 &&
     (rawBaseBranch === undefined || existing.baseBranch === rawBaseBranch.trim()) &&
     (protectedBranchesList === undefined ||
       (Array.isArray(existing.protectedBranches) &&
-       JSON.stringify(existing.protectedBranches.slice().sort()) === JSON.stringify(protectedBranchesList.slice().sort())));
+       JSON.stringify(existing.protectedBranches.slice().sort()) === JSON.stringify(protectedBranchesList.slice().sort()))) &&
+    (rawArtifactLanguage === undefined || existing.artifactLanguage === rawArtifactLanguage.trim());
   if (isNoOp) {
     console.log(`Sin cambios: ${targetPath} ya tiene los valores indicados.`);
     process.exit(0);
@@ -709,7 +727,7 @@ function cmdWriteConfig(argv, projectRoot) {
   fs.writeFileSync(targetPath, proposed, 'utf8');
 
   const level = isGlobal ? 'global' : 'proyecto';
-  console.log(`Configuración de ramas escrita en ${targetPath} (nivel: ${level})`);
+  console.log(`Configuración escrita en ${targetPath} (nivel: ${level})`);
 }
 
 function sddHelp() {
@@ -745,11 +763,12 @@ function sddHelp() {
     sdd config [--json]                Muestra la configuración efectiva de ramas
                                          (project > global > defaults)
       [--json]                           Salida en JSON (útil para agentes)
-    sdd write-config                   Escribe la configuración de ramas en el archivo de config
+    sdd write-config                   Escribe la configuración en el archivo de config
       [--global]                         Escribe en ~/.refacil-sdd-ai/config.yaml (global)
                                          Sin --global: escribe en refacil-sdd/config.yaml (proyecto)
       [--base-branch <branch>]           Rama base para nuevos cambios
       [--protected-branches <csv>]       Ramas protegidas (separadas por coma)
+      [--artifact-language <language>]   Idioma para los artefactos SDD generados (english, spanish)
 
   Notas:
     - Los nombres de cambio deben empezar con minúscula y usar solo [a-z0-9-]

package/lib/config.js

@@ -6,6 +6,8 @@ const os = require('os');
 
 const DEFAULT_PROTECTED_BRANCHES = ['master', 'main', 'develop', 'dev', 'testing', 'qa'];
 const DEFAULT_BASE_BRANCH = 'develop';
+const SUPPORTED_LANGUAGES = ['english', 'spanish'];
+const DEFAULT_ARTIFACT_LANGUAGE = 'english';
 
 // Minimal YAML parser — supports string scalars and string-array values only.
 function parseYaml(content) {
@@ -86,6 +88,31 @@ function extractProtectedBranches(cfg, src) {
   return val;
 }
 
+/**
+ * Validate `artifactLanguage` from a parsed config object.
+ * Returns the value if valid, or null + emits a warning if unknown.
+ * @param {object} cfg  — parsed YAML object
+ * @param {string} src  — source label for the warning ('project' | 'global')
+ */
+function extractArtifactLanguage(cfg, src) {
+  if (!('artifactLanguage' in cfg)) return null;
+  const val = cfg.artifactLanguage;
+  if (typeof val !== 'string' || val.trim() === '') {
+    process.stderr.write(
+      `[refacil-sdd-ai] warning: artifactLanguage in ${src} config must be a non-empty string — ignoring.\n`,
+    );
+    return null;
+  }
+  const trimmed = val.trim();
+  if (!SUPPORTED_LANGUAGES.includes(trimmed)) {
+    process.stderr.write(
+      `[refacil-sdd-ai] warning: artifactLanguage "${trimmed}" in ${src} config is not a supported language (${SUPPORTED_LANGUAGES.join(', ')}) — ignoring.\n`,
+    );
+    return null;
+  }
+  return trimmed;
+}
+
 /**
  * Validate `baseBranch` from a parsed config object.
  * Returns the value if valid, or null + emits a warning if invalid.
@@ -184,12 +211,39 @@ function loadBranchConfigWithSources(projectRoot) {
     baseBranchSource = 'default';
   }
 
+  // --- artifactLanguage ---
+  let artifactLanguage = null;
+  let artifactLanguageSource = 'default';
+
+  if (projectCfg !== null) {
+    const val = extractArtifactLanguage(projectCfg, 'project');
+    if (val !== null) {
+      artifactLanguage = val;
+      artifactLanguageSource = 'project';
+    }
+  }
+
+  if (artifactLanguage === null && globalCfg !== null) {
+    const val = extractArtifactLanguage(globalCfg, 'global');
+    if (val !== null) {
+      artifactLanguage = val;
+      artifactLanguageSource = 'global';
+    }
+  }
+
+  if (artifactLanguage === null) {
+    artifactLanguage = DEFAULT_ARTIFACT_LANGUAGE;
+    artifactLanguageSource = 'default';
+  }
+
   return {
     protectedBranches,
     baseBranch,
+    artifactLanguage,
     sources: {
       protectedBranches: protectedBranchesSource,
       baseBranch: baseBranchSource,
+      artifactLanguage: artifactLanguageSource,
     },
   };
 }
@@ -202,8 +256,8 @@ function loadBranchConfigWithSources(projectRoot) {
  * @param {string} projectRoot  — absolute path to the project root
  */
 function loadBranchConfig(projectRoot) {
-  const { protectedBranches, baseBranch } = loadBranchConfigWithSources(projectRoot);
-  return { protectedBranches, baseBranch };
+  const { protectedBranches, baseBranch, artifactLanguage } = loadBranchConfigWithSources(projectRoot);
+  return { protectedBranches, baseBranch, artifactLanguage };
 }
 
 module.exports = {
@@ -211,6 +265,9 @@ module.exports = {
   readConfigFile,
   loadBranchConfig,
   loadBranchConfigWithSources,
+  extractArtifactLanguage,
   DEFAULT_PROTECTED_BRANCHES,
   DEFAULT_BASE_BRANCH,
+  SUPPORTED_LANGUAGES,
+  DEFAULT_ARTIFACT_LANGUAGE,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor and OpenCode",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/propose/SKILL.md

@@ -45,9 +45,14 @@ Communicate the final agreed slug to the user before generating.
 
 ### Step 2: Delegate to the refacil-proposer sub-agent
 
+Before delegating, resolve the artifact language:
+
+Run `refacil-sdd-ai sdd config --json` and read the `artifactLanguage` field. If the command fails or the field is missing/unknown, use `english`.
+
 Invoke the `refacil-proposer` sub-agent passing it:
 - `changeName`: the valid slug agreed in Step 1.5.
 - `description`: complete description of the change (from Step 1 or from `$ARGUMENTS`).
+- `artifactLanguage`: the resolved language (e.g. `english` or `spanish`). Pass it explicitly so the sub-agent uses it immediately, before it reads AGENTS.md.
 
 The sub-agent:
 - Explores the codebase (reads `AGENTS.md`, detects relevant files and conventions) before generating.