@jaimevalasek/aioson 1.3.0 → 1.4.0

package/docs/pt/agentes-customizados.md

@@ -0,0 +1,670 @@
+# 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.