@guilhermefsousa/open-spec-kit 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# Open Spec Kit
+
+Kit de especificação assistida por IA que transforma documentos do PO em specs técnicas prontas para implementar. Suporta **Claude Code** e **GitHub Copilot** via arquitetura dual-platform.
+
+## Quick Start
+
+```bash
+# Scaffold um novo projeto de specs
+npx open-spec-kit init
+
+# Verificar ambiente (Confluence, MCP, Python, Git)
+npx open-spec-kit doctor
+
+# Validar specs (32 regras determinísticas)
+npx open-spec-kit validate
+
+# Sincronizar .agents/ → .github/
+npx open-spec-kit update
+```
+
+## Workflow
+
+O workflow completo roda com 4 skills no VS Code:
+
+```
+/setup → /discovery → /spec → /dev
+```
+
+Cada skill lê o que a anterior produziu, gera artefatos e atualiza o Confluence automaticamente.
+
+## Comandos
+
+| Comando | Descrição |
+|---------|-----------|
+| `open-spec-kit init` | Scaffold de um novo projeto de specs (interativo) |
+| `open-spec-kit doctor` | Verifica ambiente: Confluence, MCP server, Python, Git |
+| `open-spec-kit validate` | Valida specs com 32 regras determinísticas |
+| `open-spec-kit validate --spec 001` | Valida uma spec específica |
+| `open-spec-kit validate --json` | Output JSON (para CI) |
+| `open-spec-kit validate --trace` | Mostra matriz de rastreabilidade REQ↔CT |
+| `open-spec-kit update` | Re-sincroniza `.agents/` → `.github/` |
+
+## Pré-requisitos
+
+- **Node.js 18+**
+- **VS Code** + Claude Code ou GitHub Copilot
+- **Confluence Cloud** + MCP server (`mcp-atlassian`)
+- **Python 3.10+** (para o MCP server)
+- **Git**
+
+## Documentação
+
+Veja o [guia completo](https://github.com/guilhermefsousa/open-spec-kit#readme) no repositório.
+
+## License
+
+MIT

package/bin/open-spec-kit.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from '../src/commands/init.js';
+import { updateCommand } from '../src/commands/update.js';
+import { validateCommand } from '../src/commands/validate.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+
+const program = new Command();
+
+program
+  .name('open-spec-kit')
+  .description('CLI para spec-driven development com suporte a Claude Code e GitHub Copilot')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Inicializar estrutura de spec-driven development no projeto')
+  .action(initCommand);
+
+program
+  .command('update')
+  .description('Re-gerar arquivos de adapter quando skills ou agents mudarem')
+  .action(updateCommand);
+
+program
+  .command('validate')
+  .description('Validate spec consistency (32 rules: structure, traceability, contracts, cross-spec)')
+  .option('--json', 'Output results as JSON (for CI pipelines)')
+  .option('--trace', 'Show REQ → CT traceability matrix')
+  .option('--spec <id>', 'Validate a single spec by number (e.g., 001)')
+  .action(validateCommand);
+
+program
+  .command('doctor')
+  .description('Verificar se o ambiente está configurado corretamente')
+  .action(doctorCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@guilhermefsousa/open-spec-kit",
+  "version": "0.1.0",
+  "description": "CLI para spec-driven development com suporte a Claude Code e GitHub Copilot",
+  "type": "module",
+  "bin": {
+    "open-spec-kit": "bin/open-spec-kit.js",
+    "osk-kit": "bin/open-spec-kit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/open-spec-kit.js",
+    "prepublishOnly": "node bin/open-spec-kit.js --version"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "inquirer": "^12.0.0",
+    "chalk": "^5.4.0",
+    "ora": "^8.0.0",
+    "zod": "^3.24.0",
+    "yaml": "^2.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "specification",
+    "claude",
+    "copilot",
+    "ai-agents",
+    "technical-specs",
+    "confluence"
+  ],
+  "author": "Guilherme Sousa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guilhermefsousa/open-spec-kit.git"
+  },
+  "homepage": "https://github.com/guilhermefsousa/open-spec-kit#readme",
+  "bugs": {
+    "url": "https://github.com/guilhermefsousa/open-spec-kit/issues"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,324 @@
+import chalk from 'chalk';
+import { readFile, access } from 'fs/promises';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import yaml from 'yaml';
+
+export async function doctorCommand() {
+  console.log(chalk.bold('\n  open-spec-kit doctor\n'));
+
+  const cwd = process.cwd();
+  let pass = 0;
+  let fail = 0;
+  let projectsContent = '';
+  let claudeMcpContent = '';
+  let copilotMcpContent = '';
+
+  // Check 1: projects.yml exists and is filled
+  try {
+    projectsContent = await readFile(join(cwd, 'projects.yml'), 'utf-8');
+    const hasName = /name:\s*\S+/.test(projectsContent) && !projectsContent.includes('name: #');
+    if (hasName) {
+      console.log(chalk.green('  ✓ projects.yml existe e tem nome do projeto'));
+      pass++;
+    } else {
+      console.log(chalk.yellow('  ⚠ projects.yml existe mas não está preenchido'));
+      fail++;
+    }
+  } catch {
+    console.log(chalk.red('  ✗ projects.yml não encontrado'));
+    fail++;
+  }
+
+  // Check 2: Agents configured
+  let agents = [];
+  let projectsData = null;
+  try {
+    projectsData = yaml.parse(projectsContent);
+    agents = projectsData?.project?.agents || [];
+    if (!Array.isArray(agents)) agents = [];
+  } catch { /* fallback: ignore parse error, agents = [] */ }
+
+  if (agents.length > 0) {
+    console.log(chalk.green(`  ✓ AI tools configurados: ${agents.join(', ')}`));
+    pass++;
+  } else {
+    console.log(chalk.yellow('  ⚠ Nenhum AI tool configurado em projects.yml (campo agents:)'));
+
+    fail++;
+  }
+
+  // Check 2b: Repos configured
+  try {
+    const repos = projectsData?.repos;
+    const hasRepos = Array.isArray(repos) && repos.some(r => r && typeof r === 'object' && r.name);
+    if (hasRepos) {
+      console.log(chalk.green(`  ✓ ${repos.filter(r => r && r.name).length} repo(s) configurado(s) em projects.yml`));
+      pass++;
+    } else {
+      console.log(chalk.yellow('  ⚠ Nenhum repo configurado em projects.yml — adicione ao menos 1 em repos:'));
+      fail++;
+    }
+  } catch { /* ignore */ }
+
+  // Check 3: Claude Code files
+  if (agents.includes('claude')) {
+    try {
+      claudeMcpContent = await readFile(join(cwd, '.mcp.json'), 'utf-8');
+      if (claudeMcpContent.includes('SEU-TOKEN') || claudeMcpContent.includes('SEU-DOMINIO')) {
+        console.log(chalk.yellow('  ⚠ .mcp.json (Claude) existe mas tem placeholders'));
+        fail++;
+      } else {
+        console.log(chalk.green('  ✓ .mcp.json (Claude) configurado'));
+        pass++;
+      }
+    } catch {
+      console.log(chalk.red('  ✗ .mcp.json (Claude) nao encontrado'));
+      fail++;
+    }
+
+    try {
+      await access(join(cwd, '.agents/agents/spec-hub.agent.md'));
+      console.log(chalk.green('  ✓ .agents/agents/spec-hub.agent.md existe'));
+      pass++;
+    } catch {
+      console.log(chalk.red('  ✗ .agents/agents/spec-hub.agent.md ausente'));
+      fail++;
+    }
+  }
+
+  // Check 4: Copilot files
+  if (agents.includes('copilot')) {
+    try {
+      copilotMcpContent = await readFile(join(cwd, '.vscode/mcp.json'), 'utf-8');
+      console.log(chalk.green('  ✓ .vscode/mcp.json (Copilot) encontrado'));
+      pass++;
+    } catch {
+      console.log(chalk.red('  ✗ .vscode/mcp.json (Copilot) ausente'));
+      fail++;
+    }
+
+    try {
+      await access(join(cwd, '.github/agents/spec-hub.agent.md'));
+      console.log(chalk.green('  ✓ .github/agents/spec-hub.agent.md existe'));
+      pass++;
+    } catch {
+      console.log(chalk.red('  ✗ .github/agents/spec-hub.agent.md ausente'));
+      fail++;
+    }
+
+    try {
+      await access(join(cwd, '.github/copilot-instructions.md'));
+      console.log(chalk.green('  ✓ .github/copilot-instructions.md existe'));
+      pass++;
+    } catch {
+      console.log(chalk.red('  ✗ .github/copilot-instructions.md ausente'));
+      fail++;
+    }
+  }
+
+  // Check 5: Skills exist
+  const skills = [
+    '.agents/skills/setup-project/SKILL.md',
+    '.agents/skills/discovery/SKILL.md',
+    '.agents/skills/specifying-features/SKILL.md',
+    '.agents/skills/dev-orchestrator/SKILL.md',
+  ];
+  let skillCount = 0;
+  for (const skill of skills) {
+    try {
+      await access(join(cwd, skill));
+      skillCount++;
+    } catch { /* missing */ }
+  }
+  if (skillCount === skills.length) {
+    console.log(chalk.green(`  ✓ ${skillCount}/4 skills encontrados`));
+    pass++;
+  } else {
+    console.log(chalk.yellow(`  ⚠ ${skillCount}/4 skills encontrados`));
+    fail++;
+  }
+
+  // Check 6: Rules exist
+  const rules = [
+    '.agents/rules/ownership.instructions.md',
+    '.agents/rules/hub_structure.instructions.md',
+  ];
+  let ruleCount = 0;
+  for (const rule of rules) {
+    try {
+      await access(join(cwd, rule));
+      ruleCount++;
+    } catch { /* missing */ }
+  }
+  if (ruleCount === rules.length) {
+    console.log(chalk.green(`  ✓ ${ruleCount}/2 rules encontradas`));
+    pass++;
+  } else {
+    console.log(chalk.yellow(`  ⚠ ${ruleCount}/2 rules encontradas`));
+    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'));
+    pass++;
+  } catch {
+    console.log(chalk.yellow('  ⚠ mcp-atlassian nao encontrado'));
+    console.log(chalk.dim('  Instale com: pip install mcp-atlassian  (requer Python >= 3.10)'));
+    fail++;
+  }
+
+  // Check 7b: Python version >= 3.10 (required by mcp-atlassian)
+  try {
+    const pyCmd = process.platform === 'win32' ? 'python --version' : 'python3 --version';
+    const pyVersion = execSync(pyCmd, { stdio: 'pipe', timeout: 5000 }).toString().trim();
+    const match = pyVersion.match(/(\d+)\.(\d+)/);
+    if (match) {
+      const major = Number(match[1]);
+      const minor = Number(match[2]);
+      if (major > 3 || (major === 3 && minor >= 10)) {
+        console.log(chalk.green(`  ✓ Python ${major}.${minor} (>= 3.10 exigido pelo mcp-atlassian)`));
+        pass++;
+      } else {
+        console.log(chalk.yellow(`  ⚠ Python ${major}.${minor} detectado — mcp-atlassian requer >= 3.10`));
+        console.log(chalk.dim('  Instale Python 3.10+: https://python.org/downloads'));
+        fail++;
+      }
+    }
+  } catch {
+    console.log(chalk.yellow('  ⚠ Python não encontrado no PATH'));
+    console.log(chalk.dim('  Instale Python 3.10+: https://python.org/downloads'));
+    fail++;
+  }
+
+  // Check 8: Git repo
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'pipe', timeout: 10000 });
+    console.log(chalk.green('  ✓ Repositório Git inicializado'));
+    pass++;
+  } catch {
+    console.log(chalk.yellow('  ⚠ Não é um repositório Git'));
+    fail++;
+  }
+
+  // Check 9: Dual-platform sync
+  if (agents.includes('claude') && agents.includes('copilot')) {
+    try {
+      const claudeAgent = await readFile(join(cwd, '.agents/agents/spec-hub.agent.md'), 'utf-8');
+      const copilotAgent = await readFile(join(cwd, '.github/agents/spec-hub.agent.md'), 'utf-8');
+
+      // Simple check: both should reference spec-agent
+      if (claudeAgent.includes('spec-agent') && copilotAgent.includes('spec-agent')) {
+        console.log(chalk.green('  ✓ Agents sincronizados entre Claude e Copilot'));
+        pass++;
+      } else {
+        console.log(chalk.yellow('  ⚠ Agents podem estar dessincronizados'));
+        fail++;
+      }
+    } catch {
+      console.log(chalk.yellow('  ⚠ Nao foi possivel verificar sincronizacao'));
+      fail++;
+    }
+  }
+
+  // Check 10: Figma MCP (optional — only if projects.yml declares figma)
+  const hasFigma = /figma:\s*\n\s+file_url:\s*\S+/.test(projectsContent);
+  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++;
+        }
+      } else {
+        console.log(chalk.yellow('  ⚠ projects.yml tem figma: mas .mcp.json não tem servidor figma'));
+        fail++;
+      }
+    }
+    if (copilotMcpContent) {
+      if (copilotMcpContent.includes('"figma"')) {
+        console.log(chalk.green('  ✓ .vscode/mcp.json (Copilot) tem servidor Figma configurado'));
+        pass++;
+      } else {
+        console.log(chalk.yellow('  ⚠ projects.yml tem figma: mas .vscode/mcp.json não tem servidor figma'));
+        fail++;
+      }
+    }
+  }
+
+  // Check 11: Confluence credentials — make real HTTP call to validate token
+  try {
+    const envContent = await readFile(join(cwd, '.env'), 'utf-8');
+    const 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()]; }),
+    );
+
+    const confUrl = envVars.CONFLUENCE_URL;
+    const confUser = envVars.CONFLUENCE_USER;
+    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'));
+      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 + ')'));
+          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`));
+          fail++;
+        }
+      } catch (fetchErr) {
+        clearTimeout(timeout);
+        if (fetchErr.name === 'AbortError') {
+          console.log(chalk.yellow('  ⚠ Confluence não respondeu em 10s — sem rede ou URL incorreta'));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Não foi possível verificar credenciais Confluence: ${fetchErr.message}`));
+        }
+        // Network errors are WARN not FAIL — offline dev should not be blocked
+        fail++;
+      }
+    }
+  } catch {
+    // .env not found — already warned by MCP config check
+  }
+
+  // Summary
+  console.log(chalk.bold('\n  Resultado:\n'));
+  console.log(`    ${chalk.green('✓')} ${pass} ok`);
+  if (fail > 0) console.log(`    ${chalk.yellow('⚠')} ${fail} problemas`);
+  console.log('');
+
+  if (fail > 0) {
+    console.log(chalk.dim('  Execute "open-spec-kit init" para corrigir a estrutura.\n'));
+  } else {
+    console.log(chalk.green('  Ambiente pronto! Execute /setup para comecar.\n'));
+  }
+}