create-genia-os 1.0.0

package/template/.genia/development/tasks/criar-story.md

@@ -0,0 +1,185 @@
+# Task: Criar Story
+
+> Tarefa executada por @sm. Somente @sm cria stories formais.
+> Output: `docs/stories/STORY-XXX.md`
+
+---
+
+## Objetivo
+
+Criar uma story bem definida, no formato INVEST, com acceptance criteria mensuráveis, pronta para ser validada por @po e desenvolvida por @dev. Uma story mal escrita é a causa mais comum de retrabalho e confusão durante o desenvolvimento.
+
+---
+
+## Pré-requisitos
+
+Antes de iniciar, confirme:
+
+- [ ] PRD.md aprovado existe (`docs/[projeto]/PRD.md`)
+- [ ] SPEC-TECNICO.md aprovado existe (`docs/[projeto]/SPEC-TECNICO.md`)
+- [ ] O épico pai da story está definido no PRD
+- [ ] Há backlog room para esta story (capacity do sprint permite)
+- [ ] @sm tem clareza sobre o que a story deve entregar
+
+---
+
+## Como Determinar o Próximo Story ID
+
+1. Liste os arquivos em `docs/stories/`
+2. Identifique o maior número existente (ex: STORY-007)
+3. A próxima story será STORY-008
+4. Se não há stories existentes, começar em STORY-001
+
+---
+
+## Passos de Execução
+
+### Passo 1 — Contexto
+1. Leia o épico pai no PRD para entender o contexto de valor
+2. Leia as seções relevantes do SPEC-TECNICO para entender implicações técnicas
+3. Verifique se há stories anteriores relacionadas que estabelecem contexto
+
+### Passo 2 — Definição da User Story
+1. Identifique a persona correta (do PRD)
+2. Defina a ação/funcionalidade específica (o mais granular possível)
+3. Defina o benefício de negócio (mensurável quando possível)
+4. Escreva no formato: "Como [persona], quero [ação], para [benefício]"
+
+**Teste de qualidade da User Story:**
+- A persona é real e definida no PRD? (não "como usuário genérico")
+- A ação é específica o suficiente para implementar? (não "melhorar a experiência")
+- O benefício é de negócio real? (não "para ter acesso a isso")
+
+### Passo 3 — Acceptance Criteria
+1. Para cada AC, pense: "Como @qa vai verificar isso?"
+2. Use o formato: "[Dado X], quando [ação Y], então [resultado Z]"
+   - Ou: "[Funcionalidade] deve [comportamento mensurável]"
+3. Cubra:
+   - Happy path (fluxo principal de sucesso)
+   - Edge cases relevantes (dados inválidos, estados vazios)
+   - Cenários negativos (o que deve ser impedido)
+4. Mínimo 3 ACs, máximo 8
+
+**Teste de qualidade dos ACs:**
+- @qa consegue verificar este AC sem ambiguidade?
+- O AC descreve o comportamento, não a implementação?
+- O AC é específico o suficiente? ("rápido" não é mensurável)
+
+### Passo 4 — Não-Escopo
+1. Liste explicitamente o que esta story NÃO inclui
+2. Seja específico sobre funcionalidades adjacentes que podem causar confusão
+3. Exemplo: "Esta story NÃO inclui a tela de edição — apenas criação"
+
+### Passo 5 — Dependências
+1. Identifique se esta story depende de outra estar concluída
+2. Se há dependências: referenciar os IDs das stories
+3. Se há bloqueadores técnicos: documentar e escalar para @architect
+
+### Passo 6 — Notas Técnicas
+1. Do SPEC-TECNICO, extraia informações relevantes para o @dev:
+   - Arquivos/módulos que devem ser criados ou modificados
+   - Padrões a seguir
+   - APIs externas envolvidas
+   - Considerações de segurança específicas
+2. Não tente especificar o "como" em detalhes — isso é papel do @dev e @architect
+
+### Passo 7 — Estimativa
+1. Estime o esforço em pontos usando a escala Fibonacci simplificada:
+   - **P (1-3 pts):** Story pequena, sem ambiguidade, menos de 1 dia
+   - **M (5 pts):** Story média, algumas decisões, 1-2 dias
+   - **G (8 pts):** Story grande, complexidade moderada, 2-3 dias
+   - **XG (13 pts):** Story muito grande — considere quebrar em 2 stories
+2. Se estimativa é XG ou maior: quebrar antes de validar com @po
+
+### Passo 8 — Self-Review
+Antes de enviar para @po, aplique o checklist INVEST:
+- [ ] **I**ndependente: pode ser desenvolvida sem dependência não-mapeada?
+- [ ] **N**egociável: os detalhes podem ser ajustados se necessário?
+- [ ] **V**aliosa: tem valor claro de negócio?
+- [ ] **E**stimável: conseguimos estimar o esforço?
+- [ ] **S**mall (pequena): cabe em uma sprint?
+- [ ] **T**estável: @qa consegue verificar todos os ACs?
+
+### Passo 9 — Criação do Arquivo
+1. Crie o arquivo em `docs/stories/STORY-XXX.md` seguindo o template
+2. Defina status inicial como `Draft`
+3. Envie para @po para validação
+
+---
+
+## Template Completo
+
+```markdown
+---
+id: STORY-XXX
+título: [Título descritivo em até 60 caracteres]
+épico: E-XX — [Nome do Épico]
+sprint: Sprint-XX
+estimativa: P | M | G | XG
+assignee: null
+status: Draft
+prioridade: CRÍTICO | ALTO | MÉDIO | BAIXO
+criada_por: "@sm"
+criada_em: YYYY-MM-DD
+aprovada_por: null
+aprovada_em: null
+---
+
+# STORY-XXX — [Título]
+
+## User Story
+Como [persona definida no PRD],
+quero [ação/funcionalidade específica],
+para [benefício de negócio mensurável].
+
+## Contexto
+[1-3 parágrafos de contexto para @dev entender o porquê e o entorno da story]
+
+## Acceptance Criteria
+
+- [ ] AC-01: Dado [contexto], quando [ação], então [resultado esperado]
+- [ ] AC-02: Dado [contexto], quando [ação], então [resultado esperado]
+- [ ] AC-03: Dado [contexto], quando [ação], então [resultado esperado]
+
+## Não-Escopo (Explícito)
+Esta story NÃO inclui:
+- [Item 1 fora do escopo]
+- [Item 2 fora do escopo]
+
+## Dependências
+- Depende de: [STORY-XXX se houver | "nenhuma"]
+- Bloqueada por: ["nenhum bloqueador" | descrição]
+
+## Notas Técnicas
+[Extraídas do SPEC-TECNICO — orientações de implementação relevantes]
+- Arquivos/módulos afetados: [lista]
+- Padrões a seguir: [referência ao SPEC-TECNICO]
+- APIs envolvidas: [se houver]
+
+## Definition of Done
+- [ ] Código implementado e funcionando localmente
+- [ ] Testes unitários escritos (coverage >= 80%)
+- [ ] Lint e typecheck passando sem erros
+- [ ] QA aprovado por @qa (todos os ACs verificados)
+- [ ] Code review aprovado por @reviewer
+- [ ] PR criado por @devops
+- [ ] @po confirmou que a story atende aos critérios de negócio
+```
+
+---
+
+## Critérios de Saída
+
+A task criar-story está concluída quando:
+
+- [ ] Arquivo `docs/stories/STORY-XXX.md` criado com template completo
+- [ ] User Story no formato correto
+- [ ] Mínimo 3 ACs mensuráveis e testáveis
+- [ ] Não-escopo documentado
+- [ ] Estimativa definida (P/M/G/XG)
+- [ ] Status: Draft
+- [ ] @po acionado para validação
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

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

@@ -0,0 +1,230 @@
+# 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

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