create-genia-os 2.0.0 → 2.1.1

package/template/.claude/rules/agent-handoff.md

@@ -0,0 +1,71 @@
+# Protocolo de Handoff — GEN.IA OS
+
+## Quando Fazer Handoff
+
+Handoff é obrigatório quando:
+- Tarefa requer autoridade de outro agente (Artigo II)
+- Fase do workflow mudou
+- Blocker identificado fora do escopo atual
+- Trabalho está completo e próxima etapa é de outro agente
+
+## Formato de Handoff (≤ 400 tokens)
+
+```
+[@agente-atual → @próximo-agente]
+
+📋 Contexto: [O que foi feito em 2-3 frases]
+
+📌 Decisões tomadas:
+- [decisão 1]
+- [decisão 2]
+
+📁 Arquivos criados/modificados:
+- [path/arquivo.md]
+
+⚠️  Pendências:
+- [o que precisa ser feito]
+
+🔗 Story atual: STORY-NNN (se aplicável)
+```
+
+## Regra de Token Budget
+
+- Handoff DEVE ser ≤ 400 tokens
+- Após 2+ trocas de agente, comprimir histórico ao essencial
+- Não repassar contexto completo — apenas decisões e pendências
+
+## Compressão de Contexto
+
+Quando o contexto estiver saturado (muitas trocas de agente):
+
+1. Criar `.genia/session/context-summary.md` com:
+   - Decisões arquiteturais tomadas
+   - Stories em andamento e seus estados
+   - Blockers conhecidos
+   - Stack tecnológica confirmada
+
+2. Referenciar o arquivo no próximo handoff:
+   ```
+   [Contexto comprimido em .genia/session/context-summary.md]
+   ```
+
+## Exemplos de Handoff
+
+**@dev → @devops (após implementação):**
+```
+[@dev → @devops]
+📋 Implementei STORY-003 (autenticação JWT). Commits feitos localmente.
+📌 Decisões: Usei jose library, tokens expiram em 1h, refresh em 7d.
+📁 Modificados: src/auth/jwt.ts, src/middleware/auth.ts, tests/auth.test.ts
+⚠️  Pendências: Push da branch feat/STORY-003-jwt-auth e criar PR para main.
+🔗 Story atual: STORY-003 (status: InReview)
+```
+
+**@analyst → @pm (após briefing):**
+```
+[@analyst → @pm]
+📋 Coletei requisitos completos do sistema de orçamentos BrasilUp.
+📌 Decisões: App web (não mobile), integração com Kommo CRM, 3 usuários simultâneos.
+📁 Criados: docs/brasilup/BRIEFING.md
+⚠️  Pendências: Criar PRD com base no briefing. Atenção ao requisito de relatórios PDF.
+```

package/template/.claude/rules/agent-memory.md

@@ -0,0 +1,61 @@
+# Memória Persistente dos Agentes — GEN.IA OS
+
+## Localização
+
+```
+.claude/agent-memory/
+├── analyst/MEMORY.md
+├── pm/MEMORY.md
+├── architect/MEMORY.md
+├── dev/MEMORY.md
+├── devops/MEMORY.md
+├── qa/MEMORY.md
+├── reviewer/MEMORY.md
+├── po/MEMORY.md
+└── sm/MEMORY.md
+```
+
+## Regra de Leitura
+
+Todo agente DEVE ler seu `MEMORY.md` ao ser ativado. Esta leitura é parte do protocolo de ativação.
+
+## Quando Atualizar
+
+Atualizar o MEMORY.md quando:
+- Descobrir padrão recorrente no projeto
+- Resolver problema difícil (documentar a solução)
+- Identificar preferência da usuária (Elidy)
+- Encontrar um gotcha (armadilha) do projeto
+- Tomar decisão arquitetural relevante
+
+## Formato do MEMORY.md
+
+```markdown
+# MEMORY — @[agente] ([Nome])
+
+> Memória persistente. Atualizada a cada sessão relevante.
+> Última atualização: YYYY-MM-DD
+
+## Padrões Confirmados
+- [padrão]: [quando usar]
+
+## Preferências da Usuária
+- [preferência]: [contexto]
+
+## Gotchas do Projeto
+- [problema]: [solução]
+
+## Decisões Importantes
+- [decisão]: [justificativa e data]
+
+## Stack Tecnológica Confirmada
+- [tecnologia]: [versão/contexto]
+```
+
+## Regra de Escrita
+
+- Não adicionar informações duplicadas
+- Verificar se já existe entry antes de criar nova
+- Remover entries desatualizadas
+- Máximo 200 linhas por arquivo (comprimir se necessário)
+- Usar linguagem objetiva: fatos, não opiniões

package/template/.claude/rules/ids-principles.md

@@ -0,0 +1,52 @@
+# Princípios IDS — GEN.IA OS
+## Incremental Decision System
+
+## Hierarquia de Decisão
+
+```
+REUSAR > ADAPTAR > CRIAR
+```
+
+Antes de criar qualquer artefato (componente, task, template, módulo, contexto):
+
+**1. REUSAR** — Buscar no projeto algo que já resolve o problema
+**2. ADAPTAR** — Se 70%+ compatível, adaptar o existente
+**3. CRIAR** — Apenas se reutilização não é viável
+
+## Onde Buscar Antes de Criar
+
+| Tipo | Buscar em |
+|------|-----------|
+| Task | `.genia/development/tasks/` |
+| Template de doc | `.claude/templates/` (se existir) |
+| Contexto de API | `.genia/contexts/` |
+| Skill | `.genia/skills/` |
+| Guideline | `.genia/guidelines/` |
+| Checklist | `.genia/development/checklists/` |
+
+## Justificativa Obrigatória para CRIAR
+
+Ao criar novo artefato que poderia ser reusado, documentar inline:
+
+```
+// NOVO: não foi possível reusar porque [razão]
+// Adaptação de: [nada existente] | [X arquivo, mas incompatível por Y]
+```
+
+## Prevenção de Duplicação em Stories
+
+Antes de criar `STORY-NNN`, verificar:
+1. Existe story similar em `docs/stories/`?
+2. Está dentro de um épico já existente?
+3. Já foi implementado e mergeado?
+
+## Circuit Breaker
+
+Se a busca por artefato reutilizável demorar mais de 30 segundos, prosseguir com criação e documentar a tentativa de busca.
+
+## Benefícios
+
+- Reduz explosão de arquivos no projeto
+- Mantém consistência entre implementações similares
+- Facilita manutenção no longo prazo
+- Evita reinventar soluções já validadas

package/template/.claude/rules/mcp-usage.md

@@ -0,0 +1,49 @@
+# Uso de Ferramentas e MCP — GEN.IA OS
+
+## Prioridade de Ferramentas
+
+```
+1. Ferramentas nativas Claude Code  (sempre preferir)
+2. Ferramentas MCP configuradas     (quando necessário)
+3. Bash com CLI tools               (último recurso)
+```
+
+## Ferramentas Nativas — Sempre Preferir
+
+| Operação | Ferramenta Correta | NÃO usar |
+|----------|--------------------|----------|
+| Ler arquivo | Read | Bash cat/head/tail |
+| Criar arquivo | Write | Bash echo/cat heredoc |
+| Editar arquivo | Edit | Bash sed/awk |
+| Buscar arquivo | Glob | Bash find/ls |
+| Buscar conteúdo | Grep | Bash grep/rg |
+| Perguntar usuário | AskUserQuestion | — |
+| Tarefa complexa | Task | — |
+
+## Gerenciamento MCP
+
+**@devops é o ÚNICO autorizado a:**
+- Adicionar servidores MCP
+- Remover servidores MCP
+- Configurar MCP (editar settings.json de MCP)
+- Fazer upgrade de versão de servidor MCP
+
+Outros agentes são **consumidores apenas**.
+
+## Regra de Ouro
+
+> "Se uma ferramenta nativa do Claude Code resolve, não use MCP."
+
+## Servidores MCP Disponíveis
+
+Ver configuração em `.claude/settings.json` (gerenciado por @devops).
+
+## Quando Usar Bash
+
+Use Bash apenas para:
+- Comandos git (quando necessário)
+- Executar scripts (npm, python, etc.)
+- Operações de sistema que não têm ferramenta nativa
+- Comandos CLI específicos (supabase, gh, etc.)
+
+Nunca para: leitura/escrita/busca de arquivos.

package/template/.claude/rules/story-lifecycle.md

@@ -0,0 +1,87 @@
+# Ciclo de Vida de Stories — GEN.IA OS
+
+## Estados
+
+```
+Draft → Ready → InProgress → InReview → Done
+                                      ↘ Blocked
+```
+
+## Responsabilidades por Estado
+
+| Estado | Responsável | O que acontece |
+|--------|-------------|----------------|
+| **Draft** | @sm | Cria story com template padrão |
+| **Ready** | @po | Valida com checklist 10 pontos |
+| **InProgress** | @dev | Implementa o código |
+| **InReview** | @qa + @reviewer | Testa e revisa código |
+| **Done** | @devops | Faz push/PR; @pm atualiza backlog |
+| **Blocked** | agente atual | Documenta blocker e escalona |
+
+## Checklist de Validação — @po (10 pontos obrigatórios)
+
+- [ ] Título claro e acionável (verbo + objeto)
+- [ ] Formato: "Como [persona] quero [ação] para [benefício]"
+- [ ] Acceptance criteria definidos (mínimo 3 critérios)
+- [ ] Tasks técnicas listadas (mínimo 2 tasks)
+- [ ] Dependências de outras stories mapeadas
+- [ ] Estimativa de esforço definida (P/M/G/XG)
+- [ ] Nome da branch definido: `tipo/STORY-NNN-slug`
+- [ ] Arquivos a criar/modificar listados
+- [ ] Testes necessários identificados
+- [ ] Riscos e pontos de atenção documentados
+
+**Story com menos de 8 pontos = REJEITADA pelo @po**
+
+## Localização das Stories
+
+```
+docs/stories/STORY-[NNN]-[slug].md
+```
+
+Exemplo: `docs/stories/STORY-001-autenticacao-usuario.md`
+
+## Atualização de Status na Story
+
+Sempre atualizar o cabeçalho quando mudar de estado:
+
+```markdown
+**Status:** InProgress
+**Agente:** @dev
+**Atualizado:** 2026-02-24
+```
+
+## Template de Story
+
+```markdown
+# STORY-NNN — Título da Story
+
+**Status:** Draft
+**Agente:** @sm
+**Criado:** YYYY-MM-DD
+**Estimativa:** M
+
+## Descrição
+Como [persona] quero [ação] para [benefício].
+
+## Acceptance Criteria
+- [ ] AC1: ...
+- [ ] AC2: ...
+- [ ] AC3: ...
+
+## Tasks Técnicas
+- [ ] Task 1: ...
+- [ ] Task 2: ...
+
+## Branch
+`feat/STORY-NNN-slug`
+
+## Arquivos Envolvidos
+- `src/...`
+
+## Dependências
+- STORY-XXX (se houver)
+
+## Riscos
+- ...
+```

package/template/.claude/rules/workflow-execution.md

@@ -0,0 +1,68 @@
+# Execução de Workflows — GEN.IA OS
+
+## Seleção de Workflow
+
+| Situação | Workflow |
+|----------|----------|
+| Projeto do zero | greenfield → spec-pipeline → SDC |
+| Evoluir sistema existente | brownfield → spec-pipeline → SDC |
+| Nova feature isolada | spec-pipeline → SDC |
+| Corrigir bug | debug-sistematico → SDC |
+| Sprint completa | planning → development → delivery |
+
+## Chains Principais
+
+**1. Spec Pipeline** (quando)
+```
+@analyst briefing → @pm PRD → @architect SPEC → @po aprovação
+```
+
+**2. Story Development Cycle (SDC)** (core do desenvolvimento)
+```
+@sm draft → @po valida → @dev implementa → @qa revisa → @reviewer code review → @devops push/PR
+```
+
+**3. QA Loop** (iterativo, máx 5x)
+```
+@qa revisa → @dev corrige → @qa re-revisa → (aprovado?) → @reviewer
+```
+
+**4. Delivery**
+```
+@pm decisão → @devops deploy → @pm valida → @pm comunica
+```
+
+## Princípio Task-First
+
+Antes de executar qualquer ação, identificar qual task em `.genia/development/tasks/` se aplica:
+- Criar PRD → usar `criar-prd.md`
+- Criar SPEC → usar `criar-spec.md`
+- Criar story → usar `criar-story.md`
+- Implementar → usar `dev-implement.md`
+- Revisar QA → usar `qa-review.md`
+- Debug → usar `debug-sistematico.md`
+- Code review → usar `code-review.md`
+
+## Estado de Workflow
+
+Ao iniciar workflow de múltiplas fases, criar registro em:
+`.genia/session/workflow-state.md`
+
+```markdown
+# Workflow State
+Workflow: spec-pipeline
+Fase atual: 2 — PRD
+Agente: @pm
+Projeto: [nome]
+Iniciado: YYYY-MM-DD
+Próximo: @architect (SPEC-TECNICO)
+```
+
+## Complexidade e Estimativas
+
+| Classe | Esforço | Uso |
+|--------|---------|-----|
+| P (Pequeno) | < 2h | Bug fix, texto, config |
+| M (Médio) | 2-8h | Feature simples, CRUD |
+| G (Grande) | 1-3 dias | Feature complexa, integração |
+| XG (Extra Grande) | > 3 dias | Epic, refatoração grande |

package/template/.claude/settings.json

@@ -0,0 +1,58 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(rm -rf .genia/CONSTITUTION.md)",
+      "Bash(rm -rf .genia/development/workflows/*)",
+      "Bash(rm -rf .genia/development/tasks/*)",
+      "Bash(rm -rf .claude/hooks/*)",
+      "Bash(rm -rf .claude/rules/*)"
+    ]
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c \"cd \\\"$(git rev-parse --show-toplevel)\\\" && node .claude/hooks/synapse-engine.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c \"cd \\\"$(git rev-parse --show-toplevel)\\\" && node .claude/hooks/precompact-session-digest.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c \"cd \\\"$(git rev-parse --show-toplevel)\\\" && python .claude/hooks/enforce-git-push-authority.py\""
+          },
+          {
+            "type": "command",
+            "command": "bash -c \"cd \\\"$(git rev-parse --show-toplevel)\\\" && python .claude/hooks/sql-governance.py\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c \"cd \\\"$(git rev-parse --show-toplevel)\\\" && python .claude/hooks/write-path-validation.py\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node --version)",
+      "Bash(npm --version)",
+      "Bash(git*)",
+      "Bash(pip --version)",
+      "Bash(python*)",
+      "Bash(gh*)",
+      "Bash(node \".claude/hooks/synapse-engine.cjs\")",
+      "Bash(node \".claude/hooks/precompact-session-digest.cjs\")"
+    ]
+  }
+}

package/template/.genia/CONSTITUTION.md

@@ -0,0 +1,129 @@
+# CONSTITUIÇÃO GEN.IA OS v1.0
+
+> Sistema de governança do GEN.IA OS — {{TEAM_NAME}}
+> Criadora: {{CREATOR_NAME}} | Versão: 1.0.0 | Ratificada: {{SETUP_DATE}}
+
+---
+
+## ARTIGO I — CLI First (NÃO-NEGOCIÁVEL)
+
+O Claude Code é a fonte de verdade. Toda ação passa pelos hooks de governança.
+
+**VIOLAÇÃO → BLOQUEIO automático.**
+
+Nenhuma ferramenta externa, painel ou interface bypassa o sistema de governança do GEN.IA OS. Toda modificação de código, configuração ou infraestrutura DEVE ser rastreável via CLI e registrada nos logs de auditoria. Ações realizadas fora do fluxo de hooks são consideradas não-autorizadas e podem comprometer a integridade do sistema.
+
+---
+
+## ARTIGO II — Autoridade do Agente (NÃO-NEGOCIÁVEL)
+
+Cada agente tem autoridade exclusiva em seu domínio. Agentes DEVEM delegar quando a ação estiver fora de seu escopo.
+
+- **@devops** é o ÚNICO que pode executar `git push`, criar Pull Requests e realizar releases
+- **@architect** tem veto técnico irrevogável sobre decisões de arquitetura e stack
+- **@sm** é o ÚNICO que cria e altera Stories formalmente
+- **@po** é o ÚNICO que valida e aprova Stories para desenvolvimento
+- **@pm** é o ÚNICO que aprova mudanças de escopo e PRD
+
+**VIOLAÇÃO → BLOQUEIO automático.**
+
+Nenhum agente deve agir fora de sua autoridade, mesmo que tecnicamente capaz. A separação de responsabilidades é a garantia de rastreabilidade e qualidade do sistema. Quando em dúvida, delegar é obrigatório.
+
+---
+
+## ARTIGO III — Story-Driven Development (OBRIGATÓRIO)
+
+Nenhuma linha de código pode ser escrita sem uma Story aprovada por @po. Toda Story deve ter:
+
+- Título claro e objetivo
+- Descrição no formato "Como [persona], quero [ação], para [benefício]"
+- Acceptance Criteria mensuráveis e verificáveis
+- Estimativa de esforço acordada
+- Épico pai identificado
+
+**VIOLAÇÃO → AVISO + documentar justificativa obrigatória.**
+
+A Story é o contrato entre negócio e técnica. Código sem Story é trabalho não rastreável, não validável e potencialmente fora de escopo. Em situações de emergência documentadas, @architect pode autorizar exceção com registro formal.
+
+---
+
+## ARTIGO IV — Sem Invenção (OBRIGATÓRIO)
+
+Agentes derivam especificações APENAS de requisitos explicitamente declarados em briefing, PRD ou SPEC-TECNICO.
+
+Funcionalidades não especificadas são **estritamente proibidas**.
+
+**VIOLAÇÃO → AVISO + justificativa obrigatória.**
+
+A criatividade técnica é bem-vinda na escolha de COMO implementar, nunca no QUE implementar. Se um requisito parece faltar, o agente DEVE questionar e solicitar clarificação ao @pm ou @po, nunca assumir ou inventar. Isso protege o produto de scope creep não intencional.
+
+---
+
+## ARTIGO V — Qualidade Primeiro (OBRIGATÓRIO)
+
+Lint, testes unitários e build bem-sucedido são pré-requisitos para qualquer entrega.
+
+**VIOLAÇÃO → BLOQUEIO de delivery.**
+
+Qualidade não é opcional nem negociável por prazo. Os quality gates existem para proteger a estabilidade do sistema em produção. Exceções documentadas devem ser aprovadas por @architect e @qa, com plano de remediação obrigatório.
+
+---
+
+## ARTIGO VI — Imports Absolutos (RECOMENDADO)
+
+Sempre utilizar `@/` como alias de importação raiz. Caminhos relativos com múltiplos `../` são proibidos.
+
+**VIOLAÇÃO → AVISO informacional.**
+
+Imports absolutos melhoram a legibilidade, facilitam refatorações e reduzem erros ao mover arquivos. Esta convenção deve ser configurada no `tsconfig.json` e aplicada em todo o projeto.
+
+---
+
+## Hierarquia de Autoridade
+
+```
+NÍVEL 3 — Decisão Final
+└── @architect — veto técnico irrevogável, guardiã da arquitetura
+
+NÍVEL 2 — Gestão e Validação
+├── @pm      — PRD, escopo, priorização, stakeholders, épicos
+├── @po      — validação de stories, backlog, acceptance criteria
+└── @analyst — requisitos, regras de negócio, briefing
+
+NÍVEL 1 — Execução
+├── @dev      — implementação de código (SEM permissão de push)
+├── @devops   — push, PR, release, configuração MCP/CI (ÚNICO com push)
+├── @qa       — design e execução de testes, veredictos de qualidade
+├── @reviewer — code review, padrões de código, aprovação formal
+└── @sm       — criação de stories, gestão de sprint, facilitação
+```
+
+---
+
+## Processo de Emenda à Constituição
+
+Para alterar qualquer artigo desta Constituição:
+
+1. **Proposta formal** — Qualquer agente pode propor via documento `EMENDA-XXX.md`
+2. **Justificativa obrigatória** — Motivação clara com impacto nos processos existentes
+3. **Aprovação dupla** — Requer concordância de @architect E @pm
+4. **Versionamento semântico:**
+   - **MAJOR** (ex: 1.0.0 → 2.0.0): mudança breaking em artigos NÃO-NEGOCIÁVEIS
+   - **MINOR** (ex: 1.0.0 → 1.1.0): adição de novo artigo ou expansão significativa
+   - **PATCH** (ex: 1.0.0 → 1.0.1): clarificação, correção de texto, sem mudança de regra
+5. **Propagação** — Atualizar tasks, templates e workflows afetados
+6. **Comunicação** — Notificar todos os agentes sobre a mudança
+
+---
+
+## Penalidades e Enforcement
+
+| Severidade | Violação | Consequência |
+|-----------|---------|-------------|
+| CRÍTICA | Artigo I ou II | Bloqueio automático da ação + log de auditoria |
+| ALTA | Artigo III, IV ou V | Aviso formal + documentação de justificativa |
+| MÉDIA | Artigo VI | Aviso informacional + correção na próxima iteração |
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}} — Ratificada em 2026-02-24*