@guilhermefsousa/open-spec-kit 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guilhermefsousa/open-spec-kit",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "CLI para spec-driven development com suporte a Claude Code e GitHub Copilot",
   "type": "module",
   "bin": {
@@ -16,15 +16,18 @@
   ],
   "scripts": {
     "start": "node bin/open-spec-kit.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "node bin/open-spec-kit.js --version"
   },
   "dependencies": {
+    "chalk": "^5.4.0",
     "commander": "^13.0.0",
     "inquirer": "^12.0.0",
-    "chalk": "^5.4.0",
     "ora": "^8.0.0",
-    "zod": "^3.24.0",
-    "yaml": "^2.7.0"
+    "yaml": "^2.7.0",
+    "zod": "^3.24.0"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -47,5 +50,9 @@
   "homepage": "https://github.com/guilhermefsousa/open-spec-kit#readme",
   "bugs": {
     "url": "https://github.com/guilhermefsousa/open-spec-kit/issues"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "vitest": "^4.1.4"
   }
 }

package/src/commands/doctor.js

@@ -3,6 +3,8 @@ import { readFile, access } from 'fs/promises';
 import { join } from 'path';
 import { execSync } from 'child_process';
 import yaml from 'yaml';
+import { detectMcpRunner, getInstallInstructions } from '../utils/mcp-detect.js';
+import { confluenceRequest, figmaRequest } from '../utils/http.js';
 
 export async function doctorCommand() {
   console.log(chalk.bold('\n  open-spec-kit doctor\n'));
@@ -159,22 +161,29 @@ export async function doctorCommand() {
     fail++;
   }
 
-  // Check 7: MCP CLI available — verify Python version too
-  try {
-    const whereCmd = process.platform === 'win32' ? 'where mcp-atlassian' : 'which mcp-atlassian';
-    execSync(whereCmd, { stdio: 'pipe', timeout: 5000 });
-    console.log(chalk.green('  ✓ mcp-atlassian disponivel no PATH'));
+  // Check 7: MCP CLI available — detect best runner (direct, uvx, pipx)
+  const mcpRunner = detectMcpRunner();
+  if (mcpRunner.method !== 'pip-fallback') {
+    const via = mcpRunner.method === 'direct' ? 'PATH' : mcpRunner.method;
+    console.log(chalk.green(`  ✓ mcp-atlassian disponível via ${via} (${mcpRunner.command}${mcpRunner.prefix.length > 0 ? ' ' + mcpRunner.prefix.join(' ') : ''})`));
     pass++;
-  } catch {
-    console.log(chalk.yellow('  ⚠ mcp-atlassian nao encontrado'));
-    console.log(chalk.dim('  Instale com: pip install mcp-atlassian  (requer Python >= 3.10)'));
+  } else {
+    console.log(chalk.yellow('  ⚠ mcp-atlassian não encontrado (nem direto, nem via uvx/pipx)'));
+    for (const line of getInstallInstructions()) {
+      console.log(chalk.dim(`    ${line}`));
+    }
     fail++;
   }
 
   // Check 7b: Python version >= 3.10 (required by mcp-atlassian)
+  // Try python3 first (Linux/macOS default), fall back to python (Windows default)
   try {
-    const pyCmd = process.platform === 'win32' ? 'python --version' : 'python3 --version';
-    const pyVersion = execSync(pyCmd, { stdio: 'pipe', timeout: 5000 }).toString().trim();
+    let pyVersion;
+    try {
+      pyVersion = execSync('python3 --version', { stdio: 'pipe', timeout: 5000 }).toString().trim();
+    } catch {
+      pyVersion = execSync('python --version', { stdio: 'pipe', timeout: 5000 }).toString().trim();
+    }
     const match = pyVersion.match(/(\d+)\.(\d+)/);
     if (match) {
       const major = Number(match[1]);
@@ -229,13 +238,8 @@ export async function doctorCommand() {
   if (hasFigma) {
     if (claudeMcpContent) {
       if (claudeMcpContent.includes('"figma"')) {
-        if (claudeMcpContent.includes('SEU-FIGMA-API-KEY')) {
-          console.log(chalk.yellow('  ⚠ .mcp.json tem servidor Figma mas com placeholder'));
-          fail++;
-        } else {
-          console.log(chalk.green('  ✓ .mcp.json (Claude) tem servidor Figma configurado'));
-          pass++;
-        }
+        console.log(chalk.green('  ✓ .mcp.json (Claude) tem servidor Figma configurado'));
+        pass++;
       } else {
         console.log(chalk.yellow('  ⚠ projects.yml tem figma: mas .mcp.json não tem servidor figma'));
         fail++;
@@ -252,62 +256,75 @@ export async function doctorCommand() {
     }
   }
 
-  // Check 11: Confluence credentials — make real HTTP call to validate token
+  // Parse .env once for credential checks (11 + 12)
+  let envVars = {};
   try {
     const envContent = await readFile(join(cwd, '.env'), 'utf-8');
-    const envVars = Object.fromEntries(
+    envVars = Object.fromEntries(
       envContent.split('\n')
         .filter(l => l.includes('=') && !l.startsWith('#'))
         .map(l => { const idx = l.indexOf('='); return [l.slice(0, idx).trim(), l.slice(idx + 1).trim()]; }),
     );
+  } catch {
+    // .env not found — already warned by MCP config check
+  }
+
+  const isPlaceholder = (v) => !v || v.includes('seu-') || v.includes('SEU-') || v === 'seu-api-token-aqui' || v === 'seu-figma-api-key';
 
+  // Check 11: Confluence credentials — make real HTTP call to validate token
+  {
     const confUrl = envVars.CONFLUENCE_URL;
-    const confUser = envVars.CONFLUENCE_USER;
+    const confUser = envVars.CONFLUENCE_USERNAME;
     const confToken = envVars.CONFLUENCE_API_TOKEN;
 
-    const isPlaceholder = (v) => !v || v.includes('seu-') || v.includes('SEU-') || v === 'seu-api-token-aqui';
-
     if (isPlaceholder(confUrl) || isPlaceholder(confUser) || isPlaceholder(confToken)) {
       console.log(chalk.yellow('  ⚠ .env não configurado — pular validação de credenciais Confluence'));
-      console.log(chalk.dim('  Configure CONFLUENCE_URL, CONFLUENCE_USER e CONFLUENCE_API_TOKEN no .env'));
+      console.log(chalk.dim('  Configure CONFLUENCE_URL, CONFLUENCE_USERNAME e CONFLUENCE_API_TOKEN no .env'));
       fail++;
     } else {
-      const basicAuth = Buffer.from(`${confUser}:${confToken}`).toString('base64');
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), 10000);
-
       try {
-        const res = await fetch(`${confUrl}/rest/api/space?limit=1`, {
-          headers: { Authorization: `Basic ${basicAuth}`, Accept: 'application/json' },
-          signal: controller.signal,
-        });
-        clearTimeout(timeout);
-
-        if (res.ok) {
-          console.log(chalk.green('  ✓ Credenciais Confluence válidas (token ativo)'));
-          pass++;
-        } else if (res.status === 401 || res.status === 403) {
-          console.log(chalk.red('  ✗ Token Confluence inválido ou expirado (HTTP ' + res.status + ')'));
+        await confluenceRequest(confUrl, '/rest/api/space?limit=1', confUser, confToken, 10000);
+        console.log(chalk.green('  ✓ Credenciais Confluence válidas (token ativo)'));
+        pass++;
+      } catch (err) {
+        if (err.status === 401 || err.status === 403) {
+          console.log(chalk.red(`  ✗ Token Confluence inválido ou expirado (HTTP ${err.status})`));
           console.log(chalk.dim('  Renove em: https://id.atlassian.com/manage-profile/security/api-tokens'));
           console.log(chalk.dim('  Atualize CONFLUENCE_API_TOKEN no .env'));
           fail++;
         } else {
-          console.log(chalk.yellow(`  ⚠ Confluence respondeu HTTP ${res.status} — verifique CONFLUENCE_URL`));
+          console.log(chalk.yellow(`  ⚠ Não foi possível verificar credenciais Confluence: ${err.message}`));
           fail++;
         }
-      } catch (fetchErr) {
-        clearTimeout(timeout);
-        if (fetchErr.name === 'AbortError') {
-          console.log(chalk.yellow('  ⚠ Confluence não respondeu em 10s — sem rede ou URL incorreta'));
+      }
+    }
+  }
+
+  // Check 12: Figma credentials — make real HTTP call to validate token
+  if (hasFigma) {
+    const figmaKey = envVars.FIGMA_API_KEY;
+
+    if (isPlaceholder(figmaKey)) {
+      console.log(chalk.yellow('  ⚠ FIGMA_API_KEY não configurado no .env'));
+      console.log(chalk.dim('  Gere em: Figma > Account Settings > Personal Access Tokens'));
+      fail++;
+    } else {
+      try {
+        const result = await figmaRequest(figmaKey, 10000);
+        console.log(chalk.green(`  ✓ Token Figma válido (usuário: ${result.data.handle || result.data.email || 'OK'})`));
+        pass++;
+      } catch (err) {
+        if (err.status === 401 || err.status === 403) {
+          console.log(chalk.red(`  ✗ Token Figma inválido ou expirado (HTTP ${err.status})`));
+          console.log(chalk.dim('  Renove em: Figma > Account Settings > Personal Access Tokens'));
+          console.log(chalk.dim('  Atualize FIGMA_API_KEY no .env'));
+          fail++;
         } else {
-          console.log(chalk.yellow(`  ⚠ Não foi possível verificar credenciais Confluence: ${fetchErr.message}`));
+          console.log(chalk.yellow(`  ⚠ Não foi possível verificar token Figma: ${err.message}`));
+          fail++;
         }
-        // Network errors are WARN not FAIL — offline dev should not be blocked
-        fail++;
       }
     }
-  } catch {
-    // .env not found — already warned by MCP config check
   }
 
   // Summary

package/src/commands/init.js

@@ -5,8 +5,8 @@ import { writeFile, mkdir, access, cp } from 'fs/promises';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
-import https from 'https';
-import http from 'http';
+import { detectMcpRunner, detectNpxRunner, tryInstallMcpAtlassian, getInstallInstructions } from '../utils/mcp-detect.js';
+import { confluenceRequest, figmaRequest } from '../utils/http.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates');
@@ -48,7 +48,7 @@ const KNOWN_TECH_KEYWORDS = [
 ];
 
 // ──────────────────────────────────────────────────────
-// HTTP helper using Node.js built-in modules
+// SSL error detection (corporate proxy workaround)
 // ──────────────────────────────────────────────────────
 const SSL_ERROR_CODES = new Set([
   'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
@@ -67,48 +67,6 @@ function isSslError(err) {
   );
 }
 
-function confluenceRequest(baseUrl, path, user, token, timeoutMs = 15000, allowInsecure = false) {
-  return new Promise((resolve, reject) => {
-    try {
-      const fullUrl = new URL(baseUrl.replace(/\/$/, '') + path);
-      const mod = fullUrl.protocol === 'https:' ? https : http;
-      const auth = Buffer.from(`${user}:${token}`).toString('base64');
-      const options = {
-        headers: {
-          'Authorization': `Basic ${auth}`,
-          'Accept': 'application/json',
-        },
-        timeout: timeoutMs,
-        ...(allowInsecure && fullUrl.protocol === 'https:'
-          ? { agent: new https.Agent({ rejectUnauthorized: false }) }
-          : {}),
-      };
-      const req = mod.get(fullUrl, options, (res) => {
-        let data = '';
-        res.on('data', (chunk) => { data += chunk; });
-        res.on('end', () => {
-          if (res.statusCode >= 200 && res.statusCode < 300) {
-            try {
-              resolve({ status: res.statusCode, data: JSON.parse(data) });
-            } catch {
-              resolve({ status: res.statusCode, data });
-            }
-          } else {
-            reject({ status: res.statusCode, message: `HTTP ${res.statusCode}` });
-          }
-        });
-      });
-      req.on('error', (err) => reject({ status: 0, message: err.message, code: err.code }));
-      req.on('timeout', () => {
-        req.destroy();
-        reject({ status: 0, message: 'Timeout (15s)' });
-      });
-    } catch (err) {
-      reject({ status: 0, message: err.message, code: err.code });
-    }
-  });
-}
-
 function stripHtml(html) {
   if (!html) return '';
   return html
@@ -419,13 +377,13 @@ Thumbs.db
 
 function generateEnvFile(config) {
   let content = `CONFLUENCE_URL=${config.confluenceUrl}
-CONFLUENCE_USER=${config.confluenceUser}
+CONFLUENCE_USERNAME=${config.confluenceUser}
 CONFLUENCE_API_TOKEN=${config.confluenceToken}
 GCHAT_WEBHOOK_URL=${config.gchatWebhookUrl || ''}
 `;
 
   if (config.hasFigma && config.figmaFileUrl) {
-    content += 'FIGMA_API_KEY=\n';
+    content += `FIGMA_API_KEY=${config.figmaToken}\n`;
   }
 
   return content;
@@ -435,7 +393,7 @@ function generateEnvExample(config) {
   let content = `# Confluence credentials
 # Obtenha o token em: https://id.atlassian.com/manage-profile/security/api-tokens
 CONFLUENCE_URL=https://seu-dominio.atlassian.net/wiki
-CONFLUENCE_USER=seu-email@empresa.com
+CONFLUENCE_USERNAME=seu-email@empresa.com
 CONFLUENCE_API_TOKEN=seu-token-aqui
 
 # Google Chat webhook (opcional)
@@ -454,41 +412,49 @@ FIGMA_API_KEY=seu-figma-api-key
 }
 
 function generateClaudeMcp(config) {
+  const runner = detectMcpRunner();
+  const confluenceArgs = [
+    ...runner.prefix,
+    '--confluence-url', '${CONFLUENCE_URL}',
+    '--confluence-username', '${CONFLUENCE_USERNAME}',
+    '--confluence-token', '${CONFLUENCE_API_TOKEN}'
+  ];
   const servers = {
     confluence: {
-      command: 'mcp-atlassian',
-      args: [
-        '--confluence-url', '${CONFLUENCE_URL}',
-        '--confluence-username', '${CONFLUENCE_USER}',
-        '--confluence-token', '${CONFLUENCE_API_TOKEN}'
-      ]
+      command: runner.command,
+      args: confluenceArgs,
     }
   };
   if (config.hasFigma && config.figmaFileUrl) {
+    const npx = detectNpxRunner();
     servers.figma = {
-      command: 'npx',
-      args: ['-y', FIGMA_MCP_PACKAGE, '--figma-api-key', '${FIGMA_API_KEY}']
+      command: npx.command,
+      args: [...npx.prefix, FIGMA_MCP_PACKAGE, '--figma-api-key', '${FIGMA_API_KEY}']
     };
   }
   return JSON.stringify({ mcpServers: servers }, null, 2) + '\n';
 }
 
 function generateCopilotMcp(config) {
+  const runner = detectMcpRunner();
+  const confluenceArgs = [
+    ...runner.prefix,
+    '--env-file', '.env',
+    '--no-confluence-ssl-verify'
+  ];
   const servers = {
     confluence: {
       type: 'stdio',
-      command: 'mcp-atlassian',
-      args: [
-        '--env-file', '.env',
-        '--no-confluence-ssl-verify'
-      ]
+      command: runner.command,
+      args: confluenceArgs,
     }
   };
   if (config.hasFigma && config.figmaFileUrl) {
+    const npx = detectNpxRunner();
     servers.figma = {
       type: 'stdio',
-      command: 'npx',
-      args: ['-y', FIGMA_MCP_PACKAGE, '--figma-api-key', '${input:figma-api-key}']
+      command: npx.command,
+      args: [...npx.prefix, FIGMA_MCP_PACKAGE, '--figma-api-key', '${input:figma-api-key}']
     };
   }
   return JSON.stringify({ servers }, null, 2) + '\n';
@@ -771,8 +737,22 @@ export async function initCommand() {
     {
       type: 'input',
       name: 'figmaFileUrl',
-      message: 'URL do arquivo Figma (deixe vazio para pular):',
-      when: (answers) => answers.hasFigma
+      message: 'URL do arquivo Figma (ex: https://www.figma.com/design/ABC123/Nome):',
+      when: (answers) => answers.hasFigma,
+      validate: v => {
+        const trimmed = v.trim();
+        if (!trimmed) return 'Obrigatório — se não tem URL, responda "Não" na pergunta anterior';
+        if (!trimmed.includes('figma.com')) return 'URL deve ser do Figma (figma.com)';
+        return true;
+      }
+    },
+    {
+      type: 'password',
+      name: 'figmaToken',
+      message: 'Figma API token (Personal Access Token):',
+      mask: '*',
+      when: (answers) => answers.hasFigma && answers.figmaFileUrl?.trim(),
+      validate: v => v.trim().length > 0 || 'Obrigatório — gere em: Figma > Account Settings > Personal Access Tokens'
     },
     {
       type: 'confirm',
@@ -789,6 +769,29 @@ export async function initCommand() {
     phase3.figmaFileUrl = '';
   }
 
+  // Validate Figma token
+  let figmaTokenValidated = false;
+  if (phase3.hasFigma && phase3.figmaToken) {
+    const figmaSpinner = ora('Validando token do Figma...').start();
+    try {
+      const result = await figmaRequest(phase3.figmaToken.trim());
+      figmaSpinner.succeed(`Token Figma validado — usuário: ${result.data.handle || result.data.email || 'OK'}`);
+      figmaTokenValidated = true;
+    } catch (err) {
+      if (err.status === 401 || err.status === 403) {
+        figmaSpinner.fail(`Token Figma inválido (HTTP ${err.status}). Verifique o Personal Access Token.`);
+        console.log(chalk.dim('  Gere em: Figma > Account Settings > Personal Access Tokens'));
+        console.log(chalk.yellow('  Continuando sem Figma...\n'));
+        phase3.hasFigma = false;
+        phase3.figmaFileUrl = '';
+        phase3.figmaToken = '';
+      } else {
+        figmaSpinner.warn(`Não foi possível validar o token Figma: ${err.message}`);
+        console.log(chalk.yellow('  Token será salvo, mas verifique com "open-spec-kit doctor".\n'));
+      }
+    }
+  }
+
   // B3: se .git já existe, git init é false independente do prompt (que foi pulado)
   const initGitFinal = gitAlreadyExists ? false : (phase3.initGit ?? false);
 
@@ -812,6 +815,7 @@ export async function initCommand() {
     gchatWebhookUrl: (phase3.gchatWebhookUrl || '').trim(),
     hasFigma: phase3.hasFigma,
     figmaFileUrl: (phase3.figmaFileUrl || '').trim(),
+    figmaToken: (phase3.figmaToken || '').trim(),
     initGit: initGitFinal,
   };
 
@@ -833,7 +837,10 @@ export async function initCommand() {
   console.log(`  VCS:           ${vcsDisplay}`);
   console.log(`  Confluence:    ${chalk.cyan(config.confluenceRef)} (${config.confluenceLayout === 'space' ? 'space key' : 'page ID'}) @ ${chalk.cyan(config.confluenceUrl)}`);
   console.log(`  GChat:         ${chalk.cyan(config.gchatWebhookUrl ? '(webhook configurado)' : chalk.dim('Não configurado'))}`);
-  console.log(`  Figma:         ${chalk.cyan(config.hasFigma ? (config.figmaFileUrl || 'Sim (URL não informada)') : 'Não')}`);
+  const figmaStatus = config.hasFigma
+    ? `${config.figmaFileUrl} (${figmaTokenValidated ? 'token validado' : 'token salvo, não validado'})`
+    : 'Não';
+  console.log(`  Figma:         ${chalk.cyan(figmaStatus)}`);
   if (gitAlreadyExists) {
     console.log(`  Git init:      ${chalk.dim('Pulado (.git já existe)')}`);
   } else {
@@ -913,19 +920,16 @@ export async function initCommand() {
 
     genSpinner.succeed('Estrutura gerada com sucesso!');
 
-    // Install mcp-atlassian (BUG-024 fix)
-    const pipSpinner = ora('Verificando mcp-atlassian...').start();
-    try {
-      const pipList = execSync('pip list', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-      if (!pipList.toLowerCase().includes('mcp-atlassian')) {
-        pipSpinner.text = 'Instalando mcp-atlassian...';
-        execSync('pip install mcp-atlassian', { stdio: 'pipe', timeout: 120000 });
-        pipSpinner.succeed('mcp-atlassian instalado com sucesso!');
-      } else {
-        pipSpinner.succeed('mcp-atlassian já está instalado.');
+    // Install mcp-atlassian — cross-platform detection (uvx > pipx > pip)
+    const mcpSpinner = ora('Verificando mcp-atlassian...').start();
+    const installResult = tryInstallMcpAtlassian();
+    if (installResult.installed) {
+      mcpSpinner.succeed(`mcp-atlassian disponível via ${installResult.method}`);
+    } else {
+      mcpSpinner.warn(`${installResult.message}. Instale manualmente:`);
+      for (const line of getInstallInstructions()) {
+        console.log(chalk.dim(`    ${line}`));
       }
-    } catch {
-      pipSpinner.warn('Não foi possível instalar mcp-atlassian. Instale manualmente: pip install mcp-atlassian');
     }
 
     // Git init

package/src/commands/validate.js

@@ -27,7 +27,7 @@ function parseBrief(content) {
     lineCount: content.split('\n').length,
     hasProblema: !!findSection(sections, /problema|contexto|visão\s*geral|overview|background|objetivo\s+do\s+produto|situação\s*atual|descri[çc][aã]o|identifica[çc][aã]o/i),
     hasForaDeEscopo: !!findSection(sections, /fora\s+de\s+escopo/i),
-    reqIds: extractUniqueMatches(content, /REQ-\w+/g),
+    reqIds: content.match(/REQ-\w+/g) || [],
     rawContent: content,
   };
 }
@@ -35,7 +35,8 @@ function parseBrief(content) {
 function parseScenarios(content) {
   const sections = parseSections(content);
   const CT_HEADING_RE = /^CT-(\d{3}-\d{2}):\s*(.+?)(?:\s*\(REQ-(\d{3})\))?$/;
-  const CT_ID_RE = /CT-\d{3}-\d{2}/g;
+  // Broad regex: capture all CT-like IDs (including malformed) so rule07 can flag them
+  const CT_ID_RE = /CT-\d+-\d+/g;
   const REQ_REF_RE = /REQ-\d{3}/g;
 
   const allCtIds = [];
@@ -429,12 +430,7 @@ export async function validateCommand(options = {}) {
       const contracts = contractsRaw ? parseContracts(contractsRaw) : null;
       const tasks = tasksRaw ? parseTasks(tasksRaw) : null;
 
-      // Enrich brief with REQs from scenarios (union) — covers specs where brief doesn't list REQs
-      if (brief && scenarios) {
-        brief.reqIds = [...new Set([...brief.reqIds, ...scenarios.allReqRefs])];
-      }
-
-      // Rules 2-6: Brief
+      // Rules 2-6: Brief (run BEFORE enrich so rule06 sees raw duplicates)
       if (brief) {
         results.push(rules.rule02_briefMaxLines(brief));
         results.push(rules.rule03_briefHasProblema(brief));
@@ -443,6 +439,12 @@ export async function validateCommand(options = {}) {
         results.push(rules.rule06_noDuplicateReqIds(brief));
       }
 
+      // Enrich brief with REQs from scenarios (union) — covers specs where brief doesn't list REQs
+      // Runs AFTER rule05/rule06 so those rules see the original brief REQs (with duplicates)
+      if (brief && scenarios) {
+        brief.reqIds = [...new Set([...brief.reqIds, ...scenarios.allReqRefs])];
+      }
+
       // Rule 7: CT IDs
       if (scenarios) {
         results.push(rules.rule07_ctIdFormat(scenarios));

package/src/utils/http.js

@@ -0,0 +1,54 @@
+import https from 'https';
+import http from 'http';
+
+/**
+ * Simple HTTP GET that returns parsed JSON. Used by init and doctor
+ * to validate Confluence and Figma credentials.
+ */
+function httpGetJson(url, headers, { timeoutMs = 15000, allowInsecure = false } = {}) {
+  return new Promise((resolve, reject) => {
+    try {
+      const fullUrl = new URL(url);
+      const mod = fullUrl.protocol === 'https:' ? https : http;
+      const options = {
+        headers: { ...headers, 'Accept': 'application/json' },
+        timeout: timeoutMs,
+        ...(allowInsecure && fullUrl.protocol === 'https:'
+          ? { agent: new https.Agent({ rejectUnauthorized: false }) }
+          : {}),
+      };
+      const req = mod.get(fullUrl, options, (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              resolve({ status: res.statusCode, data: JSON.parse(data) });
+            } catch {
+              resolve({ status: res.statusCode, data });
+            }
+          } else {
+            reject({ status: res.statusCode, message: `HTTP ${res.statusCode}` });
+          }
+        });
+      });
+      req.on('error', (err) => reject({ status: 0, message: err.message, code: err.code }));
+      req.on('timeout', () => {
+        req.destroy();
+        reject({ status: 0, message: `Timeout (${timeoutMs / 1000}s)` });
+      });
+    } catch (err) {
+      reject({ status: 0, message: err.message, code: err.code });
+    }
+  });
+}
+
+export function confluenceRequest(baseUrl, path, user, token, timeoutMs = 15000, allowInsecure = false) {
+  const url = baseUrl.replace(/\/$/, '') + path;
+  const auth = Buffer.from(`${user}:${token}`).toString('base64');
+  return httpGetJson(url, { 'Authorization': `Basic ${auth}` }, { timeoutMs, allowInsecure });
+}
+
+export function figmaRequest(token, timeoutMs = 15000) {
+  return httpGetJson('https://api.figma.com/v1/me', { 'X-Figma-Token': token }, { timeoutMs });
+}

package/src/utils/mcp-detect.js

@@ -0,0 +1,131 @@
+/**
+ * MCP Runner Detection — cross-platform detection of the best way to run MCP servers.
+ *
+ * Detects whether mcp-atlassian is directly on PATH, or available via uvx/pipx.
+ * Used by both init.js (config generation) and doctor.js (health checks).
+ */
+
+import { execSync } from 'child_process';
+
+const WHERE_CMD = process.platform === 'win32' ? 'where' : 'which';
+
+/**
+ * Check if a command exists on PATH.
+ * @param {string} cmd
+ * @returns {boolean}
+ */
+function commandExists(cmd) {
+  try {
+    execSync(`${WHERE_CMD} ${cmd}`, { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the best way to run mcp-atlassian.
+ * Priority: direct PATH > uvx > pipx > pip-fallback
+ *
+ * @returns {{ command: string, prefix: string[], method: 'direct'|'uvx'|'pipx'|'pip-fallback' }}
+ *   - command: the executable to run
+ *   - prefix: args to prepend before mcp-atlassian's own args
+ *   - method: how it was detected (for logging)
+ */
+export function detectMcpRunner() {
+  if (commandExists('mcp-atlassian')) {
+    return { command: 'mcp-atlassian', prefix: [], method: 'direct' };
+  }
+  if (commandExists('uvx')) {
+    return { command: 'uvx', prefix: ['mcp-atlassian'], method: 'uvx' };
+  }
+  if (commandExists('pipx')) {
+    return { command: 'pipx', prefix: ['run', 'mcp-atlassian'], method: 'pipx' };
+  }
+  return { command: 'mcp-atlassian', prefix: [], method: 'pip-fallback' };
+}
+
+/**
+ * Detect the best way to run npx (for Figma MCP).
+ * @returns {{ command: string, prefix: string[], method: 'npx'|'npm-exec'|'fallback' }}
+ */
+export function detectNpxRunner() {
+  const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  if (commandExists(npxCmd)) {
+    return { command: npxCmd === 'npx.cmd' ? 'npx' : npxCmd, prefix: ['-y'], method: 'npx' };
+  }
+  if (commandExists('npm')) {
+    return { command: 'npm', prefix: ['exec', '--yes', '--'], method: 'npm-exec' };
+  }
+  return { command: 'npx', prefix: ['-y'], method: 'fallback' };
+}
+
+/**
+ * Try to install mcp-atlassian using the best available package manager.
+ * @returns {{ installed: boolean, method: string, message: string }}
+ */
+export function tryInstallMcpAtlassian() {
+  // Already available — no install needed
+  const runner = detectMcpRunner();
+  if (runner.method !== 'pip-fallback') {
+    return { installed: true, method: runner.method, message: `mcp-atlassian acessível via ${runner.method}` };
+  }
+
+  // Try uv tool install
+  if (commandExists('uv')) {
+    try {
+      execSync('uv tool install mcp-atlassian', { stdio: 'pipe', timeout: 120000 });
+      return { installed: true, method: 'uv-tool', message: 'Instalado via uv tool install' };
+    } catch { /* failed */ }
+  }
+
+  // Try pipx install
+  if (commandExists('pipx')) {
+    try {
+      execSync('pipx install mcp-atlassian', { stdio: 'pipe', timeout: 120000 });
+      return { installed: true, method: 'pipx', message: 'Instalado via pipx install' };
+    } catch { /* failed */ }
+  }
+
+  // Try pip install (legacy fallback)
+  const pipCmd = process.platform === 'win32' ? 'pip' : 'pip3';
+  if (commandExists(pipCmd)) {
+    try {
+      execSync(`${pipCmd} install mcp-atlassian`, { stdio: 'pipe', timeout: 120000 });
+      // Verify it landed on PATH
+      if (commandExists('mcp-atlassian')) {
+        return { installed: true, method: 'pip', message: `Instalado via ${pipCmd}` };
+      }
+      return { installed: false, method: 'pip-no-path', message: `${pipCmd} install executado mas mcp-atlassian não está no PATH` };
+    } catch { /* failed */ }
+  }
+
+  return { installed: false, method: 'none', message: 'Nenhum gerenciador de pacotes Python encontrado' };
+}
+
+/**
+ * Get platform-specific install instructions for mcp-atlassian.
+ * @returns {string[]} Array of instruction lines
+ */
+export function getInstallInstructions() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    return [
+      'pip install mcp-atlassian',
+      'OU: instale uv (https://docs.astral.sh/uv/) e rode: uv tool install mcp-atlassian',
+    ];
+  }
+  if (platform === 'darwin') {
+    return [
+      'brew install uv && uv tool install mcp-atlassian',
+      'OU: pip3 install mcp-atlassian',
+    ];
+  }
+  // linux
+  return [
+    'curl -LsSf https://astral.sh/uv/install.sh | sh && uv tool install mcp-atlassian',
+    'OU: pip3 install mcp-atlassian',
+  ];
+}
+
+export { commandExists };

package/templates/agents/scripts/notify-gchat.sh

@@ -54,7 +54,18 @@ else
 fi
 
 # Build and send via Python — avoids bash UTF-8 corruption
-PYTHONIOENCODING=utf-8 python -c "
+# Use python3 if available (Linux/macOS default), fall back to python (Windows)
+PYTHON_CMD="python3"
+if ! command -v python3 &>/dev/null; then
+  PYTHON_CMD="python"
+fi
+
+if ! command -v "$PYTHON_CMD" &>/dev/null; then
+  echo "[notify-gchat] Python não encontrado (nem python3, nem python) — notificação ignorada" >&2
+  exit 0
+fi
+
+PYTHONIOENCODING=utf-8 $PYTHON_CMD -c "
 import json, sys, subprocess
 
 card_mode = sys.argv[1] == 'true'

package/templates/agents/skills/discovery/SKILL.md

@@ -101,7 +101,9 @@ This ensures the PRD is a **complete description of the new feature** with expli
 1. `projects.yml` has a `figma:` section with `file_url` filled
 2. The Figma MCP is available (`figma` server configured)
 
-If either condition fails, **skip silently**.
+If `projects.yml` has `figma.file_url` but the MCP is not available, **warn the user**: "⚠ Figma configurado em projects.yml mas MCP Figma não disponível. Execute 'open-spec-kit doctor' para diagnosticar. Continuando sem contexto do Figma."
+
+If `projects.yml` does NOT have a `figma:` section, skip silently (Figma is optional).
 
 **If available:**
 1. Extract the file key from the URL in `projects.yml` → `figma.file_url` (segment after `/design/` or `/file/`)

package/templates/agents/skills/setup-project/SKILL.md

@@ -106,7 +106,9 @@ The setup supports two Confluence layouts:
 1. `projects.yml` has a `figma:` section with `file_url` filled
 2. The Figma MCP is available (`figma` server configured in `.mcp.json`)
 
-If either condition fails, **skip silently** — do not report an error or ask for configuration.
+If `projects.yml` has `figma.file_url` but the MCP is not available, **warn the user**: "⚠ Figma configurado em projects.yml mas MCP Figma não disponível. Execute 'open-spec-kit doctor' para diagnosticar. Continuando sem contexto do Figma."
+
+If `projects.yml` does NOT have a `figma:` section, skip silently (Figma is optional).
 
 **If available:**
 1. Extract the file key from the URL in `projects.yml` → `figma.file_url`
@@ -129,9 +131,11 @@ When generating the living docs (step 3), reference Figma screens where relevant
 
 ### 3. Generate living docs on Confluence
 
-Via MCP Confluence, create these pages **under the project root**, in this order.
+**CRITICAL: All pages in this section MUST be created as children of `ROOT_ID` (the project root page), NOT as children of `DEMANDAS_ID`. `Demandas/` is a SIBLING — the generated pages go NEXT TO it, not INSIDE it. Use `ROOT_ID` as the parent_id for every `confluence_create_page` call in this step.**
+
+Via MCP Confluence, create these pages **under the project root (`ROOT_ID`)**, in this order.
 
-**Title prefix (multi-project)**: when the layout is multi-project (argument is a numeric page ID), ALL created page titles must be prefixed with the project acronym (`sigla` field in projects.yml). This avoids title conflicts within the same Confluence space. The project root page does NOT get a prefix (it's already unique by definition).
+**Title prefix (multi-project)**: when the layout is multi-project (argument is a numeric page ID), ALL created page titles must be prefixed with the project acronym (`sigla` field in projects.yml). **Read the sigla from `projects.yml` field `project.sigla` — NEVER derive or invent a new one.** This avoids title conflicts within the same Confluence space. The project root page does NOT get a prefix (it's already unique by definition).
 
 Title format:
 - Domain pages: `{SIGLA} — Visão do Produto`, `{SIGLA} — Glossário`, etc.
@@ -147,8 +151,8 @@ In simple layout (1 space = 1 project), the prefix is optional — no conflict r
 - `🔀 {SIGLA} — Fluxos`
 - `📊 {SIGLA} — Tabelas de Referência`
 - `🔌 {SIGLA} — Integrações`
-- `🚀 Features`
-- `📦 Arquivados`
+- `🚀 {SIGLA} — Features`
+- `📦 {SIGLA} — Arquivados`
 - Business features: `🚀 {SIGLA}-NNN - Feature name`
 - Infrastructure feature: `⚙️ {SIGLA}-000 - Infraestrutura e Scaffold`
 
@@ -246,8 +250,8 @@ Minimum expected terms for any project:
 - External integrations: list or write "Nenhuma na v1"
 
 **Step 3.4 — Structure pages:**
-- Create `Features/` parent page under the project root if it doesn't exist
-- Create `Arquivados/` parent page under the project root if it doesn't exist
+- Create `🚀 {SIGLA} — Features` parent page under the project root if it doesn't exist
+- Create `📦 {SIGLA} — Arquivados` parent page under the project root if it doesn't exist
 
 **Step 3.5 — Create initial feature pages:**
 
@@ -290,9 +294,11 @@ All subsequent features ({SIGLA}-001 onwards) have an implicit dependency on {SI
 
 **Step 3.5b — Business features:**
 
+**Reminder: feature pages are children of `{SIGLA} — Features` (which is a child of `ROOT_ID`). Do NOT create features inside `Demandas/`.**
+
 Analyze the PO documents in `Demandas/` and identify distinct features/capabilities described. For EACH feature identified:
 
-1. Create a child page under `Features/` with title: `🚀 {SIGLA}-NNN - Feature name` (numbering sequential: 001, 002, ...). E.g., `🚀 FT-001 - Cadastro e Autenticação`, `🚀 TD-003 - Gerenciamento de Tarefas`
+1. Create a child page under `{SIGLA} — Features` with title: `🚀 {SIGLA}-NNN - Feature name` (numbering sequential: 001, 002, ...). E.g., `🚀 FT-001 - Cadastro e Autenticação`, `🚀 TD-003 - Gerenciamento de Tarefas`
 2. Content MUST start with a metadata table:
    ```
    | Campo | Valor |
@@ -315,7 +321,7 @@ In the local spec repo:
 
 **Fill `projects.yml`:**
 - Project name, domain, status, team size
-- **Sigla**: `sigla: XX` — short abbreviation (2-4 letters) used as prefix in Confluence titles and feature IDs. Derive from project name (e.g., FinTrack → FT, Todo → TD, CRM → CRM). Ask the dev if ambiguous.
+- **Sigla**: `sigla: XX` — short abbreviation (2-4 letters) used as prefix in Confluence titles and feature IDs. **MUST read from `projects.yml` field `project.sigla`** — this was already set by the user during `open-spec-kit init`. NEVER derive or invent a new sigla. If `projects.yml` has no sigla, ask the dev.
 - Stack (from PO's docs or ask the dev)
 - **VCS**: `vcs: github | gitlab` and `vcs_org: {org/group}` — ask the dev if not obvious from context
 - **Repos**: detect from the PRD what repos will be needed. If the PRD mentions "API .NET", declare a `project-api` repo with stack `dotnet` and status `planned`. If it mentions "React frontend", declare a `project-front` repo with stack `nodejs` and status `planned`. Do NOT leave repos commented out — declare them with `status: planned`.
@@ -443,9 +449,9 @@ The output is considered good when:
 - [ ] Fluxos: all flows have happy path + exceptions + Mermaid flowchart TD
 - [ ] Tabelas de Referencia: all enums defined, state transitions documented + Mermaid stateDiagram-v2
 - [ ] Integracoes: all events have producer + consumer + expected payload
-- [ ] Features/ page created
-- [ ] Initial feature pages created under Features/ (with label `em-discovery`)
-- [ ] Arquivados/ page created
+- [ ] {SIGLA} — Features parent page created
+- [ ] Initial feature pages created under {SIGLA} — Features (with label `em-discovery`)
+- [ ] {SIGLA} — Arquivados parent page created
 
 ### Spec repo updated
 - [ ] projects.yml filled with all detected repos (status: planned, not commented)