Vireum Spec — Spec Driven Development Framework

Versão: 0.7.0
Framework para documentação estruturada de projetos de software
By: Vireum Desenvolvimento

🎯 O que é?

Vireum Spec é um framework CLI que ajuda você a documentar projetos de software de forma estruturada, alinhando requisitos, arquitetura e desenvolvimento com o cliente.

Bridging the gap between:

• 💡 Ideias — O que o cliente quer
• 📋 Planejamento — Como você vai construir
• 💻 Execução — Código que funciona
• 📚 Manutenção — Por que foi feito

✨ Problemas que Resolve

✅ Falta de clareza — Requisitos confusos e mal documentados
✅ Desalinhamento — Cliente e dev querem coisas diferentes
✅ Specs desatualizadas — Documentação não reflete realidade
✅ Difícil onboarding — Novos devs entendem pouco
✅ Sem rastreabilidade — Quem decidiu o quê? Por quê?
✅ IA sem contexto — Claude Code funciona muito melhor com briefing estruturado

🚀 Quick Start

Instalação

npm install -g vireum-spec-cli

Novo Projeto

vireum-spec init --type <tipo>
vireum-spec distill
vireum-spec setup

Tipos: system, web, api, mobile, automation, ai

Projeto Existente

vireum-spec retrofit
vireum-spec distill
vireum-spec setup

📚 Documentação Completa

• Guia de Uso — Step-by-step para novos e existentes
• Documentação Técnica — Deep dive no framework

🎨 O que Gera

3 Principais Artefatos

1. .spec/ — Documentação estruturada

   • briefing.md — Suas respostas originais
   • requirements.md — Funcionalidades
   • users.md — Personas
   • architecture.md — Design técnico
   • risks.md — Riscos identificados
   • rules.md — Regras de negócio
   • E mais...

2. .vireum/ — Configuração técnica

   • stack.json — Stack escolhida
   • protocol.md — Protocolo da IA

3. .cursor/rules/ — Integração Claude Code

   • Regras estruturadas para IA trabalhar melhor

🛠️ 10 Comandos Principais

| Comando | Purpose | |---------|---------| | init | Briefing interativo | | distill | Gera spec do briefing | | setup | Configura stack & IA | | retrofit | Auto-analisa projeto | | prioritize | MVP / Fase 2 / Fora scope | | health | Verifica consistências | | brief | Resumo executivo | | verify-mcps | Diagnóstico | | skills | Instala no Claude Code | | enrich | Encontra gaps |

🎓 Exemplo: Projeto de IA

# 1. Iniciar
vireum-spec init --type ai

# Responde perguntas (6 seções):
# - Projeto: "Chatbot de Suporte"
# - Problema: "Suporte responde 200 tickets/dia, 2-3h cada"
# - Provider: "Anthropic Claude"
# - Fonte: "PDFs internos"
# - Supervisão: "Human-in-the-loop"

# 2. Gerar spec
vireum-spec distill

# 3. Configurar
vireum-spec setup
# → Next.js, Node.js + Express, PostgreSQL, Prisma, JWT, RAG

# 4. Instalar skills
vireum-spec skills

# Resultado:
# ✓ Spec completo em .spec/
# ✓ Stack definido
# ✓ Protocol de IA pronto
# ✓ Tasks para dev
# ✓ Claude Code otimizado

🎯 Tipos de Projeto Suportados

| Tipo | Para | |------|------| | system | Sistemas completos/multi-módulo (padrão) | | web | Landing pages, sites, plataformas web | | api | REST APIs, GraphQL, backends | | mobile | Apps iOS/Android | | automation | RPA, workflows, automação | | ai | Chatbots, agentes, extração de dados |

💡 Melhores Práticas

✅ Faça:

• Responda o briefing com detalhe
• Revise spec gerado manualmente
• Use .spec/INDEX.md como ponto de partida
• Mantenha atualizado conforme aprende
• Rode health regularmente

❌ Evite:

• Deixar campos em branco
• Não revisar spec auto-gerado
• Esquecer de rodar setup
• Ignorar avisos do health
• Spec preso em git sem usar

🤖 Para Claude Code

Rode vireum-spec skills para instalar skills que fazem Claude Code:

• Entender melhor seu projeto
• Seguir padrões específicos
• Usar suas regras de negócio
• Tomar decisões alinhadas
• Ser mais eficiente

📊 Workflow Recomendado

Plan     → vireum-spec init + distill
Design   → vireum-spec setup + health
Dev      → Tasks em spec como guia
Review   → Use spec como checklist
Retro    → Update changelog
Maintain → Regular health checks

🛠️ Stack Técnico

Dependências:

• Node.js 18+
• Commander (CLI)
• Chalk (colors)
• Inquirer (prompts)
• Ora (spinners)

Peso: ~10MB instalado

📦 Para Publicar no NPM

O pacote está configurado para publicar com:

{
  "files": ["dist/", "src/skills/", "README.md", "docs/"]
}

Incluindo:

• ✓ CLI compilado (dist/)
• ✓ Skills (src/skills/)
• ✓ README.md (esse)
• ✓ Documentação completa (docs/)

🗺️ Roadmap

Planejado:

• UI web para gerenciar spec
• Integração Linear/Jira
• Geração de código a partir de spec
• Multi-language support (EN, ES, FR)
• API pública para tooling

📝 Licença

ISC — Use em projetos comerciais e pessoais

🤝 Suporte

• Issues: GitHub do projeto
• Comunidade: Discord Vireum
• Consulting: [email protected]

📖 Comece Agora

1. Instale: npm install -g vireum-spec-cli
2. Leia: Guia de Uso
3. Inicie: vireum-spec init --type <tipo>
4. Gere: vireum-spec distill
5. Configure: vireum-spec setup

Made with ❤️ by Vireum Desenvolvimento