@jaimevalasek/aioson 1.3.0 → 1.5.1

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
 
 ---
 
@@ -72,11 +90,28 @@ O AIOSON tem agentes oficiais de projeto e também pode criar agentes de squad.
 **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
 - 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`
+
+**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:**
 ```
@@ -95,6 +130,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 +199,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 +268,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 +295,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 +308,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 +351,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 +436,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 +470,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)
 
 ---
 
@@ -384,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)
@@ -408,9 +534,10 @@ 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`
 
 **Como ativar:**
 ```
@@ -418,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
@@ -434,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`.
 
 ---