create-genia-os 2.0.0 → 2.1.1

package/template/.genia/development/checklists/story-dod.md

@@ -0,0 +1,155 @@
+# Checklist: Definition of Done (DoD) — Story
+
+> Critérios obrigatórios para uma story ser considerada Done.
+> Verificado por @po (negócio) + @qa (técnica) + @reviewer (código).
+
+---
+
+## O que é o Definition of Done?
+
+O Definition of Done (DoD) é o conjunto de critérios acordados pelo time que define quando uma story está genuinamente pronta — não "tecnicamente funcionando", mas entregável com qualidade para o usuário final. Uma story que não atende ao DoD não é Done, independente de o código estar escrito.
+
+---
+
+## Checklist Completo (10 Critérios)
+
+### Critério 1 — Acceptance Criteria Atendidos
+- [ ] Todos os ACs da story foram implementados
+- [ ] Todos os ACs foram verificados manualmente por @qa
+- [ ] @po confirmou que o comportamento atende à intenção de negócio
+- [ ] Não há ACs parcialmente implementados ou com workaround
+
+**Responsável de verificar:** @qa + @po
+
+---
+
+### Critério 2 — Testes Passando
+- [ ] Todos os testes unitários passam: `npm run test`
+- [ ] Nenhum teste ignorado (`skip`, `xtest`, `.only`) sem justificativa documentada
+- [ ] Testes de regressão de funcionalidades existentes passando (se brownfield)
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 3 — Cobertura de Testes
+- [ ] Cobertura de testes >= 80% nas linhas novas/modificadas
+- [ ] Verificado com: `npm run coverage`
+- [ ] Linhas não cobertas têm justificativa (ex: código de fallback impossível de testar)
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 4 — Qualidade de Código (Lint + Types)
+- [ ] `npm run lint` — zero erros e zero warnings
+- [ ] `npm run typecheck` — zero erros TypeScript
+- [ ] Sem `any` injustificado
+- [ ] Imports absolutos com `@/` em todos os arquivos novos
+
+**Responsável de verificar:** @reviewer
+
+---
+
+### Critério 5 — Sem Bugs Críticos
+- [ ] Zero bugs de severidade CRÍTICO pendentes
+- [ ] Máximo 2 bugs de severidade ALTO (documentados no backlog para sprint futuro)
+- [ ] Bugs de severidade MÉDIO e BAIXO documentados no backlog
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 6 — Code Review Aprovado
+- [ ] @reviewer realizou code review formal
+- [ ] Todos os itens BLOQUEANTES foram corrigidos
+- [ ] Aprovação (LGTM) emitida por @reviewer
+- [ ] Relatório de code review disponível em `docs/reviews/`
+
+**Responsável de verificar:** @reviewer
+
+---
+
+### Critério 7 — Arquitetura Respeitada
+- [ ] Código segue os padrões do SPEC-TECNICO.md
+- [ ] Estrutura de pastas correta
+- [ ] Separação de responsabilidades respeitada
+- [ ] Nenhuma decisão arquitetural tomada sem aprovação de @architect
+
+**Responsável de verificar:** @reviewer (+ @architect se houver dúvida)
+
+---
+
+### Critério 8 — PR Criado por @devops
+- [ ] Branch feito push para o remoto por @devops (nunca diretamente por @dev)
+- [ ] Pull Request criado com template completo
+- [ ] PR associado à story (referência no título ou body)
+- [ ] CI/CD pipeline verde no PR
+- [ ] PR mergeado para `main`
+
+**Responsável de verificar:** @devops
+
+---
+
+### Critério 9 — Segurança Básica
+- [ ] Sem hardcoded secrets, tokens ou URLs de ambiente
+- [ ] Inputs validados e sanitizados onde necessário
+- [ ] Dados sensíveis não expostos em logs
+- [ ] Autenticação/autorização corretas nos endpoints protegidos
+
+**Responsável de verificar:** @reviewer + @qa
+
+---
+
+### Critério 10 — Validação Final por @po
+- [ ] @po revisou o entregue e confirmou que atende à User Story
+- [ ] @po atualizou o status da story para `Done` no arquivo
+- [ ] @po atualizou o backlog para refletir a story entregue
+- [ ] Velocity do sprint atualizado
+
+**Responsável de verificar:** @po
+
+---
+
+## Resumo Visual
+
+| # | Critério | Responsável | Bloqueante |
+|---|---------|------------|-----------|
+| 1 | Acceptance Criteria atendidos | @qa + @po | Sim |
+| 2 | Testes passando | @qa | Sim |
+| 3 | Coverage >= 80% | @qa | Sim |
+| 4 | Lint + Typecheck limpos | @reviewer | Sim |
+| 5 | Sem bugs críticos | @qa | Sim |
+| 6 | Code review aprovado | @reviewer | Sim |
+| 7 | Arquitetura respeitada | @reviewer | Sim |
+| 8 | PR criado e mergeado | @devops | Sim |
+| 9 | Segurança básica | @reviewer + @qa | Sim |
+| 10 | Validação final de @po | @po | Sim |
+
+**Todos os 10 critérios são obrigatórios.** Uma story com 9/10 critérios não é Done.
+
+---
+
+## Processo de Verificação do DoD
+
+1. @qa verifica critérios 1, 2, 3, 5, 9 (parcial)
+2. @reviewer verifica critérios 4, 6, 7, 9 (parcial)
+3. @devops executa critério 8
+4. @po verifica critério 10 e confirma o Done
+
+Qualquer critério não atendido bloqueia a story de ir para Done.
+
+---
+
+## DoD vs. Acceptance Criteria
+
+| | DoD | Acceptance Criteria |
+|-|-----|-------------------|
+| **Escopo** | Toda story | Específico por story |
+| **Quem define** | Time (imutável no sprint) | @sm + @po (por story) |
+| **O que avalia** | Qualidade do processo de entrega | Comportamento funcional |
+| **Pode variar** | Não (é padrão do time) | Sim (por story) |
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

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

@@ -0,0 +1,197 @@
+# Task: Code Review
+
+> Tarefa executada por @reviewer. Revisão formal de código antes do merge.
+> Pré-requisito: @qa aprovou o código (story em InReview).
+
+---
+
+## Objetivo
+
+Realizar revisão técnica completa do código implementado por @dev, verificando corretude, arquitetura, segurança, legibilidade e manutenibilidade. Emitir aprovação (LGTM) ou solicitar mudanças bloqueantes com feedback construtivo.
+
+---
+
+## Pré-requisitos
+
+Antes de iniciar, confirme:
+
+- [ ] Story tem status `InReview`
+- [ ] @qa aprovou formalmente (relatório de QA disponível)
+- [ ] Branch está disponível para checkout/análise
+- [ ] @reviewer leu a story e os ACs
+
+---
+
+## Passos de Execução
+
+### Passo 1 — Contexto e Preparação
+
+1. Leia a story completa (User Story, ACs, não-escopo)
+2. Leia o relatório de QA de @qa
+3. Revise as seções relevantes do SPEC-TECNICO.md
+4. Analise o diff completo:
+   ```bash
+   git diff main...feat/STORY-XXX-descricao
+   ```
+5. Liste mentalmente o que espera ver antes de começar a revisar
+
+### Passo 2 — Revisão de Corretude
+
+**O código faz o que deveria fazer?**
+
+- [ ] A lógica implementa corretamente cada AC?
+- [ ] Edge cases relevantes são tratados?
+- [ ] Erros são capturados e tratados adequadamente?
+- [ ] Mensagens de erro são úteis e claras?
+- [ ] Não há bugs óbvios de lógica (condições invertidas, off-by-one, etc.)?
+- [ ] Fluxos assíncronos são tratados corretamente (loading, error, success)?
+
+### Passo 3 — Revisão Arquitetural
+
+**O código está na estrutura correta?**
+
+- [ ] Segue os padrões do SPEC-TECNICO.md?
+- [ ] Imports absolutos com `@/` em todos os arquivos?
+- [ ] Componentes/funções estão nas pastas corretas conforme a estrutura definida?
+- [ ] Não viola separação de responsabilidades?
+- [ ] Não há código de lógica de negócio em componentes de UI (e vice-versa)?
+- [ ] Não há código duplicado que poderia ser extraído?
+- [ ] Dependências entre módulos respeitam os boundaries definidos?
+
+### Passo 4 — Revisão de Segurança
+
+**O código é seguro?**
+
+- [ ] Sem hardcoded secrets, tokens, passwords ou URLs de ambiente?
+- [ ] Input validation presente onde dados externos são consumidos?
+- [ ] Sem vulnerabilidades de XSS (dados de usuário inseridos no DOM sem sanitização)?
+- [ ] Autenticação e autorização corretas nos endpoints/páginas protegidas?
+- [ ] Dados sensíveis não aparecem em logs?
+- [ ] Sem SQL injection ou query injection possível?
+- [ ] Dependências externas verificadas (nenhuma suspeita adicionada)?
+
+### Passo 5 — Revisão de Qualidade de Código
+
+**O código é legível e manutenível?**
+
+- [ ] Nomes de variáveis, funções e componentes são descritivos?
+- [ ] Funções têm responsabilidade única (fazem uma coisa bem)?
+- [ ] Complexidade cognitiva é aceitável? (se você precisar de >30 segundos para entender uma função, é complexa demais)
+- [ ] Comentários existentes agregam valor (explicam o "por quê", não o "o quê")?
+- [ ] Não há código morto (código comentado, imports não usados, variáveis não usadas)?
+- [ ] TypeScript usado de forma efetiva (sem `any` injustificado, tipos bem definidos)?
+
+### Passo 6 — Revisão de Testes
+
+**Os testes são de qualidade?**
+
+- [ ] Testes existem para a funcionalidade implementada?
+- [ ] Os testes testam comportamento (o que o código faz), não implementação (como faz)?
+- [ ] Testes cobrem happy path, edge cases e cenários de erro?
+- [ ] Testes são legíveis? (outro dev entende o que está sendo testado sem precisar ler o código fonte)
+- [ ] Não há testes que testam a implementação de terceiros (React, bibliotecas)?
+- [ ] Coverage >= 80% conforme verificado por @qa?
+
+### Passo 7 — Revisão de Performance
+
+**O código tem problemas de performance óbvios?**
+
+- [ ] Sem N+1 queries (buscar dados dentro de um loop)?
+- [ ] Sem re-renders desnecessários (React — memoização faltando quando necessário)?
+- [ ] Operações custosas fora de loops quando possível?
+- [ ] Assets (imagens, fontes) otimizados se aplicável?
+- [ ] Sem chamadas de API desnecessárias?
+
+### Passo 8 — Categorização de Issues
+
+Para cada problema encontrado, classifique:
+
+| Categoria | Bloqueia merge? | Quando usar |
+|-----------|----------------|------------|
+| CRÍTICO | Sim | Segurança, dados corrompidos, crash |
+| BLOQUEANTE | Sim | Violação arquitetural, lógica incorreta, AC não implementado |
+| SUGESTÃO | Não | Nome melhor, refatoração opcional, documentação |
+| COSMÉTICO | Não | Formatação (já coberta por linter automático) |
+
+**Regra:** Não invente razões para reprovar. Se o código funciona, é seguro e está na arquitetura correta, aprove — mesmo que você tivesse feito diferente.
+
+### Passo 9 — Emissão do Veredicto
+
+**APROVADO (LGTM):**
+
+```markdown
+## ✅ Code Review — APROVADO
+Story: STORY-XXX | Branch: feat/STORY-XXX-descricao
+Revisor: Rev (@reviewer) | Data: YYYY-MM-DD
+
+### Pontos Positivos
+- [Algo bem feito que merece reconhecimento]
+- [Boa prática identificada]
+
+### Sugestões (Não-Bloqueantes)
+- [arquivo:linha] [sugestão para o futuro]
+- [arquivo:linha] [alternativa a considerar]
+
+LGTM. @devops pode fazer push e criar o PR.
+```
+
+**MUDANÇAS SOLICITADAS:**
+
+```markdown
+## ❌ Code Review — MUDANÇAS SOLICITADAS
+Story: STORY-XXX | Branch: feat/STORY-XXX-descricao
+Revisor: Rev (@reviewer) | Data: YYYY-MM-DD
+
+### Issues BLOQUEANTES (devem ser corrigidos antes do merge)
+
+1. **[CRÍTICO]** `src/components/Login/index.tsx:45`
+   Token da API hardcodado na linha 45.
+   **Correção:** mover para variável de ambiente `NEXT_PUBLIC_API_TOKEN`
+
+2. **[BLOQUEANTE]** `src/services/auth.ts:23`
+   Import relativo `../../lib/api` viola o padrão de imports absolutos.
+   **Correção:** mudar para `@/lib/api`
+
+### Sugestões (Não-Bloqueantes)
+1. `src/hooks/useAuth.ts:12` — considerar usar `useCallback` para o handler
+
+@dev por favor corrija os itens BLOQUEANTES e sinalize quando pronto para re-review.
+```
+
+### Passo 10 — Comunicação
+
+**Se APROVADO:**
+- Atualize status da story para `InPR`
+- Notifique @devops com: branch name, story ID, "aprovado para push e PR"
+
+**Se MUDANÇAS SOLICITADAS:**
+- Mantenha status como `InReview`
+- Notifique @dev com o relatório de mudanças
+- Aguarde @dev corrigir e sinalizar para re-review
+
+---
+
+## Re-review
+
+Quando @dev notifica que corrigiu:
+
+1. Verifique APENAS os itens que foram sinalizados como BLOQUEANTES
+2. Se todos corrigidos: APROVAR
+3. Se algum não foi corrigido adequadamente: solicitar mudança novamente com mais clareza
+
+---
+
+## Critérios de Saída
+
+O code review está concluído quando:
+
+- [ ] Diff completo lido e analisado
+- [ ] Todos os itens do checklist verificados
+- [ ] Issues categorizados (BLOQUEANTE vs. SUGESTÃO)
+- [ ] Veredicto emitido formalmente (APROVADO ou MUDANÇAS SOLICITADAS)
+- [ ] Relatório salvo em `docs/reviews/REVIEW-STORY-XXX.md`
+- [ ] Agente correto notificado (@devops ou @dev)
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

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

@@ -0,0 +1,170 @@
+# Task: Criar PRD
+
+> Tarefa executada por @pm após receber o BRIEFING.md de @analyst.
+> Output: `docs/[projeto]/PRD.md`
+
+---
+
+## Objetivo
+
+Transformar o briefing de negócios em um Product Requirements Document (PRD) completo, priorizado e aprovado por stakeholders. O PRD é o documento de referência que guia todo o desenvolvimento — ele deve ser suficientemente claro para que qualquer agente entenda o que está sendo construído e por quê.
+
+---
+
+## Pré-requisitos
+
+Antes de iniciar, confirme:
+
+- [ ] `docs/[projeto]/BRIEFING.md` existe e está completo
+- [ ] @analyst confirmou que o briefing foi validado com stakeholders
+- [ ] Todas as ambiguidades do briefing foram resolvidas
+- [ ] @pm tem acesso a qualquer material adicional do cliente
+
+---
+
+## Passos de Execução
+
+### Passo 1 — Revisão do Briefing
+1. Leia o BRIEFING.md completamente
+2. Identifique e anote quaisquer pontos que precisam de esclarecimento
+3. Se necessário, solicite esclarecimento a @analyst antes de prosseguir
+4. Nunca assuma — dúvidas são resolvidas antes de escrever o PRD
+
+### Passo 2 — Definição da Visão de Produto
+1. Articule o problema central que o produto resolve (em 1-2 parágrafos)
+2. Defina a proposta de valor única (o que diferencia este produto)
+3. Descreva o estado futuro desejado: como fica o mundo com este produto?
+4. Identifique as restrições não-negociáveis (tecnologia, prazo, regulatório)
+
+### Passo 3 — Definição de Personas
+1. Liste as personas identificadas no briefing
+2. Para cada persona, defina:
+   - Nome e perfil
+   - Objetivos principais ao usar o sistema
+   - Dores e frustrações atuais
+   - Nível de expertise técnica
+3. Priorize as personas (primária, secundária)
+
+### Passo 4 — Estruturação em Épicos
+1. Agrupe as funcionalidades em Épicos coesos:
+   - Cada épico é um conjunto de funcionalidades relacionadas
+   - Épicos devem ser independentes entre si quando possível
+   - Épicos têm uma "promessa de valor" clara
+2. Nomeie os épicos com IDs: E-01, E-02, E-03...
+3. Escreva uma frase de valor para cada épico
+
+### Passo 5 — Priorização MoSCoW
+Para cada funcionalidade/épico, aplique:
+- **Must Have (M):** crítico para o produto funcionar. Sem isso, não há produto
+- **Should Have (S):** importante mas há workaround possível
+- **Could Have (C):** desejável se houver tempo e budget
+- **Won't Have (W):** explicitamente fora do escopo desta versão
+
+### Passo 6 — Definição de Métricas de Sucesso
+1. Defina 3-5 métricas de produto que indicam sucesso
+2. Para cada métrica:
+   - Nome claro
+   - Como é medida
+   - Baseline atual (se disponível)
+   - Meta após lançamento
+3. Evite métricas de vaidade — prefira métricas de comportamento do usuário
+
+### Passo 7 — Validação com @architect
+1. Compartilhe o PRD rascunho com @architect
+2. Aguarde avaliação de viabilidade técnica
+3. Incorpore feedback técnico (ajustes de escopo, riscos identificados)
+4. Se @architect vetar algum item, documente a decisão
+
+### Passo 8 — Aprovação com @po
+1. Compartilhe o PRD atualizado com @po
+2. @po valida que é possível criar stories claras para cada item
+3. Incorpore ajustes de @po
+4. Obtenha aprovação formal de @po
+
+### Passo 9 — Publicação
+1. Salve o documento final em `docs/[projeto]/PRD.md`
+2. Versione o documento (v1.0)
+3. Notifique o time sobre a disponibilidade do PRD
+4. Acione @sm para iniciar criação de stories
+
+---
+
+## Critérios de Saída
+
+O PRD está pronto quando:
+
+- [ ] Todos os épicos estão definidos com proposta de valor
+- [ ] Priorização MoSCoW aplicada a todas as funcionalidades
+- [ ] Personas definidas e priorizadas
+- [ ] Métricas de sucesso definidas (mínimo 3)
+- [ ] Não-escopo documentado explicitamente
+- [ ] @architect validou viabilidade técnica
+- [ ] @po aprovou formalmente
+- [ ] Documento salvo em `docs/[projeto]/PRD.md`
+
+---
+
+## Output — Estrutura do PRD.md
+
+```markdown
+# PRD — [Nome do Produto]
+Versão: 1.0 | PM: Marina (@pm) | Data: YYYY-MM-DD
+Status: Rascunho | Em Revisão | Aprovado
+
+## 1. Visão e Proposta de Valor
+### Problema Central
+### Proposta de Valor Única
+### Estado Futuro Desejado
+
+## 2. Personas
+### Persona Primária: [Nome]
+### Persona Secundária: [Nome]
+
+## 3. Objetivos de Produto
+| Objetivo | Métrica | Baseline | Meta |
+|---------|--------|---------|------|
+
+## 4. Épicos e Funcionalidades
+
+### E-01 — [Nome do Épico]
+**Promessa de valor:** [Uma frase]
+**Prioridade:** Must Have
+
+#### Funcionalidades
+- [Feature 1] — Must Have
+- [Feature 2] — Should Have
+- [Feature 3] — Could Have
+
+### E-02 — [Nome do Épico]
+...
+
+## 5. Não-Escopo (Explícito)
+O que NÃO será construído nesta versão:
+- [Item 1]
+- [Item 2]
+
+## 6. Restrições
+- Prazo: [data]
+- Budget: [informação se disponível]
+- Tecnologia obrigatória: [se houver]
+- Regulatório: [compliance, LGPD, etc]
+
+## 7. Roadmap e Milestones
+| Milestone | O que inclui | Data estimada |
+|----------|------------|--------------|
+
+## 8. Riscos de Produto
+| Risco | Probabilidade | Impacto | Mitigação |
+|-------|--------------|--------|----------|
+
+## 9. Glossário
+[Termos de negócio específicos do domínio]
+
+## 10. Histórico de Versões
+| Versão | Data | Autor | Mudança |
+|--------|------|-------|--------|
+```
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

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

@@ -0,0 +1,188 @@
+# Task: Criar SPEC-TECNICO
+
+> Tarefa executada por @architect após PRD aprovado por @pm e @po.
+> Output: `docs/[projeto]/SPEC-TECNICO.md` + ADRs iniciais
+
+---
+
+## Objetivo
+
+Criar a especificação técnica completa que traduz os requisitos de negócio do PRD em decisões de arquitetura, tecnologia, estrutura de código e padrões de desenvolvimento. O SPEC-TECNICO é o guia técnico definitivo — qualquer decisão de implementação que não esteja aqui deve ser escalada para @architect antes de ser tomada.
+
+---
+
+## Pré-requisitos
+
+Antes de iniciar, confirme:
+
+- [ ] `docs/[projeto]/PRD.md` existe e está aprovado por @pm e @po
+- [ ] @architect leu o PRD completamente
+- [ ] Acesso ao repositório (se brownfield) ou liberdade para definir stack (se greenfield)
+- [ ] Clareza sobre restrições de tecnologia (se houver imposições do cliente)
+
+---
+
+## Passos de Execução
+
+### Passo 1 — Análise do PRD
+1. Leia o PRD completamente e anote:
+   - Requisitos funcionais por épico
+   - Requisitos não-funcionais (desempenho, segurança, disponibilidade)
+   - Integrações necessárias com sistemas externos
+   - Restrições tecnológicas declaradas
+2. Identifique perguntas técnicas abertas e resolva com @pm antes de continuar
+
+### Passo 2 — Definição de Stack
+1. Para cada camada da stack, avalie opções e registre decisão:
+   - **Frontend:** React, Next.js, Vue, etc.
+   - **Backend:** Node.js, Python, Go, etc.
+   - **Banco de dados:** PostgreSQL, MongoDB, Supabase, etc.
+   - **Autenticação:** NextAuth, Clerk, Auth0, etc.
+   - **Infraestrutura:** Vercel, Railway, AWS, etc.
+   - **Cache:** Redis, memória, etc. (se necessário)
+2. Para cada escolha, justifique explicitamente (não apenas "é popular")
+3. Registre alternativas consideradas e por que foram descartadas
+4. Crie ADRs para as decisões mais relevantes
+
+### Passo 3 — Arquitetura de Alto Nível
+1. Defina os componentes principais do sistema
+2. Descreva como cada componente se comunica (REST, GraphQL, WebSocket, etc.)
+3. Identifique boundaries de domínio (onde uma responsabilidade termina e outra começa)
+4. Documente o fluxo dos dados principais
+5. Escreva um diagrama textual (ou ASCII) da arquitetura
+
+### Passo 4 — Estrutura de Pastas
+1. Defina a estrutura completa de pastas do projeto:
+   ```
+   src/
+   ├── app/           # pages e rotas (Next.js)
+   ├── components/    # componentes reutilizáveis
+   │   ├── ui/        # componentes base (Button, Input, etc.)
+   │   └── [domain]/  # componentes de domínio
+   ├── lib/           # utilitários e helpers
+   ├── hooks/         # React hooks customizados
+   ├── services/      # chamadas a APIs externas
+   ├── types/         # tipagens TypeScript
+   ├── contexts/      # React Contexts
+   └── schemas/       # validação com Zod
+   ```
+2. Justifique escolhas não-óbvias
+3. Configure `tsconfig.json` com paths absolutos (`@/`)
+
+### Passo 5 — Modelagem de Dados
+1. Defina as entidades principais do domínio
+2. Para cada entidade: campos, tipos, relacionamentos, constraints
+3. Defina estratégia de migração de banco (ferramentas, convenções)
+4. Documente índices importantes para performance
+5. Identifique dados sensíveis e como serão protegidos (LGPD/GDPR)
+
+### Passo 6 — APIs e Contratos
+1. Para cada endpoint/operação relevante, defina:
+   - Método HTTP e path
+   - Request body (campos, tipos, validações)
+   - Response body (campos, tipos)
+   - Códigos de status e cenários de erro
+2. Defina convenções de nomenclatura de API
+3. Documente integrações com APIs externas (webhook, polling, SDK)
+
+### Passo 7 — Autenticação e Autorização
+1. Defina o mecanismo de autenticação escolhido
+2. Mapeie os perfis/roles de usuário
+3. Defina regras de autorização por role
+4. Documente estratégia de sessão (JWT, cookie, etc.)
+
+### Passo 8 — Estratégia de Testes
+1. Defina a pirâmide de testes:
+   - Unitários: ferramentas, o que testar, cobertura mínima
+   - Integração: quais fluxos, ferramentas
+   - E2E: ferramentas (Cypress, Playwright), fluxos críticos
+2. Configure as ferramentas de teste no projeto
+3. Defina cobertura mínima aceitável (GEN.IA OS default: 80%)
+
+### Passo 9 — Segurança e Boas Práticas
+1. Defina como secrets são gerenciados (variáveis de ambiente, Vault)
+2. Liste as vulnerabilidades OWASP Top 10 relevantes e como serão mitigadas
+3. Defina política de rate limiting se aplicável
+4. Documente estratégia de logging (sem dados sensíveis nos logs)
+
+### Passo 10 — ADRs de Fundação
+Para cada decisão arquitetural importante, crie um ADR:
+- `docs/adr/ADR-001-escolha-de-stack.md`
+- `docs/adr/ADR-002-estrategia-autenticacao.md`
+- `docs/adr/ADR-003-modelagem-de-dados.md`
+- [etc.]
+
+---
+
+## Critérios de Saída
+
+O SPEC-TECNICO está pronto quando:
+
+- [ ] Stack definida e justificada para cada camada
+- [ ] Arquitetura de alto nível documentada
+- [ ] Estrutura de pastas definida
+- [ ] `tsconfig.json` com paths absolutos configurado
+- [ ] Modelagem de dados completa
+- [ ] APIs e contratos documentados (ao menos os principais)
+- [ ] Autenticação e autorização especificadas
+- [ ] Estratégia de testes definida com cobertura mínima
+- [ ] Considerações de segurança documentadas
+- [ ] ADRs iniciais criados (mínimo 3)
+- [ ] @qa revisou criticamente o spec (Fase 5 do Spec Pipeline)
+- [ ] Documento salvo em `docs/[projeto]/SPEC-TECNICO.md`
+
+---
+
+## Output — Estrutura do SPEC-TECNICO.md
+
+```markdown
+# Especificação Técnica — [Nome do Projeto]
+Versão: 1.0 | Arquiteta: Arqui (@architect) | Data: YYYY-MM-DD
+Status: Rascunho | Em Revisão | Aprovado
+
+## 1. Visão Técnica
+### Objetivos Técnicos
+### Princípios Guias de Arquitetura
+
+## 2. Stack Tecnológica
+| Camada | Tecnologia | Versão | Justificativa |
+|--------|-----------|--------|--------------|
+
+## 3. Arquitetura de Alto Nível
+[Diagrama textual/ASCII]
+[Descrição dos componentes e comunicações]
+
+## 4. Estrutura de Pastas
+[Árvore de pastas comentada]
+
+## 5. Modelagem de Dados
+[Entidades, campos e relacionamentos]
+
+## 6. APIs e Contratos
+[Endpoints, request/response, erros]
+
+## 7. Autenticação e Autorização
+[Mecanismo, roles, regras]
+
+## 8. Integrações Externas
+[APIs de terceiros, webhooks, SDKs]
+
+## 9. Estratégia de Testes
+[Pirâmide, ferramentas, cobertura]
+
+## 10. Segurança
+[Gestão de secrets, OWASP, logging]
+
+## 11. Requisitos Não-Funcionais
+| RNF | Requisito | Como Medir |
+|-----|----------|-----------|
+
+## 12. ADRs
+[Links para os ADRs criados]
+
+## 13. Histórico de Versões
+```
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*