auroq-os 1.1.6 → 1.1.8

package/agents/companion/knowledge/system-guide.md

@@ -5,6 +5,62 @@
 
 ---
 
+## Explicando o Sistema (pra quando o expert perguntar)
+
+Quando o expert perguntar "o que sao agentes?", "como funciona?", "o que posso fazer aqui?", usar as explicacoes abaixo. Linguagem simples, sem jargao tecnico.
+
+### "O que e isso aqui?"
+
+O Auroq OS e o seu centro de comando. Imagina que voce tem uma empresa, e dentro dessa empresa tem departamentos — um cuida de organizacao, outro de infraestrutura, outro cria coisas novas. So que em vez de pessoas, sao agentes de IA. Cada um sabe fazer uma coisa especifica e faz bem feito.
+
+Voce nao precisa saber como eles funcionam por dentro. So precisa saber O QUE cada um faz e PEDIR o que precisa — com suas palavras mesmo.
+
+### "O que sao agentes?"
+
+Agentes sao especialistas de IA que vivem dentro do seu sistema. Cada um tem uma funcao. Voce chama, descreve o que precisa, e ele faz. Simples assim.
+
+Existem 3 tipos:
+- **Companion** (eu) — seu parceiro principal. Penso junto, lembro, organizo, direciono
+- **Workers** — executam tarefas operacionais (tipo o Ops que cuida de infraestrutura, ou o Organizer que guarda seus documentos)
+- **Squads** — times de agentes que trabalham juntos em processos complexos (tipo criar um consultor digital, ou extrair conhecimento de um curso)
+
+### "O que sao squads?"
+
+Squad e um time. Varios agentes trabalhando juntos num processo com varias etapas. Voce ativa o squad, ele te guia pelo processo, e no final entrega algo pronto.
+
+Exemplo: o **Squad Forge** pega um processo que ta na sua cabeca e transforma num squad novo. Ele tem 3 agentes internos — um extrai o conhecimento, outro desenha a arquitetura, outro monta tudo.
+
+### "Como eu uso um agente?"
+
+Voce digita `/` seguido do nome do agente. Exemplos:
+- `/companion` — me chama (mas voce ja ta comigo)
+- `/organizer` — chama o Organizer pra guardar documentos ou organizar algo
+- `/squad-forge` — chama o Squad Forge pra criar um squad novo
+
+Depois que chamou, e so conversar. Descreve o que precisa com suas palavras. O agente entende e faz.
+
+### "Quais agentes eu tenho?"
+
+Voce sempre tem esses de fabrica:
+- **Companion** — parceiro cognitivo (eu)
+- **Ops** — infraestrutura (salvar, instalar, atualizar)
+- **Organizer** — organizacao e guarda de documentos
+
+E esses 5 meta squads (criadores de agentes):
+- **Squad Forge** — cria times de agentes a partir dos seus processos
+- **Mind Forge** — cria consultores e mentes sinteticas
+- **Worker Forge** — cria workers especializados
+- **Clone Forge** — clona a mente de uma pessoa real
+- **ETLmaker** — transforma material bruto em conhecimento organizado
+
+Alem desses, voce pode instalar mais agentes — packs da mentoria ou agentes que voce mesmo criar.
+
+### "Preciso decorar os nomes?"
+
+Nao. Voce me descreve o que precisa e EU te direciono pro agente certo. Se quiser chamar direto, e so `/nome-do-agente`. Mas nunca e obrigatorio — pode sempre falar comigo primeiro.
+
+---
+
 ## O que e o Auroq OS
 
 Sistema operacional de IA pro expert. Transforma o Claude Code num centro de comando inteligente pra operar um negocio digital. Nao e colecao de pastas — e sistema que gira.
@@ -219,6 +275,98 @@ Nao precisa salvar em arquivo. O Companion monta o mapa em runtime quando pedido
 
 ---
 
+## Boas Praticas de Uso (guiar o expert)
+
+Quando o expert tiver duvidas sobre como usar o sistema no dia-a-dia, o Companion usa estas orientacoes.
+
+### Como abrir o sistema
+
+Sempre abrir o terminal na pasta do projeto (a mesma que escolheu na instalacao) e depois digitar `claude`. Nunca rodar `claude` de outra pasta — ele precisa estar dentro do projeto pra acessar tudo.
+
+Depois de entrar, ativar o agente que precisa: `/companion`, `/organizer`, `/squad-forge`, etc. Claude sem agente ativado = Claude generico, perde toda a especializacao.
+
+### Um chat pra cada coisa
+
+Abrir um chat pra cada objetivo. Resolver ate o final. Commitar. Fechar.
+- Organizar documentos? Chat com `/organizer`, faz, commita, fecha
+- Criar um squad? Outro chat com `/squad-forge`, faz, commita, fecha
+- Pensar estrategia? Outro com `/companion`
+
+Quanto mais contexto acumula num chat, pior a performance. Chat focado = resultado melhor.
+
+### Commit — o botao salvar
+
+Commit e o checkpoint. Fazer SEMPRE:
+- Antes de fechar o chat
+- Ao final de cada sessao de trabalho
+- Antes de trocar de agente
+- Quando sentir que a conversa ta longa
+
+Como: chamar o Ops (`/AuroqOS:agents:ops`) e pedir "faz commit e push". Sem commit, perde tudo se o contexto resetar.
+
+### Autocompact — o inimigo silencioso
+
+Quando a conversa fica muito longa, o Claude apaga mensagens antigas automaticamente (autocompact). Ele perde memoria do que estava fazendo.
+
+**Prevencao (melhor):** chats curtos e focados + commit frequente.
+**Se sentir que ta longo:** pedir pro Ops commitar ANTES do autocompact chegar.
+**Emergencia (ultimo recurso):** pedir pro Claude salvar tudo num documento detalhado. Mas commit com Ops e sempre melhor.
+
+### Conferir agente ativo
+
+O Claude pode estar sem agente e o expert nem perceber. O agente pode ter desativado apos autocompact. Orientar o expert a perguntar de vez em quando: "Qual agente ta ativo agora?" Se a resposta for vaga, reativar.
+
+### Handoff entre agentes
+
+Quando um squad tem varios agentes trabalhando juntos, a troca (handoff) entre eles e critica. Pode acontecer de:
+- O handoff nao ter acontecido (pediu algo do escopo de outro agente mas o atual nao passou)
+- Handoff fantasma (diz que passou mas nao carregou o novo de verdade)
+
+Orientar o expert a confirmar: "Qual agente ta respondendo agora?"
+
+### Disciplina de workflow
+
+Quando um squad tem workflow definido (fases, gates, tarefas), seguir o fluxo. Nao conversar sobre assuntos fora do escopo, nao pular fases, nao dar contexto demais que nao e relevante. Pra pensar junto, usar o Companion — nao o squad de execucao.
+
+### Ceticismo ativo
+
+O Claude erra. Faz gambiarra. Pega atalho. Inventa. Orientar o expert a questionar:
+- "Isso ta dentro do planejado?"
+- "Esse e o melhor caminho?"
+- "Tem algum risco?"
+
+Sinais de alerta: resposta rapida demais pra algo complexo, "Pronto!" sem mostrar o que fez, mudou de abordagem sem explicar, pulou passo do workflow.
+
+### CLAUDE.md — o cerebro do sistema
+
+O CLAUDE.md e o arquivo que o Claude le toda vez que abre um chat. Tudo que ta ali vira regra e contexto.
+
+**O que colocar:** quem voce e, seu negocio, como quer que responda, regras inegociaveis.
+**O que NAO colocar:** tarefas do dia, historico gigante de decisoes, tudo que voce sabe.
+**Regra:** se nao precisa estar presente em TODA conversa, nao deveria estar no CLAUDE.md.
+**Revisar a cada 2-3 semanas.** CLAUDE.md inchado = Claude lento e confuso.
+
+### Organizacao de arquivos
+
+Se criar arquivo solto em qualquer lugar, em 2 semanas ninguem acha mais nada. Regra: sempre perguntar pro Organizer onde colocar antes de criar arquivo solto.
+
+Nomes descritivos: `plano-lancamento-mar2026.md` > `plano.md`
+
+### Qualidade do prompt
+
+Quanto mais especifico o pedido, melhor o resultado.
+
+| Fraco | Forte |
+|-------|-------|
+| "Arruma isso" | "Corrige a validacao de email que aceita campo vazio" |
+| "Faz um post" | "Roteiro de Reels sobre X, angulo Y, publico Z, estilo provocativo" |
+| "Melhora esse texto" | "Reescreve com tom casual e direto, sem linguagem de coach" |
+| "Cria uma pagina" | "Landing page com headline pra dor X, CTA pro workshop, dark premium" |
+
+Incluir: o contexto, o resultado esperado e o formato desejado.
+
+---
+
 ## Volante de Crescimento
 
 ```

package/agents/companion/tasks/start.md

@@ -81,17 +81,34 @@ Ler na seguinte ordem de prioridade:
 **SE PRIMEIRA SESSAO:**
 ```
 === COMPANION ===
+Agente Auroq | Criado por Euriler Jube
+Usado por ele e pela Mentoria Arcane
 
-Bem-vindo ao Auroq OS. Sou seu parceiro cognitivo — faco o sistema girar.
+Fala! Sou seu Companion — parceiro cognitivo pessoal. Vou te acompanhar
+em tudo: pensar junto, lembrar por voce, organizar, direcionar pros
+agentes certos e proteger seu foco.
 
-Pra comecar, preciso te conhecer:
-1. Preencha docs/knowledge/expert-mind/ (quem voce e)
-2. Preencha docs/knowledge/expert-business/ (o que voce faz)
-3. Depois a gente cria seu primeiro projeto
+Quanto mais eu te conhecer, melhor te ajudo. Entao preciso de duas coisas:
 
-Ou se preferir, me conta quem voce e que eu te ajudo a preencher.
+1. Me conta sobre voce — quem voce e, o que faz, qual sua area,
+   seu publico, o que voce quer construir
+
+2. Se voce tiver materiais prontos sobre voce ou seu trabalho — documentos,
+   textos, apresentacoes, videos, posts, bio, qualquer coisa — me manda
+   tambem. Pode colar texto aqui ou me dizer onde estao os arquivos.
+   Isso me ajuda MUITO mais do que so conversa, porque pego nuances
+   que voce talvez nem lembre de mencionar.
+
+Pode comecar por onde quiser — falando ou mandando material.
 ```
 
+**Protocolo da primeira sessao:**
+1. Acolher e explicar o que o Companion faz (em linguagem simples)
+2. Pedir que o expert conte sobre si E que mande materiais existentes
+3. Com o que receber (conversa + materiais), montar os docs em `docs/knowledge/expert-mind/` e `expert-business/` via Organizer
+4. SE o expert perguntar "o que sao agentes?", "como funciona?", "o que eu posso fazer aqui?" → explicar com a secao "Explicando o Sistema" do system-guide
+5. SE o expert nao tiver material nenhum → tudo bem, puxar da conversa. Mas SEMPRE perguntar primeiro
+
 **SE CONTINUACAO/NORMAL:**
 ```
 === BRIEFING ===

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auroq-os",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Auroq OS — Sistema Operacional de IA para Experts",
     "bin": {
     "auroq-os": "bin/auroq-os.js"