vireum-spec-cli 0.4.2 → 0.7.0

package/dist/lib/parsers/api.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBriefingApi = parseBriefingApi;
+function parseBriefingApi(briefing) {
+    const endpoints = extrairListaSimples(briefing, 'Principais recursos');
+    return {
+        tipo: 'api',
+        projeto: extrairCampo(briefing, 'Projeto'),
+        cliente: extrairCampo(briefing, 'Cliente'),
+        responsavel: extrairCampo(briefing, 'Responsável'),
+        data: extrairCampo(briefing, 'Data da reunião') || new Date().toLocaleDateString('pt-BR'),
+        objetivo: extrairCampo(briefing, 'Propósito'),
+        problema: '',
+        prioridade: '',
+        features: endpoints,
+        featuresDesejaveis: [],
+        regras: '',
+        riscos: { tecnico: '', juridico: '', operacional: '' },
+        extra: {
+            consumidores: extrairCampo(briefing, 'Consumidores'),
+            endpoints: endpoints.join(', '),
+            auth: extrairCampo(briefing, 'Autenticação'),
+            rate_limiting: briefing.includes('Rate limiting: Sim'),
+            cors: briefing.includes('CORS configurado: Sim'),
+            dados_sensiveis: briefing.includes('Dados sensíveis: Sim'),
+            lgpd: briefing.includes('LGPD: Sim'),
+            banco: extrairCampo(briefing, 'Banco'),
+            orm: extrairCampo(briefing, 'ORM'),
+            cache: briefing.includes('Cache (Redis): Sim'),
+            swagger: briefing.includes('Swagger / OpenAPI: Sim'),
+            versioning: briefing.includes('Versionamento de API: Sim'),
+            sdk: briefing.includes('SDK para consumidores: Sim'),
+            deploy_plataforma: extrairCampo(briefing, 'Plataforma'),
+            staging: briefing.includes('Staging: Sim'),
+            cicd: briefing.includes('CI/CD: Sim'),
+            monitoramento: briefing.includes('Monitoramento / alertas: Sim'),
+        },
+    };
+}
+function extrairCampo(briefing, campo) {
+    const r1 = new RegExp(`\\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m1 = briefing.match(r1);
+    if (m1)
+        return m1[1].trim();
+    const r2 = new RegExp(`- \\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m2 = briefing.match(r2);
+    if (m2)
+        return m2[1].trim();
+    const r3 = new RegExp(`- ${campo}:\\s*(.+)`, 'i');
+    const m3 = briefing.match(r3);
+    return m3 ? m3[1].trim() : '';
+}
+function extrairListaSimples(briefing, tituloSubsecao) {
+    const regex = new RegExp(`### ${tituloSubsecao}[^\\n]*\\n([\\s\\S]*?)(?=###|##|$)`, 'i');
+    const match = briefing.match(regex);
+    if (!match)
+        return [];
+    return match[1]
+        .split('\n')
+        .filter(l => l.trim().startsWith('- '))
+        .map(l => l.replace(/^-\s*/, '').trim())
+        .filter(Boolean);
+}

package/dist/lib/parsers/automation.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBriefingAutomation = parseBriefingAutomation;
+function parseBriefingAutomation(briefing) {
+    const objetivo = extrairCampo(briefing, 'O que faz');
+    const problema = extrairCampo(briefing, 'Processo atual');
+    return {
+        tipo: 'automation',
+        projeto: extrairCampo(briefing, 'Projeto'),
+        cliente: extrairCampo(briefing, 'Cliente'),
+        responsavel: extrairCampo(briefing, 'Responsável'),
+        data: extrairCampo(briefing, 'Data da reunião') || new Date().toLocaleDateString('pt-BR'),
+        objetivo,
+        problema,
+        prioridade: '',
+        features: objetivo ? [objetivo] : [],
+        featuresDesejaveis: [],
+        regras: '',
+        riscos: { tecnico: '', juridico: '', operacional: '' },
+        extra: {
+            trigger: extrairCampo(briefing, 'Trigger'),
+            frequencia: extrairCampo(briefing, 'Frequência'),
+            volume: extrairCampo(briefing, 'Volume por execução'),
+            fonte: extrairCampo(briefing, 'Fonte de dados'),
+            fonte_detalhe: extrairCampo(briefing, 'Detalhe da fonte'),
+            transformacao: extrairCampo(briefing, 'Transformação'),
+            destino: extrairCampo(briefing, 'Destino'),
+            destino_detalhe: extrairCampo(briefing, 'Detalhe do destino'),
+            retry: briefing.includes('Retry em caso de falha: Sim'),
+            alerta: briefing.includes('Alerta de falha: Sim'),
+            alerta_canal: extrairCampo(briefing, 'Canal de alerta'),
+            idempotente: briefing.includes('Idempotente: Sim'),
+            logs: briefing.includes('Logs de execução: Sim'),
+            dashboard_mon: briefing.includes('Dashboard de monitoramento: Sim'),
+            linguagem: extrairCampo(briefing, 'Linguagem'),
+            deploy_auto: extrairCampo(briefing, 'Deploy'),
+        },
+    };
+}
+function extrairCampo(briefing, campo) {
+    const r1 = new RegExp(`\\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m1 = briefing.match(r1);
+    if (m1)
+        return m1[1].trim();
+    const r2 = new RegExp(`- \\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m2 = briefing.match(r2);
+    if (m2)
+        return m2[1].trim();
+    const r3 = new RegExp(`- ${campo}:\\s*(.+)`, 'i');
+    const m3 = briefing.match(r3);
+    return m3 ? m3[1].trim() : '';
+}

package/dist/lib/parsers/mobile.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBriefingMobile = parseBriefingMobile;
+function parseBriefingMobile(briefing) {
+    const features = extrairCheckboxes(briefing, 'Funcionalidades obrigatórias');
+    return {
+        tipo: 'mobile',
+        projeto: extrairCampo(briefing, 'Projeto'),
+        cliente: extrairCampo(briefing, 'Cliente'),
+        responsavel: extrairCampo(briefing, 'Responsável'),
+        data: extrairCampo(briefing, 'Data da reunião') || new Date().toLocaleDateString('pt-BR'),
+        objetivo: extrairCampo(briefing, 'Propósito'),
+        problema: extrairCampo(briefing, 'Problema resolvido'),
+        prioridade: '',
+        features,
+        featuresDesejaveis: [],
+        regras: '',
+        riscos: { tecnico: '', juridico: '', operacional: '' },
+        extra: {
+            plataformas: extrairCampo(briefing, 'Plataformas'),
+            framework: extrairCampo(briefing, 'Framework'),
+            offline: briefing.includes('Funcionamento offline: Sim'),
+            push: briefing.includes('Notificações push: Sim'),
+            camera: briefing.includes('Câmera / Galeria'),
+            localizacao: briefing.includes('Localização / GPS'),
+            biometria: briefing.includes('Biometria'),
+            tem_api: briefing.includes('Conecta a API: Sim'),
+            api_propria: briefing.includes('API própria (Vireum): Sim'),
+            auth_mobile: extrairCampo(briefing, 'Autenticação'),
+            publicar: briefing.includes('Publicar nas lojas: Sim'),
+            conta_existente: briefing.includes('Contas de desenvolvedor existentes: Sim'),
+            deep_linking: briefing.includes('Deep linking: Sim'),
+            updates_ota: briefing.includes('Atualizações OTA: Sim'),
+        },
+    };
+}
+function extrairCampo(briefing, campo) {
+    const r1 = new RegExp(`\\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m1 = briefing.match(r1);
+    if (m1)
+        return m1[1].trim();
+    const r2 = new RegExp(`- \\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m2 = briefing.match(r2);
+    if (m2)
+        return m2[1].trim();
+    const r3 = new RegExp(`- ${campo}:\\s*(.+)`, 'i');
+    const m3 = briefing.match(r3);
+    return m3 ? m3[1].trim() : '';
+}
+function extrairCheckboxes(briefing, tituloSubsecao) {
+    const regex = new RegExp(`### ${tituloSubsecao}[^\\n]*\\n([\\s\\S]*?)(?=###|##|$)`, 'i');
+    const match = briefing.match(regex);
+    if (!match)
+        return [];
+    return match[1]
+        .split('\n')
+        .filter(l => l.includes('- [ ]'))
+        .map(l => l.replace('- [ ]', '').trim())
+        .filter(Boolean);
+}

package/dist/lib/parsers/system.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBriefingSystem = parseBriefingSystem;
+function parseBriefingSystem(briefing) {
+    return {
+        tipo: 'system',
+        projeto: extrairCampo(briefing, 'Projeto'),
+        cliente: extrairCampo(briefing, 'Cliente'),
+        responsavel: extrairCampo(briefing, 'Responsável'),
+        data: extrairCampo(briefing, 'Data da reunião') || new Date().toLocaleDateString('pt-BR'),
+        objetivo: extrairCampo(briefing, 'Objetivo principal'),
+        problema: extrairCampo(briefing, 'Problema que o sistema resolve'),
+        prioridade: extrairCampo(briefing, 'Prioridade do cliente'),
+        // Fix: extrair de subseções separadas para não misturar obrigatórias com desejáveis
+        features: extrairSubsecaoCheckboxes(briefing, 'Funcionalidades Obrigatórias'),
+        featuresDesejaveis: extrairSubsecaoCheckboxes(briefing, 'Funcionalidades Desej'),
+        regras: extrairSecao(briefing, 'Regras de Negócio'),
+        riscos: {
+            tecnico: extrairCampo(briefing, 'Risco técnico'),
+            juridico: extrairCampo(briefing, 'Risco jurídico'),
+            operacional: extrairCampo(briefing, 'Risco operacional'),
+        },
+        extra: {
+            usuarios: extrairCampo(briefing, 'Quem usará'),
+            multiUsuario: briefing.includes('Diferentes tipos de usuários: Sim'),
+            niveisAcesso: briefing.includes('Níveis de acesso: Sim'),
+            integracoes: extrairCampo(briefing, 'Integrações Externas'),
+            plataforma: extrairCampo(briefing, 'Tipo'),
+            hospedagem: extrairCampo(briefing, 'Hospedagem'),
+            cicd: briefing.includes('CI/CD desde o início: Sim'),
+            staging: briefing.includes('Ambiente de staging: Sim'),
+            lgpd: briefing.includes('LGPD: Sim'),
+            dados_sensiveis: briefing.includes('Dados sensíveis: Sim'),
+            pagamento: briefing.includes('Integração com pagamento: Sim'),
+            cobranca: extrairCampo(briefing, 'Modelo de cobrança'),
+            dashboard: briefing.includes('Dashboard administrativo: Sim'),
+            kpis: extrairCampo(briefing, 'KPIs'),
+        },
+    };
+}
+function extrairCampo(briefing, campo) {
+    const r1 = new RegExp(`\\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m1 = briefing.match(r1);
+    if (m1)
+        return m1[1].trim();
+    const r2 = new RegExp(`- \\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m2 = briefing.match(r2);
+    return m2 ? m2[1].trim() : '';
+}
+function extrairSecao(briefing, titulo) {
+    const regex = new RegExp(`## [^#]*${titulo}[\\s\\S]*?(?=\n## |$)`, 'i');
+    const match = briefing.match(regex);
+    return match ? match[0].trim() : '';
+}
+// Extrai checkboxes de uma subseção específica (###), sem vazar para a próxima
+function extrairSubsecaoCheckboxes(briefing, tituloSubsecao) {
+    const regex = new RegExp(`### ${tituloSubsecao}[^#\\n]*\\n([\\s\\S]*?)(?=###|##|$)`, 'i');
+    const match = briefing.match(regex);
+    if (!match)
+        return [];
+    return match[1]
+        .split('\n')
+        .filter(l => l.includes('- [ ]'))
+        .map(l => l.replace('- [ ]', '').trim())
+        .filter(Boolean);
+}

package/dist/lib/parsers/web.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBriefingWeb = parseBriefingWeb;
+function parseBriefingWeb(briefing) {
+    const subtipoRaw = extrairCampo(briefing, 'Tipo de site');
+    const secoes = extrairListaSimples(briefing, 'Seções da página');
+    const subtipoLabel = {
+        landing: 'Landing page',
+        institucional: 'Institucional',
+        blog: 'Blog / Conteúdo',
+    };
+    return {
+        tipo: 'web',
+        projeto: extrairCampo(briefing, 'Projeto'),
+        cliente: extrairCampo(briefing, 'Cliente'),
+        responsavel: extrairCampo(briefing, 'Responsável'),
+        data: extrairCampo(briefing, 'Data da reunião') || new Date().toLocaleDateString('pt-BR'),
+        objetivo: extrairCampo(briefing, 'Objetivo principal'),
+        problema: '',
+        prioridade: extrairCampo(briefing, 'CTA principal'),
+        features: secoes,
+        featuresDesejaveis: [],
+        regras: '',
+        riscos: { tecnico: '', juridico: '', operacional: '' },
+        extra: {
+            subtipo: subtipoRaw.toLowerCase(),
+            subtipo_label: subtipoLabel[subtipoRaw.toLowerCase()] || subtipoRaw,
+            cta_principal: extrairCampo(briefing, 'CTA principal'),
+            publico: extrairCampo(briefing, 'Público-alvo'),
+            secoes: secoes.join(', '),
+            formulario: briefing.includes('Formulário de contato/captura: Sim'),
+            campos_form: extrairCampo(briefing, 'Campos'),
+            blog_categorias: extrairCampo(briefing, 'Categorias do blog'),
+            analytics: briefing.includes('Analytics: Sim'),
+            chat: briefing.includes('Chat ao vivo: Sim'),
+            crm: extrairCampo(briefing, 'CRM / E-mail marketing'),
+            pixel: briefing.includes('Pixel de rastreamento: Sim'),
+            design_system: extrairCampo(briefing, 'Framework de UI'),
+            responsivo: briefing.includes('Responsivo: Sim'),
+            deploy_plataforma: extrairCampo(briefing, 'Plataforma de deploy'),
+            dominio: briefing.includes('Domínio configurado: Sim'),
+            seo: briefing.includes('SEO (meta tags, sitemap, OG): Sim'),
+            performance: briefing.includes('Performance / Core Web Vitals: Crítico'),
+        },
+    };
+}
+function extrairCampo(briefing, campo) {
+    const r1 = new RegExp(`\\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m1 = briefing.match(r1);
+    if (m1)
+        return m1[1].trim();
+    const r2 = new RegExp(`- \\*\\*${campo}:\\*\\*\\s*(.+)`, 'i');
+    const m2 = briefing.match(r2);
+    if (m2)
+        return m2[1].trim();
+    const r3 = new RegExp(`- ${campo}:\\s*(.+)`, 'i');
+    const m3 = briefing.match(r3);
+    return m3 ? m3[1].trim() : '';
+}
+function extrairListaSimples(briefing, tituloSubsecao) {
+    const regex = new RegExp(`### ${tituloSubsecao}[^\\n]*\\n([\\s\\S]*?)(?=###|##|$)`, 'i');
+    const match = briefing.match(regex);
+    if (!match)
+        return [];
+    return match[1]
+        .split('\n')
+        .filter(l => l.trim().startsWith('- '))
+        .map(l => l.replace(/^-\s*/, '').trim())
+        .filter(Boolean);
+}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/docs/COMO_USAR.md

@@ -0,0 +1,322 @@
+# Vireum Spec Framework — Guia de Uso
+
+> **Versão:** 0.7.0  
+> **Framework:** Spec Driven Development
+
+---
+
+## 📖 Índice
+1. [Instalação](#instalação)
+2. [Para Projetos Novos](#para-projetos-novos)
+3. [Para Projetos Existentes (Retrofit)](#para-projetos-existentes-retrofit)
+4. [Workflow Completo](#workflow-completo)
+5. [Referência Rápida de Comandos](#referência-rápida-de-comandos)
+
+---
+
+## Instalação
+
+### Via NPM
+```bash
+npm install -g vireum-spec-cli
+```
+
+### Verificar Instalação
+```bash
+vireum-spec --version
+```
+
+---
+
+## Para Projetos Novos
+
+### Passo 1: Inicializar o Projeto
+Execute o comando de inicialização escolhendo o tipo de projeto:
+
+```bash
+vireum-spec init --type <tipo>
+```
+
+**Tipos disponíveis:**
+- `system` — Sistema completo (padrão)
+- `web` — Landing page, site, plataforma web
+- `api` — API/Backend REST ou GraphQL
+- `mobile` — App mobile (iOS/Android)
+- `automation` — Automação de processos, workflows, RPA
+- `ai` — Aplicação com IA (chatbot, agente, extração de dados)
+
+**Exemplo:**
+```bash
+vireum-spec init --type ai
+```
+
+### Passo 2: Responder o Briefing Interativo
+
+O framework fará perguntas estruturadas em 6 seções:
+
+#### 📌 1. **Informações Gerais**
+- Nome do projeto
+- Nome do cliente
+- Responsável pela implementação
+- Data da reunião
+
+#### 🎯 2. **Problema e Caso de Uso**
+- Qual tarefa a IA/sistema vai resolver?
+- Quem executa hoje?
+- Quanto tempo leva?
+- Caso de uso mais próximo
+- Prazo esperado para MVP
+
+#### 📚 3. **Fonte de Conhecimento e Dados** *(se aplicável)*
+- Onde está o conhecimento? (docs, BD, web, API)
+- Volume de dados
+- Frequência de atualização
+
+#### 💬 4. **Interface e Interação**
+- Canal de comunicação (chat, WhatsApp, e-mail, API)
+- Precisa de dashboard/painel?
+- Quantos usuários?
+- Nível de autonomia (responder, executar ações, agente completo)
+
+#### 🤖 5. **Modelo e Infraestrutura**
+- Provider de IA (OpenAI, Anthropic, Google, etc.)
+- Restrições de custo
+- Dados sensíveis?
+- Restrição de enviar dados para API?
+- Integrações com sistemas existentes
+- Custo operacional estimado
+
+#### ✅ 6. **Qualidade e Supervisão**
+- Critério de sucesso
+- Nível de supervisão humana
+- Precisa de fallback para humano?
+
+### Passo 3: Gerar o Specification
+
+Após responder o briefing, execute:
+
+```bash
+vireum-spec distill
+```
+
+Isso irá gerar automaticamente no diretório `.spec/`:
+
+```
+.spec/
+├── briefing.md          # Suas respostas originais
+├── requirements.md      # Funcionalidades e integrações
+├── users.md            # Personas e usuários
+├── risks.md            # Riscos técnicos, jurídicos, operacionais
+├── architecture.md     # Arquitetura da solução
+├── rules.md            # Regras de negócio
+├── INDEX.md            # Índice completo do spec
+├── changelog.md        # Histórico de mudanças
+└── tasks/
+    ├── active.md       # Tasks em desenvolvimento
+    ├── backlog.md      # Tasks planejadas
+    └── done.md         # Tasks concluídas
+```
+
+### Passo 4: Configurar Stack e Infraestrutura
+
+```bash
+vireum-spec setup
+```
+
+Você será perguntado sobre:
+- **Frontend:** Next.js, React, Vue, Nuxt, outro, ou nenhum
+- **Backend:** Node.js + Express/Fastify, NestJS, Python + FastAPI, outro, ou nenhum
+- **Banco de dados:** PostgreSQL, MySQL, SQLite, MongoDB, outro
+- **ORM:** Prisma, TypeORM, Drizzle, Sequelize, nenhum, outro
+- **Cache/Filas:** Redis + BullMQ, Redis simples, nenhum, outro
+- **Autenticação:** JWT, NextAuth, Supabase Auth, Clerk, outro
+- **Multi-tenant:** Sim/Não (e qual estratégia)
+- **Protocolo de IA:** Sistema de prompts, guardrails, tools/functions
+
+Gera automaticamente:
+- `.vireum/stack.json` — Stack técnica
+- `.vireum/protocol.md` — Protocolo de funcionamento da IA
+- `.cursor/rules/` — Regras para Claude Code
+
+### Passo 5: Priorizar Features (Opcional)
+
+```bash
+vireum-spec prioritize
+```
+
+Classifica as features em:
+- **MVP** — Mínimo viável
+- **Fase 2** — Próxima iteração
+- **Fora do escopo** — Talvez nunca
+
+---
+
+## Para Projetos Existentes (Retrofit)
+
+Use quando o projeto já está em andamento ou em produção e você quer documentá-lo com o framework.
+
+### Passo 1: Executar Retrofit
+
+No diretório do projeto já existente:
+
+```bash
+vireum-spec retrofit
+```
+
+O framework irá:
+1. **Analisar automaticamente** a estrutura de arquivos
+2. **Detectar** tecnologias usadas (frontend, backend, BD, ORM, auth)
+3. **Encontrar** rotas/features implementadas
+4. **Buscar** README existente
+
+### Passo 2: Responder Complementos
+
+Você responde perguntas sobre informações que **não puderam ser inferidas automaticamente**:
+
+- Nome do projeto
+- Cliente
+- Objetivo principal
+- Que problema resolve?
+- O que já está funcionando / prioridade atual
+- Quem usa?
+- Principais regras de negócio
+- Fase do projeto (MVP em dev, MVP concluído, Produção, Manutenção)
+- Multi-tenant?
+- Dados sensíveis?
+- Principais riscos
+
+### Passo 3: Revisar Briefing Gerado
+
+O framework cria `.spec/briefing.md` com as informações coletadas e inferidas.
+
+**⚠️ Importante:** Revise e corrija manualmente qualquer detalhe detectado incorretamente.
+
+### Passo 4: Gerar Spec Completo
+
+```bash
+vireum-spec distill
+```
+
+Mesmo processo do projeto novo — gera todos os arquivos em `.spec/`.
+
+### Passo 5: (Opcional) Instalar Skills no Claude Code
+
+Se você usa Claude Code:
+
+```bash
+vireum-spec skills
+```
+
+Instala automáticamente as skills do framework no seu cliente Claude Code para acelerar o desenvolvimento.
+
+---
+
+## Workflow Completo
+
+### Novo Projeto
+```
+vireum-spec init --type <tipo>
+    ↓
+vireum-spec distill
+    ↓
+vireum-spec setup
+    ↓
+vireum-spec prioritize (opcional)
+    ↓
+Iniciar desenvolvimento com spec documentado
+```
+
+### Projeto Existente
+```
+vireum-spec retrofit
+    ↓
+(Revisar e corrigir .spec/briefing.md)
+    ↓
+vireum-spec distill
+    ↓
+vireum-spec setup
+    ↓
+Continuar com spec documentado
+```
+
+---
+
+## Referência Rápida de Comandos
+
+| Comando | Descrição | Quando usar |
+|---------|-----------|------------|
+| `vireum-spec init --type <tipo>` | Inicia novo projeto com briefing interativo | Novo projeto |
+| `vireum-spec distill` | Gera spec a partir do briefing | Após responder briefing |
+| `vireum-spec setup` | Configura stack e protocolo da IA | Após distill |
+| `vireum-spec prioritize` | Classifica features em MVP/Fase2 | Quando há muitas features |
+| `vireum-spec retrofit` | Gera spec de projeto existente | Projeto em andamento |
+| `vireum-spec health` | Verifica inconsistências no spec | Manutenção contínua |
+| `vireum-spec brief` | Gera resumo do estado atual | Status check |
+| `vireum-spec verify-mcps` | Verifica MCPs instalados | Diagnóstico |
+| `vireum-spec skills` | Instala skills no Claude Code | Integração com IA |
+| `vireum-spec enrich` | Gera prompt para identificar gaps | Qualidade do spec |
+
+---
+
+## Estrutura de Arquivos Criados
+
+### Novo Projeto
+```
+projeto-novo/
+├── .spec/
+│   ├── briefing.md
+│   ├── requirements.md
+│   ├── users.md
+│   ├── risks.md
+│   ├── architecture.md
+│   ├── rules.md
+│   ├── INDEX.md
+│   ├── changelog.md
+│   └── tasks/
+│       ├── active.md
+│       ├── backlog.md
+│       └── done.md
+├── .vireum/
+│   ├── stack.json
+│   └── protocol.md
+├── .cursor/
+│   └── rules/
+│       └── *.md
+└── package.json
+```
+
+### Projeto Retrofit
+Adiciona a mesma estrutura `.spec/` + `.vireum/` ao projeto existente.
+
+---
+
+## Dicas Importantes
+
+### ✅ Sempre faça:
+- **Responda o briefing honestamente** — quanto mais detalhe, melhor o spec
+- **Revise o spec gerado** — não é 100% automático, pode precisar de ajustes
+- **Use o .spec/INDEX.md** — começa pelo índice para navegar tudo
+- **Mantenha atualizado** — quando há mudanças significativas, rode `vireum-spec distill` novamente
+
+### ❌ Evite:
+- Deixar campos em branco quando souber a resposta
+- Ignorar riscos e restrições — eles aparecem depois
+- Não revisar o briefing gerado — pode ter interpretações erradas
+- Esquecer de rodar `setup` — o protocolo de IA é crítico
+
+### 💡 Pro Tips:
+- Use `vireum-spec health` regularmente para manter spec consistente
+- `vireum-spec brief` é perfeito para reportar status a stakeholders
+- `vireum-spec enrich` ajuda a identificar gaps antes de começar a dev
+- Skills do `vireum-spec skills` fazem a IA entender melhor seu projeto
+
+---
+
+## Próximos Passos
+
+Após setup, você está pronto para:
+
+1. **Começar a implementação** — Use o spec como guia
+2. **Integrar com Claude Code** — Skills instaladas facilitam muito
+3. **Manter o spec atualizado** — Conforme aprende, atualiza
+4. **Usar como documentação** — Compartilhe `.spec/INDEX.md` com o time