auroq-os 1.1.7 → 1.1.8

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

@@ -275,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/package.json

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