@jaimevalasek/aioson 1.3.0 → 1.4.0

package/docs/pt/agentes.md

@@ -11,19 +11,37 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 ```
 @setup        ← sempre o primeiro
 @product      ← gera o PRD base vivo e roteia o fluxo
+@deyvin       ← companheiro tecnico para continuidade e pequenas implementacoes
 @discovery-design-doc ← quando precisa clarear escopo e gerar design doc vivo
 @analyst      ← projetos SMALL e MEDIUM
 @architect    ← projetos SMALL e MEDIUM
-@ux-ui        ← quando há interfaces (SMALL e MEDIUM)
+@ux-ui        ← UI/UX quando há interfaces (SMALL e MEDIUM)
 @pm           ← apenas MEDIUM
 @orchestrator ← apenas MEDIUM
 @dev          ← sempre o último antes do QA
 @qa           ← projetos SMALL e MEDIUM
 @squad        ← cria squads especializados no projeto
-@genoma       ← cria genomas de domínio reutilizáveis
+@genome       ← cria genomes de domínio reutilizáveis
 ```
 
-> Para o fluxo completo de `@squad` e `@genoma`, veja também [Squad e Genoma](./squad-genoma.md).
+> Para o fluxo completo de `@squad` e `@genome`, veja também [Squad e Genome](./squad-genome.md).
+> Para criar agentes customizados (my-agents e squad agents), veja [Agentes Customizados](./agentes-customizados.md).
+> Para uma explicação focada no agente de continuidade, veja também [Deyvin](./deyvin.md).
+
+## Fluxo brownfield apos scan
+
+Quando o projeto ja existe e voce roda `scan:project`, o handoff correto agora e:
+
+```text
+scan:project -> @analyst -> @architect -> @dev
+```
+
+Regras do fluxo:
+- os artefatos locais do scan (`scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`) servem como mapas brutos do codigo
+- `discovery.md` continua sendo a memoria comprimida que os agentes usam para entender o sistema sem reler tudo
+- esse `discovery.md` pode ser gerado por `scan:project --with-llm` ou pelo `@analyst` usando os artefatos locais do scan
+- `@architect`, `@ux-ui`, `@pm`, `@qa` e o fluxo de `@dev` nao devem pular direto dos mapas brutos para a execucao quando a tarefa depende do comportamento atual do sistema
+- para continuidade de sessao, pequenas correcoes e implementacoes guiadas, `@deyvin` pode entrar depois que a memoria minima estiver pronta
 
 ---
 
@@ -77,6 +95,7 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 - detecta sinais visuais cedo e preserva a intenção no PRD
 - faz classificação preliminar do escopo
 - aponta o próximo agente do fluxo
+- em brownfield, usa `discovery.md` quando já existir e trata os artefatos locais do scan apenas como orientação estrutural, nunca como substituto do `@analyst`
 
 **Como ativar:**
 ```
@@ -95,6 +114,64 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 
 ---
 
+## @deyvin
+
+**Quando usar:** Quando voce quer continuar uma sessao anterior, entender o que foi feito por ultimo, corrigir uma tarefa pequena, investigar um bug ou implementar em modo colaborativo.
+
+**O que faz:**
+- atua como um companheiro tecnico de continuidade
+- le primeiro a memoria do projeto e o runtime antes de ir ao Git
+- verifica sempre `.aioson/rules/` e os docs apontados por essas rules
+- resume o que ja esta confirmado sobre o estado atual
+- pergunta o que voce quer fazer agora
+- toca passos pequenos de implementacao, correcao e validacao
+- encaminha para `@product`, `@discovery-design-doc`, `@analyst`, `@architect`, `@ux-ui`, `@dev` ou `@qa` quando a tarefa sair do modo pair
+
+**Ordem mental de contexto do `@deyvin`:**
+1. `project.context.md`
+2. `.aioson/rules/`
+3. `.aioson/docs/`
+4. `context-pack.md` quando existir e combinar com a tarefa
+5. `memory-index.md`
+6. `spec-current.md` + `spec-history.md`
+7. `spec.md`
+8. `features.md` e artefatos da feature em andamento, se houver
+9. `skeleton-system.md`, `discovery.md`, `architecture.md`
+10. runtime SQLite
+11. Git como fallback
+
+**Como ativar:**
+```
+/deyvin
+```
+
+Alias compativel:
+```text
+@pair
+```
+
+**Exemplos bons de uso:**
+```text
+@deyvin ve o que fizemos ontem e vamos continuar
+@deyvin revisa as ultimas tasks do runtime e me diga onde paramos
+@deyvin vamos corrigir esse bug pequeno juntos
+@deyvin leia as rules ativas, veja os docs relacionados e ajuste esse fluxo
+```
+
+**Entrega esperada:**
+- resumo curto do ultimo contexto confirmado
+- proximo passo pequeno e objetivo
+- implementacao/correcao em lote pequeno
+- atualizacao de `spec.md` ou `spec-{slug}.md` quando fizer sentido
+
+**Regra importante:**
+- `@deyvin` nao substitui discovery, produto ou arquitetura formal
+- quando a demanda cresce demais ou fica vaga, ele deve fazer handoff em vez de fingir que tudo cabe numa sessao de continuidade
+- se o pedido abrir projeto novo, greenfield, feature grande, escopo contraditorio ou misturar produto + UX + implementacao, o `@deyvin` deve fazer handoff imediato e nao comecar a codar
+- se voce quiser uma explicacao mais direta e focada no uso dele, consulte [Deyvin](./deyvin.md)
+
+---
+
 ## @analyst
 
 **Quando usar:** Projetos SMALL e MEDIUM, antes de @architect.
@@ -106,6 +183,7 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 - Identifica integrações externas e riscos
 - Em modo feature, passa a consumir `design-doc.md` e `readiness.md` quando já existirem
 - Usa skills e documentos sob demanda para evitar reabrir discovery desnecessária
+- em brownfield, pode gerar `discovery.md` diretamente a partir de `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md` e `scan-aioson.md`, mesmo sem API configurada no `aioson`
 
 **Como ativar:**
 ```
@@ -174,6 +252,7 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 - Define padrões de código para o time
 - Usa `design-doc.md` como documento de decisão do escopo atual
 - Respeita `readiness.md`; se a prontidão ainda estiver baixa, devolve bloqueios em vez de fingir certeza
+- só deve arquitetar em cima de `discovery.md`; se houver apenas artefatos brutos de scan, o passo correto ainda é `@analyst` antes
 
 **Como ativar:**
 ```
@@ -200,7 +279,7 @@ tests/
 
 ---
 
-## @ux-ui
+## UI/UX (`@ux-ui`)
 
 **Quando usar:** Quando o projeto tem interfaces (web apps, landing pages com formulários). SMALL e MEDIUM.
 
@@ -213,19 +292,36 @@ tests/
 - Decide dark/light e direção visual de forma autônoma quando o contexto já for suficiente
 - Só pergunta preferência estética quando a ambiguidade realmente mudar a solução
 - Carrega `premium-command-center-ui` apenas quando houver pedido explícito de interface operacional premium ou quando essa skill já estiver registrada no PRD
+- em brownfield, usa `discovery.md` como memória comprimida do sistema; se esse arquivo ainda não existir e o trabalho depender do comportamento atual da aplicação, o próximo passo correto é `@analyst`
 
-**Como ativar:**
+**Como ativar o agente UI/UX:**
 ```
 /ux-ui
 ```
 
-**Entrega:** Arquivo `.aioson/context/ui-spec.md` com:
+**Submodos disponíveis:**
+```
+/ux-ui research       → pesquisa visual e hipóteses de direção
+/ux-ui audit          → auditoria com inventário, achados por severidade e plano de consolidação
+/ux-ui tokens         → contrato formal de design tokens (primitivos, semânticos, escalas)
+/ux-ui component-map  → mapeamento de componentes (Atomic Design), gap analysis
+/ux-ui a11y           → auditoria WCAG focada, integração com @qa
+```
+
+**Entrega principal:** Arquivo `.aioson/context/ui-spec.md` com:
 - Sistema de design (tokens, cores, tipografia)
 - Componentes principais e estados
 - Fluxos de navegação
 - Checklist de acessibilidade
 - Enriquecimento da seção `Identidade visual` do PRD, sem reescrever visão, problema ou usuários
 
+**Entregas dos submodos** (opcionais, em `.aioson/context/`):
+- `ui-research.md` — benchmarking visual e direções
+- `ui-audit.md` — inventário + achados + plano de consolidação
+- `ui-tokens.md` — contrato de tokens com posse (`:root` vs `[data-theme]`)
+- `ui-component-map.md` — catálogo de componentes com variantes e estados
+- `ui-a11y.md` — relatório WCAG com checks automatizados e manuais
+
 > Se o usuário disser para o agente seguir sozinho, o comportamento esperado é decidir a direção visual com base no contexto do produto e continuar sem abrir questionário de estilo.
 
 ---
@@ -239,6 +335,7 @@ tests/
 - Define ordem de entrega sem apagar a intenção original de produto
 - Adiciona critérios de aceite compactos quando isso trouxer clareza para execução e QA
 - Preserva identidade visual, visão, problema, usuários e demais seções já existentes
+- usa `discovery.md` e `architecture.md` como base; não deve priorizar diretamente a partir de mapas brutos de scan
 
 **Como ativar:**
 ```
@@ -323,32 +420,32 @@ npx @jaimevalasek/aioson parallel:status
 - Metadata do squad
 - Estrutura de output, logs, mídia e sessão
 
-> Guia completo: [Squad e Genoma](./squad-genoma.md)
+> Guia completo: [Squad e Genome](./squad-genome.md)
 
 ---
 
-## @genoma
+## @genome
 
 **Quando usar:** Quando você quer criar uma base de conhecimento de domínio reutilizável e aplicá-la a squads ou agentes específicos.
 
 **O que faz:**
 - Gera `O que saber`, `Mentes` e `Skills`
-- Pode salvar em `.aioson/genomas/`
+- Pode salvar em `.aioson/genomes/`
 - Pode ser aplicado depois a um squad já existente
 - Atua como camada cognitiva do sistema, não como executor
 
 **Como ativar:**
 ```
-@genoma
+@genome
 ```
 
 **Entrega:**
-- Genoma estruturado
+- Genome estruturado
 - Opcionalmente, vínculo persistente com um squad
 
 **Não confundir:**
 - `skill` = capacidade operacional
-- `genoma` = forma de pensar, lentes e repertório
+- `genome` = forma de pensar, lentes e repertório
 - `executor` = quem faz o trabalho
 - `subagente` = investigação temporária
 
@@ -357,7 +454,7 @@ Quando uma skill vier do catálogo online ou de outro pacote, ela deve ser salva
 
 Depois disso, ela passa a ser parte real do pacote local da squad e deve ser considerada pelos agentes sob demanda.
 
-> Guia completo: [Squad e Genoma](./squad-genoma.md)
+> Guia completo: [Squad e Genome](./squad-genome.md)
 
 ---
 
@@ -411,6 +508,7 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 - Escreve testes unitários e de integração
 - Identifica casos de borda não cobertos
 - Valida se os critérios de aceite foram atendidos
+- usa `discovery.md` como fonte de regras e relacionamentos; se só existirem artefatos de scan, o fluxo correto ainda passa por `@analyst`
 
 **Como ativar:**
 ```

package/docs/pt/automacao-squads.md

@@ -0,0 +1,407 @@
+# Automação de Squads — LLM-to-Script
+
+> Como transformar processos de squad em scripts executáveis que rodam sem LLM.
+
+---
+
+## Conceito
+
+Toda vez que uma squad executa uma tarefa, custa tokens de LLM. Mas muitos processos seguem padrões repetíveis — mesma entrada, mesma transformação, mesma estrutura de saída. Quando isso acontece, o trabalho pode virar um **script que roda sozinho**: local, em CI/CD, cron, serverless ou qualquer ambiente.
+
+O fluxo:
+
+```
+Squad produz output com LLM
+        ↓
+Orquestrador analisa: "isso pode virar script?"
+        ↓
+Cria script plan em script-plans/
+        ↓
+Usuário revisa e aprova
+        ↓
+LLM gera o script em scripts/
+        ↓
+Script roda sem LLM — custo zero por execução
+```
+
+---
+
+## Quando funciona bem
+
+A automação faz sentido quando o processo é **determinístico** — mesma entrada sempre produz a mesma saída.
+
+**Bons candidatos:**
+- Formatação de dados (CSV → JSON, Markdown → HTML)
+- Preenchimento de templates (relatórios semanais, newsletters)
+- Extração de informações de documentos estruturados
+- Validação contra regras fixas (checklists, conformidade)
+- Transformações de texto com padrões claros (slugify, normalizar, limpar)
+- Geração de relatórios a partir de dados tabulares
+- Pipeline de preparação de conteúdo (metadata, tags, categorização por regra)
+
+**Não automatize:**
+- Trabalho criativo (escrever copy original, brainstorming)
+- Tarefas que precisam de pesquisa web ou dados em tempo real
+- Processos onde o julgamento da LLM é o valor principal (code review, análise estratégica)
+- Tarefas únicas que nunca vão se repetir
+
+---
+
+## Como usar
+
+### Opção 1: O orquestrador oferece
+
+Depois de uma sessão produtiva, o orquestrador da squad automaticamente avalia se o processo pode ser automatizado. Se a viabilidade for média ou alta, ele oferece:
+
+> "Esse processo parece automatizável. Quer que eu analise se pode virar um script standalone que roda sem LLM?"
+
+Se você aceitar, ele cria o script plan. Se recusar, segue em frente.
+
+### Opção 2: Você pede explicitamente
+
+```
+@squad automate youtube-creator
+```
+
+Isso analisa as sessões recentes da squad e propõe automações para os processos mais repetitivos.
+
+---
+
+## Fase 1: Script plan
+
+O script plan é um documento de análise que avalia **o que** pode ser automatizado e **como**.
+
+Fica em: `.aioson/squads/{slug}/script-plans/{plan-slug}.md`
+
+### Exemplo real: formatador de roteiros
+
+Imagine uma squad de YouTube onde o roteirista sempre recebe um briefing e produz um roteiro no mesmo formato: hook, desenvolvimento, CTA, descrição do vídeo.
+
+O script plan seria:
+
+```markdown
+# Script Plan: format-youtube-script
+
+**Status:** proposed
+**Squad:** youtube-creator
+**Session:** 2026-03-20-roteiro-ingles
+**Language:** python
+**Feasibility:** high
+
+## What the LLM did
+Recebeu um briefing com tema, público-alvo e estilo.
+Produziu um roteiro com estrutura fixa: hook (3 opções),
+desenvolvimento (3 blocos), CTA, descrição e tags.
+
+## Automation feasibility analysis
+
+### Can be automated
+- Leitura do briefing a partir de template JSON
+- Estruturação das seções (hook, blocos, CTA)
+- Geração da descrição a partir de template com variáveis
+- Formatação final em Markdown com frontmatter
+
+### Cannot be automated
+- Escrita criativa do conteúdo dos hooks
+- Escolha da narrativa nos blocos de desenvolvimento
+- Adaptação do tom ao público-alvo
+
+### Feasibility verdict
+Medium — a estrutura e formatação podem ser automatizadas,
+mas o conteúdo criativo ainda precisa de LLM.
+O script pode gerar o scaffold e pré-preencher seções fixas,
+economizando ~40% do trabalho do agente.
+
+## Script design
+
+### Inputs
+| Name | Type | Source | Example |
+|------|------|--------|---------|
+| briefing | JSON | arquivo local | {"tema":"inglês","publico":"25-40","estilo":"direto"} |
+| template | Markdown | squad templates | roteiro-tmpl.md |
+
+### Process
+1. Ler briefing JSON
+2. Carregar template de roteiro
+3. Preencher variáveis fixas (tema, público, data)
+4. Gerar estrutura das seções com placeholders
+5. Adicionar frontmatter com metadata
+6. Escrever arquivo Markdown de saída
+
+### Outputs
+| Name | Format | Location |
+|------|--------|----------|
+| roteiro-scaffold | Markdown | output/youtube-creator/ |
+
+### Dependencies
+- Nenhuma (stdlib Python)
+
+### Limitations
+- Não gera conteúdo criativo — apenas o scaffold
+- Não substitui o agente para roteiros que fogem do template padrão
+
+## Estimated effort
+Small (< 100 lines)
+```
+
+### Status do script plan
+
+| Status | Significado |
+|--------|-------------|
+| `proposed` | Análise feita, aguardando aprovação |
+| `approved` | Usuário aprovou, pronto para gerar script |
+| `implemented` | Script gerado e funcional |
+| `rejected` | Usuário considerou inviável ou desnecessário |
+
+---
+
+## Fase 2: Geração do script
+
+Quando você revisa o plan e diz "ok" / "pode gerar" / "implementa":
+
+1. O status do plan muda para `approved`
+2. A LLM gera o script em `.aioson/squads/{slug}/scripts/{script-slug}.py` (ou `.js`)
+3. O status muda para `implemented`
+4. O manifesto da squad é atualizado com a automação
+
+### Requisitos do script gerado
+
+Todo script deve ser **self-contained e executável**:
+
+```bash
+# Python
+python .aioson/squads/youtube-creator/scripts/format-youtube-script.py --help
+python .aioson/squads/youtube-creator/scripts/format-youtube-script.py --input=briefing.json --output=output/
+
+# Node.js
+node .aioson/squads/data-pipeline/scripts/csv-to-dashboard.js --input=report.csv --output=dashboard.json
+```
+
+**Obrigatório em todo script:**
+- Header com nome, origem (plan), e usage
+- Parse de argumentos CLI (`--input`, `--output`, `--help`, `--dry-run`)
+- Leitura de input via arquivo ou stdin
+- Escrita de output via arquivo ou stdout
+- Tratamento de erros com mensagens claras
+- Zero paths hardcoded — tudo via argumentos
+- Se precisar de pacotes externos, listar no header com instrução de install
+
+### Exemplo de script gerado
+
+```python
+#!/usr/bin/env python3
+"""
+format-youtube-script — generated from squad:youtube-creator
+Plan: script-plans/format-youtube-script.md
+
+Gera scaffold de roteiro de YouTube a partir de briefing JSON.
+
+Usage:
+  python format-youtube-script.py --input=briefing.json [--output=roteiro.md] [--template=tmpl.md]
+  python format-youtube-script.py --help
+  echo '{"tema":"..."}' | python format-youtube-script.py
+"""
+
+import argparse
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+
+def load_input(input_path):
+    if input_path == '-' or input_path is None:
+        return json.load(sys.stdin)
+    return json.loads(Path(input_path).read_text())
+
+
+def generate_scaffold(briefing, template_path=None):
+    tema = briefing.get('tema', 'Sem tema')
+    publico = briefing.get('publico', 'Geral')
+    estilo = briefing.get('estilo', 'neutro')
+    today = date.today().isoformat()
+
+    sections = [
+        f'---',
+        f'tema: {tema}',
+        f'publico: {publico}',
+        f'estilo: {estilo}',
+        f'data: {today}',
+        f'status: scaffold',
+        f'---',
+        f'',
+        f'# Roteiro: {tema}',
+        f'',
+        f'## Hook (escolher 1 de 3)',
+        f'1. [Hook opção A]',
+        f'2. [Hook opção B]',
+        f'3. [Hook opção C]',
+        f'',
+        f'## Desenvolvimento',
+        f'',
+        f'### Bloco 1',
+        f'[Conteúdo do primeiro bloco]',
+        f'',
+        f'### Bloco 2',
+        f'[Conteúdo do segundo bloco]',
+        f'',
+        f'### Bloco 3',
+        f'[Conteúdo do terceiro bloco]',
+        f'',
+        f'## CTA',
+        f'[Call to action]',
+        f'',
+        f'## Descrição do vídeo',
+        f'[Descrição para o YouTube]',
+        f'',
+        f'## Tags',
+        f'[Lista de tags]',
+    ]
+    return '\n'.join(sections)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate YouTube script scaffold from briefing')
+    parser.add_argument('--input', '-i', help='Path to briefing JSON (or - for stdin)')
+    parser.add_argument('--output', '-o', help='Output path (default: stdout)')
+    parser.add_argument('--template', '-t', help='Optional template file')
+    parser.add_argument('--dry-run', action='store_true', help='Show what would be generated')
+    args = parser.parse_args()
+
+    briefing = load_input(args.input)
+    result = generate_scaffold(briefing, args.template)
+
+    if args.dry_run:
+        print(f'[dry-run] Would generate {len(result)} chars')
+        print(f'[dry-run] Tema: {briefing.get("tema")}')
+        return
+
+    if args.output:
+        Path(args.output).write_text(result)
+        print(f'Scaffold saved to {args.output}')
+    else:
+        print(result)
+
+
+if __name__ == '__main__':
+    main()
+```
+
+---
+
+## Fase 3: Iteração
+
+Se o script não funciona perfeitamente na primeira vez:
+
+1. Reporte o problema: "O script não trata briefings sem campo 'estilo'"
+2. A LLM corrige o script no mesmo arquivo
+3. O plan ganha uma seção `## Iterations` documentando as mudanças
+
+---
+
+## Registro no manifesto
+
+Quando um script é implementado, ele aparece no `squad.manifest.json`:
+
+```json
+{
+  "automations": [
+    {
+      "slug": "format-youtube-script",
+      "plan": "script-plans/format-youtube-script.md",
+      "script": "scripts/format-youtube-script.py",
+      "language": "python",
+      "status": "implemented",
+      "createdFrom": "2026-03-20-roteiro-ingles",
+      "inputs": ["briefing JSON com tema, público e estilo"],
+      "outputs": ["scaffold de roteiro em Markdown"]
+    }
+  ]
+}
+```
+
+---
+
+## Estrutura de pastas
+
+```
+.aioson/squads/{squad-slug}/
+  script-plans/
+    format-youtube-script.md        ← análise de viabilidade
+    validate-seo-checklist.md       ← outro plan
+  scripts/
+    format-youtube-script.py        ← script aprovado e implementado
+    validate-seo-checklist.js       ← outro script
+```
+
+---
+
+## Exemplos de automação por tipo de squad
+
+### Squad de conteúdo
+
+| Processo | Viabilidade | Tipo de script |
+|----------|-------------|----------------|
+| Formatar roteiro a partir de briefing | Alta | Python — template filling |
+| Gerar metadata de vídeo (tags, descrição) | Média | Python — regras + template |
+| Converter roteiro Markdown → teleprompter HTML | Alta | Node.js — parser + template |
+| Analisar retenção de vídeo | Baixa | Precisa de API do YouTube |
+
+### Squad de dados/relatórios
+
+| Processo | Viabilidade | Tipo de script |
+|----------|-------------|----------------|
+| CSV → JSON normalizado | Alta | Python — pandas ou csv stdlib |
+| Gerar relatório semanal a partir de dados | Alta | Python — template + dados |
+| Validar conformidade de dataset | Alta | Python — regras fixas |
+| Dashboard estático a partir de métricas | Alta | Node.js — chart.js + template |
+
+### Squad de desenvolvimento
+
+| Processo | Viabilidade | Tipo de script |
+|----------|-------------|----------------|
+| Gerar migration a partir de spec | Média | Node.js — parser de spec |
+| Scaffold de CRUD completo | Alta | Node.js — templates de código |
+| Validar PR contra checklist | Alta | Python — regex + regras |
+| Gerar changelog a partir de commits | Alta | Python — git log parser |
+
+### Squad jurídico
+
+| Processo | Viabilidade | Tipo de script |
+|----------|-------------|----------------|
+| Formatar contrato a partir de template | Alta | Python — docx/md template |
+| Extrair cláusulas de documento | Média | Python — regex patterns |
+| Gerar checklist de compliance | Alta | Python — regras fixas |
+| Analisar risco de contrato | Baixa | Julgamento humano/LLM |
+
+---
+
+## Boas práticas
+
+1. **Comece pelo plan.** Não peça script direto — o plan força a análise de viabilidade antes de investir esforço na implementação.
+
+2. **Seja honesto com a viabilidade.** "Medium" é uma resposta válida. Um script que faz 60% do trabalho e deixa os 40% criativos para o LLM já economiza muito.
+
+3. **Prefira Python ou Node.js com zero dependências.** Um script que precisa de `pip install` com 10 pacotes é mais difícil de rodar em qualquer ambiente.
+
+4. **Use `--dry-run` em tudo.** O script deve poder mostrar o que faria sem fazer de fato.
+
+5. **Não force automação em trabalho criativo.** Se o valor da squad é a criatividade dos agentes, automação não é o caminho — e tudo bem.
+
+6. **Itere.** O primeiro script raramente é perfeito. A vantagem é que a LLM que gerou o script também pode corrigi-lo.
+
+---
+
+## Relação com workers
+
+A squad já tem o conceito de `worker` (tipo de executor determinístico em `workers/`). A diferença:
+
+| | Worker | Automation script |
+|---|---|---|
+| **Criado quando** | Na montagem da squad | Depois de uma sessão produtiva |
+| **Origem** | Planejado previamente | Extraído de um processo real |
+| **Localização** | `workers/` | `scripts/` |
+| **Tem plan** | Não | Sim (em `script-plans/`) |
+| **Evolução** | Editado manualmente | Iterado com ajuda da LLM |
+
+Workers são definidos na criação da squad para tarefas que **já se sabe** serem determinísticas. Scripts de automação nascem da observação de que um processo executado por agentes LLM **pode** ser replicado sem LLM.

package/docs/pt/cenarios.md

@@ -354,7 +354,7 @@ Plano de execução:
 1. /product   → PRD base vivo
 2. /analyst   → discovery e modelagem de domínio
 3. /architect → estrutura de pastas Next.js MEDIUM + decisões técnicas
-4. /ux-ui     → sistema de design e componentes
+4. /ux-ui     → UI/UX, sistema de design e componentes
 5. /pm        → priorização e critérios de aceite no PRD vivo
 6. /orchestrator → lanes de desenvolvimento paralelo
 7. /dev       → implementação por lane
@@ -408,7 +408,7 @@ src/
   types/
 ```
 
-### Passo 6: @ux-ui
+### Passo 6: UI/UX (`@ux-ui`)
 
 ```
 /ux-ui
@@ -420,7 +420,7 @@ Precisamos de:
 - Página de configurações de billing
 ```
 
-**O @ux-ui entrega** `.aioson/context/ui-spec.md`:
+**O agente UI/UX (`@ux-ui`) entrega** `.aioson/context/ui-spec.md`:
 - Tokens: primary=#6366F1, gray scale, radius-md=8px
 - Componentes: ProjectCard, TaskCard, KanbanBoard, Sidebar, BillingModal
 - Estados: loading skeleton, empty state, error state para cada componente