@jaimevalasek/aioson 1.8.0 → 1.9.1

package/docs/pt/{agentes-customizados.md → _arquivo/agentes-customizados.md}

@@ -1,670 +1,678 @@
-# Agentes Customizados
-
-> Guia prático para criar, organizar e usar agentes personalizados no AIOSON com `squad:agent-create`.
-
----
-
-## Visão rápida
-
-O AIOSON tem dois níveis de agentes:
-
-- **Agentes oficiais** — vivem em `.aioson/agents/`. São gerenciados pelo framework e atualizados com `aioson update`. Você não edita esses.
-- **Agentes customizados** — criados por você para resolver problemas específicos do projeto ou da squad. Esses são seus.
-
-Agentes customizados podem morar em dois lugares:
-
-| Local | Quando usar | Versionado no git? |
-|-------|-------------|---------------------|
-| `.aioson/my-agents/` | Agentes de uso geral no projeto inteiro | Sim |
-| `.aioson/squads/{slug}/agents/` | Agentes focados no domínio de uma squad | Sim |
-
----
-
-## O comando
-
-```bash
-aioson squad:agent-create [path] --name=<nome> [opções]
-```
-
-### Opções principais
-
-| Opção | Valor | Padrão | O que faz |
-|-------|-------|--------|-----------|
-| `--name` | texto | obrigatório | Nome do agente (vira slug automático) |
-| `--scope` | `my-agents` ou `squad` | inferido | Onde salvar |
-| `--squad` | slug da squad | — | Qual squad (implica `--scope=squad`) |
-| `--type` | `agent`, `assistant`, `clone`, `worker` | `agent` | Tipo do executor |
-| `--tier` | `0`, `1`, `2`, `3` | — | Classificação de complexidade |
-| `--disc` | perfil DISC | — | Perfil comportamental |
-| `--mission` | texto | — | Missão do agente |
-| `--domain` | texto | — | Domínio de atuação |
-| `--specialist` | nome | — | Especialista humano que inspira o agente |
-| `--focus` | lista separada por vírgula | — | Áreas de foco |
-| `--with-infra` | flag | `false` | Gera stubs de task, template e checklist |
-| `--dry-run` | flag | `false` | Mostra o que seria gerado sem criar |
-
----
-
-## Tipos de agente
-
-Cada tipo gera um template diferente:
-
-### `agent` — o padrão
-
-Agente genérico com julgamento próprio. Recebe contexto, analisa e decide como agir.
-
-Melhor para: revisão de código, análise de dados, scoping de features, automação de processos.
-
-```bash
-aioson squad:agent-create --name="code-reviewer" --type=agent \
-  --mission="Revisar PRs focando em segurança, performance e legibilidade"
-```
-
-### `assistant` — especialista com voz própria
-
-Agente que responde como um especialista de domínio. Tem seção de Voice DNA completa com vocabulário, metáforas e estados emocionais.
-
-Melhor para: consultoria técnica, mentoria, brainstorming com perspectiva especializada.
-
-```bash
-aioson squad:agent-create --name="startup-advisor" --type=assistant \
-  --squad=advisory-board \
-  --mission="Aconselhar sobre estratégia de produto e go-to-market para SaaS" \
-  --domain="product strategy" \
-  --disc=dominant-influential
-```
-
-O template gerado inclui Voice DNA:
-
-```markdown
-## Voice DNA
-
-### Sentence starters
-- **Explaining:** "[...]", "[...]"
-- **Challenging:** "[...]", "[...]"
-- **Recommending:** "[...]", "[...]"
-
-### Vocabulary
-**Always use:** [8+ termos que o agente prefere]
-**Never use:** [5+ termos que o agente evita]
-
-### Metaphors
-[5+ metáforas do domínio]
-
-### Emotional states
-- **Teaching:** paciente, detalhado, com exemplos
-- **Reviewing:** direto, preciso, sem filler
-- **Brainstorming:** energético, expansivo, provocativo
-```
-
-### `clone` — reprodução de um especialista real
-
-Semelhante ao `assistant`, mas baseado em uma pessoa real cujo estilo e metodologia são conhecidos. Inclui Voice DNA + seção de Specialist.
-
-Melhor para: reproduzir a forma de pensar e escrever de um autor, consultor ou criador específico.
-
-```bash
-aioson squad:agent-create --name="gary-halbert" --type=clone \
-  --squad=copy-factory \
-  --specialist="Gary Halbert" \
-  --domain=copywriting \
-  --disc=dominant-driver \
-  --mission="Escrever sales pages usando a metodologia de direct-response do Gary Halbert" \
-  --with-infra
-```
-
-O template gerado inclui:
-
-```markdown
-## Specialist
-Based on: **Gary Halbert**
-[Adicionar material fonte: livros, artigos, talks, metodologias]
-
-## Voice DNA
-[Seção completa para mapear a voz do especialista]
-```
-
-> **Nota:** Clones devem ser enriquecidos com material real do especialista. Um clone sem pesquisa é apenas um agente genérico com nome bonito.
-
-### `worker` — execução determinística
-
-Agente sem criatividade. Recebe instrução e executa exatamente, sem interpretar ou improvisar.
-
-Melhor para: formatação de documentos, conversão de dados, execução de checklists, processos repetitivos.
-
-```bash
-aioson squad:agent-create --name="csv-formatter" --type=worker \
-  --squad=data-pipeline \
-  --mission="Converter relatórios CSV para o formato padronizado do dashboard"
-```
-
-O template de worker inclui:
-
-```markdown
-## Response standard
-Execute the task deterministically. No creative deviation. Follow the process exactly.
-```
-
----
-
-## Tiers: classificando a complexidade do agente
-
-O tier indica o nível de responsabilidade e autonomia do agente:
-
-| Tier | Nome | Quando usar |
-|------|------|-------------|
-| 0 | Foundation | Agente que roda antes de outros (diagnóstico, análise prévia) |
-| 1 | Master | Especialista principal com histórico comprovado |
-| 2 | Systematizer | Criou frameworks que outros usam |
-| 3 | Specialist | Foco em formato ou canal específico |
-
-```bash
-aioson squad:agent-create --name="retention-analyst" --type=agent \
-  --tier=0 --squad=youtube-creator \
-  --mission="Analisar métricas de retenção antes de qualquer decisão de roteiro"
-```
-
-O tier aparece no identity tag do agente:
-
-```markdown
-<!-- identity: squad:youtube-creator/retention-analyst | type: agent | tier: 0 -->
-```
-
----
-
-## Perfis DISC
-
-O DISC define como o agente se comporta em interação:
-
-| Perfil | Estilo |
-|--------|--------|
-| `dominant-driver` | Direto, decisivo, orientado a resultado |
-| `influential-expressive` | Expansivo, persuasivo, entusiasmado |
-| `steady-amiable` | Paciente, colaborativo, detalhista |
-| `compliant-analytical` | Preciso, metódico, baseado em dados |
-| `dominant-influential` | Líder carismático, rápido e envolvente |
-| `influential-steady` | Comunicador paciente, bom em onboarding |
-| `steady-compliant` | Revisor meticuloso, confiável |
-| `compliant-dominant` | Analista que decide rápido com base em fatos |
-
----
-
-## Infraestrutura operacional (`--with-infra`)
-
-Quando você usa `--with-infra` em agentes de squad, o comando gera 3 arquivos adicionais:
-
-```
-.aioson/squads/{squad-slug}/
-  tasks/{slug}-main-workflow.md      ← processo passo a passo
-  templates/{slug}-output-tmpl.md    ← formato do entregável
-  checklists/{slug}-quality-gate.md  ← critérios de aprovação
-```
-
-### Task (workflow)
-
-Define o processo determinístico do agente:
-
-```markdown
-# Task: seo-copywriter main workflow
-
-## Steps
-
-### Step 1: Understand context
-**Action:** Read inputs and identify constraints
-
-### Step 2: Execute
-**Action:** [The core work]
-
-### Step 3: Validate
-**Action:** Run against completion criteria
-
-## Veto conditions
-- [ ] [Condição que bloqueia] → STOP and report
-```
-
-### Template (output)
-
-Define o formato esperado do entregável:
-
-```markdown
-# Template: seo-copywriter output
-
-## {Title}
-**Date:** {date}
-
-### Summary
-{1-3 sentence executive summary}
-
-### Content
-{Main structured output}
-
-### Recommendations
-{Actionable next steps}
-```
-
-### Checklist (quality gate)
-
-Define os critérios de qualidade com veto:
-
-```markdown
-# Quality gate: @seo-copywriter
-
-## Blocking (all must pass)
-- [ ] Output follows the defined template structure
-- [ ] No invented facts
-- [ ] Completion criteria satisfied
-
-## Recommended (80%+ should pass)
-- [ ] Output is concise
-- [ ] Domain-specific vocabulary used correctly
-- [ ] Hand-off context is clear
-
-## Approval
-- 100% blocking + 80% recommended = **PASS**
-- Any blocking failure = **VETO**
-```
-
-> **Por que isso importa:** Um agente sem infraestrutura operacional é uma persona sem processo. Ele sabe quem é, mas não sabe como fazer nada de forma determinística. Se o executor consegue improvisar, vai improvisar — e cada execução será diferente.
-
----
-
-## Maturity scoring
-
-Após criar o agente, o comando calcula automaticamente o nível de maturidade:
-
-```
-Maturity: Level 2 — Functional (needs enrichment) (5.5/10)
-Add real output examples and domain-specific anti-patterns to reach Level 3.
-```
-
-### Níveis
-
-| Nível | Score | Significado |
-|-------|-------|-------------|
-| 1 | 0–3.9 | Persona only (scaffold) — precisa de tudo |
-| 2 | 4–6.9 | Funcional — precisa de exemplos e anti-patterns reais |
-| 3 | 7–8.9 | Operacional (determinístico) — pronto para uso |
-| 3+ | 9–10 | Production-ready — completo com infraestrutura |
-
-### O que aumenta o score
-
-| Dimensão | Peso | Como completar |
-|----------|------|----------------|
-| Identity (missão preenchida) | 1.0 | Escrever missão concreta, não placeholder |
-| Core principles | 1.0 | 5-10 princípios reais do domínio |
-| Operational framework | 1.0 | Metodologia passo a passo |
-| Voice DNA | 1.5 | Vocabulário, metáforas, sentence starters (assistant/clone) |
-| Output examples | 1.5 | 3+ exemplos reais de input → output |
-| Anti-patterns | 1.0 | Never do + always do com itens específicos |
-| Completion criteria | 0.5 | Critérios mensuráveis, não subjetivos |
-| Hand-off | 0.5 | Tabela de hand-off preenchida |
-| Infrastructure | 1.5 | Task + template + checklist via `--with-infra` |
-
----
-
-## Anatomia do agente gerado
-
-O template segue 6 níveis inspirados na estrutura AIOX:
-
-### Nível 1 — Identity
-
-Quem é o agente.
-
-```markdown
-## Mission
-Escrever sales pages usando a metodologia de direct-response do Gary Halbert
-
-## Quick context
-Squad: Copy Factory | Agent: @gary-halbert | Type: clone
-Domain: copywriting
-
-## Specialist
-Based on: **Gary Halbert**
-
-## Behavioral profile
-DISC: dominant-driver
-```
-
-### Nível 2 — Operational
-
-Como o agente trabalha.
-
-```markdown
-## Core principles
-[5-10 crenças fundamentais]
-
-## Focus
-- Sales pages de conversão
-- Headlines que capturam atenção
-- CTAs que geram urgência real
-
-## Operational framework
-1. **Understand** — Ler contexto, inputs e constraints
-2. **Analyze** — Identificar o que é necessário
-3. **Execute** — Produzir seguindo a metodologia
-4. **Validate** — Checar contra critérios de qualidade
-```
-
-### Nível 3 — Voice DNA (assistant/clone)
-
-Como o agente se comunica.
-
-```markdown
-## Voice DNA
-
-### Sentence starters
-- **Explaining:** "Look, here's the deal...", "The secret is..."
-- **Challenging:** "You think that works? Let me tell you why..."
-- **Recommending:** "Here's what I'd do if I were you..."
-
-### Vocabulary
-**Always use:** prospect, offer, headline, lead, hook, proof, close, guarantee
-**Never use:** synergy, leverage, paradigm, optimize, ecosystem
-
-### Metaphors
-- "Your headline is the ad for the ad"
-- "Copy is salesmanship in print"
-- "The envelope is the bouncer at the door"
-```
-
-### Nível 4 — Quality
-
-Como saber que o trabalho está bom.
-
-```markdown
-## Output examples
-
-### Example 1
-**Input:** Landing page para curso de inglês online, público 25-40, preço R$497
-**Output:** [Sales page completa com headline, lead, body, proof, CTA, guarantee]
-
-## Anti-patterns
-
-**Never do:**
-- Usar jargão corporativo em vez de linguagem de rua
-- Abrir com a feature em vez do benefício
-- Pular a prova social
-- Escrever CTA genérico como "Saiba mais"
-- Usar parágrafos longos no above-the-fold
-
-**Always do:**
-- Abrir com headline que gera curiosidade ou urgência
-- Incluir pelo menos 3 elementos de prova
-- Fechar com garantia antes do CTA
-- Usar frases curtas e diretas no lead
-- Testar o CTA como se fosse um headline separado
-```
-
-### Nível 5 — Integration
-
-Para onde o trabalho vai depois.
-
-```markdown
-## Output contract
-
-| Artifact | Location | Format |
-|----------|----------|--------|
-| Sales page | .aioson/squads/copy-factory/output/ | Markdown |
-| Headline variants | .aioson/squads/copy-factory/output/ | Markdown list |
-
-## Hand-off
-
-| Condition | Next agent | Context to pass |
-|-----------|------------|-----------------|
-| Sales page completa | @editor-chefe | Revisar tom e CTA |
-| Precisa de prova social | @pesquisador | Coletar depoimentos |
-```
-
-### Nível 0 — Infrastructure (com `--with-infra`)
-
-Referências para arquivos operacionais.
-
-```markdown
-## Dependencies
-
-```yaml
-skills: []
-tasks:
-  - .aioson/squads/copy-factory/tasks/gary-halbert-main-workflow.md
-templates:
-  - .aioson/squads/copy-factory/templates/gary-halbert-output-tmpl.md
-checklists:
-  - .aioson/squads/copy-factory/checklists/gary-halbert-quality-gate.md
-```
-```
-
----
-
-## Exemplos práticos completos
-
-### 1. Revisor de código para o projeto
-
-Cenário: você quer um agente que revise PRs em qualquer sessão do projeto.
-
-```bash
-aioson squad:agent-create \
-  --name="code-reviewer" \
-  --type=agent \
-  --mission="Revisar código focando em segurança OWASP, performance e legibilidade" \
-  --focus="segurança,performance,legibilidade,testes"
-```
-
-Resultado:
-
-```
-Agent created: .aioson/my-agents/code-reviewer.md
-Scope: my-agents (versioned, available globally)
-Slug: @code-reviewer
-```
-
-Depois, em qualquer sessão:
-
-```
-@code-reviewer
-Revise o PR #42 — mudanças no módulo de pagamento.
-```
-
-### 2. Squad de conteúdo com agentes especializados
-
-Cenário: squad de YouTube com roteirista, analista e copywriter.
-
-```bash
-# Primeiro, criar a squad (via @squad na sessão ou CLI)
-
-# Depois, criar agentes especializados
-aioson squad:agent-create \
-  --name="roteirista-viral" \
-  --type=clone \
-  --squad=youtube-creator \
-  --specialist="MrBeast" \
-  --domain="YouTube scripts" \
-  --disc=influential-expressive \
-  --mission="Criar roteiros de vídeo com hooks fortes e retenção alta" \
-  --with-infra
-
-aioson squad:agent-create \
-  --name="analista-retencao" \
-  --type=agent \
-  --tier=0 \
-  --squad=youtube-creator \
-  --domain="YouTube analytics" \
-  --disc=compliant-analytical \
-  --mission="Analisar métricas de retenção e recomendar ajustes no roteiro"
-
-aioson squad:agent-create \
-  --name="copywriter-thumbnail" \
-  --type=assistant \
-  --squad=youtube-creator \
-  --domain="thumbnail copywriting" \
-  --disc=dominant-driver \
-  --mission="Criar textos de thumbnail com CTR alto usando tensão visual e curiosidade"
-```
-
-Estrutura gerada:
-
-```
-.aioson/squads/youtube-creator/
-  agents/
-    roteirista-viral.md         ← clone com Voice DNA + infra
-    analista-retencao.md        ← agent tier 0 (roda primeiro)
-    copywriter-thumbnail.md     ← assistant com Voice DNA
-  tasks/
-    roteirista-viral-main-workflow.md
-  templates/
-    roteirista-viral-output-tmpl.md
-  checklists/
-    roteirista-viral-quality-gate.md
-```
-
-### 3. Agente consultor baseado em especialista
-
-Cenário: você quer um consultor de copy baseado no Gary Halbert.
-
-```bash
-aioson squad:agent-create \
-  --name="gary-halbert" \
-  --type=clone \
-  --squad=copy-factory \
-  --specialist="Gary Halbert" \
-  --domain=copywriting \
-  --disc=dominant-driver \
-  --mission="Escrever sales pages usando direct-response methodology" \
-  --with-infra
-```
-
-Depois de criar, enriqueça o agente:
-
-1. **Preencha a Voice DNA** com vocabulário real do Gary Halbert
-2. **Adicione output examples** com sales pages reais como referência
-3. **Complete os anti-patterns** com o que ele mesmo dizia para nunca fazer
-4. **Defina completion criteria** mensuráveis (ex: "headline gera curiosidade", "tem pelo menos 3 provas")
-
-### 4. Worker determinístico para pipeline de dados
-
-Cenário: agente que formata relatórios sem criatividade.
-
-```bash
-aioson squad:agent-create \
-  --name="report-formatter" \
-  --type=worker \
-  --squad=data-pipeline \
-  --mission="Converter dados brutos do CSV para o formato padronizado do relatório semanal" \
-  --with-infra
-```
-
-O worker não tem Voice DNA e inclui a regra:
-
-```markdown
-## Response standard
-Execute the task deterministically. No creative deviation. Follow the process exactly.
-```
-
-### 5. Board de advisors para decisões estratégicas
-
-Cenário: múltiplos consultores com perspectivas diferentes.
-
-```bash
-# Advisor de produto
-aioson squad:agent-create \
-  --name="product-advisor" \
-  --type=assistant \
-  --squad=advisory-board \
-  --domain="product strategy" \
-  --disc=dominant-influential \
-  --mission="Aconselhar sobre priorização de features e product-market fit"
-
-# Advisor técnico
-aioson squad:agent-create \
-  --name="tech-advisor" \
-  --type=assistant \
-  --squad=advisory-board \
-  --domain="software architecture" \
-  --disc=compliant-analytical \
-  --mission="Avaliar viabilidade técnica e riscos de arquitetura"
-
-# Advisor de growth
-aioson squad:agent-create \
-  --name="growth-advisor" \
-  --type=assistant \
-  --squad=advisory-board \
-  --domain="growth marketing" \
-  --disc=influential-expressive \
-  --mission="Identificar alavancas de crescimento e estratégias de go-to-market"
-```
-
-Depois, use na sessão:
-
-```
-@product-advisor @tech-advisor @growth-advisor
-Estamos considerando adicionar um plano gratuito. Analisem prós, contras e riscos.
-```
-
----
-
-## Receita para um agente Level 3
-
-Um agente scaffold (Level 1) precisa de enriquecimento para chegar a Level 3. Aqui está o checklist:
-
-1. **Missão concreta** — não genérica. "Revisar PRs focando em OWASP top 10" é melhor que "Revisar código".
-
-2. **Core principles reais** — 5-10 crenças que guiam toda decisão. Extraia de livros, artigos ou experiência do domínio.
-
-3. **Operational framework detalhado** — substitua os 4 passos genéricos por passos específicos do domínio. Um copywriter não trabalha igual a um code reviewer.
-
-4. **3+ output examples reais** — mostrando input → output concreto. Não exemplos genéricos — exemplos que alguém copiaria.
-
-5. **Anti-patterns específicos** — não "evitar erros". Anti-patterns como "nunca abrir com feature em vez de benefício" ou "nunca usar mock no teste de integração".
-
-6. **Completion criteria mensuráveis** — "headline gera curiosidade" não serve. "Headline contém pelo menos um gatilho emocional e tem menos de 10 palavras" serve.
-
-7. **Hand-off table preenchida** — para quem o trabalho vai quando termina, e com que contexto.
-
-8. **Voice DNA preenchida** (assistant/clone) — vocabulário real, não placeholder. 8+ termos que o agente usa, 5+ que evita, metáforas específicas.
-
----
-
-## Relação com o sistema existente
-
-### Agentes customizados vs agentes oficiais
-
-- Agentes oficiais (`@dev`, `@product`, `@analyst`, etc.) seguem o workflow do AIOSON
-- Agentes customizados não participam do workflow oficial — são chamados diretamente
-- Agentes de squad são coordenados pelo `@orquestrador` da própria squad
-
-### Agentes customizados vs skills
-
-- **Skill** = capacidade reutilizável (ex: "estruturar roteiro", "analisar hook")
-- **Agente** = executor com identidade, processo e julgamento (ex: "@roteirista-viral")
-- Use skill quando o conhecimento é genérico e compartilhável
-- Use agente quando precisa de identidade, voz e processo específico
-
-### Agentes customizados vs genomes
-
-- **Genome** = lente cognitiva passiva que enriquece agentes
-- **Agente** = executor ativo que produz trabalho
-- Genomes são aplicados em agentes — não substituem agentes
-- Use `@genome` para criar o genome, depois aplique ao agente
-
----
-
-## FAQ
-
-### O `aioson update` sobrescreve meus agentes?
-
-Não. Tanto `.aioson/my-agents/` quanto `.aioson/squads/{slug}/agents/` são protegidos pelo installer. O `update` só toca arquivos gerenciados pelo framework.
-
-### Agentes customizados funcionam no Codex?
-
-Sim. O comando registra o agente no `AGENTS.md`, então o Codex encontra via `@slug`. Claude Code encontra via `CLAUDE.md` onde é registrado como `/{slug}`.
-
-### Posso usar `--with-infra` em my-agents?
-
-Não — infraestrutura operacional (tasks, templates, checklists) só faz sentido dentro de uma squad que tem estrutura de pastas para isso.
-
-### Qual a diferença entre `--type=assistant` e `--type=clone`?
-
-Ambos têm Voice DNA. A diferença é que `clone` inclui a seção "Specialist" com referência ao especialista humano e a instrução explícita de "Write as the specialist would write". Use `clone` quando tiver material real do especialista; use `assistant` para especialistas de domínio sem referência a uma pessoa específica.
-
-### Preciso usar tier e DISC?
-
-Não são obrigatórios. Use tier quando tiver agentes que precisam rodar em ordem (tier 0 primeiro). Use DISC quando quiser que o agente tenha um estilo de interação definido — especialmente útil em assistants e clones.
+# [Arquivado] Agentes Customizados
+
+> **Esta doc foi substituída.**
+> Conteúdo migrado para a ficha do `@squad` em [`../4-agentes/squad.md`](../4-agentes/squad.md), que cobre `squad:agent-create`, domínio, Voice DNA e scoring.
+> Conteúdo abaixo preservado para referência histórica.
+
+---
+
+# Agentes Customizados
+
+> Guia prático para criar, organizar e usar agentes personalizados no AIOSON com `squad:agent-create`.
+
+---
+
+## Visão rápida
+
+O AIOSON tem dois níveis de agentes:
+
+- **Agentes oficiais** — vivem em `.aioson/agents/`. São gerenciados pelo framework e atualizados com `aioson update`. Você não edita esses.
+- **Agentes customizados** — criados por você para resolver problemas específicos do projeto ou da squad. Esses são seus.
+
+Agentes customizados podem morar em dois lugares:
+
+| Local | Quando usar | Versionado no git? |
+|-------|-------------|---------------------|
+| `.aioson/my-agents/` | Agentes de uso geral no projeto inteiro | Sim |
+| `.aioson/squads/{slug}/agents/` | Agentes focados no domínio de uma squad | Sim |
+
+---
+
+## O comando
+
+```bash
+aioson squad:agent-create [path] --name=<nome> [opções]
+```
+
+### Opções principais
+
+| Opção | Valor | Padrão | O que faz |
+|-------|-------|--------|-----------|
+| `--name` | texto | obrigatório | Nome do agente (vira slug automático) |
+| `--scope` | `my-agents` ou `squad` | inferido | Onde salvar |
+| `--squad` | slug da squad | — | Qual squad (implica `--scope=squad`) |
+| `--type` | `agent`, `assistant`, `clone`, `worker` | `agent` | Tipo do executor |
+| `--tier` | `0`, `1`, `2`, `3` | — | Classificação de complexidade |
+| `--disc` | perfil DISC | — | Perfil comportamental |
+| `--mission` | texto | — | Missão do agente |
+| `--domain` | texto | — | Domínio de atuação |
+| `--specialist` | nome | — | Especialista humano que inspira o agente |
+| `--focus` | lista separada por vírgula | — | Áreas de foco |
+| `--with-infra` | flag | `false` | Gera stubs de task, template e checklist |
+| `--dry-run` | flag | `false` | Mostra o que seria gerado sem criar |
+
+---
+
+## Tipos de agente
+
+Cada tipo gera um template diferente:
+
+### `agent` — o padrão
+
+Agente genérico com julgamento próprio. Recebe contexto, analisa e decide como agir.
+
+Melhor para: revisão de código, análise de dados, scoping de features, automação de processos.
+
+```bash
+aioson squad:agent-create --name="code-reviewer" --type=agent \
+  --mission="Revisar PRs focando em segurança, performance e legibilidade"
+```
+
+### `assistant` — especialista com voz própria
+
+Agente que responde como um especialista de domínio. Tem seção de Voice DNA completa com vocabulário, metáforas e estados emocionais.
+
+Melhor para: consultoria técnica, mentoria, brainstorming com perspectiva especializada.
+
+```bash
+aioson squad:agent-create --name="startup-advisor" --type=assistant \
+  --squad=advisory-board \
+  --mission="Aconselhar sobre estratégia de produto e go-to-market para SaaS" \
+  --domain="product strategy" \
+  --disc=dominant-influential
+```
+
+O template gerado inclui Voice DNA:
+
+```markdown
+## Voice DNA
+
+### Sentence starters
+- **Explaining:** "[...]", "[...]"
+- **Challenging:** "[...]", "[...]"
+- **Recommending:** "[...]", "[...]"
+
+### Vocabulary
+**Always use:** [8+ termos que o agente prefere]
+**Never use:** [5+ termos que o agente evita]
+
+### Metaphors
+[5+ metáforas do domínio]
+
+### Emotional states
+- **Teaching:** paciente, detalhado, com exemplos
+- **Reviewing:** direto, preciso, sem filler
+- **Brainstorming:** energético, expansivo, provocativo
+```
+
+### `clone` — reprodução de um especialista real
+
+Semelhante ao `assistant`, mas baseado em uma pessoa real cujo estilo e metodologia são conhecidos. Inclui Voice DNA + seção de Specialist.
+
+Melhor para: reproduzir a forma de pensar e escrever de um autor, consultor ou criador específico.
+
+```bash
+aioson squad:agent-create --name="gary-halbert" --type=clone \
+  --squad=copy-factory \
+  --specialist="Gary Halbert" \
+  --domain=copywriting \
+  --disc=dominant-driver \
+  --mission="Escrever sales pages usando a metodologia de direct-response do Gary Halbert" \
+  --with-infra
+```
+
+O template gerado inclui:
+
+```markdown
+## Specialist
+Based on: **Gary Halbert**
+[Adicionar material fonte: livros, artigos, talks, metodologias]
+
+## Voice DNA
+[Seção completa para mapear a voz do especialista]
+```
+
+> **Nota:** Clones devem ser enriquecidos com material real do especialista. Um clone sem pesquisa é apenas um agente genérico com nome bonito.
+
+### `worker` — execução determinística
+
+Agente sem criatividade. Recebe instrução e executa exatamente, sem interpretar ou improvisar.
+
+Melhor para: formatação de documentos, conversão de dados, execução de checklists, processos repetitivos.
+
+```bash
+aioson squad:agent-create --name="csv-formatter" --type=worker \
+  --squad=data-pipeline \
+  --mission="Converter relatórios CSV para o formato padronizado do dashboard"
+```
+
+O template de worker inclui:
+
+```markdown
+## Response standard
+Execute the task deterministically. No creative deviation. Follow the process exactly.
+```
+
+---
+
+## Tiers: classificando a complexidade do agente
+
+O tier indica o nível de responsabilidade e autonomia do agente:
+
+| Tier | Nome | Quando usar |
+|------|------|-------------|
+| 0 | Foundation | Agente que roda antes de outros (diagnóstico, análise prévia) |
+| 1 | Master | Especialista principal com histórico comprovado |
+| 2 | Systematizer | Criou frameworks que outros usam |
+| 3 | Specialist | Foco em formato ou canal específico |
+
+```bash
+aioson squad:agent-create --name="retention-analyst" --type=agent \
+  --tier=0 --squad=youtube-creator \
+  --mission="Analisar métricas de retenção antes de qualquer decisão de roteiro"
+```
+
+O tier aparece no identity tag do agente:
+
+```markdown
+<!-- identity: squad:youtube-creator/retention-analyst | type: agent | tier: 0 -->
+```
+
+---
+
+## Perfis DISC
+
+O DISC define como o agente se comporta em interação:
+
+| Perfil | Estilo |
+|--------|--------|
+| `dominant-driver` | Direto, decisivo, orientado a resultado |
+| `influential-expressive` | Expansivo, persuasivo, entusiasmado |
+| `steady-amiable` | Paciente, colaborativo, detalhista |
+| `compliant-analytical` | Preciso, metódico, baseado em dados |
+| `dominant-influential` | Líder carismático, rápido e envolvente |
+| `influential-steady` | Comunicador paciente, bom em onboarding |
+| `steady-compliant` | Revisor meticuloso, confiável |
+| `compliant-dominant` | Analista que decide rápido com base em fatos |
+
+---
+
+## Infraestrutura operacional (`--with-infra`)
+
+Quando você usa `--with-infra` em agentes de squad, o comando gera 3 arquivos adicionais:
+
+```
+.aioson/squads/{squad-slug}/
+  tasks/{slug}-main-workflow.md      ← processo passo a passo
+  templates/{slug}-output-tmpl.md    ← formato do entregável
+  checklists/{slug}-quality-gate.md  ← critérios de aprovação
+```
+
+### Task (workflow)
+
+Define o processo determinístico do agente:
+
+```markdown
+# Task: seo-copywriter main workflow
+
+## Steps
+
+### Step 1: Understand context
+**Action:** Read inputs and identify constraints
+
+### Step 2: Execute
+**Action:** [The core work]
+
+### Step 3: Validate
+**Action:** Run against completion criteria
+
+## Veto conditions
+- [ ] [Condição que bloqueia] → STOP and report
+```
+
+### Template (output)
+
+Define o formato esperado do entregável:
+
+```markdown
+# Template: seo-copywriter output
+
+## {Title}
+**Date:** {date}
+
+### Summary
+{1-3 sentence executive summary}
+
+### Content
+{Main structured output}
+
+### Recommendations
+{Actionable next steps}
+```
+
+### Checklist (quality gate)
+
+Define os critérios de qualidade com veto:
+
+```markdown
+# Quality gate: @seo-copywriter
+
+## Blocking (all must pass)
+- [ ] Output follows the defined template structure
+- [ ] No invented facts
+- [ ] Completion criteria satisfied
+
+## Recommended (80%+ should pass)
+- [ ] Output is concise
+- [ ] Domain-specific vocabulary used correctly
+- [ ] Hand-off context is clear
+
+## Approval
+- 100% blocking + 80% recommended = **PASS**
+- Any blocking failure = **VETO**
+```
+
+> **Por que isso importa:** Um agente sem infraestrutura operacional é uma persona sem processo. Ele sabe quem é, mas não sabe como fazer nada de forma determinística. Se o executor consegue improvisar, vai improvisar — e cada execução será diferente.
+
+---
+
+## Maturity scoring
+
+Após criar o agente, o comando calcula automaticamente o nível de maturidade:
+
+```
+Maturity: Level 2 — Functional (needs enrichment) (5.5/10)
+Add real output examples and domain-specific anti-patterns to reach Level 3.
+```
+
+### Níveis
+
+| Nível | Score | Significado |
+|-------|-------|-------------|
+| 1 | 0–3.9 | Persona only (scaffold) — precisa de tudo |
+| 2 | 4–6.9 | Funcional — precisa de exemplos e anti-patterns reais |
+| 3 | 7–8.9 | Operacional (determinístico) — pronto para uso |
+| 3+ | 9–10 | Production-ready — completo com infraestrutura |
+
+### O que aumenta o score
+
+| Dimensão | Peso | Como completar |
+|----------|------|----------------|
+| Identity (missão preenchida) | 1.0 | Escrever missão concreta, não placeholder |
+| Core principles | 1.0 | 5-10 princípios reais do domínio |
+| Operational framework | 1.0 | Metodologia passo a passo |
+| Voice DNA | 1.5 | Vocabulário, metáforas, sentence starters (assistant/clone) |
+| Output examples | 1.5 | 3+ exemplos reais de input → output |
+| Anti-patterns | 1.0 | Never do + always do com itens específicos |
+| Completion criteria | 0.5 | Critérios mensuráveis, não subjetivos |
+| Hand-off | 0.5 | Tabela de hand-off preenchida |
+| Infrastructure | 1.5 | Task + template + checklist via `--with-infra` |
+
+---
+
+## Anatomia do agente gerado
+
+O template segue 6 níveis inspirados na estrutura AIOX:
+
+### Nível 1 — Identity
+
+Quem é o agente.
+
+```markdown
+## Mission
+Escrever sales pages usando a metodologia de direct-response do Gary Halbert
+
+## Quick context
+Squad: Copy Factory | Agent: @gary-halbert | Type: clone
+Domain: copywriting
+
+## Specialist
+Based on: **Gary Halbert**
+
+## Behavioral profile
+DISC: dominant-driver
+```
+
+### Nível 2 — Operational
+
+Como o agente trabalha.
+
+```markdown
+## Core principles
+[5-10 crenças fundamentais]
+
+## Focus
+- Sales pages de conversão
+- Headlines que capturam atenção
+- CTAs que geram urgência real
+
+## Operational framework
+1. **Understand** — Ler contexto, inputs e constraints
+2. **Analyze** — Identificar o que é necessário
+3. **Execute** — Produzir seguindo a metodologia
+4. **Validate** — Checar contra critérios de qualidade
+```
+
+### Nível 3 — Voice DNA (assistant/clone)
+
+Como o agente se comunica.
+
+```markdown
+## Voice DNA
+
+### Sentence starters
+- **Explaining:** "Look, here's the deal...", "The secret is..."
+- **Challenging:** "You think that works? Let me tell you why..."
+- **Recommending:** "Here's what I'd do if I were you..."
+
+### Vocabulary
+**Always use:** prospect, offer, headline, lead, hook, proof, close, guarantee
+**Never use:** synergy, leverage, paradigm, optimize, ecosystem
+
+### Metaphors
+- "Your headline is the ad for the ad"
+- "Copy is salesmanship in print"
+- "The envelope is the bouncer at the door"
+```
+
+### Nível 4 — Quality
+
+Como saber que o trabalho está bom.
+
+```markdown
+## Output examples
+
+### Example 1
+**Input:** Landing page para curso de inglês online, público 25-40, preço R$497
+**Output:** [Sales page completa com headline, lead, body, proof, CTA, guarantee]
+
+## Anti-patterns
+
+**Never do:**
+- Usar jargão corporativo em vez de linguagem de rua
+- Abrir com a feature em vez do benefício
+- Pular a prova social
+- Escrever CTA genérico como "Saiba mais"
+- Usar parágrafos longos no above-the-fold
+
+**Always do:**
+- Abrir com headline que gera curiosidade ou urgência
+- Incluir pelo menos 3 elementos de prova
+- Fechar com garantia antes do CTA
+- Usar frases curtas e diretas no lead
+- Testar o CTA como se fosse um headline separado
+```
+
+### Nível 5 — Integration
+
+Para onde o trabalho vai depois.
+
+```markdown
+## Output contract
+
+| Artifact | Location | Format |
+|----------|----------|--------|
+| Sales page | .aioson/squads/copy-factory/output/ | Markdown |
+| Headline variants | .aioson/squads/copy-factory/output/ | Markdown list |
+
+## Hand-off
+
+| Condition | Next agent | Context to pass |
+|-----------|------------|-----------------|
+| Sales page completa | @editor-chefe | Revisar tom e CTA |
+| Precisa de prova social | @pesquisador | Coletar depoimentos |
+```
+
+### Nível 0 — Infrastructure (com `--with-infra`)
+
+Referências para arquivos operacionais.
+
+```markdown
+## Dependencies
+
+```yaml
+skills: []
+tasks:
+  - .aioson/squads/copy-factory/tasks/gary-halbert-main-workflow.md
+templates:
+  - .aioson/squads/copy-factory/templates/gary-halbert-output-tmpl.md
+checklists:
+  - .aioson/squads/copy-factory/checklists/gary-halbert-quality-gate.md
+```
+```
+
+---
+
+## Exemplos práticos completos
+
+### 1. Revisor de código para o projeto
+
+Cenário: você quer um agente que revise PRs em qualquer sessão do projeto.
+
+```bash
+aioson squad:agent-create \
+  --name="code-reviewer" \
+  --type=agent \
+  --mission="Revisar código focando em segurança OWASP, performance e legibilidade" \
+  --focus="segurança,performance,legibilidade,testes"
+```
+
+Resultado:
+
+```
+Agent created: .aioson/my-agents/code-reviewer.md
+Scope: my-agents (versioned, available globally)
+Slug: @code-reviewer
+```
+
+Depois, em qualquer sessão:
+
+```
+@code-reviewer
+Revise o PR #42 — mudanças no módulo de pagamento.
+```
+
+### 2. Squad de conteúdo com agentes especializados
+
+Cenário: squad de YouTube com roteirista, analista e copywriter.
+
+```bash
+# Primeiro, criar a squad (via @squad na sessão ou CLI)
+
+# Depois, criar agentes especializados
+aioson squad:agent-create \
+  --name="roteirista-viral" \
+  --type=clone \
+  --squad=youtube-creator \
+  --specialist="MrBeast" \
+  --domain="YouTube scripts" \
+  --disc=influential-expressive \
+  --mission="Criar roteiros de vídeo com hooks fortes e retenção alta" \
+  --with-infra
+
+aioson squad:agent-create \
+  --name="analista-retencao" \
+  --type=agent \
+  --tier=0 \
+  --squad=youtube-creator \
+  --domain="YouTube analytics" \
+  --disc=compliant-analytical \
+  --mission="Analisar métricas de retenção e recomendar ajustes no roteiro"
+
+aioson squad:agent-create \
+  --name="copywriter-thumbnail" \
+  --type=assistant \
+  --squad=youtube-creator \
+  --domain="thumbnail copywriting" \
+  --disc=dominant-driver \
+  --mission="Criar textos de thumbnail com CTR alto usando tensão visual e curiosidade"
+```
+
+Estrutura gerada:
+
+```
+.aioson/squads/youtube-creator/
+  agents/
+    roteirista-viral.md         ← clone com Voice DNA + infra
+    analista-retencao.md        ← agent tier 0 (roda primeiro)
+    copywriter-thumbnail.md     ← assistant com Voice DNA
+  tasks/
+    roteirista-viral-main-workflow.md
+  templates/
+    roteirista-viral-output-tmpl.md
+  checklists/
+    roteirista-viral-quality-gate.md
+```
+
+### 3. Agente consultor baseado em especialista
+
+Cenário: você quer um consultor de copy baseado no Gary Halbert.
+
+```bash
+aioson squad:agent-create \
+  --name="gary-halbert" \
+  --type=clone \
+  --squad=copy-factory \
+  --specialist="Gary Halbert" \
+  --domain=copywriting \
+  --disc=dominant-driver \
+  --mission="Escrever sales pages usando direct-response methodology" \
+  --with-infra
+```
+
+Depois de criar, enriqueça o agente:
+
+1. **Preencha a Voice DNA** com vocabulário real do Gary Halbert
+2. **Adicione output examples** com sales pages reais como referência
+3. **Complete os anti-patterns** com o que ele mesmo dizia para nunca fazer
+4. **Defina completion criteria** mensuráveis (ex: "headline gera curiosidade", "tem pelo menos 3 provas")
+
+### 4. Worker determinístico para pipeline de dados
+
+Cenário: agente que formata relatórios sem criatividade.
+
+```bash
+aioson squad:agent-create \
+  --name="report-formatter" \
+  --type=worker \
+  --squad=data-pipeline \
+  --mission="Converter dados brutos do CSV para o formato padronizado do relatório semanal" \
+  --with-infra
+```
+
+O worker não tem Voice DNA e inclui a regra:
+
+```markdown
+## Response standard
+Execute the task deterministically. No creative deviation. Follow the process exactly.
+```
+
+### 5. Board de advisors para decisões estratégicas
+
+Cenário: múltiplos consultores com perspectivas diferentes.
+
+```bash
+# Advisor de produto
+aioson squad:agent-create \
+  --name="product-advisor" \
+  --type=assistant \
+  --squad=advisory-board \
+  --domain="product strategy" \
+  --disc=dominant-influential \
+  --mission="Aconselhar sobre priorização de features e product-market fit"
+
+# Advisor técnico
+aioson squad:agent-create \
+  --name="tech-advisor" \
+  --type=assistant \
+  --squad=advisory-board \
+  --domain="software architecture" \
+  --disc=compliant-analytical \
+  --mission="Avaliar viabilidade técnica e riscos de arquitetura"
+
+# Advisor de growth
+aioson squad:agent-create \
+  --name="growth-advisor" \
+  --type=assistant \
+  --squad=advisory-board \
+  --domain="growth marketing" \
+  --disc=influential-expressive \
+  --mission="Identificar alavancas de crescimento e estratégias de go-to-market"
+```
+
+Depois, use na sessão:
+
+```
+@product-advisor @tech-advisor @growth-advisor
+Estamos considerando adicionar um plano gratuito. Analisem prós, contras e riscos.
+```
+
+---
+
+## Receita para um agente Level 3
+
+Um agente scaffold (Level 1) precisa de enriquecimento para chegar a Level 3. Aqui está o checklist:
+
+1. **Missão concreta** — não genérica. "Revisar PRs focando em OWASP top 10" é melhor que "Revisar código".
+
+2. **Core principles reais** — 5-10 crenças que guiam toda decisão. Extraia de livros, artigos ou experiência do domínio.
+
+3. **Operational framework detalhado** — substitua os 4 passos genéricos por passos específicos do domínio. Um copywriter não trabalha igual a um code reviewer.
+
+4. **3+ output examples reais** — mostrando input → output concreto. Não exemplos genéricos — exemplos que alguém copiaria.
+
+5. **Anti-patterns específicos** — não "evitar erros". Anti-patterns como "nunca abrir com feature em vez de benefício" ou "nunca usar mock no teste de integração".
+
+6. **Completion criteria mensuráveis** — "headline gera curiosidade" não serve. "Headline contém pelo menos um gatilho emocional e tem menos de 10 palavras" serve.
+
+7. **Hand-off table preenchida** — para quem o trabalho vai quando termina, e com que contexto.
+
+8. **Voice DNA preenchida** (assistant/clone) — vocabulário real, não placeholder. 8+ termos que o agente usa, 5+ que evita, metáforas específicas.
+
+---
+
+## Relação com o sistema existente
+
+### Agentes customizados vs agentes oficiais
+
+- Agentes oficiais (`@dev`, `@product`, `@analyst`, etc.) seguem o workflow do AIOSON
+- Agentes customizados não participam do workflow oficial — são chamados diretamente
+- Agentes de squad são coordenados pelo `@orquestrador` da própria squad
+
+### Agentes customizados vs skills
+
+- **Skill** = capacidade reutilizável (ex: "estruturar roteiro", "analisar hook")
+- **Agente** = executor com identidade, processo e julgamento (ex: "@roteirista-viral")
+- Use skill quando o conhecimento é genérico e compartilhável
+- Use agente quando precisa de identidade, voz e processo específico
+
+### Agentes customizados vs genomes
+
+- **Genome** = lente cognitiva passiva que enriquece agentes
+- **Agente** = executor ativo que produz trabalho
+- Genomes são aplicados em agentes — não substituem agentes
+- Use `@genome` para criar o genome, depois aplique ao agente
+
+---
+
+## FAQ
+
+### O `aioson update` sobrescreve meus agentes?
+
+Não. Tanto `.aioson/my-agents/` quanto `.aioson/squads/{slug}/agents/` são protegidos pelo installer. O `update` só toca arquivos gerenciados pelo framework.
+
+### Agentes customizados funcionam no Codex?
+
+Sim. O comando registra o agente no `AGENTS.md`, então o Codex encontra via `@slug`. Claude Code encontra via `CLAUDE.md` onde é registrado como `/{slug}`.
+
+### Posso usar `--with-infra` em my-agents?
+
+Não — infraestrutura operacional (tasks, templates, checklists) só faz sentido dentro de uma squad que tem estrutura de pastas para isso.
+
+### Qual a diferença entre `--type=assistant` e `--type=clone`?
+
+Ambos têm Voice DNA. A diferença é que `clone` inclui a seção "Specialist" com referência ao especialista humano e a instrução explícita de "Write as the specialist would write". Use `clone` quando tiver material real do especialista; use `assistant` para especialistas de domínio sem referência a uma pessoa específica.
+
+### Preciso usar tier e DISC?
+
+Não são obrigatórios. Use tier quando tiver agentes que precisam rodar em ordem (tier 0 primeiro). Use DISC quando quiser que o agente tenha um estilo de interação definido — especialmente útil em assistants e clones.