vireum-spec-cli 0.5.0 → 0.7.0

package/dist/lib/generators-setup.js

@@ -0,0 +1,764 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gerarClaudeSettings = gerarClaudeSettings;
+exports.gerarContextInjectHook = gerarContextInjectHook;
+exports.gerarPreToolGuardHook = gerarPreToolGuardHook;
+exports.gerarPrePushHook = gerarPrePushHook;
+exports.gerarArchitecture = gerarArchitecture;
+exports.gerarMcpSetup = gerarMcpSetup;
+exports.gerarRulesGlobal = gerarRulesGlobal;
+exports.gerarMcpsGlobal = gerarMcpsGlobal;
+exports.gerarClaudeMd = gerarClaudeMd;
+exports.gerarCursorRules = gerarCursorRules;
+exports.gerarDesign = gerarDesign;
+exports.gerarAgentsMd = gerarAgentsMd;
+function gerarClaudeSettings() {
+    return JSON.stringify({
+        hooks: {
+            UserPromptSubmit: [
+                {
+                    matcher: '',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '.vireum/hooks/context-inject.sh',
+                        },
+                    ],
+                },
+            ],
+            PreToolUse: [
+                {
+                    matcher: 'Edit|Write',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '.vireum/hooks/pre-tool-guard.sh',
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
+function gerarContextInjectHook() {
+    return `#!/bin/bash
+# Vireum Spec — Context Injection Hook
+# Gerado por vireum-spec setup
+# Injeta tasks ativas no contexto do prompt
+
+SPEC_DIR=".spec"
+ACTIVE_TASKS="\${SPEC_DIR}/tasks/active.md"
+
+if [ -f "\$ACTIVE_TASKS" ]; then
+  echo ""
+  echo "📋 Tasks Ativas (Context Inject):"
+  echo "=================================="
+  grep "^##" "\$ACTIVE_TASKS" | head -10
+  echo ""
+fi
+`;
+}
+function gerarPreToolGuardHook() {
+    return `#!/bin/bash
+# Vireum Spec — Pre-Tool Guard Hook (Soft Enforcement)
+# Gerado por vireum-spec setup
+# Avisa se .spec/INDEX.md não foi lido nesta sessão
+
+INDEX_FILE=".spec/INDEX.md"
+FLAG_FILE="/tmp/vireum_index_read_\$\$"
+
+# Verificar se INDEX.md foi lido (marcado por outro hook ou ação)
+if [ ! -f "\$FLAG_FILE" ] && [ -f "\$INDEX_FILE" ]; then
+  echo ""
+  echo "⚠️  AVISO: .spec/INDEX.md não foi lido nesta sessão"
+  echo "   Leia o INDEX.md antes de implementar para entender o contexto"
+  echo ""
+fi
+`;
+}
+function gerarPrePushHook() {
+    return `#!/bin/sh
+# Vireum Spec — Health Check automatico pre-push
+# Gerado por vireum-spec setup
+
+echo ""
+echo "  Vireum Spec — verificando consistencia do spec..."
+echo ""
+
+if command -v vireum-spec >/dev/null 2>&1; then
+  vireum-spec health
+else
+  npx --no-install vireum-spec-cli health 2>/dev/null || npx -y vireum-spec-cli health
+fi
+
+STATUS=$?
+
+if [ $STATUS -ne 0 ]; then
+  echo ""
+  echo "  Spec com problemas criticos. Corrija antes de fazer push."
+  echo "  Execute: vireum-spec health para detalhes"
+  echo ""
+  exit 1
+fi
+
+exit 0
+`;
+}
+function gerarArchitecture(d) {
+    const { stack, infra, mcps, projeto } = d;
+    const tenant = stack.multiTenant
+        ? `\n## Multi-Tenancy\n- Estratégia: ${stack.tenantStrategy}\n- Nunca fazer query sem filtro de tenantId`
+        : '';
+    return `# Architecture — ${projeto}
+
+> Atualizado via vireum-spec setup
+> A IA deve registrar aqui cada decisão técnica relevante
+
+## Stack
+- Frontend: ${stack.frontend}
+- Backend: ${stack.backend}
+- Banco de dados: ${stack.banco}
+- ORM: ${stack.orm}
+- Cache / Filas: ${stack.cache}
+- Auth: ${stack.auth}
+${tenant}
+
+## Infraestrutura
+- Hospedagem: ${infra.hospedagem}
+- Containerização: ${infra.containerizacao}
+- CI/CD: ${infra.cicd ? infra.cicdFerramenta : 'Não configurado'}
+
+## MCPs Ativos
+${mcps.map((m) => `- ${m}`).join('\n')}
+
+## Decisões Arquiteturais
+> A IA deve registrar aqui cada decisão técnica com justificativa
+
+| Data | Decisão | Alternativas descartadas | Motivo |
+|------|---------|--------------------------|--------|
+|      |         |                          |        |
+`;
+}
+function gerarMcpSetup(d) {
+    const mcpInfo = {
+        context7: 'https://github.com/upstash/context7',
+        github: 'https://github.com/modelcontextprotocol/servers/tree/main/src/github',
+        database: 'https://github.com/modelcontextprotocol/servers/tree/main/src/postgres',
+        browser: 'https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer',
+        puppeteer: 'https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer',
+        docker: 'https://github.com/modelcontextprotocol/servers',
+        redis: 'https://github.com/modelcontextprotocol/servers',
+    };
+    const lista = d.mcps
+        .map((m) => `### ${m}\n- Instalação: ${mcpInfo[m] || 'Ver documentação oficial'}\n- Credenciais: configurar manualmente após instalação`)
+        .join('\n\n');
+    return `# MCP Setup — ${d.projeto}
+
+> MCPs necessários para este projeto.
+> Instalação é feita manualmente — o framework não acessa credenciais.
+
+## MCPs do Projeto
+${lista}
+
+## Como instalar
+1. Acesse o link de cada MCP acima
+2. Siga as instruções de instalação
+3. Configure as credenciais manualmente no seu cliente (Claude Code / Cursor)
+4. Execute: vireum-spec verify-mcps
+`;
+}
+function gerarRulesGlobal() {
+    return `# Rules — Global Vireum
+
+> Regras globais que se aplicam a TODOS os projetos Vireum.
+> Nunca editar por projeto. Em conflito com .spec/rules.md, estas prevalecem.
+
+## Regras de Escopo
+- Nunca implementar funcionalidade fora do requirements.md sem criar task [PENDING]
+- Nunca puxar task do backlog para active sem validação humana explícita
+- Sempre avisar escopo creep antes de implementar — parar e perguntar
+
+## Regras de Planejamento
+- Sempre planejar antes de implementar — escrever o que sera feito e quais arquivos serao tocados
+- Confirmar o plano com o dev em tasks complexas antes de executar
+- Nunca comecar a escrever codigo sem ter um plano claro
+
+## Regras de Design
+- Sempre consultar .spec/design.md antes de criar ou modificar qualquer componente de UI
+- Nunca hardcodar cores — usar sempre os tokens definidos em design.md
+- Nunca misturar design systems
+
+## Regras de Health
+- Verificar consistencia do spec no inicio de cada sessao
+- Avisar o dev sobre inconsistencias antes de qualquer implementacao
+- Tasks sem criterios de aceitacao devem ser sinalizadas antes de implementar
+
+## Regras de Spec
+- Nunca marcar task como done sem validar os critérios de aceitação
+- Nunca tomar decisão de arquitetura sem registrar em architecture.md com justificativa
+- Sempre definir contrato de interface antes de implementar features com frontend e backend
+- Ao identificar risco novo, adicionar em risks.md antes de continuar
+
+## Regras de Contexto
+- Sempre ler INDEX.md no início de cada sessão
+- Carregar outros arquivos de spec apenas quando a task exigir
+- Registrar decisões relevantes em changelog.md com data
+
+## Regras de Tasks
+- Bugs viram hotfix com tag [H] — nunca são tratados como tasks normais
+- Demandas novas do cliente viram [PENDING] no backlog — nunca vão direto para active
+- Task só é done quando critérios de aceitação estão validados
+
+## Nunca
+- Implementar sem ler o spec primeiro
+- Implementar sem planejar primeiro
+- Criar componente de UI sem consultar design.md
+- Tomar decisão de lib ou stack sem documentar o porquê
+- Responder dúvida de escopo sem consultar requirements.md
+- Comunicar diretamente com o cliente — isso é papel do dev
+`;
+}
+function gerarMcpsGlobal(d) {
+    return `# MCPs — Global Vireum
+
+> MCPs padrão disponíveis nos projetos Vireum.
+> MCPs ativos por projeto estão em .spec/architecture.md
+
+## Stack Padrão
+- context7   — documentação atualizada das libs (sempre ativo)
+- filesystem — leitura e escrita no projeto (nativo)
+- github     — PRs, issues, branches referenciando tasks
+- database   — validar schema e dados em desenvolvimento
+- browser    — testar endpoints e validar fluxos
+- puppeteer  — testes de jornada de UI
+- docker     — gerenciar containers em desenvolvimento
+- redis      — inspecionar cache e filas (quando aplicável)
+
+## MCPs Ativos Neste Projeto
+${d.mcps.map((m) => `- ${m}`).join('\n')}
+
+## Quando usar cada MCP
+- Antes de usar qualquer lib → context7: buscar docs atualizadas
+- Task concluída → github: criar PR referenciando a task
+- Bug identificado → github: abrir issue com contexto
+- Decisão de schema → database: validar antes de implementar
+- Feature implementada → browser: testar endpoint ou fluxo
+- Jornada de UI → puppeteer: validar fluxo completo
+`;
+}
+function gerarClaudeMd(d) {
+    const { projeto, stack, mcps } = d;
+    const tenant = stack.multiTenant
+        ? '\n- NUNCA fazer query sem filtro de tenantId — projeto multi-tenant'
+        : '';
+    const libs = [stack.frontend, stack.backend, stack.orm, stack.cache]
+        .filter((l) => l && l !== 'Nenhum' && l !== 'Outro')
+        .join(', ');
+    return `# ${projeto} — Vireum Spec Protocol
+
+> Este projeto usa Spec Driven Development pela Vireum Desenvolvimento.
+> Leia este arquivo completamente antes de qualquer ação.
+
+## Início de cada sessão
+1. Leia \`.spec/INDEX.md\` — estado atual do projeto
+2. Verifique consistencia do spec:
+   - tasks/active.md tem tasks sem criterios de aceitacao? → avisar o dev
+   - architecture.md tem stack definida? → se nao, avisar
+   - INDEX.md reflete o estado real do MVP? → se desatualizado, avisar
+3. Se encontrar inconsistencias criticas → avisar antes de qualquer implementacao
+4. Identifique o modo da sessão pela solicitação do dev
+5. Carregue arquivos adicionais apenas se a task exigir
+
+## Modos de operação
+
+### Modo 1 — Implementar
+Acionado por: "desenvolve", "implementa", "cria", + nome de task
+1. Leia \`.spec/tasks/active.md\`
+2. Leia \`.spec/requirements.md\` para contexto da feature
+3. Consulte o Context7 para docs atualizadas da lib que vai usar
+4. Se task de UI: leia \`.spec/design.md\` antes de qualquer componente
+5. PLANEJAR: escreva o que sera implementado, quais arquivos serao tocados e riscos identificados
+6. Confirme o plano com o dev antes de executar em tasks complexas
+7. Implemente seguindo os critérios de aceitação da task
+8. Ao concluir: marque como done, mova para \`tasks/done.md\`, atualize \`INDEX.md\`
+9. Se decisão arquitetural tomada: registre em \`architecture.md\`
+
+### Modo 2 — Bug
+Acionado por: "erro", "bug", "quebrou", "não funciona"
+1. PLANEJAR: descreva o que sera investigado e quais arquivos serao tocados
+2. Crie hotfix em \`tasks/active.md\` com tag [H] e prioridade crítica
+3. Identifique e resolva a causa raiz
+4. Registre causa raiz em \`changelog.md\`
+5. Verifique se o bug afeta outras tasks em \`tasks/active.md\`
+
+### Modo 3 — Nova demanda
+Acionado por: "cliente pediu", "adiciona", "quero incluir" (fora do spec)
+1. Verifique se já existe em \`.spec/requirements.md\`
+2. Se não existir: crie task com tag [PENDING] em \`tasks/backlog.md\`
+3. Informe o impacto estimado e aguarde decisão do dev
+4. NUNCA implemente demanda nova sem aprovação explícita
+
+### Modo 4 — Dúvida de escopo
+Acionado por: "como deve funcionar", "o que foi combinado", "qual o comportamento"
+1. Leia \`.spec/requirements.md\`
+2. Responda com base no spec — não invente comportamento
+
+## Context7 — Documentação atualizada
+Sempre que for usar uma lib do projeto, consulte a documentação atualizada via Context7 antes de implementar.
+Nunca assuma que você conhece a API mais recente — sempre verifique.
+Libs deste projeto: ${libs}
+
+## Arquivos de contexto disponíveis
+- Escopo e features → leia \`.spec/requirements.md\`
+- Decisoes tecnicas → leia \`.spec/architecture.md\`
+- Perfis e permissoes → leia \`.spec/users.md\`
+- Riscos → leia \`.spec/risks.md\`
+- Tarefas ativas → leia \`.spec/tasks/active.md\`
+- Historico → leia \`.spec/changelog.md\`
+- Design e componentes → leia \`.spec/design.md\` antes de qualquer UI
+
+## Regras globais
+Leia \`.vireum/rules.md\` — aplicam-se a todas as sessões.
+
+## Regras do projeto
+Leia \`.spec/rules.md\` — regras específicas deste projeto.
+
+## Stack
+- Frontend: ${stack.frontend}
+- Backend: ${stack.backend}
+- Banco: ${stack.banco}
+- Auth: ${stack.auth}${tenant}
+
+## MCPs ativos
+${mcps.map((m) => `- ${m}`).join('\n')}
+
+## Alertas
+- Escopo creep: se a solicitação não está em requirements.md → PARAR e avisar
+- Decisão de lib nova: registrar em architecture.md antes de usar
+- Risco identificado: adicionar em risks.md antes de continuar
+- UI sem consultar design.md → PARAR e consultar primeiro
+- Spec inconsistente → avisar o dev antes de implementar
+`;
+}
+function gerarCursorRules(d) {
+    return `---
+description: Vireum Spec Protocol — ${d.projeto}
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Vireum Spec Protocol
+
+Este projeto usa Spec Driven Development pela Vireum Desenvolvimento.
+
+## Início de sessão
+- Sempre leia \`.spec/INDEX.md\` primeiro
+- Verifique consistencia: tasks sem criterios, stack indefinida, INDEX desatualizado
+- Avise inconsistencias antes de qualquer implementacao
+- Carregue outros arquivos de spec apenas quando necessário
+
+## Planejamento obrigatorio
+Antes de qualquer implementacao:
+- Escreva o que sera feito e quais arquivos serao tocados
+- Identifique riscos e dependencias
+- Confirme com o dev em tasks complexas antes de executar
+
+## Design
+- SEMPRE leia \`.spec/design.md\` antes de criar ou modificar qualquer componente de UI
+- Nunca hardcodar cores — usar tokens do design.md
+
+## Context7
+- Sempre consultar Context7 antes de usar qualquer lib do projeto
+- Nunca assumir que conhece a API mais recente
+
+## Modos
+- Implementar → PLANEJAR primeiro, consulte Context7, leia tasks/active.md, se UI leia design.md
+- Bug → PLANEJAR investigacao, crie hotfix [H] em active.md, registre causa raiz em changelog.md
+- Nova demanda → crie [PENDING] em backlog.md, aguarde aprovação
+- Dúvida de escopo → consulte requirements.md
+
+## Regras
+- Ver \`.vireum/rules.md\` — regras globais
+- Ver \`.spec/rules.md\` — regras do projeto
+- Nunca implementar fora do spec sem [PENDING] aprovado
+- Nunca implementar sem planejar primeiro
+- Nunca criar UI sem consultar design.md
+- Nunca marcar done sem critérios validados
+`;
+}
+function gerarDesign(d) {
+    const { design, projeto } = d;
+    const sistemas = {
+        shadcn: {
+            descricao: 'Shadcn/ui com Tailwind CSS e Radix UI',
+            convencoes: [
+                'Usar cn() para mesclar classes Tailwind',
+                'Componentes em src/components/ui/',
+                'Variaveis CSS em globals.css via --primary, --secondary, etc.',
+                'Icones via lucide-react',
+                'Formularios com react-hook-form + zod',
+            ],
+            tokens: 'Tailwind config + CSS variables',
+        },
+        tailwind: {
+            descricao: 'Tailwind CSS puro',
+            convencoes: [
+                'Classes utilitarias diretamente nos componentes',
+                'Cores customizadas em tailwind.config.ts',
+                'Componentes em src/components/',
+                'Nao criar classes CSS customizadas sem necessidade',
+            ],
+            tokens: 'tailwind.config.ts',
+        },
+        chakra: {
+            descricao: 'Chakra UI',
+            convencoes: [
+                'Usar componentes do Chakra sempre que disponivel',
+                'Theme customizado em src/theme/',
+                'Variaveis de cor via useColorModeValue para dark/light mode',
+                'Spacing seguindo escala do Chakra (1 = 4px)',
+            ],
+            tokens: 'ChakraProvider theme',
+        },
+        mui: {
+            descricao: 'Material UI (MUI)',
+            convencoes: [
+                'Usar componentes MUI sempre que disponivel',
+                'Theme customizado em src/theme/index.ts',
+                'Usar sx prop para customizacoes pontuais',
+                'Evitar inline styles — preferir theme tokens',
+            ],
+            tokens: 'createTheme()',
+        },
+        base: {
+            descricao: 'Design system basico gerado pelo Vireum Spec Framework',
+            convencoes: [
+                `Usar ${design.baseTailwind ? 'Tailwind CSS' : 'CSS customizado'} para estilizacao`,
+                'Tokens de cor definidos neste arquivo — nunca hardcodar valores',
+                'Componentes em src/components/',
+                'Tipografia consistente — usar apenas as fontes definidas aqui',
+                'Espacamento em multiplos de 4px',
+                'Bordas arredondadas padrao: 8px',
+            ],
+            tokens: design.baseTailwind
+                ? 'tailwind.config.ts + CSS variables'
+                : 'CSS variables em globals.css',
+        },
+        custom: {
+            descricao: 'Design system proprio',
+            convencoes: ['Ver secao de convencoes abaixo'],
+            tokens: 'Ver secao de tokens abaixo',
+        },
+        none: {
+            descricao: 'Sem design system definido',
+            convencoes: ['A definir'],
+            tokens: 'A definir',
+        },
+    };
+    const ds = sistemas[design.system] || sistemas.none;
+    const coresSection = Object.keys(design.cores).filter((k) => design.cores[k]).length > 0
+        ? Object.entries(design.cores)
+            .filter(([, v]) => v)
+            .map(([k, v]) => `- ${k}: ${v}`)
+            .join('\n')
+        : `> Usar tokens padrao do ${ds.descricao}`;
+    const fontesSection = Object.keys(design.fontes).filter((k) => design.fontes[k]).length > 0
+        ? Object.entries(design.fontes)
+            .filter(([, v]) => v)
+            .map(([k, v]) => `- ${k}: ${v}`)
+            .join('\n')
+        : '> Usar fonte padrao do sistema';
+    const baseSection = design.system === 'base'
+        ? `
+## Espacamento
+- Base: 4px
+- xs: 4px | sm: 8px | md: 16px | lg: 24px | xl: 32px | 2xl: 48px
+
+## Bordas
+- Radius padrao: 8px
+- Radius pequeno: 4px
+- Radius grande: 16px
+- Radius pill: 9999px
+
+## Sombras
+- sm: 0 1px 2px rgba(0,0,0,0.05)
+- md: 0 4px 6px rgba(0,0,0,0.07)
+- lg: 0 10px 15px rgba(0,0,0,0.10)
+`
+        : '';
+    return `# Design — ${projeto}
+
+> A IA deve consultar este arquivo antes de criar ou modificar qualquer componente de UI.
+> Nunca usar cores, fontes ou espacamentos fora dos tokens definidos aqui.
+
+## Design System
+**${ds.descricao}**
+- Tokens: ${ds.tokens}
+
+## Cores
+${coresSection}
+
+## Fontes
+${fontesSection}
+
+## Convencoes
+${ds.convencoes.map((c) => `- ${c}`).join('\n')}
+${design.customizacoes ? `\n## Convencoes Customizadas\n${design.customizacoes}` : ''}
+${baseSection}
+## Regras para a IA
+- Nunca criar componente sem consultar este arquivo primeiro
+- Nunca hardcodar cores — usar sempre os tokens definidos acima
+- Nunca misturar design systems — usar apenas ${ds.descricao}
+- Novos componentes seguem as convencoes desta secao
+- Em caso de duvida sobre UI, perguntar ao dev antes de implementar
+${design.system === 'shadcn' ? '- Sempre usar cn() para mesclar classes condicionais\n- Preferir componentes do Shadcn antes de criar do zero' : ''}
+${design.system === 'tailwind' ? '- Preferir classes Tailwind a CSS customizado\n- Nao criar novas classes sem necessidade real' : ''}
+${design.system === 'base' ? `- Seguir tokens de espacamento e bordas definidos acima\n- ${design.baseTailwind ? 'Usar classes Tailwind mapeadas para os tokens' : 'Usar CSS variables definidas em globals.css'}` : ''}
+
+## Componentes Existentes
+> A IA deve atualizar esta secao conforme novos componentes sao criados
+
+| Componente | Localizacao | Descricao |
+|------------|-------------|-----------|
+|            |             |           |
+`;
+}
+function gerarAgentsMd(d) {
+    const { projeto, stack, infra, mcps, design } = d;
+    const tenant = stack.multiTenant
+        ? `\n- **Multi-tenant:** Estratégia — ${stack.tenantStrategy}\n- **Isolamento:** Nunca fazer query sem filtro de tenantId`
+        : '';
+    const libs = [stack.frontend, stack.backend, stack.orm, stack.cache]
+        .filter((l) => l && l !== 'Nenhum' && l !== 'Outro')
+        .join(', ');
+    const designSection = design.system !== 'none'
+        ? `\n## Design System\n**${design.system === 'base' ? 'Base' : design.system.charAt(0).toUpperCase() + design.system.slice(1)}**\n${design.cores.primary ? `- Cor primária: ${design.cores.primary}` : ''}\n${design.cores.secondary ? `- Cor secundária: ${design.cores.secondary}` : ''}\n- Nunca hardcodar cores — usar sempre os tokens do design.md`
+        : '';
+    const regrasGlobaisEmbutidas = `## Regras Globais (Vireum Framework)
+
+**Regras de Escopo**
+- Nunca implementar funcionalidade fora do requirements.md sem criar task [PENDING]
+- Nunca puxar task do backlog para active sem validação humana
+- Sempre avisar escopo creep antes de implementar
+
+**Regras de Planejamento**
+- SEMPRE planejar antes de implementar — escrever o que será feito, quais arquivos serão tocados
+- Confirmar o plano com o dev em tasks complexas antes de executar
+- Nunca começar código sem plano claro
+
+**Regras de Design**
+- SEMPRE consultar design.md antes de criar ou modificar qualquer componente UI
+- Nunca hardcodar cores/fontes — usar sempre os tokens definidos
+- Nunca misturar design systems
+
+**Regras de Spec**
+- Nunca marcar task como done sem validar critérios de aceitação
+- Nunca tomar decisão arquitetural sem registrar em architecture.md com justificativa
+- Sempre definir contrato de interface antes de implementar features frontend+backend
+- Ao identificar risco novo, adicionar em risks.md antes de continuar
+
+**Regras de Contexto**
+- SEMPRE ler INDEX.md no início de cada sessão
+- Carregar outros arquivos de spec apenas quando a task exigir
+- Registrar decisões relevantes em changelog.md com data
+
+**Regras de Tasks**
+- Bugs viram hotfix [H] — nunca tasks normais
+- Demandas novas do cliente viram [PENDING] em backlog — nunca vão direto para active
+- Task só é done quando critérios validados
+
+**Nunca**
+- Implementar sem ler spec primeiro
+- Implementar sem planejar
+- Criar UI sem consultar design.md
+- Tomar decisão de lib/stack sem documentar
+- Comunicar com cliente — isso é papel do dev`;
+    return `# ${projeto} — Vireum Spec Protocol (Agentes)
+
+> Protocolo completo e autossuficiente para agentes (Codex CLI, Gemini CLI, ou qualquer agente).
+> Documento é **first-class** — não precisa ler CLAUDE.md.
+
+---
+
+## Início de cada sessão
+
+1. Leia \`.spec/INDEX.md\` — estado atual do projeto e tasks ativas
+2. Verifique consistência:
+   - \`.spec/tasks/active.md\` tem tasks sem critérios de aceitação? → avisar
+   - \`.spec/architecture.md\` tem stack definida? → avisar se não
+   - \`.spec/INDEX.md\` reflete estado real do MVP? → avisar se desatualizado
+   - \`.spec/requirements.md\` tem funcionalidades mapeadas? → avisar se vago
+3. Se encontrar inconsistências → avisar o desenvolvedor ANTES de qualquer implementação
+4. Identifique o modo da sessão pela solicitação
+5. **Carregue apenas os arquivos de spec que a task exigir**
+
+---
+
+## Modos de Operação
+
+### Modo 1 — Implementar Feature/Task
+**Acionado por:** "desenvolve", "implementa", "cria", + nome de task ou feature
+
+1. Leia \`.spec/tasks/active.md\` e identifique a task
+2. Leia \`.spec/requirements.md\` para entender contexto da feature
+3. Consulte **Context7** para documentação ATUALIZADA da lib que vai usar
+   - Nunca assuma que conhece a API mais recente
+4. **SE TASK FOR UI:** leia \`.spec/design.md\` ANTES de escrever qualquer componente
+5. **PLANEJAR:** escreva o que será implementado, quais arquivos serão tocados, riscos identificados
+6. Implemente rigorosamente segundo os **critérios de aceitação** da task
+7. Ao concluir:
+   - Marque task como done com validação dos critérios
+   - Mova para \`.spec/tasks/done.md\`
+   - Atualize \`.spec/INDEX.md\`
+8. Se tomou decisão arquitetural: registre em \`.spec/architecture.md\` com justificativa
+
+### Modo 2 — Bug / Fix Crítico
+**Acionado por:** "erro", "bug", "quebrou", "não funciona", "falha"
+
+1. **PLANEJAR:** descreva o que será investigado, quais arquivos serão analisados
+2. Crie hotfix em \`.spec/tasks/active.md\` com tag **[H]** e prioridade crítica
+3. Identifique causa raiz (não apenas sintoma)
+4. Registre causa raiz em \`.spec/changelog.md\` com data
+5. Verifique se o bug afeta outras tasks em \`.spec/tasks/active.md\`
+
+### Modo 3 — Nova Demanda do Cliente
+**Acionado por:** "cliente pediu", "adiciona", "quero incluir", "pode fazer"
+
+1. Verifique se já existe em \`.spec/requirements.md\`
+2. Se não existir: crie task com tag **[PENDING]** em \`.spec/tasks/backlog.md\`
+3. Descreva o impacto estimado (esforço, risco, dependências)
+4. **NUNCA implemente demanda nova sem aprovação explícita do dev**
+
+### Modo 4 — Dúvida de Escopo / Comportamento
+**Acionado por:** "como deve funcionar", "qual comportamento foi combinado", "o que faz isso"
+
+1. Consulte \`.spec/requirements.md\` — lá está o comportamento esperado
+2. Responda **com base no spec** — não invente comportamento
+3. Se spec estiver vago: peça ao dev para clarificar em requirements.md
+
+---
+
+## Context7 — Documentação Atualizada
+
+Quando for usar qualquer lib do projeto:
+1. Consulte **Context7** ANTES de implementar
+2. Nunca assuma que conhece a versão/API mais recente
+3. Libs deste projeto: ${libs}
+
+---
+
+## Stack Completo do Projeto
+
+### Frontend
+- Framework: ${stack.frontend}
+
+### Backend
+- Framework: ${stack.backend}
+
+### Banco de Dados
+- BD: ${stack.banco}
+- ORM: ${stack.orm}
+
+### Cache / Filas
+- ${stack.cache}
+
+### Autenticação
+- ${stack.auth}${tenant}
+
+### Infraestrutura
+- Hospedagem: ${infra.hospedagem}
+- Containerização: ${infra.containerizacao}
+- CI/CD: ${infra.cicd ? infra.cicdFerramenta : 'Não configurado'}
+
+---
+
+## MCPs Ativos Neste Projeto
+
+${mcps.map((m) => `- **${m}** — usar para tarefas relacionadas`).join('\n')}
+
+**Quando usar cada MCP:**
+- Antes de usar qualquer lib → **context7:** buscar docs atualizadas
+- Task concluída → **github:** criar PR referenciando a task
+- Bug identificado → **github:** abrir issue com contexto
+- Decisão de schema → **database:** validar antes de implementar
+- Feature implementada → **browser:** testar endpoint ou fluxo
+- Jornada de UI → **puppeteer:** validar fluxo completo
+
+---
+
+## Arquivos de Spec — Mapa Completo
+
+| Arquivo | Propósito | Quando Ler |
+|---------|-----------|-----------|
+| \`.spec/INDEX.md\` | Estado atual, tasks ativas mapeadas | SEMPRE no início de sessão |
+| \`.spec/requirements.md\` | Escopo completo, features MVP, Fase 2 | Antes de implementar feature |
+| \`.spec/architecture.md\` | Decisões técnicas, stack, MCPs | Antes de tomar decisão arquitetural |
+| \`.spec/users.md\` | Perfis de usuário, permissões, jornadas | Se task envolver acesso/permissões |
+| \`.spec/risks.md\` | Riscos técnicos, compliance, mitigações | Ao identificar risco novo |
+| \`.spec/tasks/active.md\` | Tasks em progresso, critérios de aceitação | Quando vai implementar |
+| \`.spec/tasks/backlog.md\` | Demandas futuras, [PENDING], ideias | Quando cliente pede feature nova |
+| \`.spec/tasks/done.md\` | Funcionalidades já entregues | Raramente — histórico |
+| \`.spec/changelog.md\` | Histórico de decisões e causa raiz de bugs | Ao investigar ou documentar decisão |
+| \`.spec/rules.md\` | Regras específicas DO PROJETO | Se task envolver lógica especial |
+| \`.spec/design.md\` | Design system, cores, fontes, componentes | SEMPRE antes de criar UI${designSection} |
+| \`.vireum/rules.md\` | Regras globais do Vireum Framework | Referência — aplicam-se a tudo |
+
+---
+
+## Planejamento Obrigatório (Resumo)
+
+Antes de QUALQUER implementação, você deve:
+
+1. **Escrever o plano:**
+   - O que será feito (resumo)
+   - Quais arquivos serão tocados
+   - Quais riscos foram identificados
+   - Dependências externas (bibliotecas, APIs, etc)
+
+2. **Validar com o desenvolvedor** (em tasks complexas)
+   - Mostrar plano antes de começar
+   - Aguardar feedback/aprovação
+
+3. **Implementar seguindo o plano**
+   - Não saia do escopo da task
+   - Registre decisões em architecture.md
+   - Use os tokens de design.md (se UI)
+
+4. **Validar antes de marcar como done**
+   - Todos os critérios de aceitação foram atendidos?
+   - Testes passam?
+   - Sem regressões em outras features?
+
+---
+
+## Regras Globais — Vireum Framework
+
+${regrasGlobaisEmbutidas}
+
+---
+
+## Resumo Rápido
+
+- **Pense antes de agir:** planejar é metade do trabalho
+- **Leia o spec:** sempre há resposta documentada antes de você perguntar
+- **Consulte Context7:** doc atualizada antes de assumir conhecimento
+- **Respeite design.md:** nunca hardcode cores ou componentes
+- **Registre decisões:** não é "óbvio" para o próximo — documenta
+- **Valide critérios:** task só é done quando TUDO foi testado
+- **Comunique com dev:** você não fala com cliente, dev fala
+
+---
+
+## Stack Resumido para Referência Rápida
+
+**Stack:** ${[stack.frontend, stack.backend, stack.banco, stack.orm, stack.auth].filter(s => s && s !== 'Nenhum').join(' + ')}
+
+**Design:** ${design.system}
+
+**MCPs:** ${mcps.slice(0, 3).join(', ')}${mcps.length > 3 ? ` (+ ${mcps.length - 3} mais)` : ''}
+
+---
+
+*Documento gerado por Vireum Spec. Última atualização: setup.*
+`;
+}