npm - create-genia-os - Versions diffs - 2.4.0 → 3.0.0 - Mend

create-genia-os 2.4.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (724) hide show

package/template/.genia/development/tasks/debug-sistematico.md DELETED Viewed

@@ -1,230 +0,0 @@
-# Task: Debug Sistemático
-> Processo estruturado para investigar e resolver bugs complexos.
-> Aplicável por @dev (com suporte de @architect quando necessário).
----
-## Objetivo
-Resolver bugs de forma sistemática e documentada, evitando soluções por tentativa e erro que geram mais problemas do que resolvem. Um bug resolvido sem ser compreendido é um bug que vai voltar.
----
-## Quando Usar Esta Task
-- Bug reportado por @qa com severidade CRÍTICO ou ALTO
-- Bug intermitente que não reproduz de forma consistente
-- Bug de performance ou memory leak
-- Erro em produção que precisa de investigação rápida
-- Bug cuja causa raiz não é óbvia na primeira análise
----
-## Passos de Execução
-### Passo 1 — Leitura do Bug Report
-Antes de tocar no código:
-1. Leia o bug report completo de @qa
-2. Confirme que você consegue reproduzir o bug com os passos fornecidos
-3. Se não conseguir reproduzir: notifique @qa imediatamente com evidência (screenshot, log)
-4. **Reprodução é obrigatória antes de começar a debugar**
-### Passo 2 — Hipótese Antes de Código
-Antes de abrir qualquer arquivo:
-1. Baseado na descrição do bug, qual é a sua hipótese inicial sobre a causa?
-2. Anote a hipótese (não pule este passo — ajuda a manter o foco)
-3. Liste os locais do código mais prováveis onde o problema pode estar
-4. Estime: este bug é de lógica, de dados, de timing, de estado, de integração?
-**Tipos comuns de bug:**
-- **Lógica:** condição incorreta, comparação errada, operação matemática errada
-- **Estado:** estado React não atualizado, variável mutada incorretamente
-- **Assincronismo:** race condition, Promise não awaited, callback timing
-- **Integração:** API retornando formato inesperado, erro de rede não tratado
-- **Dados:** null/undefined não tratado, tipo de dado incorreto
-- **Ambiente:** variável de ambiente não configurada, versão de dependência diferente
-### Passo 3 — Isolamento
-1. **Reduza o problema ao mínimo reproduzível:**
-   - Existe um teste unitário que reproduz o bug? (crie um se não houver)
-   - Você consegue remover partes do código e ainda reproduzir?
-   - O bug ocorre com dados específicos? Quais?
-2. **Delimite a área suspeita:**
-   - Adicione logs estratégicos para entender o fluxo de execução
-   - Verifique os valores das variáveis no momento do bug
-   - Use o debugger (breakpoints) se disponível
-```bash
-# Exemplo de log estratégico (temporário, remover após debug)
-console.log('[DEBUG STORY-XXX]', { variavel, estado, resultado })
-```
-### Passo 4 — Investigação com Ferramentas
-**Para bugs de runtime:**
-```bash
-# Execute com mais verbosidade
-NODE_DEBUG=http npm run dev
-# Verifique os logs do servidor
-npm run dev 2>&1 | grep ERROR
-# Execute testes específicos em modo verbose
-npm run test -- --verbose NomeDoTeste
-```
-**Para bugs de TypeScript:**
-```bash
-npm run typecheck -- --listFiles
-npm run typecheck 2>&1 | grep -A5 "error TS"
-```
-**Para bugs de performance:**
-- React DevTools Profiler para re-renders desnecessários
-- Network tab para requests lentos
-- Memory tab para memory leaks
-**Para bugs de integração:**
-- Verifique o contrato da API com a documentação
-- Log do request e response completos (sem dados sensíveis nos logs de prod)
-- Verifique se o ambiente correto está sendo usado
-### Passo 5 — Causa Raiz
-Após a investigação:
-1. Documente a causa raiz identificada:
-   ```
-   Causa raiz: [descrição técnica precisa]
-   Arquivo: src/[caminho]/arquivo.ts linha XX
-   Por que ocorre: [explicação do mecanismo do bug]
-   ```
-2. Valide a causa raiz:
-   - Se você corrigir isso, o bug vai sumir?
-   - Há outros lugares no código com o mesmo problema?
-   - Esta causa raiz explica todos os sintomas relatados?
-### Passo 6 — Solução Planejada
-Antes de escrever qualquer código de correção:
-1. Defina a solução:
-   - O que exatamente vai ser mudado?
-   - A mudança tem efeitos colaterais em outros lugares?
-   - Há uma solução mais simples que resolve o problema?
-2. Verifique se a solução está dentro do escopo:
-   - Esta correção está dentro do que foi especificado no SPEC-TECNICO?
-   - Se for uma solução arquitetural maior: consultar @architect ANTES
-   - Se mudança de comportamento esperado: consultar @po ANTES
-### Passo 7 — Implementação da Correção
-1. Crie ou use o branch da story associada
-2. Implemente a correção mínima necessária (não aproveite para "melhorar outras coisas")
-3. Remova todos os logs de debug temporários
-4. Escreva ou atualize o teste que reproduzia o bug (agora deve passar)
-5. Execute a suite completa de testes:
-   ```bash
-   npm run lint && npm run typecheck && npm run test
-   ```
-6. Verifique que o bug original não reproduz mais
-### Passo 8 — Commit da Correção
-```bash
-git add [arquivos modificados]
-git commit -m "fix(escopo): corrigir [descrição do bug]
-Causa raiz: [breve descrição]
-Solução: [breve descrição da correção]
-Bug: BUG-QA-XXX
-Story: STORY-XXX
-Co-Authored-By: GEN.IA OS <genia@bedata.com.br>"
-```
-### Passo 9 — Documentação e Comunicação
-1. Atualize o bug report com:
-   - Causa raiz identificada
-   - Solução implementada
-   - Arquivos modificados
-   - Status: Resolvido
-2. Notifique @qa para re-verificar:
-   - Bug resolvido
-   - Como verificar que a correção funciona
-   - Se há outros cenários relacionados para testar
----
-## Quando Escalar para @architect
-Escale imediatamente se:
-- A causa raiz é um problema de arquitetura (não pode ser corrigido localmente)
-- A correção requer mudança significativa na estrutura do sistema
-- O bug está relacionado a segurança ou corrupção de dados
-- Não há clareza sobre qual é a solução correta após 1h de investigação
-- O bug afeta múltiplos módulos e a correção impacta contratos de API
-**Ao escalar:**
-```
-@architect — encontrei bug complexo em STORY-XXX
-Descrição do bug: [...]
-Causa raiz suspeita: [...]
-O que já investiguei: [...]
-Por que estou escalando: [...]
-Qual decisão preciso de você: [...]
-```
----
-## Registro de Bug Para Aprendizado
-Bugs complexos devem ser documentados para o time:
-```markdown
-## Post-Mortem — BUG-XXX — [Título]
-Data: YYYY-MM-DD | Investigado por: @dev
-### Sintoma
-[Como o bug se manifestava]
-### Causa Raiz
-[O que causava o bug]
-### Solução Implementada
-[Como foi corrigido]
-### Como Prevenir No Futuro
-[Mudança de processo, teste adicional, ou documentação]
-```
----
-## Critérios de Saída
-O debug sistemático está concluído quando:
-- [ ] Bug reproduzido e documentado
-- [ ] Causa raiz identificada e documentada
-- [ ] Correção implementada e commitada
-- [ ] Testes passando (incluindo teste do cenário do bug)
-- [ ] Logs de debug removidos
-- [ ] @qa notificado para re-verificar
-- [ ] Bug report atualizado com causa raiz e solução
----
-*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

package/template/.genia/development/tasks/dev-implement.md DELETED Viewed

@@ -1,199 +0,0 @@
-# Task: Dev — Implementar Story
-> Tarefa executada por @dev. Transforma uma story validada em código funcional.
-> Pré-requisito: story com status Ready (aprovada por @po).
----
-## Objetivo
-Implementar o código necessário para satisfazer todos os Acceptance Criteria da story, seguindo os padrões arquiteturais definidos no SPEC-TECNICO.md. Entregar código limpo, testado e commitado localmente, pronto para revisão de @qa.
----
-## Pré-requisitos
-Antes de iniciar, confirme:
-- [ ] Story tem status `Ready` (aprovada por @po)
-- [ ] SPEC-TECNICO.md lido e compreendido
-- [ ] Branch `main` local está atualizado (`git pull`)
-- [ ] Ambiente de desenvolvimento funcionando (dependências instaladas, env vars configuradas)
-- [ ] Clareza sobre todos os Acceptance Criteria (se houver dúvida, consultar @po ANTES de começar)
----
-## Passos de Execução
-### Passo 1 — Leitura e Preparação
-1. Leia a story completa: User Story, contexto, todos os ACs, não-escopo
-2. Leia as seções relevantes do SPEC-TECNICO.md
-3. Identifique todos os arquivos que precisarão ser criados ou modificados
-4. Se houver qualquer dúvida sobre o comportamento esperado: perguntar para @po AGORA (não depois de implementar errado)
-5. Estime internamente o tempo necessário e comunique para @sm se houver risco de não entregar no sprint
-### Passo 2 — Criar Branch
-```bash
-git checkout main
-git pull origin main
-git checkout -b feat/STORY-XXX-descricao-kebab-case
-```
-Exemplos de nomes de branch:
-- `feat/STORY-001-tela-de-login`
-- `fix/STORY-015-corrigir-validacao-email`
-- `refactor/STORY-022-extrair-servico-autenticacao`
-### Passo 3 — Planejamento da Implementação
-Antes de escrever código, faça um planejamento mental ou escrito:
-1. Quais componentes/funções precisam ser criados?
-2. Quais precisam ser modificados?
-3. Há alguma dependência técnica (biblioteca nova, configuração)?
-4. Qual a ordem lógica de implementação?
-### Passo 4 — Implementação (TDD quando possível)
-**Abordagem preferida (TDD):**
-1. Escreva o teste primeiro (descreve o comportamento esperado)
-2. Execute o teste — deve falhar (red)
-3. Implemente o código mínimo para o teste passar (green)
-4. Refatore o código mantendo os testes passando (refactor)
-**Abordagem alternativa (test-after):**
-1. Implemente a funcionalidade
-2. Escreva os testes cobrindo os cenários
-3. Garanta que os testes passam
-**Regras de implementação:**
-- Imports sempre absolutos com `@/` (nunca `../../../`)
-- Tipagem TypeScript estrita (sem `any` sem justificativa)
-- Funções com responsabilidade única (max 30 linhas como guia)
-- Nomes descritivos (variáveis, funções, componentes)
-- Comentários explicam o "por quê", não o "o quê"
-- Nunca hardcodar values que deveriam ser variáveis de ambiente
-### Passo 5 — Testes
-Execute após cada unidade coesa de código:
-```bash
-# Lint (zero tolerância a erros)
-npm run lint
-# TypeScript (zero erros)
-npm run typecheck
-# Testes unitários
-npm run test
-# Cobertura
-npm run coverage
-```
-**Meta de cobertura:** >= 80% nas linhas modificadas/criadas
-O que testar:
-- Happy path de cada AC
-- Edge cases (valores nulos, strings vazias, arrays vazios)
-- Cenários de erro (exceções esperadas)
-- Comportamento com dados inválidos
-O que NÃO testar (não agrega valor):
-- Implementações de terceiros (não testa o que o React faz)
-- Trivialidades óbvias (getters/setters simples sem lógica)
-### Passo 6 — Self-Review (Antes do Commit Final)
-Leia seu próprio código como se fosse o @reviewer:
-- [ ] O código implementa EXATAMENTE os ACs? (nem mais, nem menos)
-- [ ] Imports absolutos com `@/` em todos os arquivos novos?
-- [ ] Sem `any` sem justificativa no TypeScript?
-- [ ] Sem `console.log` de debug esquecidos?
-- [ ] Sem `.env` ou secrets hardcodados?
-- [ ] Sem código comentado desnecessário?
-- [ ] Funções com responsabilidade única?
-- [ ] Testes com cobertura >= 80%?
-- [ ] Lint sem warnings?
-### Passo 7 — Commits Atômicos
-Commite em unidades coesas — cada commit deve descrever uma mudança em uma frase:
-```bash
-git add src/components/Auth/LoginForm.tsx
-git add src/components/Auth/LoginForm.test.tsx
-git commit -m "feat(auth): implementar formulário de login com validação
-Implementa o formulário de login da STORY-001 com:
-- Campos de email e senha com validação client-side
-- Estado de loading durante autenticação
-- Exibição de erros da API
-Story: STORY-001
-Co-Authored-By: GEN.IA OS <genia@bedata.com.br>"
-```
-Tipos de commit:
-- `feat` — nova funcionalidade
-- `fix` — correção de bug
-- `refactor` — refatoração sem mudança de comportamento
-- `test` — adição ou correção de testes
-- `docs` — documentação inline
-**NUNCA** fazer `git push` — exclusivo de @devops.
-### Passo 8 — Verificação Final
-Antes de declarar pronto para @qa:
-```bash
-# Garanta que tudo ainda passa com o conjunto completo
-npm run lint && npm run typecheck && npm run test
-```
-- [ ] Todos os ACs foram implementados?
-- [ ] Todos os testes passando?
-- [ ] Cobertura >= 80%?
-- [ ] Lint e typecheck limpos?
-- [ ] Não-escopo da story foi respeitado? (não implementou nada além do escopo)
-### Passo 9 — Comunicar para @qa
-1. Atualize o status da story para `InQA` no arquivo `docs/stories/STORY-XXX.md`
-2. Notifique @qa que o código está pronto para revisão
-3. Informe:
-   - Story ID e branch name
-   - Quais ACs foram implementados
-   - Qualquer ponto de atenção que @qa deve saber
----
-## Gestão de Blockers
-Se encontrar um blocker durante a implementação:
-1. **Blocker técnico de arquitetura** → consultar @architect
-2. **Dúvida sobre requisito/AC** → consultar @po
-3. **Dependência de outra story** → comunicar @sm
-4. **Blocker de ambiente/ferramenta** → comunicar @devops
-Nunca inventar uma solução para um blocker sem validação — isso é violação do Artigo IV.
----
-## Critérios de Saída
-A implementação está pronta para @qa quando:
-- [ ] Todos os ACs da story implementados
-- [ ] Testes unitários com coverage >= 80%
-- [ ] `npm run lint` — zero erros ou warnings
-- [ ] `npm run typecheck` — zero erros
-- [ ] `npm run test` — todos passando
-- [ ] Código commitado localmente no branch correto
-- [ ] Status da story atualizado para InQA
-- [ ] @qa notificado com contexto
----
-*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

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

@@ -1,224 +0,0 @@
-# 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}}*