@jaimevalasek/aioson 1.3.0 → 1.5.1

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

@@ -124,6 +124,22 @@ Objetivo: gerar o PRD base antes de mapear pacientes, médicos, agendamentos e r
 
 ### Passo 4: @product — PRD base
 
+**Atalho com documento de kickoff (opcional):**
+
+Se você já tiver uma ideia esboçada, crie um arquivo de entrada antes de ativar o `@product`:
+
+```bash
+# Crie plans/agendamentos.md com suas notas brutas:
+# - quero que pacientes agendem consultas online
+# - médico pode bloquear horários
+# - notificação por email na confirmação
+```
+
+Ao ativar `/product`, o agente detecta `plans/agendamentos.md` e pergunta:
+> "Encontrei `plans/agendamentos.md`. Quer que eu use como fonte para o PRD?"
+
+Se sim, ele sintetiza o conteúdo e gera o PRD formal. Você pode deletar o arquivo original depois.
+
 ```
 /product
 ```
@@ -260,7 +276,7 @@ tests/Feature/AppointmentTest.php
 - N+1: Eager loading em todos os índices (with('doctor.user', 'patient.user'))
 - Timezone: UTC no banco, conversão na camada de apresentação
 
-### Passo 6: @dev — Implementação
+### Passo 6: @dev — Implementação com TDD Gate
 
 ```
 /dev
@@ -269,8 +285,32 @@ Implemente a feature de agendamentos primeiro.
 Comece pela migration, model, action e controller.
 ```
 
-**O @dev implementa seguindo as convenções:**
+O `@dev` detecta o test runner (`pest.xml` encontrado → Pest PHP) e aplica o TDD Gate antes de implementar qualquer lógica de negócio:
 
+**1. Escreve o teste com falha (RED):**
+```php
+// tests/Feature/CreateAppointmentTest.php
+it('throws exception on doctor schedule conflict', function () {
+    $doctor = Doctor::factory()->create();
+    $slot = now()->addDay()->setHour(10)->setMinute(0);
+
+    Appointment::factory()->create([
+        'doctor_id' => $doctor->id,
+        'date'      => $slot,
+        'status'    => 'confirmed',
+    ]);
+
+    expect(fn () => (new CreateAppointmentAction)->execute([
+        'doctor_id'  => $doctor->id,
+        'patient_id' => Patient::factory()->create()->id,
+        'date'       => $slot,
+    ]))->toThrow(AppointmentConflictException::class);
+});
+```
+
+Roda o teste → **falha** (RED confirmado). Só então implementa:
+
+**2. Implementa o suficiente para passar (GREEN):**
 ```php
 // app/Actions/CreateAppointmentAction.php
 class CreateAppointmentAction
@@ -304,6 +344,8 @@ class CreateAppointmentAction
 }
 ```
 
+Roda o teste → **passa** (GREEN). Commit. Próximo passo.
+
 ### Passo 7: @qa — Testes
 
 ```
@@ -318,6 +360,8 @@ Revise a CreateAppointmentAction e escreva os testes para:
 
 **O @qa entrega** `tests/Feature/AppointmentTest.php` com todos os casos.
 
+> **Quando usar @tester em vez de @qa:** Se após o `@dev` a cobertura estiver em zero ou muito baixa, ative `/tester` em vez de `/qa`. O `@tester` começa por um inventário completo (`test-inventory.md`), mapeia os riscos, escolhe a estratégia e escreve testes em ordem de prioridade — Auth/Authorization > Business rules > Data integrity > UI. O `@qa` é um revisor pontual; o `@tester` é um engenheiro de testes que parte do zero.
+
 ---
 
 ## Cenário 3 — SaaS multi-tenant (MEDIUM)
@@ -354,7 +398,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 +452,7 @@ src/
   types/
 ```
 
-### Passo 6: @ux-ui
+### Passo 6: UI/UX (`@ux-ui`)
 
 ```
 /ux-ui
@@ -420,7 +464,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

package/docs/pt/clientes-ai.md

@@ -22,6 +22,8 @@ O AIOSON funciona com **Claude Code**, **Codex CLI** e **Gemini CLI**. Cada um t
 
 O Claude Code lê `CLAUDE.md` automaticamente ao iniciar. Os agentes do AIOSON ficam em `.claude/commands/aioson/` — isso cria o namespace `/aioson/*` no autocomplete.
 
+O nome humano do agente é **UI/UX**, mas o comando continua sendo `/aioson/ux-ui`.
+
 ### Ativando agentes
 
 Digite `/` para abrir o autocomplete e depois `aioson/`:
@@ -30,6 +32,7 @@ Digite `/` para abrir o autocomplete e depois `aioson/`:
 /aioson/setup
 /aioson/analyst
 /aioson/architect
+/aioson/deyvin
 /aioson/ux-ui
 /aioson/pm
 /aioson/dev
@@ -49,6 +52,16 @@ Digite `/` para abrir o autocomplete e depois `aioson/`:
 ```
 > O agente @dev recebe o argumento como contexto extra e começa a implementação em steps atômicos.
 
+```
+/aioson/deyvin veja o que fizemos ontem e vamos continuar
+```
+> O agente @deyvin prioriza memoria + runtime + rules/docs antes de olhar Git e segue em modo companheiro tecnico.
+
+Alias compativel:
+```text
+/aioson/pair
+```
+
 ```
 /aioson/qa
 ```
@@ -88,6 +101,34 @@ use @architect para desenhar a estrutura de pastas do projeto
 activate the @qa agent to write tests for the auth module
 ```
 
+### Sessao rastreada no dashboard
+
+Se voce quer que a ativacao apareca em `tasks`, `agent_runs` e no dashboard do runtime, nao dependa so da mencao natural ao agente na conversa.
+
+Use um gateway oficial antes de continuar no Codex:
+
+```bash
+aioson workflow:next . --tool=codex
+```
+
+ou, para handoff direto rastreado:
+
+```bash
+aioson agent:prompt deyvin . --tool=codex
+```
+
+Se quiser que o proprio AIOSON abra e supervisione uma sessao viva do cliente externo, use:
+
+```bash
+aioson live:start . --tool=codex --agent=deyvin --no-launch
+```
+
+Dentro dessa sessao viva, o agente passa a usar `runtime:emit`, `live:handoff`, `live:status` e `live:close` para manter o dashboard e os arquivos de sessao sincronizados.
+
+Depois cole o prompt gerado no Codex e continue a sessao.
+
+A ativacao por linguagem natural via `AGENTS.md` pode executar o contrato do agente, mas nao garante registros no dashboard porque esse caminho nao passa pelo gateway oficial.
+
 ### Exemplos completos
 
 **Iniciar projeto novo:**
@@ -100,6 +141,11 @@ use the @setup agent to onboard this project
 use @dev to implement user registration with email verification, atomic steps
 ```
 
+**Continuar sessao anterior:**
+```
+use @deyvin to review the latest runtime/tasks, tell me where we stopped, and continue with me
+```
+
 **Revisar plano:**
 ```
 use @analyst to analyze the requirements in prd.md and identify gaps
@@ -125,6 +171,8 @@ Quando você menciona `@setup`, o Codex lê o arquivo correspondente e segue tod
 ### Dicas para Codex
 
 - **Seja explícito**: `use @dev` funciona melhor que apenas "implemente"
+- **Para continuidade**: `use @deyvin` funciona melhor que "ve o que fizemos ontem"
+- **Para rastreamento no dashboard**: prefira `aioson workflow:next . --tool=codex` ou `aioson agent:prompt <agente> . --tool=codex` antes de colar o prompt no Codex
 - **Passe contexto**: `use @dev to implement X — read spec.md first`
 - **Comece sempre com @setup** se `project.context.md` não existir
 - O Codex também lê o contexto do agente selecionado automaticamente via `AGENTS.md`
@@ -137,6 +185,8 @@ Quando você menciona `@setup`, o Codex lê o arquivo correspondente e segue tod
 
 O Gemini CLI lê `.gemini/GEMINI.md` ao iniciar e reconhece comandos definidos em `.gemini/commands/*.toml`. Os agentes do AIOSON são registrados com o prefixo `aios-`.
 
+O nome humano do agente é **UI/UX**, mas o comando continua sendo `/aios-ux-ui`.
+
 ### Ativando agentes
 
 Digite `/aios-` para ver os comandos disponíveis no autocomplete:
@@ -145,6 +195,7 @@ Digite `/aios-` para ver os comandos disponíveis no autocomplete:
 /aios-setup
 /aios-analyst
 /aios-architect
+/aios-deyvin
 /aios-ux-ui
 /aios-pm
 /aios-dev
@@ -164,6 +215,16 @@ Digite `/aios-` para ver os comandos disponíveis no autocomplete:
 ```
 > Ativa o agente de desenvolvimento.
 
+```
+/aios-deyvin
+```
+> Ativa o agente de continuidade e pair programming.
+
+Alias compativel:
+```text
+/aios-pair
+```
+
 ```
 /aios-orchestrator
 ```
@@ -203,6 +264,7 @@ Independente de qual CLI você usa, todos leem os mesmos arquivos:
   context/
     project.context.md   ← gerado pelo @setup, lido por todos
     spec.md              ← documento vivo, atualizado pelo @orchestrator
+    runtime/aios.sqlite  ← tasks, runs e logs consultados pelo @deyvin e pelo dashboard
 ```
 
 Você pode começar um projeto com Claude Code, continuar com Codex no dia seguinte, e o contexto persiste — todos os agentes leem o mesmo `project.context.md`.