@nathanramorim/forge-sdd 1.8.1-beta → 1.9.1-beta

package/README.md

@@ -3,7 +3,7 @@
 [![NPM Version](https://img.shields.io/npm/v/@nathanramorim/forge-sdd)](https://www.npmjs.com/package/@nathanramorim/forge-sdd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> CLI open source que instala em qualquer projeto a **Metodologia Forge-SDD** v1.8.1-beta — um framework de desenvolvimento guiado por IA que elimina a repetição de instruções, garante padrões arquiteturais e traz a expertise de um engenheiro sênior para o seu fluxo diário.
+> CLI open source que instala em qualquer projeto a **Metodologia Forge-SDD** v1.9.0-beta — um framework de desenvolvimento guiado por IA que elimina a repetição de instruções, garante padrões arquiteturais e traz a expertise de um engenheiro sênior para o seu fluxo diário.
 
 🚀 **Landing Page Oficial:** [forge-sdd.vercel.app](https://forge-sdd.vercel.app)
 📖 **Wiki & Documentação Completa:** [Wiki do Forge-SDD](https://forge-sdd.vercel.app/wiki#introducao)
@@ -20,8 +20,18 @@ Para conhecer todos os comandos disponíveis (`/status`, `/discovery`, `/nova-fe
 
 ## 💻 Instalação & Inicialização Rápida
 
-Inicialize a estrutura em segundos. O instalador gerará as pastas de memória, especificações e configurações específicas para a sua IA preferida (Copilot, Gemini ou Claude):
+Você pode rodar diretamente via `npx` ou instalar globalmente para ter o comando simplificado `forge` à disposição:
 
+### Via Instalação Global (Recomendado)
+```bash
+# Instale globalmente no seu sistema
+npm install -g @nathanramorim/forge-sdd
+
+# Inicialize de forma simples em qualquer projeto
+forge init
+```
+
+### Via Execução Direta (npx)
 ```bash
 # Inicialização interativa (escolha os agentes no menu)
 npx @nathanramorim/forge-sdd@latest init
@@ -30,38 +40,38 @@ npx @nathanramorim/forge-sdd@latest init
 npx @nathanramorim/forge-sdd@latest init . --agent copilot,gemini --name meu-projeto
 ```
 
-## 📢 Novidades da Versão (v1.8.1-beta)
+## 📢 Novidades da Versão (v1.9.0-beta)
 
-Esta versão de testes beta traz a proteção de customizações locais durante upgrades e a automação contínua de sessões:
+Esta versão de testes beta traz o atalho global de execução `forge`, uma interface de onboarding pós-instalação e melhorias focadas em reduzir a curva de aprendizado do Forge-SDD:
 
-*   **Backup Automático no Upgrade:** Toda vez que você rodar um upgrade ou update via CLI, um backup físico de arquivos de configuração e prompts de agentes customizados no seu projeto (como `.github/copilot-instructions.md`, `CLAUDE.md`, prompts e skills) será salvo automaticamente em `sdd/backups/upgrade-<timestamp>/` antes de qualquer sobrescrita, eliminando o risco de perda de lógica do projeto.
-*   **Modo Piloto Automático (Auto-Pilot):** Os prompts e chatmodes do Orquestrador foram atualizados para ler o arquivo flag `.sdd-auto-pilot` e ignorar a confirmação humana do `PLAN`. O CLI agora também scaffolda o script daemon padrão `sdd/scripts/sdd-daemon.sh` e o guia técnico de automação `sdd/docs/autonomia-autopilot.md`.
-*   **Convenção de Versionamento Simplificada:** Tags do canal de homologação passam a usar apenas o sufixo simples `-beta` (ex: `1.8.1-beta`), permitindo o acúmulo de múltiplos fixes ou features antes de lançar a estável oficial `1.8.0` correspondente (Regra 15).
-*   **Métricas Granulares e Robustas:** Mapeamento incondicional de telemetria mesmo para sessões parciais, abortadas ou com timeouts.
-*   **Diagnóstico de Nome Padrão:** O comando `doctor` alerta caso o projeto use o nome padrão `"meu-projeto"` no `.sddrc` ou nos cabeçalhos dos arquivos de agentes.organização.
+*   **Atalho Global (`forge`) e Onboarding Pós-Instalação:** Agora você pode acionar todos os comandos da CLI simplesmente usando `forge` (ex: `forge init`, `forge doctor`). Ao instalar o pacote globalmente, uma tela de boas-vindas interativa e instrutiva é exibida com o guia dos comandos.
+*   **Cheat-Sheet de Comandos:** O `forge init` agora imprime a lista completa dos comandos SDD disponíveis para os agentes escolhidos ao final da inicialização.
+*   **`/status` Prescritivo:** O comando `/status` (Copilot, Claude e Gemini) agora sempre sugere o próximo comando a ser executado, com base no estado real do progresso do projeto.
+*   **Diagnóstico de Deriva de Nomenclatura:** O comando `doctor` passa a detectar quando um projeto mistura a nomenclatura sequencial (`feat-NN`) com a nomenclatura por hash (`feat-xxxx`), alertando o usuário sobre a inconsistência.
+*   **Onboarding Guiado:** Novo comando `/tutorial` (Copilot, Claude e Gemini) guia o usuário por um ciclo SDD completo e fictício, isolado dos dados reais do projeto.
+*   **Comando `autopilot`:** Novo comando CLI que ativa o modo autopilot somente após um número mínimo de ciclos completos registrados em telemetria, com bypass consciente disponível via flag.
+*   **Modo Iniciante:** O comando `/constitution` (Copilot, Claude e Gemini) passa a perguntar, opcionalmente, se o usuário prefere explicações em linguagem simplificada, com exemplos concretos no lugar de jargão técnico.
 
 ---
 
-## 📢 Novidades da Versão Anterior (v1.6.1-beta.0)
+## 📢 Novidades da Versão Anterior (v1.7.1-beta.5)
 
-A versão beta trouxe detecção inteligente de projetos existentes e upgrade aprimorado:
+Esta versão de testes beta trouxe correções e alinhamento no fluxo de descobertas (discovery):
 
-- **Fase 38 — Detecção Inteligente e Upgrade no CLI**: O CLI agora detecta automaticamente se o diretório já possui a metodologia estruturada e redireciona para a interface de upgrade.
-- **Integração NPM Registry**: O CLI consulta dinamicamente as versões oficiais (`latest`) e de teste (`beta`) publicadas no NPM Registry para que o usuário escolha para qual deseja atualizar.
+*   **Plano de Discovery Padronizado:** O prompt de `/discovery` de todos os agentes (Copilot, Claude e Gemini) foi atualizado e alinhado para gerar obrigatoriamente o arquivo `plan-XX-*.md` na pasta `sdd/discovery/` contendo o roadmap e sugestão de quebra de tarefas/features.
+*   **Agrupamento Opcional de Releases Beta:** A política de releases beta (Regra 11 da Constituição) foi atualizada para explicitar que a publicação e geração de tags beta pode, opcionalmente, agrupar e acumular múltiplos fixes ou features antes de lançar novas tags ou bumps de versão, otimizando o fluxo.
+*   **Diagnóstico de Nome Padrão:** O comando `doctor` e os prompts `/doctor` dos agentes passam a verificar se o projeto ainda utiliza o nome genérico `"meu-projeto"`, listando as correções e os cabeçalhos de agentes recomendados a serem renomeados.
+*   **Métricas Granulares e Robustas:** Implementado mapeamento e telemetria incondicional para caminhos aninhados de subpastas de features e discoveries.
+*   **Prompt do Orquestrador Refatorado:** Instruções do Orquestrador atualizadas para impor os novos guardrails de close em todos os agentes suportados.
 
 ---
 
-## 📢 Novidades da Versão Anterior (v1.6.0)
+## 📢 Novidades da Versão Anterior (v1.6.1-beta.0)
 
-A versão estável v1.6.0 trouxe grandes evoluções de arquitetura e consistência no desenvolvimento:
+A versão beta trouxe detecção inteligente de projetos existentes e upgrade aprimorado:
 
-- **Fase 36 — Documentação Estruturada**: Estruturação de diagramas conceituais Mermaid detalhados para visualização clara de fluxos e arquitetura.
-- **Fase 35 — Remoção de Skill Incompleta**: Limpeza completa da funcionalidade de instalação de skill (`/install-skill`) em todos os prompts, agentes e documentação.
-- **Fase 34 — Reestruturação de Prompts por Agente**: Migração dos prompts do Copilot e unificação dos prompts de sistema e habilidades customizadas específicas para Gemini, Claude e Copilot.
-- **Fase 33 — Sincronização Automática da Wiki**: A documentação oficial (diretório docs/ e README) agora é enviada e atualizada automaticamente na wiki do repositório lp-forge-sdd a cada nova tag publicada.
-- **Fase 32 — Geração de Release Notes**: Agora o agente documenta as entregas de cada feature de forma automática e em linguagem clara de produto ao encerrar as tarefas.
-- **Fase 31 — Preservação de Domínio no Upgrade**: As atualizações do Forge-SDD ou do CLI protegem e preservam todas as suas especificações e arquivos de domínio do usuário.
-- **Fase 30 — Correções de Fluxo de Branches**: Ajustado o fluxo de desenvolvimento automático do agente para garantir criação prévia de branches e integração robusta de PRs via `gh` CLI.
+- **Fase 38 — Detecção Inteligente e Upgrade no CLI**: O CLI agora detecta automaticamente se o diretório já possui a metodologia estruturada e redireciona para a interface de upgrade.
+- **Integração NPM Registry**: O CLI consulta dinamicamente as versões oficiais (`latest`) e de teste (`beta`) publicadas no NPM Registry para que o usuário escolha para qual deseja atualizar.
 
 ---
 

package/bin/postinstall.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+
+const isColorSupported = !process.env.NO_COLOR && (process.stdout.isTTY || process.env.FORCE_COLOR);
+
+const colors = {
+  reset: isColorSupported ? '\x1b[0m' : '',
+  bold: isColorSupported ? '\x1b[1m' : '',
+  green: isColorSupported ? '\x1b[32m' : '',
+  cyan: isColorSupported ? '\x1b[36m' : '',
+  yellow: isColorSupported ? '\x1b[33m' : '',
+  dim: isColorSupported ? '\x1b[90m' : '',
+};
+
+const width = 74;
+
+function printLine(content, color = '') {
+  // Remove escapes ANSI para calcular o comprimento visível
+  const cleanLength = content.replace(/\x1b\[\d+m/g, '').length;
+  
+  // Calcula o espaço restante
+  const spacesCount = Math.max(0, width - cleanLength - 1);
+  console.log(`${colors.cyan}│${colors.reset} ${color}${content}${colors.reset}${' '.repeat(spacesCount)}${colors.cyan}│${colors.reset}`);
+}
+
+function printEmptyLine() {
+  console.log(`${colors.cyan}│${colors.reset}${' '.repeat(width)}${colors.cyan}│${colors.reset}`);
+}
+
+function printSeparator() {
+  console.log(`${colors.cyan}├${'─'.repeat(width)}┤${colors.reset}`);
+}
+
+function printBorderTop() {
+  console.log(`${colors.cyan}┌${'─'.repeat(width)}┐${colors.reset}`);
+}
+
+function printBorderBottom() {
+  console.log(`${colors.cyan}└${'─'.repeat(width)}┘${colors.reset}`);
+}
+
+console.log('');
+printBorderTop();
+printEmptyLine();
+printLine(`🚀  ${colors.bold}${colors.cyan}Bem-vindo ao Forge-SDD!${colors.reset}`);
+printEmptyLine();
+printLine(`O CLI definitivo para scaffolding de Software Design Doc (SDD)`);
+printLine(`pronto para uso com múltiplos agentes de Inteligência Artificial.`);
+printEmptyLine();
+printSeparator();
+printEmptyLine();
+printLine(`⚡  ${colors.bold}${colors.green}Comando global ativo: forge${colors.reset}`);
+printEmptyLine();
+printLine(`💡  ${colors.bold}Guia de Comandos Disponíveis:${colors.reset}`);
+printEmptyLine();
+printLine(`   ${colors.cyan}•${colors.reset} ${colors.bold}forge init${colors.reset}     ${colors.dim}─${colors.reset} Inicializa o SDD interativamente no projeto`);
+printLine(`   ${colors.cyan}•${colors.reset} ${colors.bold}forge update${colors.reset}   ${colors.dim}─${colors.reset} Adiciona novos agentes ou atualiza a versão`);
+printLine(`   ${colors.cyan}•${colors.reset} ${colors.bold}forge doctor${colors.reset}   ${colors.dim}─${colors.reset} Verifica a integridade da estrutura local`);
+printLine(`   ${colors.cyan}•${colors.reset} ${colors.bold}forge destroy${colors.reset}  ${colors.dim}─${colors.reset} Remove a estrutura SDD local do projeto`);
+printEmptyLine();
+printSeparator();
+printEmptyLine();
+printLine(`👉  ${colors.bold}Como começar agora:${colors.reset}`);
+printEmptyLine();
+printLine(`   1. Navegue até o diretório do seu projeto`);
+printLine(`   2. Execute o comando:`);
+printLine(`      ${colors.bold}${colors.yellow}$ forge init${colors.reset}`);
+printLine(`   3. Abra seu projeto com VS Code, Claude Code ou Gemini!`);
+printEmptyLine();
+printBorderBottom();
+console.log('');

package/bin/run.js

@@ -157,6 +157,16 @@ async function ensureBinary() {
     fs.chmodSync(bin, 0o755);
   }
 
+  // Executa a tela de boas-vindas pós-instalação no primeiro download
+  try {
+    const postinstallPath = path.join(__dirname, 'postinstall.js');
+    if (fs.existsSync(postinstallPath)) {
+      execFileSync(process.execPath, [postinstallPath], { stdio: 'inherit' });
+    }
+  } catch (err) {
+    // Silencia qualquer erro de renderização para não bloquear o fluxo do CLI
+  }
+
   return bin;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathanramorim/forge-sdd",
-  "version": "1.8.1-beta",
+  "version": "1.9.1-beta",
   "description": "CLI que scaffolda estruturas Forge-SDD em segundos",
   "homepage": "https://github.com/nathanramorim/forge-sdd",
   "repository": {
@@ -9,10 +9,12 @@
   },
   "license": "MIT",
   "bin": {
-    "forge-sdd": "bin/run.js"
+    "forge-sdd": "bin/run.js",
+    "forge": "bin/run.js"
   },
   "files": [
     "bin/run.js",
+    "bin/postinstall.js",
     "README.md"
   ],
   "engines": {