create-genia-os 2.4.0 → 3.0.0

package/template/.claude/CLAUDE.md

@@ -1,162 +1,378 @@
-# GEN.IA OS — Master Instructions v2.0
+# CLAUDE.md - Synkra AIOX
 
-> GEN.IA SQUAD | Elidy Izidio (fundadora e chefe) | Idioma: Português do Brasil
-> Baseado no AIOX-CORE v5.0.5 (SynkraAI, MIT License) — adaptado para GEN.IA SQUAD
+Este arquivo configura o comportamento do Claude Code ao trabalhar neste repositório.
 
 ---
 
-## Regra de Comportamento Padrão
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Constitution
 
-**Sem agente ativo:** perguntar "Qual agente devo ativar? Use `/squad` para ver todos."
-**Com agente ativo:** anunciar `[@agente] Nome iniciando...` e ler MEMORY.md do agente.
-**NUNCA** responder como assistente genérico quando há trabalho de produto/código em curso.
+O AIOX possui uma **Constitution formal** com princípios inegociáveis e gates automáticos.
 
-O contexto é injetado automaticamente pelo Synapse Engine via hooks.
-Leitura manual de arquivos de contexto NÃO é necessária a cada prompt.
+**Documento completo:** `.aiox-core/constitution.md`
+
+**Princípios fundamentais:**
+
+| Artigo | Princípio | Severidade |
+|--------|-----------|------------|
+| I | CLI First | NON-NEGOTIABLE |
+| II | Agent Authority | NON-NEGOTIABLE |
+| III | Story-Driven Development | MUST |
+| IV | No Invention | MUST |
+| V | Quality First | MUST |
+| VI | Absolute Imports | SHOULD |
+
+**Gates automáticos bloqueiam violações.** Consulte a Constitution para detalhes completos.
 
 ---
 
-## Como invocar agentes
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Language Configuration
 
-```
-/analyst   → @analyst Cypher   — briefing, requisitos, pesquisa
-/pm        → @pm Morpheus      — PRD, épicos, PITCH.md
-/architect → @architect Trinity — arquitetura, SPEC, VETO técnico
-/dev       → @dev Neo          — implementação de código
-/devops    → @devops Tank      — push, PR, deploy, MCP, sessão
-/qa        → @qa Smith         — veredictos de qualidade
-/reviewer  → @reviewer Switch  — code review, aprovação de merge
-/po        → @po Oracle        — validação e aprovação de stories
-/sm        → @sm Mouse         — criação de stories, sprint
-/squad     → lista completa de agentes e comandos
+Language preference is handled by Claude Code's native `language` setting (v2.1.0+).
+Configure in `~/.claude/settings.json` (global) or `.claude/settings.json` (project):
+
+```json
+{ "language": "portuguese" }
 ```
 
-Também aceito: `@analyst`, `@pm`, `@architect`, `@dev`, `@devops`, `@qa`, `@reviewer`, `@po`, `@sm`
+The installer writes this automatically during `npx aiox-core install`. No language config in `core-config.yaml`.
 
 ---
 
-## Constituição (6 Artigos — invioláveis)
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Premissa Arquitetural: CLI First
 
-| Artigo | Severidade | Regra |
-|--------|-----------|-------|
-| I — CLI First | **BLOQUEIO** | Claude Code é fonte de verdade. CLI executa, UI observa. |
-| II — Autoridade | **BLOQUEIO** | @devops = único push/PR. @sm = único cria stories. @po = único aprova stories. @architect = VETO técnico. |
-| III — Story-Driven | **OBRIG** | Zero código sem story aprovada por @po. Sem exceção. |
-| IV — Sem Invenção | **OBRIG** | Apenas features dos requisitos explícitos. Nada além do escopo da story. |
-| V — Qualidade | **OBRIG** | Lint + testes + build devem passar antes de qualquer commit. |
-| VI — Imports | INFO | Sempre `@/` — nunca `../../../` |
+O Synkra AIOX segue uma hierarquia clara de prioridades que deve guiar **TODAS** as decisões:
 
----
+```
+CLI First → Observability Second → UI Third
+```
+
+| Camada | Prioridade | Descrição |
+|--------|------------|-----------|
+| **CLI** | Máxima | Onde a inteligência vive. Toda execução, decisões e automação. |
+| **Observability** | Secundária | Observar e monitorar o que acontece no CLI em tempo real. |
+| **UI** | Terciária | Gestão pontual e visualizações quando necessário. |
+
+### Princípios Derivados
 
-## Os 9 Agentes do SQUAD
+1. **A CLI é a fonte da verdade** - Dashboards apenas observam, nunca controlam
+2. **Funcionalidades novas devem funcionar 100% via CLI** antes de ter qualquer UI
+3. **A UI nunca deve ser requisito** para operação do sistema
+4. **Observabilidade serve para entender** o que o CLI está fazendo, não para controlá-lo
+5. **Ao decidir onde implementar algo**, sempre prefira CLI > Observability > UI
 
-| Slash | Agente | Nome | Autoridade Exclusiva |
-|-------|--------|------|---------------------|
-| `/analyst` | @analyst | Cypher | Briefing, requisitos |
-| `/pm` | @pm | Morpheus | PRD, PITCH.md, épicos |
-| `/architect` | @architect | Trinity | Arquitetura, SPEC, VETO |
-| `/dev` | @dev | Neo | Implementação (SEM push) |
-| `/devops` | @devops | Tank | **git push, PR, deploy, MCP** |
-| `/qa` | @qa | Smith | Veredictos de qualidade |
-| `/reviewer` | @reviewer | Switch | Code review, aprovação |
-| `/po` | @po | Oracle | **Aprovação de stories** |
-| `/sm` | @sm | Mouse | **Criação de stories** |
+> **Referência formal:** Constitution Artigo I - CLI First (NON-NEGOTIABLE)
 
-### Workflow do SQUAD
+---
+
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Estrutura do Projeto
 
 ```
-PLANNING                              DEVELOPMENT               QA / DELIVERY
-/analyst → /pm → /architect → /po → /sm → /dev → /qa → /reviewer → /devops
-[Briefing] [PRD]  [SPEC]      [Val] [Story] [Código] [Teste] [Review]  [Push/PR]
+aiox-core/
+├── .aiox-core/              # Core do framework
+│   ├── core/                # Módulos principais (orchestration, memory, etc.)
+│   ├── data/                # Knowledge base, entity registry
+│   ├── development/         # Agents, tasks, templates, checklists, scripts
+│   └── infrastructure/      # CI/CD templates, scripts
+├── bin/                     # CLI executables (aiox-init.js, aiox.js)
+├── docs/                    # Documentação
+│   └── stories/             # Development stories (active/, completed/)
+├── packages/                # Shared packages
+├── pro/                     # Pro submodule (proprietary)
+├── squads/                  # Squad expansions
+└── tests/                   # Testes
 ```
 
 ---
 
-## Protocolo de Ação Crítica — OBRIGATÓRIO
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Framework vs Project Boundary
 
-Antes de qualquer ação irreversível:
+O AIOX usa um modelo de 4 camadas (L1-L4) para separar artefatos do framework e do projeto. Deny rules em `.claude/settings.json` reforçam isso deterministicamente.
 
-```
-🔴 AÇÃO CRÍTICA — aguardando aprovação
+| Camada | Mutabilidade | Paths | Notas |
+|--------|-------------|-------|-------|
+| **L1** Framework Core | NEVER modify | `.aiox-core/core/`, `.aiox-core/constitution.md`, `bin/aiox.js`, `bin/aiox-init.js` | Protegido por deny rules |
+| **L2** Framework Templates | NEVER modify | `.aiox-core/development/tasks/`, `.aiox-core/development/templates/`, `.aiox-core/development/checklists/`, `.aiox-core/development/workflows/`, `.aiox-core/infrastructure/` | Extend-only |
+| **L3** Project Config | Mutable (exceptions) | `.aiox-core/data/`, `agents/*/MEMORY.md`, `core-config.yaml` | Allow rules permitem |
+| **L4** Project Runtime | ALWAYS modify | `docs/stories/`, `packages/`, `squads/`, `tests/` | Trabalho do projeto |
 
-O que vou fazer: [descrição]
-Por que é necessário: [justificativa]
-O que muda: [impacto]
-Como desfazer: [rollback]
+**Toggle:** `core-config.yaml` → `boundary.frameworkProtection: true/false` controla se deny rules são ativas (default: true para projetos, false para contribuidores do framework).
 
-Posso prosseguir?
-```
+> **Referência formal:** `.claude/settings.json` (deny/allow rules), `.claude/rules/agent-authority.md`
+
+---
+
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Sistema de Agentes
+
+### Ativação de Agentes
+Use `@agent-name` ou `/AIOX:agents:agent-name`:
+
+| Agente | Persona | Escopo Principal |
+|--------|---------|------------------|
+| `@dev` | Dex | Implementação de código |
+| `@qa` | Quinn | Testes e qualidade |
+| `@architect` | Aria | Arquitetura e design técnico |
+| `@pm` | Morgan | Product Management |
+| `@po` | Pax | Product Owner, stories/epics |
+| `@sm` | River | Scrum Master |
+| `@analyst` | Alex | Pesquisa e análise |
+| `@data-engineer` | Dara | Database design |
+| `@ux-design-expert` | Uma | UX/UI design |
+| `@devops` | Gage | CI/CD, git push (EXCLUSIVO) |
+
+### Comandos de Agentes
+Use prefixo `*` para comandos:
+- `*help` - Mostrar comandos disponíveis
+- `*create-story` - Criar story de desenvolvimento
+- `*task {name}` - Executar task específica
+- `*exit` - Sair do modo agente
+
+### Mapeamento Agente → Codebase
+
+| Agente | Diretórios Principais |
+|--------|----------------------|
+| `@dev` | `packages/`, `.aiox-core/core/`, `bin/` |
+| `@architect` | `docs/architecture/`, system design |
+| `@data-engineer` | `packages/db/`, migrations, schema |
+| `@qa` | `tests/`, `*.test.js`, quality gates |
+| `@po` | Stories, epics, requirements |
+| `@devops` | `.github/`, CI/CD, git operations |
+
+---
 
-**Ações que sempre exigem protocolo:**
-git push · deploy · release · deletar arquivo/pasta/banco · alterar config de produção · expor credencial · mudar stack
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Story-Driven Development
+
+1. **Trabalhe a partir de stories** - Todo desenvolvimento começa com uma story em `docs/stories/`
+2. **Atualize progresso** - Marque checkboxes conforme completa: `[ ]` → `[x]`
+3. **Rastreie mudanças** - Mantenha a seção File List na story
+4. **Siga critérios** - Implemente exatamente o que os acceptance criteria especificam
+
+### Workflow de Story
+```
+@po *create-story → @dev implementa → @qa testa → @devops push
+```
 
 ---
 
-## Push Protocol — OBRIGATÓRIO
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Padrões de Código
+
+### Convenções de Nomenclatura
 
-Sempre que houver necessidade de push:
-1. Perguntar: "Deseja invocar @devops (Tank) para fazer o push?"
-2. Se sim → `/devops` e executar protocolo de flag
-3. Se não → informar que o push deve ser feito manualmente
+| Tipo | Convenção | Exemplo |
+|------|-----------|---------|
+| Componentes | PascalCase | `WorkflowList` |
+| Hooks | prefixo `use` | `useWorkflowOperations` |
+| Arquivos | kebab-case | `workflow-list.tsx` |
+| Constantes | SCREAMING_SNAKE_CASE | `MAX_RETRIES` |
+| Interfaces | PascalCase + sufixo | `WorkflowListProps` |
 
+### Imports
+**Sempre use imports absolutos.** Nunca use imports relativos.
+```typescript
+// ✓ Correto
+import { useStore } from '@/stores/feature/store'
+
+// ✗ Errado
+import { useStore } from '../../../stores/feature/store'
 ```
-[@devops] Tank iniciando push...
-1. Write → .genia/session/devops-active (conteúdo: "authorized")
-2. git push [args]
-3. Hook enforce-git-push-authority.py consome o flag
-4. Reportar resultado
+
+**Ordem de imports:**
+1. React/core libraries
+2. External libraries
+3. UI components
+4. Utilities
+5. Stores
+6. Feature imports
+7. CSS imports
+
+### TypeScript
+- Sem `any` - Use tipos apropriados ou `unknown` com type guards
+- Sempre defina interface de props para componentes
+- Use `as const` para objetos/arrays constantes
+- Tipos de ref explícitos: `useRef<HTMLDivElement>(null)`
+
+### Error Handling
+```typescript
+try {
+  // Operation
+} catch (error) {
+  logger.error(`Failed to ${operation}`, { error })
+  throw new Error(`Failed to ${operation}: ${error instanceof Error ? error.message : 'Unknown'}`)
+}
 ```
 
 ---
 
-## Protocolo de Novo Projeto — OBRIGATÓRIO
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Testes & Quality Gates
 
+### Comandos de Teste
+```bash
+npm test                    # Rodar testes
+npm run test:coverage       # Testes com cobertura
+npm run lint                # ESLint
+npm run typecheck           # TypeScript
 ```
-1. /analyst  → BRIEFING.md (5 perguntas antes de qualquer arquivo)
-2. /pm       → PRD.md + PITCH.md
-3. /architect → SPEC-TECNICO.md + STATE.md inicial
-4. /po       → Validação
-5. /sm       → STORY-001.md
-6. /po       → Aprovação da story
-7. /dev      → Código (só aqui)
+
+### Quality Gates (Pre-Push)
+Antes de push, todos os checks devem passar:
+```bash
+npm run lint        # ESLint
+npm run typecheck   # TypeScript
+npm test            # Jest
 ```
 
-Estrutura obrigatória em `.Apps/[nome]/`:
+---
+
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Convenções Git
+
+### Commits
+Seguir Conventional Commits:
+- `feat:` - Nova funcionalidade
+- `fix:` - Correção de bug
+- `docs:` - Documentação
+- `test:` - Testes
+- `chore:` - Manutenção
+- `refactor:` - Refatoração
+
+**Referencie story ID:** `feat: implement feature [Story 2.1]`
+
+### Branches
+- `main` - Branch principal
+- `feat/*` - Features
+- `fix/*` - Correções
+- `docs/*` - Documentação
+
+### Push Authority
+**Apenas `@devops` pode fazer push para remote.**
+
+---
+
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## Otimização Claude Code
+
+### Uso de Ferramentas
+| Tarefa | Use | Não Use |
+|--------|-----|---------|
+| Buscar conteúdo | `Grep` tool | `grep`/`rg` no bash |
+| Ler arquivos | `Read` tool | `cat`/`head`/`tail` |
+| Editar arquivos | `Edit` tool | `sed`/`awk` |
+| Buscar arquivos | `Glob` tool | `find` |
+| Operações complexas | `Task` tool | Múltiplos comandos manuais |
+
+### Performance
+- Prefira chamadas de ferramentas em batch
+- Use execução paralela para operações independentes
+- Cache dados frequentemente acessados durante a sessão
+
+### Context Management (NOG-18 + TOK-4A)
+- Use `/compact` when context feels heavy or approaching limits
+- Context brackets (SYNAPSE) replaced by native compaction
+- Agent memory persists in `.aiox-core/development/agents/{id}/MEMORY.md`
+- Rules with `paths:` frontmatter only load when working on matching files
+- **Agent Handoff:** On agent switch (`@agent`), previous agent is compacted to ~379-token handoff artifact. See `.claude/rules/agent-handoff.md` for full protocol. Max 3 retained summaries, oldest discarded.
+
+### Gerenciamento de Sessão
+- Rastreie progresso da story durante a sessão
+- Atualize checkboxes imediatamente após completar tasks
+- Mantenha contexto da story atual sendo trabalhada
+- Salve estado importante antes de operações longas
+
+### Recuperação de Erros
+- Sempre forneça sugestões de recuperação para falhas
+- Inclua contexto do erro em mensagens ao usuário
+- Sugira procedimentos de rollback quando apropriado
+- Documente quaisquer correções manuais necessárias
+
+---
+
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Comandos Frequentes
+
+### Desenvolvimento
+```bash
+npm run dev                 # Iniciar desenvolvimento
+npm test                    # Rodar testes
+npm run lint                # Verificar estilo
+npm run typecheck           # Verificar tipos
+npm run build               # Build produção
 ```
-docs/ (BRIEFING, PRD, SPEC-TECNICO, PITCH, stories/)
-.planning/ (STATE.md)
-src/ · tests/ · README.md
+
+### AIOX
+```bash
+npx aiox-core install       # Instalar AIOX
+npx aiox-core doctor        # Diagnóstico do sistema
+npx aiox-core info          # Informações do sistema
 ```
 
-**Nunca `src/` antes do `BRIEFING.md`. Nunca código antes da `STORY-001` aprovada.**
+### Dashboard (apps/dashboard/)
+```bash
+cd apps/dashboard
+npm install
+npm run dev                 # Desenvolvimento
+npm run build               # Build produção
+```
 
 ---
 
-## Padrões de Código
+<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->
+## MCP Usage
 
-- **Commits:** `tipo(escopo): descrição` + `Co-Authored-By: GEN.IA OS <genia@bedata.com.br>`
-- **Imports:** sempre `@/` — nunca relativos
-- **Funções:** máximo 50 linhas
-- **TypeScript:** tipagem explícita em APIs públicas
-- **NUNCA** commitar `.env` ou credenciais
+Ver `.claude/rules/mcp-usage.md` para regras detalhadas.
+
+**Resumo:**
+- Preferir ferramentas nativas do Claude Code sobre MCP
+- MCP Docker Gateway apenas quando explicitamente necessário
+- `@devops` gerencia toda infraestrutura MCP
 
 ---
 
-## Protocolo de Encerramento de Sessão
+<!-- PROJECT-CUSTOMIZED: Token Optimization TOK-2 -->
+## Tool Selection Guidance
+
+Prefer native Claude Code tools over MCP for common operations. The tool-registry at `.aiox-core/data/tool-registry.yaml` defines the 3-Tier Tool Mesh:
+
+| Tier | When Loaded | Examples |
+|------|-------------|---------|
+| **1** (Always) | Session start | Read, Write, Edit, Bash, Grep, Glob, Task |
+| **2** (Deferred) | Agent activation | git, coderabbit, context7, supabase |
+| **3** (Deferred) | Via tool search | EXA, Playwright, Apify, Nogic, Code-Graph |
 
-Quando Elidy disser "pode fechar", "boa noite", "vou parar": invocar `/devops` (Tank) para executar encerramento.
+**Guidelines:**
+- Use Tier 1 native tools for file ops, search, and commands — avoid MCP equivalents
+- Tier 3 MCP tools are deferred via Tool Search — only loaded when explicitly needed
+- Limit tool search to maximum 2 searches per turn to avoid overhead
+- Essential MCP servers (nogic, code-graph) are never disabled
+- Non-essential servers (EXA, Apify, Playwright) load on-demand via tool search
+
+**Tool Examples (TOK-4B):** Concrete input examples improve tool selection accuracy by +18pp. See `.claude/rules/tool-examples.md` for examples of top-10 tools. Full registry: `.aiox-core/data/mcp-tool-examples.yaml`. ADR-5: examples for always-loaded tools only, search for deferred tools.
+
+**Runtime capabilities:** `.aiox/runtime-capabilities.json` (generated by capability-detection.js)
 
 ---
 
-## Ferramentas — Prioridade
+<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->
+## Debug
 
+### Habilitar Debug
+```bash
+export AIOX_DEBUG=true
 ```
-1. Read, Write, Edit, Grep, Glob (nativas — sempre preferir)
-2. MCP configurado (gerenciado por @devops)
-3. Bash (CLI tools, git, scripts — nunca para ler/escrever arquivos)
+
+### Logs
+```bash
+tail -f .aiox/logs/agent.log
 ```
 
 ---
 
-_GEN.IA OS v2.0 — GEN.IA SQUAD — Elidy Izidio_
-_Baseado em AIOX-CORE v5.0.5 (MIT License, SynkraAI)_
+*Synkra AIOX Claude Code Configuration v4.0*
+*CLI First | Observability Second | UI Third*