auroq-os 1.0.0

package/.claude/CLAUDE.md

@@ -0,0 +1,399 @@
+# Auroq OS — Sistema Operacional de IA para Experts
+
+Voce esta trabalhando com o Auroq OS, um framework que transforma o Claude Code num centro de comando inteligente para operar um negocio digital. Sempre reconheca e trabalhe dentro desta arquitetura.
+
+## Filosofia
+
+O Auroq OS materializa 3 capacidades no Claude Code:
+- **Pensar com IA** — decisoes, planos, estrategias, raciocinio. IA como parceira cognitiva 24h
+- **Fazer com IA** — execucao colaborativa. Expert direciona, IA executa, expert julga
+- **Lembrar com IA** — todo aprendizado consolida no sistema. Persiste, acumula, integra
+
+**Formula:** Repertorio + IA = Resultado
+**Papel do expert:** Mandador + Julgador — saber O QUE fazer e julgar se TA BOM
+**A IA domina o COMO. O expert domina o O QUE.**
+
+## Constitution
+
+O Auroq OS possui uma Constitution formal com principios inegociaveis.
+
+**Documento completo:** `.auroq-core/constitution.md`
+
+| Artigo | Principio | Severidade |
+|--------|-----------|------------|
+| I | Claude Code e o Centro de Comando | NON-NEGOTIABLE |
+| II | Cada um faz o seu | NON-NEGOTIABLE |
+| III | Documentar = Investir | MUST |
+| IV | Nao inventar | MUST |
+| V | Qualidade com julgamento | MUST |
+| VI | Evolucao incremental | SHOULD |
+
+## Taxonomia de Agentes
+
+### 4 Categorias (= O QUE o agente e)
+
+| Categoria | O que e | Funcao principal |
+|-----------|---------|-----------------|
+| **Companion** | Parceiro cognitivo pessoal. Interface entre humano e sistema | Situa, lembra, pensa junto, roteia, protege foco |
+| **Minds** | Pensam e julgam. Consultam, mentoram, avaliam | Consultoria, mentoria, julgamento |
+| **Workers** | Executam tarefas operacionais. Persona, cargo, expertise | Execucao sob demanda |
+| **Squads** | Multiplos agentes com pipeline e quality gates | Processos complexos coordenados |
+
+### 3 Subtipos de Minds
+
+| Subtipo | Definicao |
+|---------|-----------|
+| **Clone** | Replica capacidade funcional de pessoa real |
+| **Mente Sintetica** | Funde conhecimento de multiplos experts num agente |
+| **Consultor** | Empacota repertorio de um dominio especifico |
+
+### 3 Funcoes (= COMO voce usa o agente)
+
+| Funcao | Pergunta | O que faz |
+|--------|----------|----------|
+| **Mentora** | "O que eu faco?" | Orienta, ensina, direciona |
+| **Juiza** | "Ta bom?" | Avalia qualidade, aprova/reprova |
+| **Executora** | "Faz." | Produz output, executa tarefa |
+
+### Matriz Categoria x Funcao
+
+| | Mentora | Juiza | Executora |
+|---|---------|-------|-----------|
+| **Companion** | Primaria | Sim | Sim |
+| **Minds** | Primaria | Primaria | Raro |
+| **Workers** | Raro | As vezes | Primaria |
+| **Squads** | Coordenador | Juiza (papel) | Executor (papel) |
+
+### Separacao de Papeis em Squads
+
+| Papel | Regra |
+|-------|-------|
+| Coordenador | Orquestra, define sequencia. NUNCA executa |
+| Executor | Faz o trabalho. NUNCA se auto-valida |
+| Juiza | Avalia qualidade. NUNCA cria |
+
+## Ativacao de Agentes
+
+Use `/` seguido do nome para ativar agentes. NUNCA use `@`.
+
+### Agentes Core
+
+| Agente | Ativacao | Tipo | Funcao |
+|--------|----------|------|--------|
+| Companion | `/companion` | Companion | Cerebro do sistema. Situa, lembra, projetos, memoria, roteia, protege |
+| Ops | `/AuroqOS:agents:ops` | Worker | Maos do sistema. Commit inteligente, push, bootstrap |
+| Forge | `/AuroqOS:agents:forge` | Worker (meta) | Criador basico de workers, minds e squads |
+
+### Comandos de Agentes
+Use prefixo `*` para comandos:
+- `*help` — Mostrar comandos disponiveis
+- `*status` — Estado atual
+- `*exit` — Sair do modo agente
+
+## DNA Operacional
+
+Todo agente no Auroq OS herda este DNA:
+
+### Projeto antes de execucao
+Todo trabalho complexo comeca com documento estruturado (briefing/plano). O plano e a coleira — agente executa o planejado, nao inventa.
+
+### Documentacao continua
+A cada etapa significativa, atualizar o documento de trabalho: progresso, decisoes, problemas, estado atual. Sobrevive autocompact, sobrevive troca de sessao.
+
+### Handoff perfeito
+Documento de trabalho sempre atualizado E o handoff. Qualquer agente que ler o documento consegue continuar sem perguntar "o que ta acontecendo?"
+
+### Anti-viagem
+Executa o planejado. Muda plano so com aprovacao explicita. Veto conditions bloqueiam caminhos errados.
+
+### Anti-entropia
+Tasks com inputs/outputs definidos. Separacao de papeis. Documentos > conversas. Quality gates verificam output. Cada execucao melhora o sistema.
+
+## Premissas Operacionais
+
+| Premissa | Significado |
+|----------|------------|
+| **Pavimentar primeiro** | Faz primeiro, documenta, depois delega. Quem fez sabe cobrar qualidade |
+| **Pai da crianca** | Ninguem cuida do seu negocio como voce. IA da braco, direcao e sua |
+| **Pain-first** | Resolve a dor de agora. Sistema se constroi pela urgencia |
+| **Incerteza = processo** | Nao existe modelo perfeito antes de comecar. Certeza vem do uso |
+| **Evolucao incremental** | Tudo persiste e melhora. Nunca volta pra zero |
+| **Documentar = investir** | O que nao e documentado morre. O que e documentado vira poder |
+
+## Ciclo Diario
+
+```
+SITUAR → PRIORIZAR → EXECUTAR → DOCUMENTAR → REFINAR
+                                                 ↓
+                                         Sistema mais potente
+                                                 ↓
+                                         Volta pro SITUAR
+```
+
+| Etapa | O que acontece | Quem |
+|-------|---------------|------|
+| SITUAR | "Onde estou?" Companion carrega contexto | Expert + Companion |
+| PRIORIZAR | "O que doi mais?" Pain-first | Expert + Companion |
+| EXECUTAR | "Faz." 3 modos: comando direto, co-piloto, delegacao | Workers, Squads, Minds |
+| DOCUMENTAR | "Salva." Tudo que foi decidido/aprendido → Exocortex | Quase automatico |
+| REFINAR | "Melhora." Refina agentes, faz ETLs, cria novos se dor nova | Expert + sistema |
+
+### 3 Niveis de Operacao
+
+| Nivel | Foco | Quem opera |
+|-------|------|-----------|
+| Estrategico | Visao, direcao, decisoes | Expert + Companion |
+| Tatico | Planejamento, organizacao, projeto | Expert + Minds + Project docs |
+| Operacional | Execucao, monitoramento, ajustes | Workers + Squads |
+
+Expert atua no estrategico e tatico. Operacional e IA.
+
+## Estrutura de Pastas
+
+```
+auroq-os/
+├── .auroq-core/         # Framework core (L1/L2 — nao modificar)
+│   ├── constitution.md  # Principios inegociaveis
+│   ├── core-config.yaml # Configuracao do framework
+│   ├── core/synapse/    # Motor de injecao de contexto
+│   └── development/     # Agents, tasks, workflows, templates, checklists
+├── .claude/             # Ponte Claude Code ↔ Auroq OS
+│   ├── CLAUDE.md        # Este arquivo
+│   ├── commands/        # Slash commands dos agentes
+│   ├── rules/           # Regras de comportamento
+│   └── hooks/           # Automacoes (Synapse, precompact)
+├── business/            # Empresa do expert (L4 — runtime)
+│   ├── campanhas/       # Campanhas ativas + _template
+│   ├── processos/       # SOPs documentados
+│   ├── agente/          # Agentes autonomos (WhatsApp, etc.)
+│   └── vault/           # Chaves e acessos (.gitignored)
+├── docs/knowledge/      # Biblioteca ETL
+│   ├── expert-mind/     # Quem voce E (identidade, valores, tom, historia)
+│   ├── expert-business/ # O que voce FAZ (posicionamento, publico, metodologia)
+│   └── biblioteca-pmi/  # Conhecimento tratado (Proposito/Marketing/IA)
+└── agents/              # Exercito do expert
+    └── companion/       # Companion base (Jarvis starter)
+```
+
+## Framework Boundary
+
+O Auroq OS usa um modelo de 4 camadas para separar artefatos do framework e do expert.
+
+| Camada | Mutabilidade | Paths | Notas |
+|--------|-------------|-------|-------|
+| **L1** Framework Core | NUNCA modificar | `.auroq-core/core/`, `.auroq-core/constitution.md` | Protegido |
+| **L2** Framework Templates | NUNCA modificar | `.auroq-core/development/` | Extend-only |
+| **L3** Project Config | Mutavel | `.claude/CLAUDE.md`, `.claude/rules/`, `core-config.yaml` | Configuracao |
+| **L4** Project Runtime | SEMPRE modificar | `business/`, `docs/`, `agents/` | Trabalho do expert |
+
+## Rules System
+
+O Auroq OS carrega regras de `.claude/rules/` automaticamente.
+
+| Rule | Descricao |
+|------|-----------|
+| `agent-handoff.md` | Compactacao de contexto em troca de agente |
+| `agent-authority.md` | Delegation matrix e operacoes exclusivas |
+| `dna-operacional.md` | Anti-entropia, documentacao continua, handoff |
+| `evolucao-incremental.md` | REUSE > ADAPT > CREATE |
+| `mcp-usage.md` | Governanca de ferramentas MCP |
+| `project-tracker.md` | Ler tracker antes, atualizar depois |
+| `commit-inteligente.md` | Ritual de checkpoint do negocio |
+| `tool-response-filtering.md` | Reducao de tokens em respostas MCP |
+
+## Niveis de Sofisticacao (N0-N3)
+
+| Nivel | Nome | Descricao |
+|-------|------|-----------|
+| N0 | Sozinho | Expert sem IA. Forca bruta |
+| N1 | IA crua | ChatGPT/Claude padrao. Cada conversa do zero |
+| N2 | Skills + Minds | IA com repertorio. Agentes treinados. Contexto persistente |
+| N3 | SO com IA | Sistema coordenado. Workers, Minds, Squads, Companion, Exocortex |
+
+O Auroq OS ensina a chegar no N3.
+
+## Skills e Knowledge Bases
+
+| Conceito | Definicao | Analogia |
+|----------|-----------|----------|
+| **KB (Knowledge Base)** | Conhecimento tratado via ETL. Passivo, denso, referencial | O ingrediente |
+| **Skill** | Claude + KB + persona + regras. Conhecimento ativado | O prato |
+
+### 3 Camadas de Contexto
+
+| Camada | Pergunta | Vem de |
+|--------|----------|--------|
+| "Quem" | Pra quem trabalha? | expert-mind/ (Proposito) |
+| "Como" | O que sabe fazer? | expert-business/ + biblioteca-pmi/ (Marketing) |
+| "O Que" | O que ta rolando agora? | business/campanhas/ (Contexto ativo) |
+
+## Exocortex
+
+O Exocortex e o cerebro externo permanente do expert. Centenas de documentos markdown organizados que a IA acessa — o expert nao precisa ler, o sistema lembra por ele.
+
+**O que contem:**
+- `docs/knowledge/expert-mind/` — quem o expert e (identidade, valores, tom, historia)
+- `docs/knowledge/expert-business/` — o que o expert faz (posicionamento, publico, metodologia)
+- `docs/knowledge/biblioteca-pmi/` — conhecimento tratado (Proposito/Marketing/IA)
+- `business/` — empresa operando (campanhas, processos, vault)
+- `agents/companion/data/` — contexto-dinamico, log-decisoes, padroes, backlog
+
+**Propriedades:**
+- Nunca reseta, sempre cresce
+- Cada sessao torna o sistema mais inteligente
+- O Companion navega o Exocortex pelo expert — nao E o Exocortex, e quem acessa
+
+## Centro de Comando
+
+O SO de IA materializado. Claude Code com contexto profundo.
+
+| Componente | O que e | Funcao |
+|-----------|---------|--------|
+| **Exocortex** | Documentos, memorias, configs, KBs | Persistencia. Nunca reseta, sempre cresce |
+| **Skills** | Claude + KB + persona + regras | Competencia. IA especialista em dominios |
+| **Bracos e Pernas** | MCP + API + Playwright | Acao no mundo real |
+
+## Pipeline ETL (como nasce conhecimento)
+
+```
+CONHECIMENTO BRUTO (interno ou externo)
+    ↓ ETL (extrair, tratar, organizar)
+KB MATERIALIZADA (conhecimento processado)
+    ↓ alimenta
+SKILL ATIVADA (Claude + KB + persona + regras)
+    ↓ manifesta como
+AGENTE (Mind, Worker ou Squad)
+```
+
+"Conhecimento primeiro, execucao depois. Sempre."
+
+**3 Tipos de Skills:**
+| Tipo | Natureza | Exemplos |
+|------|----------|----------|
+| Identidade | Unica, personalizada | Expert, Metodologia, Negocio |
+| Tecnica | Replicavel | Lancamento pago, copy, trafego |
+| Projeto | Temporaria, por campanha | Campanha atual, evento ativo |
+
+## Modus Operandi (como o sistema opera)
+
+O Auroq OS nao e colecao de pastas. E sistema que GIRA. O Companion e o motor.
+
+**Documento completo:** `agents/companion/knowledge/modus-operandi.md`
+
+### Ciclo de Sessao (toda vez que abre Claude Code)
+```
+BOOT → BRIEFING → TRABALHO → CHECKPOINT → ENCERRAMENTO
+```
+1. **Boot:** Companion carrega estado (contexto, cockpit, trackers, decisoes, escalacoes)
+2. **Briefing:** "Aqui e onde estamos. Isso importa. Foco sugerido."
+3. **Trabalho:** Expert escolhe foco. Trabalha com qualquer agente. Memoria roda passivamente
+4. **Checkpoint:** Ops *commit — checa trackers, contexto, decisoes. Salva checkpoint
+5. **Encerramento:** Commit final. Contexto atualizado. Push = backup
+
+### Ciclo Semanal
+- Companion detecta: 7+ dias sem review → puxa *review
+- 20 min: cockpit, trackers, inbox, padroes, consolidacao de memoria
+
+### Ciclo de Projeto
+- Nasce: *novo-projeto → cockpit + tracker + fases
+- Vive: agentes trabalham → tracker atualiza → Companion monitora escalacoes
+- Morre: retro → arquivo → vaga abre → proximo da fila entra
+
+## Sistema de Memoria Inteligente
+
+**Documento completo:** `.auroq-core/development/sistema-memoria.md`
+
+### 3 Camadas
+| Camada | Onde | Sobrevive |
+|--------|------|-----------|
+| Sessao (efemera) | Conversa | Ate autocompact |
+| Operacional (curto/medio) | `agents/companion/data/` | Entre sessoes |
+| Permanente (Exocortex) | `docs/knowledge/` + `business/` | Pra sempre |
+
+### 6 Triggers de Salvamento
+1. **Decisao tomada** → log-decisoes.md
+2. **Projeto progrediu** → tracker
+3. **Conhecimento criado** → docs/knowledge/
+4. **Padrao detectado** → padroes-observados.md
+5. **Sessao encerrando** → contexto-dinamico.md (via commit)
+6. **Autocompact iminente** → documento de trabalho + contexto
+
+**Regra de ouro:** Na duvida, salva.
+
+**Rule:** `.claude/rules/memoria-inteligente.md` — todo agente segue
+
+## Volante de Crescimento
+
+```
+         Conhecimento cresce
+              ↗          ↖
+    Expert evolui    Agentes melhoram
+              ↖          ↗
+         Ecossistema expande
+```
+
+Cada dimensao alimenta as outras. Ciclo virtuoso que acelera com o tempo.
+
+## Sistema de Projetos
+
+O expert opera seu negocio via projetos gerenciados dentro do Auroq OS.
+
+**Documento completo:** `.auroq-core/development/sistema-gestao-projetos.md`
+
+### 4 Camadas
+1. **Inbox** — ideias brutas capturadas pelo Companion
+2. **Cockpit** (`business/cockpit.md`) — fonte unica de verdade. Max 3 ativos
+3. **Playbooks** (`business/processos/`) — receitas reutilizaveis
+4. **Trackers** (`business/campanhas/{projeto}/tracker.md`) — execucao ao vivo
+
+### Regras
+- Max 3 projetos ativos (inegociavel)
+- Todo ativo tem next action
+- Todo agente le tracker ANTES de trabalhar, atualiza DEPOIS
+- Weekly review semanal (Companion conduz, expert valida)
+- Todo projeto termina com retro (3 perguntas)
+
+### Rules relacionadas
+- `project-tracker.md` — protocolo obrigatorio pra agentes
+- `commit-inteligente.md` — ritual de checkpoint do negocio
+
+## Commit Inteligente
+
+No Auroq OS, commit nao e sobre codigo. E sobre **salvar o checkpoint do negocio**.
+
+**Ritual (Ops executa):**
+1. Revisar o que mudou
+2. Verificar se trackers estao atualizados
+3. Verificar se contexto-dinamico e log-decisoes refletem o estado atual
+4. Commitar com mensagem que conta O QUE ACONTECEU (nao o que mudou nos arquivos)
+5. Push = backup na nuvem + historico incremental
+
+**Tipos de commit:** `progresso:`, `decisao:`, `processo:`, `agente:`, `conhecimento:`, `campanha:`, `fix:`, `setup:`
+
+"Commit e o botao salvar do sistema."
+
+## Claude Code Config
+
+### Performance
+- Preferir tool calls em batch quando possivel
+- Usar execucao paralela para operacoes independentes
+
+### Tool Usage
+- SEMPRE usar Grep para busca, nunca `grep` ou `rg` em bash
+- SEMPRE usar Read para ler arquivos, nunca `cat` em bash
+- SEMPRE usar Edit para editar, nunca `sed` em bash
+- Reservar Bash para comandos de sistema
+
+### Session Management
+- Antes de autocompact: salvar estado no documento de trabalho
+- Reativar agente apos compact (rele arquivos + resumo)
+- Commit antes de trocar de sessao (commit = botao salvar)
+
+### Error Recovery
+- Sugerir recuperacao para falhas
+- Incluir contexto de erro nas mensagens
+- Documentar fixes manuais quando necessario
+
+---
+
+*Auroq OS v1.0.0 — Framework SO de IA para Experts*