vireum-spec-cli 0.5.0 → 0.7.0

package/docs/DOCUMENTACAO_FRAMEWORK.md

@@ -0,0 +1,568 @@
+# Vireum Spec Framework — Documentação Completa
+
+> **Versão:** 0.7.0  
+> **Autor:** Vireum Desenvolvimento  
+> **Licença:** ISC
+
+---
+
+## 📌 O que é o Vireum Spec?
+
+**Vireum Spec** é um **framework de Spec Driven Development** — uma abordagem estruturada para documentar e estruturar projetos de software desde o planejamento até a implementação.
+
+### Problema que Resolve
+
+1. **Falta de clareza nos requisitos** — Briefings confusos, mal documentados
+2. **Desalinhamento com cliente** — Expectativas diferentes entre dev e cliente
+3. **Specs incompletos ou desatualizados** — Documentação que não reflete realidade
+4. **Difícil onboarding** — Novos devs entendem difícil a arquitetura
+5. **Falta de rastreabilidade** — Quem decidiu o quê? Por quê?
+6. **Retrofitting em projetos existentes** — Documentar o que já existe é árduo
+7. **IA sem direção** — Claude Code trabalha melhor com briefing estruturado
+
+---
+
+## 🎯 Filosofia
+
+O framework acredita que:
+- **Spec bem feito = dev mais rápida e com menos bugs**
+- **Spec é vivo** — muda conforme você aprende
+- **Spec é para humanos e máquinas** — IA entende melhor contexto estruturado
+- **Brevidade é força** — 80% do spec em 20% do esforço
+
+---
+
+## 🛠️ O que o Framework Gera
+
+### 1. **Briefing** (`.spec/briefing.md`)
+
+Documento estruturado com 6 seções que captura:
+- Informações gerais (projeto, cliente, responsável, data)
+- Problema e caso de uso
+- Fonte de conhecimento/dados
+- Interface e interação esperada
+- Modelo e infraestrutura
+- Qualidade e supervisão
+
+**Propósito:** Source of truth sobre o que foi discutido com o cliente.
+
+---
+
+### 2. **Requirements** (`.spec/requirements.md`)
+
+Especificação técnica e funcional gerada automaticamente a partir do briefing.
+
+**Contém:**
+- Objetivo do projeto
+- Features MVP (checklist)
+- Features Fase 2
+- Regras de negócio
+- Integrações planejadas
+- Modelo financeiro (se aplicável)
+- KPIs e métricas de sucesso
+
+**Exemplo:**
+```markdown
+## Funcionalidades — MVP
+- [ ] R-001 Autenticação com JWT
+- [ ] R-002 CRUD de usuários
+- [ ] R-003 Dashboard com gráficos
+```
+
+---
+
+### 3. **Architecture** (`.spec/architecture.md`)
+
+Diagrama técnico e explicação da solução.
+
+**Contém:**
+- Stack escolhida (frontend, backend, BD, cache, auth)
+- Fluxo de dados
+- Componentes principais
+- Estratégia de deployment
+- Escalabilidade
+- High-level design
+
+---
+
+### 4. **Users** (`.spec/users.md`)
+
+Personas e perfis de usuário do sistema.
+
+**Contém:**
+- Quem usa o sistema
+- Goals de cada persona
+- Pain points
+- Permissões e acessos
+- Jornada esperada
+
+**Exemplo:**
+```markdown
+## Admin
+- **Goal:** Gerenciar usuários e permissões
+- **Pain points:** Muita clicagem para tasks simples
+- **Permissões:** CRUD total
+```
+
+---
+
+### 5. **Risks** (`.spec/risks.md`)
+
+Identificação de riscos potenciais.
+
+**Contém:**
+- Riscos técnicos (performance, scaling, integração)
+- Riscos jurídicos/compliance (LGPD, PCI-DSS, saúde)
+- Riscos operacionais (suporte, manutenção)
+- Mitigação de cada risco
+
+---
+
+### 6. **Rules** (`.spec/rules.md`)
+
+Regras de negócio estruturadas.
+
+**Formato:**
+- Cada regra tem um ID único
+- Descreve comportamento esperado
+- Exceções e casos especiais
+- Impacto na implementação
+
+**Exemplo:**
+```
+RN-001: Usuários grátis só podem ter 10 projetos
+RN-002: Admin pode resestar senha de qualquer usuário
+RN-003: Dados devem ser deletados após 30 dias de inatividade
+```
+
+---
+
+### 7. **INDEX** (`.spec/INDEX.md`)
+
+Mapa completo do spec. Ponto de partida para entender tudo.
+
+**Contém:**
+- Resumo executivo
+- Links para todos os documentos
+- Estado atual do projeto
+- Próximos passos
+
+---
+
+### 8. **Changelog** (`.spec/changelog.md`)
+
+Histórico de mudanças no spec.
+
+**Rastreia:**
+- O que mudou
+- Quando mudou
+- Por quê
+- Quem decidiu
+
+---
+
+### 9. **Tasks** (`.spec/tasks/`)
+
+Backlog estruturado em 3 arquivos:
+
+#### **active.md**
+Tasks atualmente em desenvolvimento.
+```markdown
+## [ID] Titulo da Task
+- Status: In Progress / To Do
+- Assignee: Nome
+- Prioridade: Alta / Média / Baixa
+- Estimativa: X pontos
+```
+
+#### **backlog.md**
+Próximas tasks planejadas.
+
+#### **done.md**
+Tasks concluídas. Histórico de trabalho.
+
+---
+
+### 10. **Stack Configuration** (`.vireum/stack.json`)
+
+Configuração técnica escolhida no `setup`.
+
+**Exemplo:**
+```json
+{
+  "frontend": "Next.js",
+  "backend": "Node.js + Express",
+  "database": "PostgreSQL",
+  "orm": "Prisma",
+  "cache": "Redis + BullMQ",
+  "auth": "JWT + Refresh Token",
+  "multiTenant": true,
+  "tenantStrategy": "schema-isolation"
+}
+```
+
+---
+
+### 11. **AI Protocol** (`.vireum/protocol.md`)
+
+Instruções estruturadas para a IA trabalhar efetivamente no projeto.
+
+**Contém:**
+- Objetivo do projeto (para IA)
+- Padrões de código esperados
+- Como estruturar prompts
+- Guardrails (o que não fazer)
+- Tools disponíveis
+- Exemplos de work flow
+
+---
+
+### 12. **Cursor Rules** (`.cursor/rules/`)
+
+Regras específicas para Claude Code executar tarefas melhor.
+
+Arquivos gerados:
+- `project-overview.md` — Visão geral
+- `coding-standards.md` — Padrões de código
+- `architecture.md` — Arquitetura esperada
+- `testing.md` — Estratégia de testes
+- `security.md` — Segurança
+
+---
+
+## 🎨 Tipos de Projeto Suportados
+
+### 1. **System** (padrão)
+Sistema completo/multi-módulo.
+- Briefing genérico
+- Aplicável a qualquer tipo
+
+### 2. **Web**
+Landing pages, sites, plataformas web.
+- Perguntas específicas sobre UI/UX
+- SEO, analytics, conversão
+- Seções da página
+- Formulários
+
+### 3. **API**
+REST API, GraphQL, backend services.
+- Endpoints esperados
+- Autenticação/autorização
+- Rate limiting
+- Versionamento
+
+### 4. **Mobile**
+iOS, Android, ou ambos.
+- Plataforma (iOS, Android, ambas)
+- Tipo (nativa, cross-platform)
+- Offline-first?
+- Push notifications
+
+### 5. **Automation**
+RPA, workflows, automação de processos.
+- Qual processo automatizar?
+- Gatilhos
+- Integração com sistemas
+- Frequência
+
+### 6. **AI**
+Chatbots, agentes de IA, extração de dados.
+- Tarefa que IA resolve
+- Fonte de conhecimento
+- Provider de IA
+- Nível de autonomia
+- Dados sensíveis?
+
+---
+
+## 📊 Fluxo de Dados
+
+```
+Briefing Interativo (init)
+        ↓
+   Briefing.md
+        ↓
+   Distill (análise)
+        ↓
+ ┌──────────────────────────────┐
+ │ Requirements, Users, Risks    │
+ │ Rules, Architecture, Tasks    │
+ │ INDEX, Changelog              │
+ └──────────────────────────────┘
+        ↓
+     Setup (Tech Stack)
+        ↓
+ ┌──────────────────────────────┐
+ │ stack.json, protocol.md       │
+ │ .cursor/rules/*               │
+ └──────────────────────────────┘
+        ↓
+   Desenvolvimento com
+   Spec como Guia
+```
+
+---
+
+## 🔄 Operações Disponíveis
+
+### **init** — Criar Novo Spec
+```bash
+vireum-spec init --type <web|api|mobile|ai|automation|system>
+```
+- Briefing interativo
+- Salva em `.spec/briefing.md`
+
+### **distill** — Gerar Documentação
+```bash
+vireum-spec distill
+```
+- Lê briefing.md
+- Gera requirements.md, users.md, risks.md, etc.
+- Detecta tipo automaticamente
+
+### **setup** — Configurar Stack
+```bash
+vireum-spec setup
+```
+- Perguntas sobre tecnologias
+- Gera stack.json e protocol.md
+- Cria .cursor/rules/
+
+### **retrofit** — Documentar Projeto Existente
+```bash
+vireum-spec retrofit
+```
+- Analisa projeto automaticamente
+- Detecta stack, rotas, features
+- Pergunta sobre o não-detectado
+- Gera briefing e spec
+
+### **prioritize** — Classificar Features
+```bash
+vireum-spec prioritize
+```
+- MVP (deve ter)
+- Fase 2 (deveria ter)
+- Fora do escopo (pode deixar)
+
+### **health** — Verificar Consistências
+```bash
+vireum-spec health
+```
+- Verifica se briefing e spec batem
+- Alerta sobre gaps
+- Sugere atualizações
+
+### **brief** — Resumo Executivo
+```bash
+vireum-spec brief
+```
+- Gera resumo do projeto
+- Status atual
+- Próximos passos
+- Ideal para stakeholders
+
+### **verify-mcps** — Diagnóstico
+```bash
+vireum-spec verify-mcps
+```
+- Verifica MCPs/ferramentas instalados
+- Alerta sobre problemas
+
+### **skills** — Integração com IA
+```bash
+vireum-spec skills
+```
+- Instala skills no Claude Code
+- Skills facilitam trabalho com spec
+
+### **enrich** — Encontrar Gaps
+```bash
+vireum-spec enrich
+```
+- Gera prompt para IA analisar spec
+- Identifica inconsistências
+- Sugere melhorias
+
+---
+
+## 📝 Qual Documento para Quê?
+
+| Você quer... | Leia isto |
+|---|---|
+| Entender tudo rapidamente | `INDEX.md` |
+| Ver o que foi combinado com cliente | `briefing.md` |
+| Começar a codar | `requirements.md` + `architecture.md` |
+| Entender usuarios | `users.md` |
+| Dormir tranquilo (riscos) | `risks.md` |
+| Explicar regras | `rules.md` |
+| Saber quem faz o quê | `tasks/active.md` |
+| Reportar status | `brief` (comando) |
+| Debugar problema de spec | `health` (comando) |
+
+---
+
+## 🤖 Para IA (Claude Code)
+
+Quando você tem o spec completo:
+1. IA entende melhor o contexto
+2. Prompts mais específicos
+3. Menos erros
+4. Onboarding mais rápido
+5. Decisões mais alinhadas
+
+Rode `vireum-spec skills` para instalar skills que fazem IA usar melhor seu spec.
+
+---
+
+## 🔐 Segurança
+
+O framework ajuda a documentar:
+- Dados sensíveis (saúde, financeiro, pessoal)
+- Restrições de API/local
+- Autenticação e autorização
+- Compliance (LGPD, PCI-DSS)
+
+**Tudo em `risks.md`** com ações de mitigação.
+
+---
+
+## 📈 Escalabilidade
+
+Stack pode ser configurado para:
+- **Baixo volume:** SQLite, sem cache
+- **Médio volume:** PostgreSQL, Redis
+- **Alto volume:** Multi-DB, CDN, replicação
+- **Global:** Multi-region, multi-tenant
+
+Tudo documentado no `architecture.md`.
+
+---
+
+## 🚀 Deployment
+
+Setup pode gerar instruções para:
+- Docker / Docker Compose
+- Vercel, Netlify (frontend)
+- AWS, GCP, Azure (backend)
+- CI/CD pipelines
+
+---
+
+## 📚 Exemplo Prático: Startup de IA
+
+```bash
+# 1. Criar projeto de IA
+vireum-spec init --type ai
+
+# Responde:
+# - Projeto: "ChatBot de Atendimento"
+# - Problema: "Suporte responde 200 tickets/dia, 2-3h por ticket"
+# - Provider: "Anthropic (Claude)"
+# - Dados: "PDFs com base de conhecimento"
+# - Supervisão: "Human-in-the-loop"
+
+# 2. Gerar spec
+vireum-spec distill
+
+# 3. Configurar
+vireum-spec setup
+# - Frontend: Next.js
+# - Backend: Node.js + Express
+# - BD: PostgreSQL
+# - Auth: JWT
+# - IA Protocol: RAG com embeddings
+
+# 4. Priorizar
+vireum-spec prioritize
+
+# 5. Instalar skills
+vireum-spec skills
+
+# Agora você tem:
+# - .spec/ com tudo documentado
+# - Stack técnica definida
+# - Protocol de IA
+# - Tasks prontas para dev
+# - Claude Code com skills instaladas
+```
+
+---
+
+## 🎓 Melhores Práticas
+
+### ✅ Faça:
+- **Seja específico no briefing** — "Chat web com Claude Sonnet" > "chatbot"
+- **Documente decisões** — Por que PostgreSQL e não MongoDB?
+- **Mantenha risco atualizado** — Novos riscos aparecem durante dev
+- **Use status nas tasks** — Saiba quem faz o quê
+- **Roda health regularmente** — Catch gaps cedo
+
+### ❌ Evite:
+- **Deixar briefing vago** — Leva a retrabalho
+- **Não revisar spec gerado** — Pode ter interpretações erradas
+- **Esquecer de atualizar changelog** — Perde rastreabilidade
+- **Ignorar avisos de health** — Acumula débito técnico
+- **Spec preso em git sem usar** — Não é documentação, é decoração
+
+---
+
+## 🔗 Integração com Fluxo de Dev
+
+1. **Planning:** Rode `init` + `distill`
+2. **Refinement:** Use `prioritize` + `enrich`
+3. **Dev:** Consulte spec como single source of truth
+4. **PR:** Reference `rules.md` e `architecture.md`
+5. **Maintenance:** Rode `health` periodicamente
+6. **Retrospective:** Atualiza `changelog.md`
+
+---
+
+## 📦 Stack Técnica Mínima
+
+- Node.js 18+
+- TypeScript (recomendado)
+- Commander CLI
+- Chalk (colors)
+- Inquirer (prompts)
+- Ora (spinners)
+
+**Peso:** ~10MB instalado
+
+---
+
+## 🛣️ Roadmap
+
+**Planejado:**
+- UI web para gerenciar spec
+- Integração com Linear/Jira
+- Geração de código a partir de spec
+- Multi-language support
+- API pública para tooling
+
+---
+
+## 📞 Suporte
+
+- **Issues:** GitHub do projeto
+- **Comunidade:** Discord da Vireum
+- **Consultoria:** vireum@dev.com
+
+---
+
+## 📄 Licença
+
+ISC — Usável em projetos comerciais e pessoais.
+
+---
+
+## Conclusão
+
+**Vireum Spec** é a ponte entre:
+- **Ideias** (o que o cliente quer)
+- **Planejamento** (como vamos fazer)
+- **Execução** (código que funciona)
+- **Manutenção** (saber por que foi feito)
+
+Use bem e seu projeto será mais rápido, com melhor qualidade e muito menos dor de cabeça. 🚀
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vireum-spec-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Spec Driven Development framework by Vireum Desenvolvimento",
   "main": "dist/index.js",
   "bin": {
@@ -10,11 +10,15 @@
     "build": "tsc",
     "dev": "ts-node src/index.ts",
     "start": "node dist/index.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
     "prepublishOnly": "npm run build"
   },
   "files": [
     "dist/",
-    "src/skills/"
+    "src/skills/",
+    "README.md",
+    "docs/"
   ],
   "keywords": [
     "spec",
@@ -33,7 +37,9 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@vitest/ui": "^1.0.0",
     "ts-node": "^10.9.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
   }
 }