@jaimevalasek/aioson 1.33.1 → 1.37.0

package/docs/pt/4-agentes/orchestrator.md

@@ -1,118 +1,176 @@
-# @orchestrator — Coordene lanes paralelas em projetos MEDIUM
-
-> **Para quem é:** quem trabalha em projetos MEDIUM e precisa dividir a implementação em frentes paralelas.
-> **Tempo de leitura:** 4 min.
-> **O que você vai sair sabendo:**
-> - O que é uma "lane" e quando paralelizar faz sentido
-> - Comandos CLI do sistema de lanes
-
----
-
-## Para que serve
-
-Em projetos MEDIUM, a implementação pode ser grande o suficiente para ter partes independentes — backend de autenticação e frontend de listagem, por exemplo — que podem acontecer em paralelo sem conflito. Tentar fazer isso manualmente sem coordenação é receita para conflitos de merge e arquivos sobrescritos.
-
-`@orchestrator` divide o trabalho em **lanes** (faixas de execução): cada lane tem seu escopo, seus arquivos permitidos, e seu estado independente. Ele garante que as lanes não escrevam nos mesmos arquivos e coordena o merge no final.
-
-**Regra dura:** `@orchestrator` só ativa em projetos MEDIUM. Para MICRO e SMALL, execução sequencial é o suficiente.
-
----
-
-## Quando invocar
-
-- Projetos MEDIUM, após `@pm`, quando há implementação paralelizável.
-- Quando você tem múltiplos devs (humanos ou IAs) trabalhando na mesma feature.
-- Quando uma feature tem frentes claramente independentes (ex: API + UI + migrations).
-
----
-
-## Quando NÃO invocar
-
-- Projeto MICRO ou SMALL → ele mesmo recusa e te avisa.
-- A feature tem dependências lineares fortes → implemente sequencialmente com `@dev`.
-
----
-
-## Diálogo típico
-
-```
-Você > @orchestrator
-
-@orchestrator > Verificando classificação... MEDIUM. OK.
-                Lendo architecture.md, tasks.md, ui-spec.md...
-                
-                Dividindo em 3 lanes:
-                Lane 1 — backend
-                  Escopo: src/models/payment.js, src/services/payment-service.js, src/routes/checkout.js
-                Lane 2 — frontend
-                  Escopo: src/views/checkout/, src/components/PaymentForm/
-                Lane 3 — migrations
-                  Escopo: db/migrations/add-payment-table.sql
-                
-                Guard configurado: lanes não podem escrever fora do próprio escopo.
-                
-                $ aioson parallel:init .          ✓
-                $ aioson parallel:assign .        ✓
-                Workspace pronto em .aioson/context/parallel/
-                
-                Quando terminar cada lane, rode:
-                  aioson parallel:status .
-                  aioson parallel:merge . --apply
-```
-
----
-
-## Saídas em disco
-
-| Arquivo/Diretório | Conteúdo |
-|---|---|
-| `.aioson/context/parallel/lane-1.md` | Escopo e estado da lane 1 |
-| `.aioson/context/parallel/lane-2.md` | Escopo e estado da lane 2 |
-| `.aioson/context/parallel/lane-N.md` | ... |
-
----
-
-## Como ele lê seu projeto
-
-- `.aioson/context/project.context.md` — confirma `classification: MEDIUM`
-- `.aioson/context/discovery.md`, `architecture.md`, `prd.md`, `ui-spec.md`
-- `.aioson/context/implementation-plan-{slug}.md` — se existir
-- `.aioson/context/parallel/` — ao retomar sessão
-
----
-
-## Comandos CLI relacionados
-
-```bash
-# Inicializar workspace de lanes
-aioson parallel:init .
-
-# Distribuir escopos
-aioson parallel:assign .
-
-# Ver progresso de cada lane
-aioson parallel:status .
-
-# Validar que uma lane está autorizada a escrever num arquivo
-aioson parallel:guard . --lane=1 --paths=src/models/payment.js
-
-# Merge final (só quando todas as lanes estão prontas)
-aioson parallel:merge . --apply
-
-# Corrigir workspace quebrado
-aioson parallel:doctor . --fix
-```
-
----
-
-## Handoff típico
-
-- **Vem de:** `@pm`
-- **Vai para:** `@dev` (em cada lane)
-
----
-
-## Próximo passo
-
-- [Ficha do @dev](./dev.md) — executa dentro de cada lane
-- [Decisões iniciais: MEDIUM](../2-comecar/decisoes-iniciais.md#medium--workflow-completo)
+# @orchestrator — Maestro de spec para projetos MEDIUM
+
+> **Para quem é:** quem trabalha em projetos MEDIUM e precisa de uma autoridade única de spec que coordene a fase de descoberta e planejamento.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:**
+> - Por que `@orchestrator` é o maestro do MEDIUM (não apenas coordenador de execução)
+> - Como funciona o fan-out para sub-agentes e a consolidação do pacote de spec
+> - Quando (e como) usar lanes paralelas pós-spec
+
+---
+
+## Para que serve
+
+Em projetos MEDIUM, a especificação envolve múltiplas dimensões — domínio, arquitetura, UX, backlog — que precisam ser coordenadas e verificadas antes que o `@dev` comece. Tentar gerenciar cada agente de spec manualmente, em sequência, é lento e sujeito a drift entre artefatos.
+
+`@orchestrator` assume o papel de **maestro de spec**: ele dispara `@analyst`, `@architect` e `@pm` (e `@ux-ui` quando a feature tem UI pesada) como **sub-agentes em fan-out**, depois **consolida, verifica e retrabaha** os artefatos deles num único pacote de spec validado — com Gates A/B/C aprovados — e só então passa o bastão para o `@dev`.
+
+**Regra dura:** `@orchestrator` só ativa em projetos MEDIUM. Para MICRO e SMALL, o `@sheldon` cobre a spec sozinho.
+
+> SMALL = `@sheldon` (vertical, solo). MEDIUM = `@orchestrator` (horizontal, fan-out). Mesma ideia — uma autoridade única de spec — formas diferentes.
+
+---
+
+## O papel duplo do `@orchestrator`
+
+### 1. Maestro de spec (papel principal no MEDIUM)
+
+Sequência padrão da lane MEDIUM:
+
+```
+@product → @orchestrator → @dev → @pentester → @qa
+```
+
+O `@orchestrator`:
+1. Lê o PRD e confirma classificação MEDIUM.
+2. (Opcional) Dispara `@sheldon` como pré-etapa para endurecer o PRD antes do fan-out.
+3. Fan-out: dispara `@analyst` + `@architect` + `@pm` como sub-agentes (+ `@ux-ui` se UI-heavy).
+4. Consolida os artefatos recebidos.
+5. Verifica consistência entre eles (detecta drift, gaps, conflitos).
+6. Retrabaha as inconsistências detectadas.
+7. Produz o pacote de spec consolidado (Gates A/B/C + plano de implementação faseado + harness-contract).
+8. Passa para `@dev`.
+
+### 2. Coordenador de lanes paralelas (papel secundário, pós-spec)
+
+Quando a implementação de uma feature MEDIUM tem frentes genuinamente independentes — backend, UI, migrations — o `@orchestrator` pode dividir o trabalho em **lanes** após o pacote de spec estar consolidado:
+
+- Cada lane tem escopo próprio, arquivos permitidos e estado independente.
+- `@dev` implementa uma lane por sessão.
+- `aioson parallel:merge` faz o merge determinístico no final.
+
+---
+
+## Quando invocar
+
+- Projetos MEDIUM, após `@product` (pacote de spec ainda não existe).
+- Quando você quer que a fase de spec rode de forma coordenada, com verificação cruzada entre sub-agentes, sem gerenciar cada um manualmente.
+
+---
+
+## Quando NÃO invocar
+
+- Projeto MICRO ou SMALL → `@sheldon` cobre sozinho; `@orchestrator` recusa e avisa.
+- Feature com pacote de spec já consolidado e você só quer dividir a implementação em lanes → use `aioson parallel:init` diretamente.
+
+---
+
+## Diálogo típico
+
+```
+Você > @orchestrator
+
+@orchestrator > Verificando classificação... MEDIUM. Confirmado.
+                Lendo prd-mvp.md...
+                
+                Iniciando fan-out de spec:
+                ├── @analyst   → mapeamento de domínio e entidades
+                ├── @architect → estrutura técnica, libs, integração
+                └── @pm        → backlog, user stories, plano de implementação
+                
+                (+ @ux-ui — feature tem UI pesada, adicionando ao fan-out)
+                
+                [sub-agentes executados]
+                
+                Consolidando artefatos...
+                Verificando consistência:
+                ✓ Entidades do @analyst alinhadas com as decisões do @architect
+                ⚠ @pm criou US-07 (notificação SMS) sem AC verificável — retrabalhando
+                ✓ @ux-ui spec alinhada com componentes declarados em architecture.md
+                
+                Gates A/B/C aprovados.
+                Pacote de spec consolidado:
+                  .aioson/context/requirements-mvp.md
+                  .aioson/context/architecture.md
+                  .aioson/context/design-doc-mvp.md
+                  .aioson/context/implementation-plan-mvp.md
+                  .aioson/context/parallel/harness-contract.json
+                
+                Próximo: @dev.
+```
+
+---
+
+## `@sheldon` como pré-etapa (opcional)
+
+Se o PRD tiver gaps ou decisões técnicas difíceis, rode `@sheldon` antes de `@orchestrator` para endurecer o PRD. Também é possível configurar `@orchestrator` para disparar `@sheldon` como um stream do fan-out.
+
+```
+@product → @sheldon (endurecimento de PRD) → @orchestrator → @dev → @pentester → @qa
+```
+
+---
+
+## Autopilot: travessia automática para `@dev`
+
+Sob autopilot (`auto_handoff: true`, esquema já semeado para a feature, ou token `--auto` recebido do `@product`), `@orchestrator` não para no handoff manual: uma vez com o pacote de spec com gates aprovados (Gates A/B/C, readiness pronta) + `dev-state.md` gravados, ele invoca `@dev` diretamente. O fan-out para `@analyst`/`@architect`/`@pm` acontece como sub-agentes internos — eles não viram estágios do workflow, exceto sob um detour opt-in full-chain. Um gate bloqueado ou readiness `blocked` continua sendo parada manual normal. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/orchestrator --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
+## Saídas em disco
+
+| Arquivo/Diretório | Conteúdo |
+|---|---|
+| `.aioson/context/requirements-{slug}.md` | Domínio consolidado (de @analyst) |
+| `.aioson/context/architecture.md` | Decisões técnicas (de @architect) |
+| `.aioson/context/design-doc-{slug}.md` | Spec de UI/UX (de @ux-ui, quando UI-heavy) |
+| `.aioson/context/implementation-plan-{slug}.md` | Plano faseado (de @pm) |
+| `.aioson/context/parallel/harness-contract.json` | Contrato de sucesso (Gates A/B/C) |
+| `.aioson/context/parallel/lane-*.md` | Lanes de execução (quando paralelização é usada) |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — confirma `classification: MEDIUM`
+- `.aioson/context/prd-{slug}.md` — entrada para o fan-out de spec
+- `.aioson/context/parallel/` — ao retomar sessão com lanes já criadas
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Ver progresso de cada lane
+aioson parallel:status .
+
+# Validar que uma lane está autorizada a escrever num arquivo
+aioson parallel:guard . --lane=1 --paths=src/models/payment.js
+
+# Merge final (quando todas as lanes estão prontas)
+aioson parallel:merge . --apply
+
+# Corrigir workspace quebrado
+aioson parallel:doctor . --fix
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@product`
+- **Vai para:** `@dev`
+
+---
+
+## Próximo passo
+
+- [Ficha do @dev](./dev.md) — executa o plano produzido pelo orchestrator
+- [Ficha do @sheldon](./sheldon.md) — autoridade de spec para SMALL; pré-etapa opcional no MEDIUM
+- [Decisões iniciais: MEDIUM](../2-comecar/decisoes-iniciais.md#medium--maestro-lane)

package/docs/pt/4-agentes/pentester.md

@@ -35,10 +35,10 @@ Os dois modos produzem `security-findings-{slug}.json` com a mesma estrutura, ma
 
 ## Quando invocar
 
-- Antes de publicar uma feature para produção.
-- Quando a feature toca autenticação, pagamentos, upload de arquivos, ou dados sensíveis.
-- Quando você quer um audit point de segurança antes de uma release.
+- **MEDIUM (padrão):** `@pentester` é **inline** na lane MEDIUM — entra entre `@dev` e `@qa` como etapa padrão, não apenas opt-in.
+- **SMALL/MICRO (opt-in):** ative manualmente quando a feature toca autenticação, pagamentos, upload de arquivos, ou dados sensíveis.
 - Quando o `@tester` encontrou indícios de problemas de segurança.
+- Quando você quer um audit point de segurança antes de uma release em qualquer tamanho.
 
 ---
 
@@ -117,10 +117,16 @@ Você > checkout-stripe
 
 ---
 
+## Opção `--help`
+
+Uma ativação com `--help` (`/pentester --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Handoff típico
 
-- **Vem de:** você diretamente, ou `@tester` (que encontrou indício)
-- **Vai para:** `@dev` (para corrigir findings HIGH/MEDIUM) → `@qa` (re-validação)
+- **Vem de:** `@dev` (na lane MEDIUM, onde é inline) — ou você diretamente / `@tester` (detour em SMALL/MICRO)
+- **Vai para:** `@dev` (para corrigir findings HIGH/MEDIUM) → `@qa` (re-validação final)
 
 ---
 

package/docs/pt/4-agentes/pm.md

@@ -19,19 +19,27 @@ Sua regra interna de ouro: máximo 2 páginas. Se o output excede isso, ele est
 
 ## Dois contextos de ativação
 
-### 1. Feature workflow MEDIUM (pré-dev — v1.22.0+)
+### 1. Feature workflow MEDIUM — sub-agente do `@orchestrator` (v1.35.0)
 
-No workflow de feature MEDIUM, `@pm` aparece logo antes do `@dev` — após `@discovery-design-doc` e antes do `@scope-check` pré-dev. Aqui sua responsabilidade é produzir o `implementation-plan-{slug}.md` (Gate C) que o `@dev` precisa para começar.
+No workflow MEDIUM padrão (maestro lane), `@pm` é disparado pelo `@orchestrator` como parte do fan-out de spec. O `@orchestrator` consolida e verifica o plano produzido pelo `@pm` antes de passar para `@dev`.
 
 ```
-@analyst → @scope-check → @architect → @discovery-design-doc → @pm → STOP → /dev
+@orchestrator fan-out: @analyst + @architect + @pm + @ux-ui → consolida → @dev
 ```
 
-O Gate C só é aprovado com o plano pronto. Se o `@pm` for pulado em features MEDIUM, o `gate:check --gate=C` vai bloquear o `@dev`.
+O Gate C (plano de implementação aprovado) é verificado pelo `@orchestrator` antes do handoff.
 
-### 2. Projeto MEDIUM (modo tradicional)
+### 2. Detour opt-in (qualquer tamanho)
 
-Para o projeto completo (configuração inicial), `@pm` entra após `@ux-ui` e antes de `@orchestrator` — priorizando e sequenciando as histórias do backlog.
+Quando você quer criar o backlog e plano de implementação manualmente, sem passar pelo `@orchestrator`, pode invocar `@pm` diretamente após a fase de spec. Útil quando o `@sheldon` (SMALL) produziu o plano mas você quer expandir as user stories.
+
+### 3. Fluxo legado (escape hatch full-merged)
+
+Para quem prefere gerenciar cada sub-agente manualmente no MEDIUM:
+
+```
+@analyst → @architect → @discovery-design-doc → @pm → @orchestrator (lanes only) → @dev
+```
 
 ---
 
@@ -117,7 +125,7 @@ aioson workflow:status .
 **Feature MEDIUM (pré-dev):**
 - **Vem de:** `@discovery-design-doc`
 - **Produz:** `implementation-plan-{slug}.md` (Gate C)
-- **Vai para:** STOP — desenvolvedor faz `/compact` e ativa `/dev` quando continuar a mesma feature; usa `/clear` só para reset forte
+- **Vai para:** STOP — desenvolvedor faz `/compact` e ativa `/dev` quando continuar a mesma feature; usa `/clear` só para reset forte
 
 **Projeto MEDIUM (modo completo):**
 - **Vem de:** `@ux-ui`

package/docs/pt/4-agentes/product.md

@@ -65,6 +65,24 @@ Você > Não salvar cartões. Um cartão por pedido. Fora de escopo: parcelament
 
 ---
 
+## Modo de execução: autopilot ou passo a passo
+
+No handoff do PRD, `@product` decide como a feature vai rodar daqui em diante:
+
+- **Token inline (maior precedência, nunca pergunta):** `/product --auto <tarefa>` arma o autopilot para toda a feature; `/product --step <tarefa>` desarma para esta feature (grava a escolha mesmo em projeto "sempre autopilot"). O token é removido do texto da tarefa.
+- **Sem token, com escolha já registrada** (`auto_handoff: true`/`false` no `project.context.md`, ou um esquema já semeado para esta feature): `@product` segue a escolha em silêncio.
+- **Sem token e sem escolha registrada:** `@product` pergunta uma vez, na tela, ao fechar o PRD — *Autopilot (só esta feature)* / *Passo a passo* / *Sempre autopilot neste projeto* (grava `auto_handoff: true`).
+
+Escolhendo autopilot, `@product` semeia o esquema agêntico (`aioson workflow:execute . --feature={slug} --seed`) e invoca automaticamente o próximo agente — `@sheldon` (SMALL), `@orchestrator` (MEDIUM) ou `@dev` (MICRO) — que por sua vez encadeia sozinho até a recomendação de `aioson feature:close`. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md) para a cadeia completa e as condições de parada.
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/product --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
+---
+
 ## Saídas em disco
 
 | Arquivo | Quando cria |
@@ -101,7 +119,7 @@ aioson context:validate .
 ## Handoff típico
 
 - **Vem de:** `@setup` (projeto novo) ou você mesmo (nova feature)
-- **Vai para:** `@analyst` (SMALL/MEDIUM) ou `@dev` (MICRO sem novas entidades)
+- **Vai para:** `@sheldon` (SMALL — lane lean) · `@orchestrator` (MEDIUM — lane maestro) · `@dev` (MICRO)
 
 ---
 

package/docs/pt/4-agentes/qa.md

@@ -90,10 +90,18 @@ Você > @qa
 
 ## Detalhes recentes
 
-**Ciclo autônomo QA→Dev (Mai 2026):** em falhas pequenas e localizadas, `@qa` itera com `@dev` automaticamente, com cap de 2 rodadas. Na terceira falha, para e pede sua intervenção. Isso evita loops infinitos sem perder a agilidade de correções óbvias.
+**Ciclo autônomo QA→Dev (cap 3):** em falhas pequenas e localizadas, `@qa` itera com `@dev` automaticamente, com cap de 3 rodadas (`agentic_policy.review_cycle`). Ao esgotar as tentativas, para e pede sua intervenção. Isso evita loops infinitos sem perder a agilidade de correções óbvias.
 
 **Suporte a Sheldon phased plans:** quando a feature usa um plano por fases, `@qa` valida fase a fase, marcando `qa_approved` só quando todos os Criticals/Highs da fase estão resolvidos.
 
+**`@qa` é o hub do autopilot pós-dev:** sob autopilot (`auto_handoff: true`, esquema semeado, ou token `--auto`), `@qa` não para no PASS — ele encaminha automaticamente para `@tester` (se o trigger de gap de cobertura disparar), `@pentester` (se a superfície é sensível: auth/pagamentos/upload/secrets) e `@validator` (se há harness-contract), nessa ordem, até não sobrar pendência. Só então recomenda `aioson feature:close`. Veja [Autopilot Handoff](../5-referencia/autopilot-handoff.md).
+
+---
+
+## Opção `--help`
+
+Uma ativação com `--help` (`/qa --help`) imprime um resumo rápido — o que faz, quando usar, opções, chamada típica, o que produz, próximo agente — localizado no seu idioma, e para sem executar nada. Fonte: `.aioson/docs/agent-help.md`.
+
 ---
 
 ## Comandos CLI relacionados
@@ -113,7 +121,7 @@ aioson dossier:show . --slug=checkout-stripe
 ## Handoff típico
 
 - **Vem de:** `@dev`
-- **Vai para:** `@validator` (quando há harness-contract) ou encerramento da feature
+- **Vai para:** `@tester` (gap de cobertura) · `@pentester` (superfície sensível) · `@validator` (harness-contract presente) — ou recomendação de `feature:close` quando nada fica pendente
 
 > Desde a v1.24.0, o `@validator` roda `aioson harness:check` **primeiro** (verificação determinística, exit 0 = pass) e julga por LLM só os critérios sem `verification`. Ele é ativado a partir do `validator-prompt.txt` autocontido (critérios + resultados do check + diff vs. base) em **contexto fresco e isolado** — não na sessão que implementou. Ver [Ficha do @validator](./validator.md).
 

package/docs/pt/4-agentes/setup.md

@@ -50,7 +50,9 @@ Você > Stripe e S3 (2)
 Você > Não
 
 @setup > Score: 1 + 1 + 0 = 2 → SMALL.
-         Design system?
+         Sistema visual? Recomendo interface-design guiado pelas suas
+         imagens de referência (extraídas uma única vez em identity.md).
+         Ou um preset instalado:
          [clean-saas-ui · aurora-command-ui · cognitive-core-ui · (outros) · Pular]
 Você > clean-saas-ui