create-genia-os 2.0.0 → 2.1.1

package/template/.genia/development/tasks/qa-review.md

@@ -0,0 +1,224 @@
+# Task: QA Review
+
+> Tarefa executada por @qa. Verifica qualidade e conformidade do código com os ACs.
+> Pré-requisito: @dev declarou implementação concluída (story em InQA).
+
+---
+
+## Objetivo
+
+Verificar sistematicamente que o código implementado por @dev satisfaz todos os Acceptance Criteria da story, atende aos padrões de qualidade técnica e não introduz regressões. Emitir veredicto formal: APROVADO ou REPROVADO com bugs documentados.
+
+---
+
+## Pré-requisitos
+
+Antes de iniciar, confirme:
+
+- [ ] Story tem status `InQA`
+- [ ] @dev comunicou que a implementação está pronta
+- [ ] Arquivo da story está em `docs/stories/STORY-XXX.md`
+- [ ] Branch do @dev está disponível para checkout
+
+---
+
+## Passos de Execução
+
+### Passo 1 — Preparação
+1. Leia a story completa: User Story, todos os ACs, não-escopo
+2. Faça checkout do branch:
+   ```bash
+   git checkout feat/STORY-XXX-descricao
+   ```
+3. Instale dependências se necessário:
+   ```bash
+   npm install
+   ```
+4. Configure variáveis de ambiente para testes
+
+### Passo 2 — Execução de Verificações Automáticas
+
+```bash
+# 1. Lint — deve estar limpo
+npm run lint
+
+# 2. TypeScript — zero erros
+npm run typecheck
+
+# 3. Testes unitários — todos devem passar
+npm run test
+
+# 4. Cobertura — deve ser >= 80%
+npm run coverage
+```
+
+Documente os resultados de cada comando.
+
+### Passo 3 — Verificação dos Acceptance Criteria
+
+Para CADA AC da story:
+
+1. Leia o AC
+2. Execute o cenário descrito
+3. Verifique se o resultado corresponde ao esperado
+4. Documente o resultado: ✅ VERIFICADO ou ❌ FALHOU
+
+**Para cada AC, Quinn verifica também:**
+- Happy path funciona como descrito?
+- Edge cases tratados corretamente?
+- Mensagens de erro claras e úteis para o usuário?
+- Estados de loading/empty/error presentes (se aplicável)?
+
+### Passo 4 — Verificação de Qualidade Adicional
+
+Além dos ACs, @qa verifica:
+
+**Interface (se aplicável):**
+- [ ] Responsividade em diferentes tamanhos de tela
+- [ ] Acessibilidade básica (contraste, labels, keyboard navigation)
+- [ ] Sem quebras visuais óbvias
+- [ ] Textos sem erros de ortografia
+
+**Performance básica:**
+- [ ] Requests desnecessariamente lentos identificados?
+- [ ] Sem re-renders infinitos (React)
+- [ ] Sem memory leaks óbvios
+
+**Segurança básica:**
+- [ ] Inputs validados e sanitizados
+- [ ] Dados sensíveis não expostos em logs
+- [ ] Autenticação verificada nos endpoints protegidos
+
+### Passo 5 — Documentação de Bugs
+
+Para cada problema encontrado, use o template:
+
+```markdown
+### BUG-QA-[STORY-XXX]-[número]
+
+**Iteração:** X/5
+**Severidade:** CRÍTICO | ALTO | MÉDIO | BAIXO
+**AC relacionado:** AC-XX | Qualidade Geral | Regressão
+**Tipo:** Funcional | Visual | Performance | Segurança | Acessibilidade
+
+#### Comportamento Esperado
+[Descrição clara do que deveria acontecer]
+
+#### Comportamento Atual
+[Descrição clara do que está acontecendo]
+
+#### Passos para Reproduzir
+1. [Passo 1]
+2. [Passo 2]
+3. [Resultado obtido]
+
+#### Evidência
+```
+[Log de erro, mensagem de falha, ou descrição detalhada]
+```
+
+#### Critério de Resolução
+[Como @qa saberá que o bug foi corrigido]
+```
+
+### Passo 6 — Emissão do Veredicto
+
+**APROVADO** se:
+- Zero bugs CRÍTICOS
+- Máximo 2 bugs ALTOS (documentados para backlog futuro)
+- Todos os ACs verificados e passando
+- Testes unitários passando com coverage >= 80%
+- Lint e typecheck limpos
+
+**REPROVADO** se:
+- Qualquer bug CRÍTICO presente
+- Mais de 2 bugs ALTOS
+- Qualquer AC não-atendido
+- Testes falhando
+- Lint com erros
+
+### Passo 7 — Comunicação do Resultado
+
+**Se APROVADO:**
+1. Atualize status da story para `InReview`
+2. Notifique @reviewer com:
+   - Branch name
+   - Story ID
+   - Relatório de QA resumido
+   - "Pronto para code review"
+
+**Se REPROVADO:**
+1. Mantenha status como `InQA`
+2. Notifique @dev com:
+   - Lista de bugs ordenados por severidade
+   - Orientações claras sobre o que corrigir
+   - Pedido de re-notificação após correções
+3. Registre a iteração (1ª, 2ª, 3ª...)
+4. Se 5ª iteração e ainda reprovado: escalar para @architect + @pm
+
+---
+
+## Relatório Final de QA
+
+Ao aprovar, gerar relatório:
+
+```markdown
+# Relatório QA — STORY-XXX
+Data: YYYY-MM-DD | QA: Quinn (@qa)
+Iterações utilizadas: X/5
+
+## Veredicto: ✅ APROVADO
+
+## Resultados de Testes Automáticos
+- Lint: ✅ Limpo
+- TypeScript: ✅ Zero erros
+- Testes unitários: ✅ XX/XX passando
+- Cobertura: ✅ XX%
+
+## Acceptance Criteria
+| AC | Descrição resumida | Resultado |
+|----|-------------------|---------|
+| AC-01 | ... | ✅ VERIFICADO |
+| AC-02 | ... | ✅ VERIFICADO |
+| AC-03 | ... | ✅ VERIFICADO |
+
+## Bugs Encontrados
+| ID | Título | Severidade | Disposição |
+|----|--------|-----------|-----------|
+| BUG-001 | ... | MÉDIO | Documentado para backlog |
+
+## Observações
+[Pontos de atenção ou sugestões não-bloqueantes]
+
+Aprovado por Quinn (@qa) em YYYY-MM-DD.
+Próximo passo: code review por @reviewer.
+```
+
+---
+
+## Classificação de Bugs (Referência)
+
+| Severidade | Definição | Exemplos |
+|-----------|----------|---------|
+| CRÍTICO | Sistema quebra, perda de dados, falha de segurança | Crash, SQL injection, dados corrompidos |
+| ALTO | Funcionalidade principal comprometida | AC não-atendido, workflow quebrado |
+| MÉDIO | Funcionalidade parcialmente afetada | Mensagem de erro incorreta, visual quebrado em caso específico |
+| BAIXO | Cosmético, menor, alternativa disponível | Texto levemente diferente, UI pixel imperfect |
+
+---
+
+## Critérios de Saída
+
+A task QA Review está concluída quando:
+
+- [ ] Todos os ACs verificados e documentados
+- [ ] Testes automáticos executados e resultados documentados
+- [ ] Bugs (se houver) documentados com severidade e passos de reprodução
+- [ ] Veredicto formal emitido (APROVADO ou REPROVADO)
+- [ ] Status da story atualizado (InReview ou InQA)
+- [ ] Agente correto notificado (@reviewer ou @dev)
+- [ ] Relatório QA salvo em `docs/qa/RELATORIO-QA-STORY-XXX.md`
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

package/template/.genia/development/workflows/brownfield.md

@@ -0,0 +1,178 @@
+# Workflow: Brownfield
+
+> Para evoluir sistemas já em produção. Primeiro entender, depois mudar.
+> Ordem: @architect → @qa → @architect + @dev → @pm → @sm → SDC
+
+---
+
+## Visão Geral
+
+O workflow Brownfield é usado quando o projeto já tem código em produção, usuários ativos e histórico de decisões técnicas. Diferente do Greenfield, qualquer mudança pode ter impacto direto em funcionalidades existentes. A palavra de ordem é cautela e investigação antes de ação.
+
+**Quando usar:** Sistema existente em produção, adição de features a produto ativo, migração tecnológica gradual
+**Duração da fase de discovery:** 3-7 dias (dependendo da complexidade do sistema)
+**Pré-requisito:** Acesso ao repositório existente e documentação disponível
+
+---
+
+## Fase 1 — Discovery (@architect)
+
+**Responsável:** Arqui (@architect)
+**Output:** Mapa arquitetural do sistema atual (`docs/discovery/ARQUITETURA-ATUAL.md`)
+
+### O que acontece:
+1. @architect mergulha no código existente:
+   - Lê os principais arquivos de configuração
+   - Mapeia a estrutura de pastas e módulos
+   - Identifica padrões (ou ausência deles) no código
+2. Documenta a arquitetura atual:
+   - Linguagens e frameworks em uso
+   - Banco de dados e estratégia de dados
+   - Integrações externas ativas
+   - Sistemas de autenticação/autorização
+   - Pipelines CI/CD existentes (se houver)
+3. Identifica decisões arquiteturais implícitas (sem ADR documentado)
+4. Mapeia pontos de acoplamento alto e riscos de mudança
+5. Avalia a saúde geral do codebase
+
+### Entregáveis:
+- `docs/discovery/ARQUITETURA-ATUAL.md`
+- Diagrama de componentes e fluxos principais
+- Lista de tecnologias e versões em uso
+- Pontos críticos de risco documentados
+
+---
+
+## Fase 2 — Auditoria de Qualidade (@qa)
+
+**Responsável:** Quinn (@qa)
+**Output:** `docs/discovery/AUDITORIA-QA.md`
+
+### O que acontece:
+1. @qa analisa a cobertura de testes existente (ou ausência)
+2. Executa ferramentas de análise estática se disponíveis
+3. Identifica:
+   - Áreas sem cobertura de teste (risk zones)
+   - Padrões de código inconsistentes
+   - Dívida técnica acumulada
+   - Bugs conhecidos não resolvidos
+4. Cria mapa de risco: quais áreas têm mais chance de quebrar com mudanças?
+5. Define estratégia de testes para o projeto de evolução
+
+### Entregáveis:
+- `docs/discovery/AUDITORIA-QA.md`
+- Mapa de risco de mudanças por módulo
+- Estratégia de testes proposta
+- Lista de dívida técnica priorizada
+
+---
+
+## Fase 3 — Análise de Impacto (@architect + @dev)
+
+**Responsáveis:** Arqui (@architect) + Dev (@dev)
+**Input:** ARQUITETURA-ATUAL.md + AUDITORIA-QA.md + requisitos das mudanças desejadas
+**Output:** `docs/discovery/ANALISE-IMPACTO.md`
+
+### O que acontece:
+1. @architect e @dev mapeiam juntos o impacto de cada mudança proposta:
+   - Quais módulos serão afetados?
+   - Há risco de breaking changes?
+   - Quais integrações podem ser impactadas?
+2. Definem estratégia de migração (big bang vs. gradual vs. strangler fig)
+3. Identificam testes de regressão necessários
+4. Estimam esforço de cada mudança considerando o estado atual do código
+5. @architect documenta ADRs para decisões de evolução
+
+### Entregáveis:
+- `docs/discovery/ANALISE-IMPACTO.md`
+- ADRs de evolução arquitetural
+- Estratégia de migração definida
+- Estimativas de esforço ajustadas para o contexto brownfield
+
+---
+
+## Fase 4 — Épico de Evolução (@pm)
+
+**Responsável:** Marina (@pm)
+**Input:** ANALISE-IMPACTO.md + requisitos do cliente
+**Output:** PRD atualizado com épico de evolução + `docs/[projeto]/PRD-EVOLUCAO.md`
+
+### O que acontece:
+1. @pm revisa os impactos e ajusta escopo se necessário
+2. Cria épico de evolução no backlog com base real nas estimativas
+3. Define o que é refatoração necessária vs. nova funcionalidade
+4. Alinha expectativas com stakeholders sobre complexidade adicional do brownfield
+5. Define critérios de sucesso para a evolução
+
+### Importante:
+Em brownfield, @pm frequentemente precisa negociar prazo adicional para lidar com:
+- Testes de regressão
+- Compatibilidade retroativa
+- Migração gradual de dados
+- Rollback planejado
+
+---
+
+## Fase 5 — Stories com Consciência Brownfield (@sm)
+
+**Responsável:** Sami (@sm) em colaboração com @architect
+**Output:** Stories com notas técnicas específicas de compatibilidade
+
+### O que acontece:
+1. @sm cria stories considerando o contexto brownfield
+2. Cada story inclui:
+   - **Notas de compatibilidade:** o que não pode quebrar
+   - **Testes de regressão:** cenários existentes que devem ser mantidos
+   - **Plano de rollback:** como desfazer se necessário
+3. Stories de brownfield tendem a ser menores que greenfield para reduzir risco
+
+### Adições ao template padrão de story:
+```markdown
+## Compatibilidade Brownfield
+- Funcionalidades existentes NÃO devem ser afetadas: [lista]
+- Testes de regressão obrigatórios: [lista de cenários]
+- Plano de rollback: [como desfazer esta mudança]
+- Áreas de risco identificadas por @architect: [referência à ANALISE-IMPACTO]
+```
+
+---
+
+## Fase 6 — Desenvolvimento com Cautela (SDC adaptado)
+
+**Workflow:** [Story Development Cycle](./story-development-cycle.md) com adições brownfield
+
+O SDC é executado normalmente com estas adições:
+
+- **@dev:** sempre roda testes de regressão completos antes de declarar pronto
+- **@qa:** verifica explicitamente que funcionalidades existentes não foram quebradas
+- **@qa:** executa cenários de regressão além dos ACs da nova story
+- **@devops:** valida staging completamente antes de qualquer deploy em produção
+- **@devops:** mantém plano de rollback ativo
+
+---
+
+## Estratégias de Migração Disponíveis
+
+| Estratégia | Quando usar | Risco |
+|-----------|-------------|-------|
+| Big Bang | Sistema pequeno, pode ter downtime | Alto |
+| Gradual | Sistemas grandes, sem downtime | Médio |
+| Strangler Fig | Substituição incremental de módulos | Baixo |
+| Blue/Green | Alta disponibilidade necessária | Baixo (custo maior) |
+| Feature Flags | Lançamento controlado | Baixíssimo |
+
+@architect define a estratégia na Fase 3.
+
+---
+
+## Regras Específicas do Brownfield
+
+1. **Nunca refatorar e adicionar feature no mesmo commit** — separar em stories distintas
+2. **Testes de regressão são obrigatórios** — sem exceção, mesmo que não existissem antes
+3. **Staging é espelho de produção** — qualquer divergência de ambiente deve ser resolvida antes do deploy
+4. **Rollback planejado** — @devops tem plano de rollback para cada deploy significativo
+5. **Comunicação com usuários** — mudanças que afetam UX devem ser comunicadas antecipadamente
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

package/template/.genia/development/workflows/delivery.md

@@ -0,0 +1,208 @@
+# Workflow: Delivery
+
+> Fase de entrega. Transforma código aprovado em produto em produção.
+> Ordem: @pm → @devops → @qa (validação) → @pm (comunicação)
+
+---
+
+## Visão Geral
+
+O workflow Delivery é a fase final do ciclo de desenvolvimento. Ele abrange todo o processo desde a decisão de fazer uma release até o produto estar em produção, monitorado e com os stakeholders informados. Delivery não é apenas `git push` — é um processo gerenciado de entrega de valor.
+
+**Quando usar:** Ao final de um sprint ou conjunto de sprints com stories Done suficientes para uma release
+**Pré-requisito:** Stories aprovadas por @po, código mergeado em main por @devops, staging validado
+
+---
+
+## Fase 1 — Decisão de Release (@pm)
+
+**Responsável:** Marina (@pm)
+**Output:** Decisão formal de release com escopo definido
+
+### O que acontece:
+1. @pm avalia o conjunto de stories prontas e decide se há valor suficiente para uma release
+2. Define o escopo da release:
+   - O que está incluído (features prontas)
+   - O que NÃO está incluído (features parciais ou não concluídas)
+3. Define a versão semântica (Major.Minor.Patch):
+   - **Major:** mudanças breaking, redesign significativo
+   - **Minor:** novas funcionalidades, expansões
+   - **Patch:** bug fixes, melhorias menores
+4. Alinha expectativas com stakeholders sobre o que será entregue
+5. Define data e hora de release (evitar deploy em sexta-feira à tarde)
+6. Aprova formalmente a release
+
+### Critérios para autorizar release:
+- [ ] Mínimo de stories Done que justifiquem o deploy
+- [ ] Nenhum bug crítico pendente
+- [ ] Staging estável há pelo menos 48h
+- [ ] Plano de rollback documentado
+- [ ] Stakeholders informados
+
+---
+
+## Fase 2 — Preparação de Release (@devops)
+
+**Responsável:** Gate (@devops)
+**Output:** Ambiente de produção pronto, release notes preparadas
+
+### O que acontece:
+1. @devops confirma que o pipeline CI/CD está verde em staging
+2. Gera as release notes a partir dos commits e stories:
+   ```markdown
+   # Release v1.2.0 — YYYY-MM-DD
+
+   ## Novidades
+   - [STORY-001] Funcionalidade X implementada
+   - [STORY-003] Melhoria Y aplicada
+
+   ## Correções
+   - [STORY-005] Bug Z corrigido
+
+   ## Notas Técnicas
+   - Migração de banco de dados necessária: [sim/não]
+   - Configurações de ambiente alteradas: [lista]
+   - Breaking changes: [sim/não]
+   ```
+3. Executa checklist completo de pré-deploy
+4. Prepara o plano de rollback documentado
+5. Cria a tag de release: `git tag -a v1.2.0 -m "Release v1.2.0"`
+6. Comunica janela de deploy para o time
+
+### Checklist pré-produção de @devops:
+- [ ] Pipeline CI em staging: verde
+- [ ] Testes de integração em staging: passando
+- [ ] Security scan: sem vulnerabilidades críticas
+- [ ] Performance check: dentro dos SLAs
+- [ ] Variáveis de ambiente de produção: configuradas
+- [ ] Backup de banco de dados: realizado
+- [ ] Plano de rollback: documentado e testado
+- [ ] Time avisado sobre a janela de deploy
+- [ ] Escalação de suporte configurada (se necessário)
+
+---
+
+## Fase 3 — Deploy em Produção (@devops)
+
+**Responsável:** Gate (@devops)
+**Output:** Sistema em produção com nova versão
+
+### O que acontece:
+1. @devops executa o pipeline de produção
+2. Monitora cada etapa do deploy:
+   - Build de produção
+   - Testes pré-deploy (smoke tests)
+   - Deploy incremental (canary ou blue/green se configurado)
+   - Verificações pós-deploy
+3. Confirma que a aplicação está saudável em produção:
+   - Health checks respondem
+   - Logs sem erros críticos
+   - Métricas de performance normais
+4. Publica a release no GitHub: `gh release create v1.2.0`
+
+### Se algo der errado durante o deploy:
+```
+1. @devops para o deploy imediatamente
+2. Avalia a severidade do problema
+3. Se crítico: executa rollback imediatamente
+4. Documenta o incidente
+5. Notifica @pm e @architect
+6. Abre post-mortem se necessário
+```
+
+---
+
+## Fase 4 — Validação Pós-Deploy (@qa)
+
+**Responsável:** Quinn (@qa)
+**Output:** Validação formal em produção
+
+### O que acontece:
+1. @qa executa smoke tests em produção (não os unitários — testes de comportamento)
+2. Verifica os principais fluxos de usuário afetados pela release
+3. Confirma que funcionalidades existentes não foram impactadas
+4. Monitora métricas por 30-60 minutos após o deploy
+5. Emite veredicto de saúde da release:
+   - **SAUDÁVEL:** release aprovada, ambiente estável
+   - **ALERTA:** problemas não-críticos identificados, monitorar
+   - **CRÍTICO:** problema grave detectado → @devops executa rollback imediatamente
+
+### Smoke tests típicos:
+- Login/autenticação funcionando
+- Principais fluxos de negócio acessíveis
+- APIs respondendo com status corretos
+- Integrações externas ativas
+- Performance aceitável (sem degradação significativa)
+
+---
+
+## Fase 5 — Comunicação e Documentação (@pm)
+
+**Responsável:** Marina (@pm)
+**Output:** Stakeholders informados, documentação atualizada
+
+### O que acontece:
+1. @pm redige e envia comunicado de release para stakeholders:
+   ```
+   Assunto: GEN.IA OS v1.2.0 — Nova versão disponível
+
+   Olá,
+
+   Acabamos de disponibilizar a versão 1.2.0 do [produto] em produção.
+
+   O que há de novo:
+   - [Feature X]: [descrição em linguagem de negócio]
+   - [Correção Y]: [impacto positivo para o usuário]
+
+   Próximos passos:
+   - [O que vem a seguir]
+   ```
+2. Atualiza o CHANGELOG.md do projeto
+3. Arquiva o sprint no histórico
+4. Agenda retrospectiva com @sm
+5. Inicia planejamento do próximo ciclo
+
+---
+
+## Processo de Rollback
+
+Se a release precisar ser revertida:
+
+1. **@devops decide ou é acionado** por @qa (veredicto CRÍTICO)
+2. **@devops executa rollback:**
+   - Deploy da versão anterior (blue/green switch ou redeploy)
+   - Ou reverte migrações de banco se necessário
+3. **@devops confirma** que versão anterior está estável
+4. **@pm comunica** stakeholders sobre o rollback com transparência
+5. **@architect investiga** a causa raiz
+6. **Post-mortem** documentado e ações de prevenção definidas
+
+---
+
+## Critérios de Conclusão do Delivery
+
+A release está concluída quando:
+
+- [ ] Nova versão em produção e estável
+- [ ] @qa validou em produção (veredicto SAUDÁVEL ou ALERTA monitorado)
+- [ ] Release notes publicadas no GitHub
+- [ ] Stakeholders comunicados por @pm
+- [ ] CHANGELOG.md atualizado
+- [ ] Tag de release criada e publicada
+- [ ] Nenhum incidente crítico ativo
+
+---
+
+## Governança de Deploy
+
+| Ambiente | Autoridade | Requer aprovação de |
+|---------|-----------|-------------------|
+| Development | @dev (local) | Ninguém |
+| Staging | @devops | @qa (implícita — pipeline) |
+| Production | @devops | @pm (formal) + @qa (pós-deploy) |
+
+**Regra de ouro:** Production nunca recebe código que não passou por staging. Sem exceção.
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*