@jaimevalasek/aioson 1.4.0 → 1.5.1

package/docs/pt/agentes.md

@@ -90,6 +90,7 @@ Regras do fluxo:
 **Quando usar:** Depois do `@setup` em projetos novos. Em features novas de projeto existente, pode entrar direto sem repetir `@setup`.
 
 **O que faz:**
+- varre a raiz do projeto em busca de documentos de entrada (`plans/*.md`, `prds/*.md`) antes de iniciar a conversa
 - conduz a conversa de produto e gera o `PRD base`
 - registra visão, problema, usuários, escopo inicial e perguntas em aberto
 - detecta sinais visuais cedo e preserva a intenção no PRD
@@ -97,6 +98,21 @@ Regras do fluxo:
 - 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`
 
+**Documentos de kickoff (plans/ e prds/ na raiz):**
+
+Você pode criar arquivos de entrada na raiz do projeto antes de ativar o `@product`:
+
+```
+plans/minha-ideia.md     ← notas, esboços, planos escritos por você
+prds/visao-produto.md    ← rascunhos de requisitos, referências
+```
+
+O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los como fonte. Se sim, ele sintetiza o conteúdo e gera o PRD formal em `.aioson/context/`. Os arquivos originais nunca são modificados — você pode deletá-los depois que o PRD estiver gerado.
+
+**Sinal de greenfield vs feature:**
+- `plans/*.md` ou `prds/*.md` existem + `prd.md` ainda não existe → kickoff de projeto novo
+- `plans/*.md` ou `prds/*.md` existem + `prd.md` já existe → nova feature ou refinamento
+
 **Como ativar:**
 ```
 /product
@@ -481,12 +497,25 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 - Seguir as convenções nativas do framework do projeto
 - Verificar skills disponíveis em `.aioson/skills/static/` antes de implementar
 
+**TDD Gate** — Antes de qualquer implementação de lógica de negócio, o `@dev` verifica o test runner configurado em `project.context.md`. Se não houver nenhum configurado, escaneia a raiz em busca de arquivos de configuração conhecidos (`pest.xml`, `vitest.config.*`, `pytest.ini`, `.rspec`, `foundry.toml`) e pergunta ao usuário se deseja configurar um antes de começar.
+
+| Classificação | Mandato |
+|---|---|
+| MICRO | Escrever o teste junto com a implementação — obrigatório antes do commit |
+| SMALL | Escrever o teste com falha (RED) **antes** de qualquer código de implementação |
+| MEDIUM | Igual ao SMALL. Anotar o teste no checkpoint do plano de implementação |
+
+**Exceções ao TDD** (nenhum teste exigido): arquivos de configuração, migrations sem regras de negócio, conteúdo estático, scaffolding de UI sem lógica de estado.
+
+Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede após insistência — nunca implementa lógica de negócio sem teste existindo primeiro.
+
 **Execução atômica** — O @dev trabalha em passos pequenos e validados, nunca implementa uma feature inteira de uma vez:
 1. Declara o próximo passo antes de escrever código
-2. Implementa apenas aquele passo
-3. Valida antes de avançar — se houver dúvida, pergunta
-4. Faz commit do passo funcional antes de seguir
-5. Para e reporta se algo der errado — não continua em estado quebrado
+2. Escreve o teste com falha (RED) — o teste deve falhar antes de qualquer implementação
+3. Implementa apenas o suficiente para o teste passar (GREEN)
+4. Verifica que o teste passa — lê o output completo, não um resumo
+5. Faz commit com mensagem semântica
+6. Repete para o próximo passo
 
 **Em projetos com Laravel especificamente:**
 - Form Requests para validação (nunca inline no controller)
@@ -505,7 +534,7 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 
 **O que faz:**
 - Revisa o código implementado
-- Escreve testes unitários e de integração
+- Escreve testes para achados Critical e High
 - 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`
@@ -516,10 +545,92 @@ Depois disso, ela passa a ser parte real do pacote local da squad e deve ser con
 ```
 
 **Entrega:**
-- Suite de testes
-- Lista de problemas encontrados
+- Lista de problemas encontrados por severidade
+- Testes para achados críticos
 - Relatório de cobertura
 
+> **@qa vs @tester** — O `@qa` é um revisor: lê o que foi implementado, aponta riscos e escreve testes pontuais para achados críticos. O `@tester` é um engenheiro de testes: parte de cobertura zero e constrói uma estratégia sistemática (inventário, mapa de risco, estratégia por camada). Use `@tester` quando a aplicação foi implementada sem testes adequados ou quando `@qa` identificar lacunas em 3+ módulos.
+
+---
+
+## @tester
+
+**Quando usar:** Após `@dev`, quando a aplicação foi implementada sem testes adequados. Também em projetos legados ou quando `@qa` identificar cobertura insuficiente em múltiplos módulos.
+
+**O que faz:**
+- Produz um inventário completo de cobertura (`test-inventory.md`)
+- Mapeia regras de negócio descobertas vs testes existentes, priorizando por risco
+- Escolhe e documenta a estratégia de teste antes de escrever qualquer linha
+- Escreve testes por módulo em ordem de prioridade, com commit atômico por módulo
+- Gera relatório de cobertura antes vs depois
+
+**Estratégias disponíveis:**
+
+| Cenário | Estratégia |
+|---|---|
+| Código legado sem testes, precisa refatorar | Characterization Testing |
+| App implementada, cobertura zero | Test Pyramid Bottom-up |
+| Cobertura razoável, regras descobertas | Risk-first Gap Filling |
+| Código crítico com edge cases complexos | Property-based Testing |
+| APIs entre times | Contract Testing |
+| Suspeita de testes fracos que sempre passam | Mutation Testing |
+
+**Frameworks detectados automaticamente por stack:**
+
+| Stack | Test Runner | Unit | Integration | E2E |
+|---|---|---|---|---|
+| Laravel | Pest PHP | Pest unit | Pest feature (HTTP) | Dusk/Playwright |
+| Next.js | Vitest | Vitest + RTL | MSW + Vitest | Playwright |
+| Django | pytest-django | pytest | pytest + client | Playwright |
+| FastAPI | pytest + httpx | pytest | AsyncClient | — |
+| Rails | RSpec | RSpec unit | Request specs | Capybara |
+| Solidity | Foundry | forge unit | forge integration | — |
+
+**Como ativar:**
+```
+/tester
+```
+
+**Entrega:**
+- `.aioson/context/test-inventory.md` — mapa de cobertura por arquivo
+- `.aioson/context/test-plan.md` — estratégia escolhida + cobertura antes/depois
+- Testes escritos por módulo, commitados incrementalmente
+
+**Restrições:**
+- Nunca modifica código de produção
+- Se encontrar um bug real: documenta em `test-plan.md` e para — não corrige silenciosamente
+- Testes sem assertions são proibidos
+
+---
+
+## @sheldon
+
+**Quando usar:** Após `@product`, antes de iniciar a cadeia de execução — para garantir que o PRD está completo, sem lacunas e pronto para gerar código correto.
+
+**O que faz:**
+- Detecta documentos de entrada na raiz (`plans/*.md`, `prds/*.md`) e oferece incorporá-los ao enriquecimento do PRD
+- Analisa o PRD por prioridade de melhorias
+- Decide entre enriquecimento in-place ou plano de fases externo
+- Valida se o PRD está legível e implementável antes de ativar `@dev`
+
+**Modos de operação:**
+
+| Modo | Como ativar | O que faz |
+|---|---|---|
+| A — Enriquecimento (padrão) | `/sheldon` | Analisa o PRD alvo e sugere melhorias prioritárias |
+| B — Revisão Global | `/sheldon` + "revisão geral" | Escaneia todos os PRDs e planos ativos |
+| C — Validação Completa | `/sheldon` + "validar" ou "preparar para dev" | Auditoria completa + checklist final antes de codar |
+
+**Como ativar:**
+```
+/sheldon
+```
+
+**Entrega:**
+- PRD enriquecido in-place (Modo A)
+- Relatório de status de todos os PRDs (Modo B)
+- Checklist de validação + decisão go/no-go para implementação (Modo C)
+
 ---
 
 ## Resumo: fluxo por tamanho
@@ -532,15 +643,18 @@ Duração típica: minutos a horas. Sem análise, sem arquitetura formal.
 
 ### SMALL
 ```
-@setup → @product → @analyst → @architect → @ux-ui → @dev → @qa
+@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]
 ```
 Duração típica: horas a dias. Análise leve, estrutura clara.
 
 ### MEDIUM
 ```
-@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa
+@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa → [@tester]
 ```
-Duração típica: dias a semanas. Análise completa, parallelismo, backlog formal.
+Duração típica: dias a semanas. Análise completa, paralelismo, backlog formal.
+
+`[@sheldon]` — opcional, recomendado antes de iniciar a cadeia de execução para validar o PRD.
+`[@tester]` — opcional, recomendado quando a cobertura de testes for insuficiente após `@dev`.
 
 ---
 

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)

package/docs/pt/comandos-cli.md

@@ -77,6 +77,13 @@
 | `qa:scan` | Faz crawl automático do app e procura riscos | Quando quer inspeção ampla de rotas |
 | `qa:report` | Reexibe ou exporta o último relatório | Quando quer consultar ou regenerar o relatório |
 
+### Web nativa
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `web:map` | Descobre URLs internas de um site por crawl simples | Quando quer mapear docs, páginas públicas ou áreas navegáveis sem serviço externo |
+| `web:scrape` | Extrai conteúdo principal de uma página em markdown, text, html ou links | Quando quer transformar HTML em contexto utilizável para agentes |
+
 ### Genomes e squads
 
 | Comando | O que faz | Quando usar |
@@ -90,6 +97,13 @@
 | `squad:export` | Exporta uma squad local para snapshot/entrega | Quando quer empacotar a squad |
 | `squad:pipeline` | Lista, inspeciona ou acompanha pipelines declarados na squad | Quando a squad define pipelines reutilizáveis |
 | `squad:agent-create` | Cria agente customizado em `.aioson/my-agents/` ou dentro de uma squad | Quando quer criar agente personalizado. Veja [Agentes Customizados](./agentes-customizados.md) |
+| `squad:dashboard` | Painel web local para monitorar squads em tempo real | Quando quer ver agentes rodando, contexto, tokens e métricas. Veja [Squad Dashboard](./squad-dashboard.md) |
+| `squad:worker` | Executa, lista e testa workers não-LLM de uma squad | Quando quer rodar workers determinísticos manualmente |
+| `squad:daemon` | Inicia/para/monitora daemon de workers automáticos | Quando quer execução 24/7 com cron e webhooks |
+| `squad:mcp` | Configura e testa conectores MCP (WhatsApp, Telegram, etc.) | Quando quer integrar canais reais à squad |
+| `squad:roi` | Define modelo de precificação e registra métricas de resultado | Quando quer calcular e reportar ROI da squad |
+| `squad:processes` | Lista e encerra processos ativos de uma squad | Quando quer inspecionar ou parar agentes sem usar o dashboard |
+| `squad:recovery` | Gera contexto de recovery para reinjecting após compact | Quando um agente perdeu contexto após compactação |
 | `output-strategy:export` | Exporta a estratégia de output (webhooks, delivery) de uma squad | Quando quer copiar configuração para outra squad ou documentar |
 | `output-strategy:import` | Importa estratégia de output de um arquivo ou outra squad | Quando quer replicar webhooks/delivery entre squads |
 | `deliver` | Dispara delivery manual de conteúdo para webhooks configurados | Quando quer reenviar conteúdo ou testar webhooks |
@@ -519,7 +533,52 @@ Use:
 - `squad:export` para empacotar a squad
 - `squad:pipeline` para inspecionar pipelines definidos dentro da squad
 
-### 18. Reparar bindings de genome em squads
+### 18. Monitorar squads com o Squad Dashboard
+
+```bash
+# Levantar o dashboard na raiz do projeto
+aioson squad:dashboard
+
+# Porta customizada
+aioson squad:dashboard --port=4200
+
+# Abrir direto em um squad específico
+aioson squad:dashboard --squad=marketing-odonto
+```
+
+Acesse `http://localhost:4180` no browser. O dashboard mostra todos os squads do projeto com agentes rodando, uso de contexto, tokens, logs de execução e métricas em tempo real.
+
+Para documentação completa: [Squad Dashboard](./squad-dashboard.md)
+
+### 19. Workers, Daemon e Integrações
+
+```bash
+# Listar workers de uma squad
+aioson squad:worker . --sub=list --squad=clinica
+
+# Executar um worker manualmente
+aioson squad:worker . --sub=run --squad=clinica --worker=confirma-consulta --input='{"phone":"5511999999999"}'
+
+# Iniciar daemon (workers automáticos 24/7)
+aioson squad:daemon . --sub=start --squad=clinica
+
+# Ver status do daemon
+aioson squad:daemon . --sub=status
+
+# Configurar integração WhatsApp
+aioson squad:mcp . --sub=configure --squad=clinica --mcp=whatsapp --connector=whatsapp-business
+
+# Testar conexão
+aioson squad:mcp . --sub=test --squad=clinica --mcp=whatsapp
+
+# Registrar métrica de ROI
+aioson squad:roi . --sub=metric --squad=clinica --key=no_show_rate --value=8 --unit=% --baseline=20 --target=5
+
+# Ver relatório de ROI
+aioson squad:roi . --sub=report --squad=clinica
+```
+
+### 20. Reparar bindings de genome em squads
 
 ```bash
 aioson squad:repair-genomes .aioson/squads/marketing/squad.manifest.json --write

package/docs/pt/inicio-rapido.md

@@ -129,8 +129,24 @@ Se voce estiver entrando num projeto ja existente e quiser um companheiro tecnic
 | Tamanho do projeto | Sequência de agentes |
 |---|---|
 | **MICRO** — 0–1 ponto | `@setup → @dev` |
-| **SMALL** — 2–3 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @dev → @qa` |
-| **MEDIUM** — 4–6 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa` |
+| **SMALL** — 2–3 pontos | `@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]` |
+| **MEDIUM** — 4–6 pontos | `@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa → [@tester]` |
+
+`[@sheldon]` — opcional, recomendado para validar e enriquecer o PRD antes de codar.
+`[@tester]` — opcional, para cobertura sistemática quando o `@dev` implementou sem testes adequados.
+
+### Estratégia de documentos de kickoff
+
+Antes de ativar `@product`, você pode criar arquivos de entrada na raiz do projeto:
+
+```
+plans/minha-ideia.md     ← suas notas brutas, esboços, referências
+prds/visao-produto.md    ← rascunhos de requisitos, inspirações
+```
+
+O `@product` e o `@sheldon` detectam esses arquivos automaticamente e perguntam se devem usá-los como fonte para gerar os artefatos formais em `.aioson/context/`. Os arquivos originais nunca são modificados — você decide quando deletá-los.
+
+Esses arquivos de kickoff **não são versionados por padrão** (estão no `.gitignore`). Eles são documentos de trabalho do desenvolvedor, não artefatos do projeto.
 
 ### Atalho recomendado quando o escopo ainda está nebuloso