@jaimevalasek/aioson 1.3.0

package/docs/pt/squad-genoma.md

@@ -0,0 +1,777 @@
+# Squad e Genoma
+
+> Guia prático para usar `@squad` e `@genoma` no AIOSON sem confundir time operacional, skill e camada cognitiva.
+
+---
+
+## Visão rápida
+
+`@squad` e `@genoma` resolvem problemas diferentes:
+
+- `@squad` cria uma **squad modular em pacote** sob `.aioson/squads/{squad-slug}/`
+- `@genoma` cria uma **base estruturada de conhecimento e lentes cognitivas** em `.aioson/genomas/{slug}.md`
+
+Em termos simples:
+
+- `skill` define **o que saber fazer**
+- `genoma` define **como pensar**
+- `@squad` organiza isso em **pacote versionável, executores leves, output, logs e media**
+- o `@orquestrador` gerado para cada squad consolida o trabalho em HTML
+
+---
+
+## Distinção central: skill, genoma, executor e subagente
+
+Essa separação precisa ficar estável no sistema:
+
+- `skill` é capacidade operacional reutilizável
+- `genoma` é lente cognitiva, repertório e forma de pensar
+- `agente executor` é um trabalhador permanente da squad
+- `subagente` é uma unidade temporária de investigação, comparação ou paralelismo
+- `agents.md` é o manifesto curto da squad, não é um executor
+
+### Skill
+
+Use skill para descrever algo como:
+
+- estruturar roteiro
+- revisar arquitetura
+- sintetizar briefing
+- analisar hook
+- extrair critérios de aceite
+
+Skill responde à pergunta:
+
+> "O que este sistema sabe fazer bem?"
+
+### Genoma
+
+Use genoma para descrever algo como:
+
+- mente de estrategista editorial
+- mente de copywriter de retenção
+- mente de advogado cético
+- mente de criador viral
+
+Genoma responde à pergunta:
+
+> "Com que lentes este sistema pensa, julga e escolhe?"
+
+### Agente executor
+
+É o papel operacional fixo do squad:
+
+- `@roteirista-viral`
+- `@copywriter-de-titulos`
+- `@analista-de-retencao`
+- `@orquestrador`
+
+### Subagente
+
+É temporário e não define a identidade principal da squad.
+
+Use para:
+
+- pesquisa ampla
+- comparação de alternativas
+- resumo de material grande
+- leitura paralela
+
+Não use subagente como substituto de:
+
+- skill
+- genoma
+- executor permanente
+
+---
+
+## O que é um squad
+
+Um squad é uma unidade operacional modular criada para um objetivo específico.
+
+O AIOSON suporta varias squads paralelas no mesmo projeto.
+
+Regra pratica:
+
+- se voce quer uma nova squad, o `@squad` deve criar uma nova squad
+- ele nao deve assumir upgrade de uma squad antiga so porque o dominio parece parecido
+- melhoria, refatoracao ou manutencao de squad existente so entram quando isso for pedido explicitamente
+
+Ela não é só uma pasta com agentes. Uma squad bem formada tem:
+
+- manifesto curto em `.aioson/squads/{squad-slug}/agents/agents.md`
+- manifesto estruturado em `.aioson/squads/{squad-slug}/squad.manifest.json`
+- `design-doc` local em `.aioson/squads/{squad-slug}/docs/design-doc.md`
+- `readiness` local em `.aioson/squads/{squad-slug}/docs/readiness.md`
+- executores permanentes em `.aioson/squads/{squad-slug}/agents/`
+- metadata em `.aioson/squads/{slug}/squad.md`
+- outputs em `output/{squad-slug}/`
+- logs em `aios-logs/{squad-slug}/`
+- mídia em `media/{squad-slug}/`
+
+Para squads de conteudo, o ideal nao e despejar tudo solto no `output/`.
+O modelo recomendado e:
+
+- `output/{squad-slug}/{content-key}/content.json`
+- `output/{squad-slug}/{content-key}/index.html`
+
+Assim o runtime e o dashboard podem tratar cada entrega como um conteudo real, e nao so como um arquivo solto.
+
+O importante aqui e: o AIOSON **nao fixa os campos internos** desse conteudo.
+Ele fixa apenas a casca:
+
+- `content_key`
+- `contentType`
+- `layoutType`
+- `payload_json`
+
+O resto nasce do dominio da squad.
+Uma squad de YouTube pode ter `roteiro` e `thumb-prompts`.
+Uma squad juridica pode ter `parecer`, `riscos` e `clausulas`.
+Uma squad de produto pode ter `prd`, `edge-cases` e `rollout`.
+
+Por isso a squad deve declarar `contentBlueprints` no manifesto JSON.
+Esse blueprint e o contrato dinamico do entregavel e precisa ser generico o suficiente para:
+
+- ser salvo no SQLite local
+- ser renderizado no dashboard
+- ser publicado no `aiosforge.com`
+- ser exportado/importado em outro projeto
+
+### Como escolher o `layoutType`
+
+Use uma heurística simples:
+
+- `document`: quando a entrega principal for longa e linear
+- `tabs`: quando houver várias saídas irmãs no mesmo pacote
+- `accordion`: quando houver alternativas, comparações, opções ou FAQs
+- `stack`: quando a leitura for uma sequência de blocos independentes
+- `mixed`: quando o pacote precisar combinar hero, seções e componentes diferentes
+
+### Como desenhar um `contentBlueprint`
+
+- derive `sections` do objetivo real da squad
+- use a linguagem do domínio do usuário quando ela fizer sentido
+- aproveite skills e docs locais que já apontem entregáveis recorrentes
+- aproveite tambem skills instaladas em `.aioson/squads/{squad-slug}/skills/`
+- prefira 1 blueprint principal forte antes de criar vários superficiais
+- escolha `blockTypes` pelo padrão de leitura esperado, não pelo efeito visual
+
+Antes de escrever essa estrutura, o `@squad` deve consolidar um mini pacote de:
+
+- discovery do problema
+- design doc do escopo atual
+- leitura de prontidao
+
+Quando esse pacote e materializado, ele passa a existir como parte da squad:
+
+- `.aioson/squads/{squad-slug}/docs/design-doc.md`
+- `.aioson/squads/{squad-slug}/docs/readiness.md`
+
+Esse passo existe para evitar squads montadas em cima de contexto vago demais.
+Na pratica, o `@squad` decide:
+
+- se o pedido parece `modo projeto` ou `modo feature`
+- quais skills e documentos realmente precisam entrar agora
+- o que pode ficar fora do contexto ativo por enquanto
+
+Exemplo:
+
+```text
+.aioson/squads/youtube-creator/agents/
+  agents.md
+  squad.manifest.json
+  roteirista-viral.md
+  estrategista-de-titulos.md
+  analista-de-retencao.md
+  copywriter-de-thumbnail.md
+  orquestrador.md
+```
+
+Esses agentes não são os agentes oficiais da aioson. Eles são executores do seu projeto.
+
+---
+
+## O que é um genoma
+
+Um genoma é um artefato de domínio e cognição. Ele descreve:
+
+- `O que saber`: conceitos, tensões, heurísticas e linguagem do domínio
+- `Mentes`: perspectivas cognitivas úteis para pensar naquele domínio
+- `Padrões de julgamento`: o que valorizar, evitar e tensionar
+- `Skills`: fragmentos curtos de capacidade reutilizável que podem nascer desse domínio
+
+Exemplo:
+
+```text
+.aioson/genomas/storytelling-retencao-youtube.md
+```
+
+Esse genoma não faz trabalho sozinho. Ele não substitui o agente. Ele não substitui skill. Ele enriquece a forma como os agentes executam suas skills.
+
+### Como pensar no genoma na prática
+
+O jeito mais útil de entender genoma é:
+
+- `skill` = ferramenta
+- `genoma` = mente
+
+Exemplo:
+
+- o agente `@roteirista-viral` pode ter a skill de `roteiro-short-form`
+- o genoma `storytelling-retencao-youtube` muda como esse agente pensa:
+  - que tipo de hook priorizar
+  - que tensão narrativa abrir
+  - que payoff prometer
+  - o que evitar por soar genérico
+
+Então, para o sistema:
+
+- skill sem genoma pode executar
+- genoma sem skill não executa
+- executor com skill + genoma tende a entregar melhor
+
+Quando uma skill vier do catálogo online ou de outro pacote, ela deve ser salva em:
+
+```text
+.aioson/squads/{squad-slug}/skills/{dominio}/{skill-slug}.md
+```
+
+Depois disso, essa skill passa a ser parte real do pacote local da squad e deve ser considerada pelos agentes sob demanda.
+
+---
+
+## Genoma não é clone literal de pessoa
+
+Se você quiser usar uma inspiração autoral, prefira este pensamento:
+
+- melhor: `genoma de estilo editorial`
+- melhor: `genoma de raciocínio`
+- melhor: `genoma de storytelling`
+- evitar como regra principal: `clone da pessoa X`
+
+O uso mais saudável é:
+
+- "genoma de copy de retenção"
+- "genoma de estratégia editorial para YouTube"
+- "genoma de narrativa emocional"
+
+Isso deixa o sistema:
+
+- mais reutilizável
+- mais consistente
+- menos confuso com persona, executor e skill
+
+---
+
+## Relação entre squad e genoma
+
+O modelo recomendado é:
+
+1. criar o squad
+2. criar ou importar genomas
+3. aplicar genomas ao squad inteiro ou a agentes específicos
+4. chamar os agentes normalmente
+
+Depois que o genoma é aplicado, o usuário não deveria precisar repetir isso em toda sessão.
+O vínculo precisa ficar salvo no metadata do squad e refletido no manifesto da squad.
+
+Exemplo:
+
+```text
+.aioson/squads/youtube-creator.md
+```
+
+```md
+Squad: YouTube Creator
+Mode: Squad
+Goal: Criar conteúdos virais com retenção forte
+Agents: .aioson/squads/youtube-creator/agents/
+Manifest: .aioson/squads/youtube-creator/squad.manifest.json
+Output: output/youtube-creator/
+Logs: aios-logs/youtube-creator/
+Media: media/youtube-creator/
+LatestSession: output/youtube-creator/latest.html
+
+Genomes:
+- .aioson/genomas/storytelling-retencao-youtube.md
+
+AgentGenomes:
+- roteirista-viral: .aioson/genomas/redacao-emocional-youtube.md
+- copywriter-thumbnail: .aioson/genomas/copy-ctr-youtube.md
+```
+
+---
+
+## Estrutura modular que o `@squad` deve gerar
+
+O contrato atual esperado de uma squad é este:
+
+```text
+.aioson/squads/{squad-slug}/
+  squad.manifest.json
+  squad.md
+  agents/
+    agents.md
+    orquestrador.md
+    {executor-1}.md
+    {executor-2}.md
+  skills/
+  templates/
+  docs/
+    design-doc.md
+    readiness.md
+    squad-rules.md
+    output-contracts.md
+
+output/{squad-slug}/
+aios-logs/{squad-slug}/
+media/{squad-slug}/
+```
+
+### `agents.md`
+
+É o manifesto curto da squad.
+
+Deve explicar:
+
+- missão
+- faz
+- não faz
+- executores permanentes
+- skills da squad
+- MCPs da squad
+- política de subagentes
+- saídas e revisão
+
+### `squad.manifest.json`
+
+É a versão estruturada da mesma squad, pensada para:
+
+- SQLite local
+- dashboard
+- export/import
+- sync com `aiosforge.com`
+
+O manifesto também deve declarar:
+
+- `mode: content | builder`
+- `storagePolicy`
+- `package`
+- `contentBlueprints`
+
+Ou seja:
+
+- `agents.md` é a leitura curta para humano/LLM
+- `squad.manifest.json` é o contrato para sistema
+
+Exemplo de `contentBlueprints` dentro do manifesto:
+
+```json
+{
+  "contentBlueprints": [
+    {
+      "slug": "entregavel-principal",
+      "contentType": "domain-package",
+      "layoutType": "tabs",
+      "description": "Contrato do entregável principal desta squad.",
+      "sections": [
+        {
+          "key": "visao-geral",
+          "label": "Visão geral",
+          "blockTypes": ["hero", "rich-text"]
+        },
+        {
+          "key": "itens-principais",
+          "label": "Itens principais",
+          "blockTypes": ["bullet-list", "tags", "accordion"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Perceba que:
+
+- `sections` nao sao uma lista fixa global do framework
+- cada squad escolhe `key`, `label` e `blockTypes` conforme o dominio
+- o dashboard so precisa saber renderizar os blocos declarativos, nao o dominio em si
+
+### Contrato minimo de `content.json`
+
+Quando o squad publicar um entregavel estruturado, o `content.json` precisa ter pelo menos:
+
+- `contentKey`
+- `title`
+- `contentType`
+- `layoutType`
+- `blocks`
+
+E o `layoutType` deve ser um destes:
+
+- `document`
+- `tabs`
+- `accordion`
+- `stack`
+- `mixed`
+
+Cada item de `blocks` precisa ser um objeto com `type`.
+Para alguns blocos, o contrato minimo tambem importa:
+
+- `tabs` precisa de `items`, e cada item precisa de `label` e `blocks`
+- `accordion` precisa de `items`, e cada item precisa de `title` e `content` ou `blocks`
+- `section` precisa de `blocks`
+
+Se o JSON estiver malformado:
+
+- o HTML ainda pode existir como arquivo
+- o artifact ainda pode ser registrado
+- mas o runtime nao indexa esse pacote como `content_item`
+
+Isso evita que dashboard e cloud passem a depender de payloads quebrados.
+
+---
+
+## Separação de responsabilidades
+
+O fluxo recomendado agora é mais direto:
+
+- `@squad` cria e mantém squads
+- `@genoma` cria e aplica genomas
+
+Na prática:
+
+- `@squad` não deve abrir perguntando entre Lite e Genoma
+- `@squad` entra direto nas perguntas para criação da squad
+- `@genoma` é chamado separadamente quando o usuário quiser enriquecer a squad
+
+---
+
+## Fluxo recomendado de uso
+
+### Cenário 1: criar um squad
+
+Exemplo:
+
+```text
+@squad
+Quero montar um squad para YouTube.
+
+Domínio: YouTube Creator focado em vídeos longos
+Objetivo: criar roteiros mais fortes e títulos com CTR alto
+Output: roteiros, títulos, ideias de thumbnail
+Restrições: público brasileiro, tom direto, sem clickbait vazio
+Papéis: pode escolher
+```
+
+Resultado esperado:
+
+- criação de manifesto em `.aioson/squads/youtube-creator/agents/agents.md`
+- criação de manifesto JSON em `.aioson/squads/youtube-creator/squad.manifest.json`
+- criação de executores em `.aioson/squads/youtube-creator/agents/`
+- criação de resumo em `.aioson/squads/youtube-creator/squad.md`
+- criação de `output/youtube-creator/`, `aios-logs/youtube-creator/` e `media/youtube-creator/`
+- geração de `output/youtube-creator/latest.html`
+
+### Cenário 2: criar um genoma depois
+
+```text
+@genoma
+Quero um genoma para storytelling com retenção alta em vídeos longos do YouTube Brasil.
+```
+
+Depois:
+
+```text
+Aplicar este genoma ao squad youtube-creator.
+Aplicar especialmente ao agente @roteirista-viral.
+```
+
+Resultado esperado:
+
+- genoma salvo em `.aioson/genomas/...`
+- vínculo salvo no metadata do squad
+- manifesto da squad refletindo o vínculo
+- agente `roteirista-viral.md` reescrito com `## Genomas ativos`
+
+### Cenário 3: usar o agente depois disso
+
+```text
+@roteirista-viral
+Crie um roteiro para um vídeo sobre como aprender inglês sem pagar curso.
+```
+
+O agente já deve operar com os genomas vinculados, sem o usuário repetir tudo.
+
+---
+
+## Arquivos gerados
+
+### Squad
+
+```text
+.aioson/squads/{squad-slug}/agents/
+output/{squad-slug}/
+.aioson/squads/{squad-slug}.md
+aios-logs/{squad-slug}/
+media/{squad-slug}/
+```
+
+### Genoma
+
+```text
+.aioson/genomas/{genoma-slug}.md
+```
+
+### Registro nos gateways
+
+Quando o squad é criado, o comportamento esperado é registrar os agentes dinâmicos nos gateways do projeto:
+
+- `CLAUDE.md` para uso via `/agente` no Claude Code
+- `AGENTS.md` para uso via `@agente` no Codex
+
+### Drafts, mídia e HTML final
+
+O fluxo recomendado é:
+
+1. cada agente especialista gera conteúdo intermediário em Markdown
+2. o `@orquestrador` do squad consolida esse material
+3. o `@orquestrador` publica o HTML final da sessão
+4. qualquer arquivo de mídia vai para `media/{squad-slug}/`
+
+Exemplo:
+
+```text
+output/youtube-creator/
+  2026-03-06-153000-roteiro-roteirista-viral.md
+  2026-03-06-153000-copy-copywriter-thumbnail.md
+  2026-03-06-153000-video-ingles.html
+  latest.html
+
+media/youtube-creator/
+  referencia-thumb-01.png
+  frame-estudo-02.jpg
+  audio-gancho-01.mp3
+```
+
+Regra prática:
+
+- texto, markdown, html, json e logs podem ser indexados e acompanhados no runtime
+- mídia deve ficar no filesystem do projeto em `media/`
+
+---
+
+## Regras importantes
+
+### 1. O orquestrador responsável pelo HTML é o do squad
+
+Não é o `@orchestrator` oficial da aioson.
+
+É o `@orquestrador` gerado dentro de `.aioson/squads/{squad-slug}/agents/`.
+
+### 2. Genoma não deve alterar agentes oficiais da aioson
+
+Não aplique genomas customizados do usuário em:
+
+```text
+.aioson/agents/
+```
+
+Os genomas devem ser aplicados aos agentes criados em:
+
+```text
+.aioson/squads/{squad-slug}/agents/
+```
+
+### 3. O usuário pode mandar contexto grande
+
+Tanto no `@squad` quanto no `@genoma`, o usuário pode enviar:
+
+- textos longos
+- PDFs ou arquivos
+- prints
+- imagens
+- anotações brutas
+- exemplos de referência
+
+### 4. Um genoma pode ser do squad inteiro ou de um agente
+
+Use no squad inteiro quando o contexto vale para todos.
+
+Use por agente quando o contexto for específico.
+
+### 5. HTML final não substitui o chat
+
+O agente ainda responde na sessão.
+
+O HTML é o entregável persistido e organizado para consulta e cópia.
+
+### 6. Estrutura de pastas deve ser leve
+
+Prefira:
+
+- `.aioson/squads/{squad-slug}/agents/`
+- `output/{squad-slug}/`
+- `aios-logs/{squad-slug}/`
+- `media/{squad-slug}/`
+
+Evite criar subpastas demais sem necessidade.
+
+---
+
+## Qualidade mínima das respostas
+
+Os agentes do squad não devem responder só com frases curtas e genéricas.
+
+O comportamento esperado é:
+
+- leitura do problema ou diagnóstico
+- recomendação principal
+- justificativa específica
+- tradeoff, risco ou tensão
+- próximo passo prático
+
+Se a tarefa pedir um artefato final:
+
+- o agente entrega primeiro o artefato
+- depois explica por que aquela solução faz sentido
+
+---
+
+## Direção visual do HTML
+
+O HTML final do squad deve seguir um dark theme mais confortável e premium.
+
+Direção recomendada:
+
+- dark sofisticado e técnico
+- contraste controlado
+- superfícies em camadas discretas
+- bordas suaves
+- no máximo 2 cores de acento
+
+Evite:
+
+- glow verde forte
+- neon exagerado
+- fundo preto puro com branco chapado
+- arco-íris de bordas por card
+- gradientes pesados que cansam a leitura
+
+---
+
+## Boas práticas
+
+- comece criando a squad antes de enriquecer com genomas
+- aplique genomas ao menor escopo possível
+- use `agents.md` como mapa curto da squad
+- use `squad.manifest.json` como contrato de runtime e sync
+- deixe o orquestrador do squad cuidar do HTML final
+- use drafts `.md` para manter rastreabilidade entre agentes e entregável final
+
+---
+
+## Genoma 3.0 e o Sistema Profiler
+
+### O que é o Genoma 3.0
+
+O Genoma 3.0 estende o formato 2.0 com suporte a profiling de personas baseado em evidência. Enquanto o Genoma 2.0 responde "como pensar sobre um assunto", o Genoma 3.0 responde "como uma pessoa específica pensa sobre um assunto".
+
+### Tipos de output
+
+| Output | O que é | Onde vive |
+|--------|---------|-----------|
+| Genoma 3.0 | Conhecimento destilado + perfil cognitivo | `.aioson/genomas/` |
+| Advisor Agent | Conselheiro ativo com a lente da persona | `.aioson/advisors/` |
+
+### O pipeline profiler
+
+O sistema profiler é composto por 3 agentes:
+
+1. `@profiler-researcher`
+   Pesquisa web e coleta material
+2. `@profiler-enricher`
+   Consolida evidências, material do usuário e análise cognitiva
+3. `@profiler-forge`
+   Gera Genoma 3.0, Advisor ou ambos
+
+O pipeline pode começar:
+
+- diretamente com `@profiler-researcher [nome da pessoa]`
+- via redirect do `@genoma` quando `type: persona` for detectado
+
+### Dimensões capturadas
+
+O profiler cobre múltiplas camadas:
+
+- `DISC`
+- `Eneagrama`
+- `Big Five`
+- `MBTI`
+- Schwartz Values inferidos
+- frameworks de decisão
+- estilo de comunicação
+- vieses cognitivos
+- padrões de erro
+- expertise demonstrada
+
+Perfis psicométricos devem ser tratados como `INFERIDOS`, nunca como avaliação formal.
+
+### Advisors
+
+Advisor não é genoma.
+
+- genoma é passivo e serve para enriquecer executores
+- advisor é ativo e serve para opinar, questionar, analisar e aconselhar
+
+O advisor pode ter:
+
+- web search
+- decision log
+- challenge mode
+- estilo de comunicação coerente com a persona
+
+### Board de Conselheiros
+
+Múltiplos advisors podem operar como board para analisar a mesma pergunta sob perspectivas diferentes. Isso é especialmente útil em decisões de alto impacto, estratégia, oferta e posicionamento.
+
+### Relação entre Genoma 3.0 e Advisor
+
+O uso mais forte costuma ser combinado:
+
+- o Genoma 3.0 entra nos agentes executores do squad
+- o Advisor revisa, desafia e aconselha sobre os outputs produzidos
+
+Exemplo:
+
+```text
+Squad: youtube-creator
+  Executores: @roteirista-viral (com Genoma 3.0 aplicado)
+  Advisory: @stefan-advisor (analisa os roteiros produzidos)
+```
+
+### Relatórios intermediários do profiler
+
+```text
+.aioson/profiler-reports/{person-slug}/
+  research-report.md
+  enriched-profile.md
+```
+
+Esses arquivos são a fonte de verdade para genomas e advisors gerados.
+
+---
+
+## O que ainda vem pela frente
+
+O modelo atual já suporta squads modulares, publish/import e genomas vinculados.
+
+Os próximos blocos naturais do framework são:
+
+- capability oficial de `Discovery / Design-Doc`
+- score formal de prontidão antes de implementação
+- uso mais claro de skills e arquivos sob demanda
+- herança disso pelo `@squad` na criação de novas squads
+
+Ou seja: a base de squad/genoma já existe, mas ainda vai ficar mais forte quando o fluxo completo de discovery/design estiver costurado no core.