@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/4-agentes/profiler-researcher.md

@@ -0,0 +1,98 @@
+# @profiler-researcher — Coletar material bruto para perfil cognitivo
+
+> **Para quem é:** quem quer criar um genome de persona baseado em evidências reais, não em suposições.
+> **Tempo de leitura:** 3 min.
+> **O que você vai sair sabendo:**
+> - O que o researcher coleta e onde salva
+> - Como ele se encaixa no pipeline de 3 etapas
+
+---
+
+## Para que serve
+
+Criar um advisor que "pensa como Steve Jobs" a partir de impressões vagas produz um estereótipo, não um perfil. O `@profiler-researcher` resolve isso coletando **material público real** — entrevistas, transcrições, posts, livros, ensaios — de forma sistemática e categorizada, antes de qualquer análise.
+
+Esta é a **etapa 1 de 3** do pipeline Profiler:
+
+```
+@profiler-researcher → @profiler-enricher → @profiler-forge
+     coleta                  analisa              gera
+```
+
+O researcher **não analisa nem infere**. Ele organiza evidências.
+
+---
+
+## Quando invocar
+
+- Você quer criar um genome de persona baseado em pessoa pública real
+- O `@genome` te redirecionou aqui ao detectar `type: persona`
+- Você tem materiais brutos (entrevistas, transcrições) e quer organizá-los antes da análise
+
+---
+
+## Quando NÃO invocar
+
+- Você quer um genome de domínio ou função (não persona) — use `@genome` direto
+- Você quer um perfil rápido sem evidências — use `@genome --quick` com disclaimer de baixa fidelidade
+
+---
+
+## Diálogo típico
+
+```
+Você > @profiler-researcher David Ogilvy copywriter
+
+@profiler-researcher > Iniciando pesquisa cognitiva para David Ogilvy.
+                       Contexto: copywriter, publicidade, Ogilvy & Mather
+                       Domínio de interesse: princípios de persuasão e escrita
+
+@profiler-researcher > Pesquisando fontes...
+                       - Entrevistas: 7 encontradas (Agency, Advertising Age, BBC)
+                       - Livros: "Ogilvy on Advertising", "Confessions of an Advertising Man"
+                       - Discursos: 3 transcrições públicas
+                       - Princípios documentados: 14 extraídos
+
+@profiler-researcher > Relatório salvo em:
+                       .aioson/profiler-reports/david-ogilvy/research-report.md
+                       Próximo: @profiler-enricher david-ogilvy
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/profiler-reports/{slug}/
+└── research-report.md    ← material categorizado por fonte
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — idioma de interação
+
+---
+
+## Comandos CLI relacionados
+
+Ativação direta no cliente AI:
+```
+@profiler-researcher [nome completo + contexto]
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@genome` (redirect automático) ou pedido direto do usuário
+- **Vai para:** `@profiler-enricher` — análise cognitiva do material coletado
+
+---
+
+## Próximo passo
+
+- Próxima etapa: [profiler-enricher.md](./profiler-enricher.md)
+- Etapa final: [profiler-forge.md](./profiler-forge.md)
+- O que é genome: [glossario.md](../1-entender/glossario.md#genome)

package/docs/pt/4-agentes/qa.md

@@ -0,0 +1,124 @@
+# @qa — Teste, valide e feche a feature com segurança
+
+> **Para quem é:** quem quer garantir que o que foi implementado realmente atende ao que foi especificado.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Como `@qa` valida os critérios de aceitação
+> - O ciclo autônomo de correção QA→Dev
+
+---
+
+## Para que serve
+
+"Funciona" é uma afirmação subjetiva. "O endpoint POST /checkout retorna 201 com order_id quando dados válidos são enviados" é verificável.
+
+`@qa` lê os ACs definidos em `prd-{slug}.md` e `requirements-{slug}.md`, verifica se o código implementado os atende, escreve os testes que comprovam isso, e gera um relatório. Se algo falhar e a falha for pequena, ele pode iterar diretamente com `@dev` sem você precisar intervir.
+
+Seu lema interno: nenhum finding inventado para parecer rigoroso. Nenhum risco ignorado para evitar atrito.
+
+---
+
+## Quando invocar
+
+- Após `@dev` terminar a implementação.
+- Para revisar cobertura de testes em features antigas (junto com `@tester`).
+- Quando você quer saber se uma feature pode ir para produção com segurança.
+
+---
+
+## Quando NÃO invocar
+
+- A implementação ainda não está feita → `@qa` não tem o que testar.
+- Você precisa de engenharia de testes para um app grande sem testes → use `@tester`.
+- Você quer revisão adversarial de segurança → use `@pentester`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @qa
+
+@qa > Lendo prd-checkout-stripe.md, requirements-checkout-stripe.md e spec-checkout-stripe.md...
+      
+      ACs identificados (4):
+      AC-01: POST /checkout com dados válidos → 201 + order_id
+      AC-02: POST /checkout com cartão inválido → 422 + mensagem clara
+      AC-03: Order.status = 'paid' após confirmação Stripe
+      AC-04: Dados de pagamento não persistem em texto plano (PCI-lite)
+      
+      Verificando código...
+      
+      [roda testes]
+      
+      AC-01: PASS
+      AC-02: PASS
+      AC-03: FAIL — Order.status não é atualizado no webhook handler
+      AC-04: PASS
+      
+      Ciclo autônomo: enviando AC-03 para @dev (iteração 1/2)...
+      [@dev corrige webhook handler]
+      Re-rodando... AC-03: PASS
+      
+      4/4 ACs cobertos.
+      test-plan.md e qa-report-test-coverage.md gravados.
+      Dossier atualizado: QA PASS.
+      Próximo: @validator (se feature usa harness-contract) ou feature:close.
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/test-plan.md` | Plano de teste com ACs mapeados |
+| `.aioson/context/qa-report-test-coverage.md` | Resultado: cobertura, findings, verdict |
+| `.aioson/plans/{slug}/corrections-{date}.md` | Plano de correções quando há findings |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/prd-{slug}.md` — ACs que serão validados
+- `.aioson/context/requirements-{slug}.md` — regras de negócio e edge cases
+- `.aioson/context/spec-{slug}.md` — o que foi implementado
+- `.aioson/context/features/{slug}/dossier.md` — code map e agent trail
+- `.aioson/rules/` — regras com `agents: qa`
+
+---
+
+## Detalhes recentes
+
+**Ciclo autônomo QA→Dev (Mai 2026):** em falhas pequenas e localizadas, `@qa` itera com `@dev` automaticamente, com cap de 2 rodadas. Na terceira falha, para e pede sua intervenção. Isso evita loops infinitos sem perder a agilidade de correções óbvias.
+
+**Suporte a Sheldon phased plans:** quando a feature usa um plano por fases, `@qa` valida fase a fase, marcando `qa_approved` só quando todos os Criticals/Highs da fase estão resolvidos.
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Registrar finding no dossier
+aioson dossier:add-finding . --slug=checkout-stripe \
+  --agent=qa --section="Agent Trail" \
+  --content="QA concluído. Verdict: PASS. Cobertura: 87%."
+
+# Ver estado do dossier
+aioson dossier:show . --slug=checkout-stripe
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@dev`
+- **Vai para:** `@validator` (quando há harness-contract) ou encerramento da feature
+
+---
+
+## Próximo passo
+
+- [Ficha do @validator](./validator.md) — gate final técnico
+- [Ficha do @tester](./tester.md) — quando há gaps grandes de cobertura
+- [Ficha do @pentester](./pentester.md) — revisão adversarial de segurança

package/docs/pt/4-agentes/setup.md

@@ -0,0 +1,104 @@
+# @setup — Onboarding do projeto e geração de contexto
+
+> **Para quem é:** quem está iniciando AIOSON num projeto novo ou existente.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que o @setup faz e quando re-ativá-lo.
+> - Quais arquivos ele cria e por que eles importam.
+
+## Para que serve
+
+Todo projeto AIOSON começa aqui. O `@setup` é o agente responsável por entrevistar você e o codebase, calcular a classificação (MICRO/SMALL/MEDIUM), e escrever o `project.context.md` — o arquivo que todos os outros agentes lêem antes de agir.
+
+Sem o `project.context.md`, nenhum outro agente sabe o stack, o idioma de interação, nem o tamanho do projeto. Eles se recusam a agir ou agem com suposições erradas. Rodar `@setup` antes de tudo evita esse problema.
+
+Em projetos existentes, o `@setup` detecta o framework automaticamente (Laravel, Next.js, Rails, Django, Node.js, etc.) e pula perguntas desnecessárias.
+
+## Quando invocar
+
+- Primeira vez que você usa AIOSON num projeto.
+- Quando o `project.context.md` está desatualizado ou com campos inválidos (`auto`, `null`, valores em branco).
+- Quando muda o stack, o idioma de interação, ou a classificação esperada.
+- Quando `@neo` retorna `needs_setup` ou `needs_setup_repair`.
+
+## Quando NÃO invocar
+
+- Se o `project.context.md` já existe e está válido — `@neo` te confirma isso.
+- Se você quer simplesmente continuar uma feature — use `@deyvin`.
+- Se quer mudar só o design skill — edite `design_skill:` diretamente no `project.context.md`.
+
+## Diálogo típico
+
+```
+Você > @setup
+
+@setup > Detectei: Node.js + Express (package.json com express 4.x).
+         Confirma a stack?
+Você > Sim, mais SQLite via better-sqlite3.
+
+@setup > Tipo de projeto?
+         [web_app · api · site · script · dapp · desktop_app]
+Você > web_app
+
+@setup > Quantos tipos de usuário? (admin conta como um)
+Você > 2
+
+@setup > Integrações externas? (APIs de terceiros, gateways, etc.)
+Você > Stripe e S3 (2)
+
+@setup > Regras de negócio não-óbvias? (cálculos especiais, fluxos condicionais)
+Você > Não
+
+@setup > Score: 1 + 1 + 0 = 2 → SMALL.
+         Design system?
+         [clean-saas-ui · aurora-command-ui · cognitive-core-ui · (outros) · Pular]
+Você > clean-saas-ui
+
+@setup > Idioma de interação? [en · pt-BR · es · fr]
+Você > pt-BR
+
+@setup > project.context.md criado em .aioson/context/project.context.md.
+         Próximo agente recomendado: @product.
+```
+
+## Saídas em disco
+
+| Arquivo | O que contém |
+|---|---|
+| `.aioson/context/project.context.md` | Frontmatter YAML com todos os campos do contexto |
+
+O frontmatter inclui: `project_name`, `project_type`, `framework`, `framework_installed`, `classification`, `interaction_language`, `design_skill`, `test_runner`, `aioson_version`.
+
+## Como ele lê seu projeto
+
+1. Verifica se `.aioson/context/project.context.md` já existe (projeto retomado vs. primeira vez).
+2. Inspeciona arquivos do workspace: `package.json`, `composer.json`, `artisan`, `manage.py`, `config/routes.rb` etc.
+3. Detecta stack e confirma com você antes de registrar.
+4. Calcula a classificação a partir das 3 dimensões (ver [Decisões iniciais](../2-comecar/decisoes-iniciais.md)).
+
+## Comandos CLI relacionados
+
+```bash
+# Instalar AIOSON e rodar wizard (novo projeto)
+npx @jaimevalasek/aioson init meu-projeto
+
+# Instalar em projeto existente
+npx @jaimevalasek/aioson install
+
+# Re-configurar ferramentas AI
+npx @jaimevalasek/aioson install --reconfigure
+
+# Escanear codebase antes do setup
+npx @jaimevalasek/aioson scan:project . --folder=src
+```
+
+## Handoff típico
+
+- **Vem de:** primeira ativação ou `@neo` detectando contexto ausente/inválido.
+- **Vai para:** `@product` (para definir a primeira feature).
+
+## Próximo passo
+
+- Entender classificações → [Decisões iniciais](../2-comecar/decisoes-iniciais.md)
+- Visão geral do ciclo → [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)
+- Termos como "design skill" e "classification" → [Glossário](../1-entender/glossario.md)

package/docs/pt/4-agentes/sheldon.md

@@ -0,0 +1,95 @@
+# @sheldon — Análise técnica profunda e revisão de PRD
+
+> **Para quem é:** quem quer uma segunda opinião técnica de peso antes de começar a implementar.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Quando o @sheldon é necessário e o que ele entrega.
+> - Como ele se encaixa entre @product e @analyst.
+
+## Para que serve
+
+O `@product` escreveu o PRD. Parece completo. Mas há gaps que só aparecem quando alguém com mentalidade técnica lê criticamente: campos de negócio não especificados, fluxos de erro ausentes, premissas implícitas que vão virar bugs.
+
+O `@sheldon` faz essa revisão crítica antes que o `@analyst`, o `@architect` e o `@dev` comecem. Ele pode ser ativado múltiplas vezes sobre o mesmo PRD — cada rodada enriquece mais. É o guardião da qualidade do PRD, não o implementador.
+
+Recentemente (commit `5b1edd6`), foi dividido em módulos on-demand, incluindo detecção de MER (missing entity relationships) — ele agora identifica relacionamentos entre entidades que o PRD não declara explicitamente.
+
+## Quando invocar
+
+- PRD parece completo mas você suspeita de gaps.
+- Feature é complexa — regras de negócio não-óbvias, múltiplos fluxos.
+- Antes de passar para `@analyst` num projeto SMALL ou MEDIUM importante.
+- Quer que alguém "tente quebrar" a spec antes do dev.
+- Há briefing aprovado (`briefing_source`) e quer garantir que os gaps do briefing foram fechados.
+
+## Quando NÃO invocar
+
+- Feature simples MICRO — é overhead desnecessário (Artigo II da Constitution).
+- PRD ainda não existe — `@product` primeiro.
+- Implementação já foi feita — `@pentester` ou `@qa` são mais adequados agora.
+
+## Diálogo típico
+
+```
+Você > @sheldon
+
+@sheldon > Lendo .aioson/context/prd-checkout-stripe.md...
+           Lendo briefing source: .aioson/briefings/marketplace-v1/briefings.md...
+
+           Análise de qualidade do PRD:
+
+           GAPS ENCONTRADOS:
+           - AC-03 não especifica o que acontece se o pagamento falhar após 3 tentativas
+             (fluxo de retry? bloqueio temporário? sem menção)
+           - Entidade "OrderItem" referenciada mas não modelada no PRD
+           - Regra de cancelamento ausente (o briefing sinalizava isso como gap aberto)
+
+           RISCOS:
+           - Webhook handler sem idempotência — pode duplicar confirmações
+           - Email de confirmação: qual provider? Sem fallback documentado
+
+           RECOMENDAÇÃO:
+           - Enriquecer o PRD in-place (gaps são fecháveis sem replanejamento)
+           - Abrir plano de execução para o webhook (risco técnico real)
+
+           Posso enriquecer o PRD agora ou prefere revisar os gaps primeiro?
+```
+
+## Saídas em disco
+
+O `@sheldon` decide entre **enriquecer in-place** ou **criar plano faseado** dependendo do tamanho do gap. Resultado:
+
+| Arquivo | Quando | O que contém |
+|---|---|---|
+| `.aioson/context/prd.md` (ou `prd-{slug}.md`) | Enriquecimento in-place | PRD com gaps fechados |
+| `.aioson/context/sheldon-enrichment.md` | Sempre | Registro das rodadas (para re-entrada) |
+| `.aioson/plans/{slug}/phase-1.md`, `phase-2.md`, ... | Quando o escopo é grande demais para uma única implementação | Plano de execução faseada lido pelos agentes seguintes (`@analyst` em diante) |
+| `.aioson/plans/{slug}/harness-contract.json` | Junto do phased plan | Contrato binário de sucesso (consumido por `@validator`) |
+| `.aioson/plans/{slug}/progress.json` | Junto do phased plan | Status corrente das fases |
+
+**Re-entrante:** se `sheldon-enrichment.md` já existir, o `@sheldon` detecta e oferece nova rodada sem refazer do zero. Você pode invocá-lo 2, 3, N vezes — cada rodada fecha mais gaps.
+
+## Como ele lê seu projeto
+
+1. `.aioson/context/project.context.md` — stack e classificação.
+2. `.aioson/context/prd.md` ou `prd-{slug}.md` — o PRD alvo.
+3. `.aioson/context/features.md` — status das features (não revisa PRDs de features já implementadas).
+4. `.aioson/context/sheldon-enrichment.md` — histórico de enriquecimentos (re-entrada).
+5. `.aioson/briefings/{slug}/briefings.md` — se `briefing_source` está no PRD.
+6. `plans/*.md` e `prds/*.md` — fontes de pesquisa pré-produção do usuário.
+
+## Handoff típico
+
+- **Vem de:** `@product` (PRD gerado) — pode ser ativado N vezes antes de ir adiante.
+- **Vai para:** `@analyst` → `@architect` → `@dev`.
+
+## Detalhe: MER detection
+
+O @sheldon agora detecta automaticamente **relacionamentos de entidade ausentes** no PRD. Se o PRD menciona `Order` e `Customer` mas não modela a relação entre eles, ele sinaliza — o `@analyst` vai precisar modelar, melhor detectar aqui.
+
+## Próximo passo
+
+- Trilha canônica de feature completa onde o `@sheldon` é peça-chave → [Feature completa com @sheldon](../3-receitas/feature-completa-com-sheldon.md)
+- PRD ainda não existe → [@product](./product.md)
+- Estrutura de planos que o `@sheldon` cria → [SDD: planos e estrutura](../5-referencia/sdd-planos-e-estrutura.md)
+- Termos como "gap", "AC" e "PRD" → [Glossário](../1-entender/glossario.md)

package/docs/pt/4-agentes/site-forge.md

@@ -0,0 +1,104 @@
+# @site-forge — Clonar, reconstruir ou extrair design de qualquer URL
+
+> **Para quem é:** quem quer replicar a estrutura ou o visual de um site real, ou extrair um design skill a partir dele.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Os 5 modos de operação e quando usar cada um
+> - Como o sistema de brains melhora a fidelidade visual ao longo do tempo
+
+---
+
+## Para que serve
+
+Você viu um site que tem exatamente o layout que quer. Redescrever tudo para a IA é lento e impreciso. O `@site-forge` faz o caminho inverso: **lê o site real, extrai estrutura e visual, e constrói um projeto ou design skill** a partir do que encontrou.
+
+Além de clonar, ele aprende: cada projeto que usa o `@site-forge` pode registrar aprendizados em `.aioson/brains/site-forge/` — uma memória procedural que melhora a fidelidade de clones futuros.
+
+---
+
+## Quando invocar
+
+- Você quer replicar a estrutura de um site com o seu design system
+- Você quer uma cópia fiel de um site como ponto de partida
+- Você quer extrair apenas o design skill de um site (sem construir código)
+- Você quer misturar a estrutura de um site com um design skill num percentual específico
+
+---
+
+## Quando NÃO invocar
+
+- Você quer criar um design system do zero — use `@ux-ui` ou `@design-hybrid-forge`
+- O site que você quer clonar está atrás de login (o forge só acessa conteúdo público)
+
+---
+
+## Os 5 modos
+
+| Modo | O que você passa | O que recebe |
+|---|---|---|
+| **A — Transform** | URL + skill | Site com visual do skill aplicado à estrutura clonada |
+| **B — Clone fiel** | URL | Réplica fiel + design skill extraído do site |
+| **C — Conteúdo** | URL + skill | Conteúdo do site encaixado no layout do skill |
+| **D — Skill apenas** | URL | Só o design skill extraído — sem construir site |
+| **E — Blend** | URL + skill + ratio | Estrutura clonada com tokens misturados em proporção |
+
+---
+
+## Diálogo típico
+
+```
+Você > @site-forge https://linear.app usando clean-saas-ui
+
+@site-forge > Modo A — Transform detectado.
+              Lendo brains... 3 nodes relevantes carregados (animações, layout SaaS, hover).
+              Carregando site...
+
+              Estrutura extraída:
+              - Hero com headline centrada
+              - Features em 3 colunas
+              - Pricing em cards
+              - CTA final
+
+@site-forge > Aplicando clean-saas-ui à estrutura...
+              Construindo Next.js...
+              Projeto criado. Design skill salvo como referência.
+              Novo aprendizado registrado em .aioson/brains/site-forge/visual-patterns.brain.json
+```
+
+---
+
+## Saídas em disco
+
+```
+src/                              ← projeto Next.js (modos A, B, C, E)
+.aioson/installed-skills/{slug}/  ← design skill extraído (modos B, D)
+.aioson/brains/site-forge/        ← aprendizados registrados após cada clone
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/brains/_index.json` — índice da memória procedural (carregado na ativação)
+- `.aioson/rules/` — restrições do projeto
+- `.aioson/context/design-doc*.md` — contexto visual existente
+
+---
+
+## Handoff típico
+
+- **Vem de:** pedido direto do usuário
+- **Vai para:** `@dev` para implementar funcionalidades sobre a estrutura clonada, ou `@design-hybrid-forge` para refinar o design skill extraído
+
+---
+
+## Detalhes recentes
+
+O sistema de brains (2026): cada sessão de `@site-forge` pode registrar novos nodes de aprendizado visual. Nodes com qualidade `q >= 4` se tornam o approach padrão em clones futuros. Nodes com `v === "AVOID"` são bloqueados automaticamente.
+
+---
+
+## Próximo passo
+
+- Para combinar dois design skills: [design-hybrid-forge.md](./design-hybrid-forge.md)
+- Para implementar funcionalidades no clone: ficha `dev.md` (em construção)

package/docs/pt/4-agentes/squad.md

@@ -0,0 +1,127 @@
+# @squad — Criar e gerenciar squads de especialistas customizados
+
+> **Para quem é:** quem precisa de agentes especializados fora do time padrão do AIOSON.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que é um squad e quando ele vale o esforço
+> - Como criar, atualizar e publicar um squad
+
+---
+
+## Para que serve
+
+O time padrão do AIOSON cobre o ciclo completo de desenvolvimento de software — do `@product` ao `@qa`. Mas e quando o seu domínio é jurídico, de saúde, de marketing de conteúdo, ou qualquer área que foge do padrão?
+
+O `@squad` resolve esse problema criando **pacotes de executores especializados** com identidade, voz, e regras próprias. Um squad de "compliance jurídico" pode ter um `@regulator`, um `@attorney`, e um `@auditor` que falam o vocabulário certo, usam os frameworks certos, e entregam no formato certo para aquele domínio.
+
+Um squad é um **pacote real** enraizado em `.aioson/squads/{slug}/`. Não é uma pasta de prompts ad-hoc — o CLI, dashboard, validação e sincronização com o aioson.com esperam a estrutura canônica.
+
+---
+
+## Quando invocar
+
+- Você precisa de especialistas em um domínio que o time padrão não cobre (jurídico, saúde, marketing, finanças, etc.)
+- Você quer reutilizar um conjunto de agentes em múltiplos projetos
+- Você quer publicar um squad no aioson.com para outros times usarem
+- Você tem um squad criado anteriormente e quer atualizar sua definição com `refresh`
+
+---
+
+## Quando NÃO invocar
+
+- O time padrão resolve — `@squad` adiciona overhead de criação desnecessário para projetos MICRO ou SMALL comuns
+- Você quer apenas um agente extra pontual — use `@squad agent-create` standalone em vez de montar um squad inteiro
+- Você ainda não sabe o domínio — investigue primeiro com `@orache`
+
+---
+
+## Diálogo típico
+
+```
+Você > @squad
+
+@squad > Qual operação?
+         [1] Criar novo squad
+         [2] Refresh de squad existente
+         [3] Criar executor avulso
+Você > 1
+
+@squad > Domínio do squad?
+Você > compliance trabalhista brasileiro
+
+@squad > Investigando domínio com @orache...
+         Frameworks identificados: CLT, Súmulas TST, eSocial
+         Vocabulário-chave: empregador, CTPS, FGTS, aviso prévio
+         Anti-padrões: análise genérica sem citar artigo, omissão de jurisprudência
+
+@squad > Definindo executores:
+         - @regulator  (analisa conformidade CLT)
+         - @attorney   (interpreta cláusulas e redigir documentos)
+         - @auditor    (checa inconsistências e riscos)
+
+@squad > Squad gerado em:
+         .aioson/squads/compliance-trabalhista/
+         ├── squad.json
+         ├── executors/regulator.md
+         ├── executors/attorney.md
+         ├── executors/auditor.md
+         └── genome-binding.json
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/squads/{slug}/
+├── squad.json              ← manifesto do squad
+├── executors/*.md          ← um arquivo por executor
+├── genome-binding.json     ← vínculo com genome (se aplicável)
+└── assets/                 ← materiais de referência
+```
+
+---
+
+## Como ele lê seu projeto
+
+Antes de criar, o `@squad` lê:
+- `.aioson/rules/` — restrições gerais do projeto
+- `.aioson/rules/squad/` — overrides específicos de squads
+- `.aioson/context/project.context.md` — classificação e idioma
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Criar squad via CLI
+aioson squad:assemble <slug>
+
+# Atualizar squad existente (breadth-aware)
+aioson squad:refresh <slug>
+
+# Publicar no aioson.com
+aioson system:publish --type=squad --slug=<slug>
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** investigação com `@orache` (quando domínio é novo) ou diretamente do usuário
+- **Vai para:** os próprios executores do squad, que operam como agentes independentes
+
+---
+
+## Detalhes recentes
+
+- **domain breadth (Mai/2026):** executores que antes recusavam pedidos adjacentes ao seu escopo agora respondem com mais amplitude contextual
+- **squad refresh:** `@squad refresh <slug>` atualiza um squad existente com nova investigação sem recriar do zero
+
+---
+
+## Próximo passo
+
+- Antes de criar um squad: [orache.md](./orache.md) — investigação de domínio
+- Depois de criar: [genome.md](./genome.md) — para vincular DNA cognitivo aos executores
+- Glossário: [squad](../1-entender/glossario.md#squad)