@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/pt/3-receitas/refatoracao-grande.md

@@ -0,0 +1,251 @@
+# Receita: Refatoração grande com segurança
+
+> **Para quem é:** desenvolvedor com um módulo crítico que precisa ser reescrito sem quebrar o que funciona.
+> **Tempo de execução:** 1–3 horas dependendo do tamanho do módulo.
+> **O que você vai ter no fim:** módulo refatorado, testes verdes, decisões documentadas, e rastreio completo do que mudou e por quê.
+
+---
+
+## Cenário
+
+Você herdou um módulo de pagamentos com 800 linhas, zero separação de responsabilidades, e a classe `PaymentService` fazendo desde validação de cartão até envio de email de confirmação. Qualquer mudança é arriscada porque não há testes, e a lógica está toda entrelaçada.
+
+A tentação é refatorar "no escuro" e ver o que quebra. A abordagem AIOSON é diferente:
+1. **`@sheldon`** analisa o módulo e documenta a lógica existente antes de qualquer mudança.
+2. **`@tester`** escreve testes que capturam o comportamento atual (testes como especificação do legado).
+3. **`@dev`** refatora com segurança, guiado pela spec e pelos testes.
+4. **`@qa`** com ciclo autônomo garante que nada quebrou.
+
+O princípio: **nunca refatore sem testes que provem que o comportamento anterior ainda funciona.**
+
+---
+
+## Pré-requisitos
+
+- AIOSON instalado no projeto (se não, siga [Em projeto existente](../2-comecar/projeto-existente.md))
+- O módulo-alvo identificado (ex: `src/services/PaymentService.js`)
+- Claude Code aberto no projeto
+
+---
+
+## Passo 1 — Criar a spec de refatoração com `@product`
+
+Sim, refatoração também começa com spec. Não porque seja burocracia — mas porque você precisa declarar o que o comportamento externo do módulo DEVE continuar sendo, mesmo que o interno mude.
+
+```
+Você > @product
+
+@product > Qual feature/tarefa vamos especificar?
+Você > Refatoração do PaymentService — slug: refactor-payment-service
+
+@product > O problema (por que refatorar)?
+Você > Uma classe de 800 linhas com 12 responsabilidades diferentes.
+       Impossível testar unitariamente. 3 bugs nos últimos 2 meses nela.
+
+@product > O que deve continuar funcionando igual (comportamento externo que não muda)?
+Você > 1. Processar pagamento via Stripe e retornar { success, transactionId }
+       2. Enviar email de confirmação após sucesso
+       3. Registrar tentativa (sucesso ou falha) no banco
+       4. Lançar PaymentError com código se cartão recusado
+
+@product > O que muda internamente?
+Você > Separar em: PaymentGateway, EmailNotifier, PaymentLogger, PaymentOrchestrator
+
+@product > Fora de escopo?
+Você > Não mudar a interface pública (assinatura das funções)
+       Não migrar banco de dados
+       Não trocar de gateway de pagamento
+
+@product > Spec gravada em features/refactor-payment-service/spec.md.
+           Próximo: @sheldon para análise técnica profunda antes de qualquer mudança.
+```
+
+---
+
+## Passo 2 — `@sheldon` analisa o módulo antes de tocar nele
+
+O `@sheldon` é o agente de análise técnica profunda. Aqui ele age como um "arqueólogo" do código — documentando o que a classe faz, quais são seus acoplamentos, e onde estão as armadilhas.
+
+```
+Você > @sheldon
+
+@sheldon > Ativando análise de PRD: refactor-payment-service.
+            [Lê spec.md, examina src/services/PaymentService.js]
+
+@sheldon > Análise completa:
+
+            RESPONSABILIDADES IDENTIFICADAS (12):
+            1. Validar dados do cartão (duplicado com frontend — risco de divergência)
+            2. Criar customer no Stripe se não existe
+            3. Criar charge no Stripe
+            4. Lidar com retry em caso de timeout (lógica inline, sem exponential backoff)
+            5. Enviar email via SendGrid (chamada direta, sem queue)
+            6. Registrar em payment_logs
+            7. Registrar em audit_logs (separado, motivo desconhecido)
+            8. Atualizar order.status
+            9. Disparar evento para analytics (Google Analytics via HTTP direto)
+            10. Verificar fraude (campo fraud_score — parece unused, ver migration 87)
+            11. Formatar erro para o cliente
+            12. Enviar Slack notification em produção
+
+            RISCOS NA REFATORAÇÃO:
+            - Item 10 (fraud_score): código comentado com `// TODO: ativar` — não mexer por ora
+            - Item 9 (analytics): chamada síncrona, se GA cair o pagamento falha — BUG LATENTE
+            - Items 6+7 (dois logs): motivo desconhecido; separar os dois na refatoração pode quebrar relatório legado
+
+            RECOMENDAÇÃO:
+            Refatorar items 1–8 + 11 em 4 classes. Items 9+10+12 extrair como "legado isolado"
+            sem modificar comportamento por enquanto.
+
+@sheldon > Análise gravada em sheldon-enrichment.md.
+            Próximo: @tester para criar testes do comportamento atual antes de qualquer mudança.
+```
+
+---
+
+## Passo 3 — `@tester` escreve testes do comportamento atual
+
+Estes testes não são sobre "o que deveria ser" — são sobre "o que é agora". Se o comportamento atual tem um bug, você testa o bug (e corrige depois, intencionalmente).
+
+```
+Você > @tester
+
+@tester > Analisando PaymentService para engenharia de testes...
+
+@tester > Coverage atual: 0% (sem testes).
+           Quality tier: CRÍTICO — zero cobertura em módulo de pagamento.
+
+@tester > Estratégia: characterization tests — capturar comportamento atual como especificação.
+
+@tester > Criando tests/payment-service.characterization.test.js:
+
+           Cenário 1: pagamento bem-sucedido
+             → mock Stripe: charge criado com sucesso
+             → espera: { success: true, transactionId: 'ch_xxx' }
+             → espera: payment_log inserido
+             → espera: email enviado (SendGrid mock)
+
+           Cenário 2: cartão recusado
+             → mock Stripe: card_declined
+             → espera: PaymentError com código 'card_declined'
+             → espera: payment_log inserido com status 'failed'
+
+           Cenário 3: timeout do Stripe
+             → mock Stripe: timeout na 1ª chamada, sucesso na 2ª (retry)
+             → espera: { success: true } após retry
+
+           [...mais 8 cenários...]
+
+@tester > Executando... 11/11 passando (comportamento atual documentado).
+           Agora você pode refatorar sem medo — se algum destes quebrar, você sabe.
+           test-plan.md atualizado.
+```
+
+---
+
+## Passo 4 — `@dev` refatora com segurança
+
+```
+Você > @dev
+
+@dev > [lê spec, sheldon-enrichment, test-plan, architecture.md]
+
+@dev > Plano de refatoração (baseado na recomendação do @sheldon):
+
+       Criar:
+       src/services/payment/
+         ├── PaymentGateway.js       (items 1, 2, 3, 4, 11)
+         ├── EmailNotifier.js        (item 5)
+         ├── PaymentLogger.js        (items 6 + 7 — mantendo os dois, só encapsulando)
+         ├── OrderUpdater.js         (item 8)
+         └── PaymentOrchestrator.js  (coordena os 4 acima)
+
+       Manter intocado (legado isolado):
+         src/services/payment/legacy/
+           ├── AnalyticsNotifier.js  (item 9 — bug latente isolado)
+           ├── FraudChecker.js       (item 10 — TODO preservado)
+           └── SlackNotifier.js      (item 12)
+
+       Manter interface pública:
+         src/services/PaymentService.js → re-exporta PaymentOrchestrator
+
+@dev > Implementando...
+       Rodando tests/payment-service.characterization.test.js após cada passo...
+       PaymentGateway: 11/11 ainda passando ✓
+       EmailNotifier: 11/11 ✓
+       PaymentLogger: 11/11 ✓
+       [...]
+       Refatoração concluída. 11/11 ✓
+       dev-state.md atualizado.
+```
+
+---
+
+## Passo 5 — `@qa` valida com ciclo autônomo
+
+```
+Você > @qa
+
+@qa > Rodando suite completa (characterization + novos testes de integração)...
+       Characterization: 11/11 ✓
+       Integração: PaymentOrchestrator chamando os 4 sub-serviços — ok
+       Edge cases: Stripe timeout com retry — ok
+
+       Encontrei 1 problema:
+       PaymentLogger está logando em payment_logs mas não em audit_logs quando status=failed.
+       Era assim no original? Verificando...
+
+       [compara com sheldon-enrichment.md]
+       Sim, o original logava nos dois. Regressão.
+
+@qa > Ciclo autônomo QA→Dev (iteração 1/2):
+       Reportando para @dev...
+@dev > Corrigindo PaymentLogger.js: ambos os logs no failure.
+@qa > Re-rodando... 11/11 characterization + integração OK. Nenhuma regressão.
+      qa-report-test-coverage.md salvo.
+```
+
+---
+
+## O que ficou em disco (rastreio)
+
+```
+.aioson/context/
+├── features/
+│   └── refactor-payment-service/
+│       └── spec.md                  ← o que muda, o que não muda, fora-de-escopo
+├── sheldon-enrichment.md            ← análise das 12 responsabilidades + riscos
+├── test-plan.md                     ← 11 characterization tests
+├── dev-state.md                     ← estrutura nova (4 classes + legado isolado)
+└── qa-report-test-coverage.md       ← 11/11 passando, 1 regressão detectada e corrigida
+```
+
+---
+
+## Variações
+
+| Situação | Ajuste |
+|---|---|
+| Já tenho testes existentes | `@tester` analisa os existentes antes de criar novos. Quality tier indica gaps. |
+| Módulo de 3.000+ linhas | `@orchestrator` divide em lanes paralelas. Cada lane refatora um grupo de responsabilidades. |
+| Posso introduzir breaking changes na interface | Declare isso no `@product` como AC. O `@dev` atualizará todos os chamadores. |
+| Quero refatorar banco de dados também | Escopo separado — crie outra feature slug para o migration. Não misture na mesma spec. |
+
+---
+
+## Solução de problemas
+
+| Problema | Solução |
+|---|---|
+| Characterization tests falhando antes de refatorar | Sinal de que o ambiente de teste não está configurado. Verifique mocks de Stripe/SendGrid. |
+| `@sheldon` não achou riscos | Diga explicitamente: "Analise acoplamentos e dependências ocultas". Ele vai mais fundo. |
+| `@dev` mudou a interface pública por engano | O spec.md diz explicitamente "não mudar interface". Mostre para `@dev`. |
+| QA→Dev ciclo não convergiu em 2 iterações | Ative `@deyvin` para debug manual em pair. |
+
+---
+
+## Próximo passo
+
+- Antes de ir para produção, faça uma auditoria: → [Auditoria de segurança](./auditoria-seguranca.md)
+- Sessão longa e complexa? Use dossier para rastreio: → [Continuidade entre sessões](./continuidade-entre-sessoes.md)
+- Quer entender melhor o `@sheldon`? Veja [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md).

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

@@ -0,0 +1,65 @@
+# Guia de Agentes AIOSON
+
+> Índice completo dos 28 agentes, com situação de uso e saída esperada.
+> Cada agente tem sua ficha — clique no nome para detalhes.
+
+---
+
+## Núcleo de desenvolvimento (neste diretório)
+
+| Agente | Para que serve | Quando invocar | Saída principal |
+|---|---|---|---|
+| [@product](./product.md) | Define visão, PRD e escopo da feature | Início de projeto ou nova feature | `prd.md`, `spec.md` |
+| [@analyst](./analyst.md) | Descobre domínio, entidades, fluxos | Após `@product`, antes de `@architect` | `architecture.md` (domínio) |
+| [@architect](./architect.md) | Decide stack, estrutura, integração técnica | Após `@analyst` | `architecture.md` (técnico) |
+| [@ux-ui](./ux-ui.md) | Design system e specs de componentes | MEDIUM, após `@architect` | `design-doc.md`, `discovery.md` |
+| [@pm](./pm.md) | Backlog, user stories, ACs detalhados | MEDIUM, após `@ux-ui` | `tasks.md` |
+| [@orchestrator](./orchestrator.md) | Coordena lanes paralelas de implementação | MEDIUM, após `@pm` | `.aioson/context/parallel/` |
+| [@dev](./dev.md) | Implementa a feature | Após planning completo | código + `dev-state.md` |
+| [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
+| [@validator](./validator.md) | Gate final: valida contrato binário de sucesso | Após `@qa`, antes de fechar feature | veredicto em `last-handoff.json` |
+| [@tester](./tester.md) | Engenharia de testes para apps já existentes | Legacy/brownfield ou lacunas graves | `test-inventory.md` |
+| [@pentester](./pentester.md) | Revisão adversarial de segurança | Antes de publicar ou por demanda | `security-findings-*.json` |
+
+---
+
+## Boot e roteamento
+
+| Agente | Para que serve | Quando invocar | Saída principal |
+|---|---|---|---|
+| [@setup](./setup.md) | Onboarding: detecta stack, classifica projeto | Sempre primeiro num projeto novo | `project.context.md` |
+| [@neo](./neo.md) | Roteador: diz qual agente é o próximo | Quando você está perdido | Orientação verbal |
+| [@briefing](./briefing.md) | Transforma anotações soltas em briefing pré-PRD | Antes de `@product`, quando ideia ainda vaga | `briefing.md` |
+| [@deyvin](./deyvin.md) | Pair-programming e continuidade de sessão | Retomar feature interrompida | continuação do trabalho |
+| [@pair](./deyvin.md) | Alias de `@deyvin` | — | — |
+| [@sheldon](./sheldon.md) | Análise técnica profunda, revisão de arquitetura | Decisões grandes, código legado | relatório de revisão |
+| [@committer](./committer.md) | Gera mensagem de commit profissional | Após implementar, antes de commitar | mensagem de commit |
+| [@discover](./discover.md) | Constrói cache semântico do projeto | Onboarding em codebase grande | `.aioson/context/bootstrap/` |
+
+---
+
+## Especializações
+
+| Agente | Para que serve | Quando invocar | Saída principal |
+|---|---|---|---|
+| [@squad](./squad.md) | Cria e gerencia squads customizados de agentes | Domínio fora do padrão AIOSON | squad em `.aioson/squads/` |
+| [@genome](./genome.md) | Cria DNA cognitivo de uma persona (Genome 4.0) | Antes de forjar um advisor | `genome.yaml` |
+| [@profiler-researcher](./profiler-researcher.md) | Coleta material bruto sobre pessoa pública | Passo 1 do pipeline Profiler | notas de pesquisa |
+| [@profiler-enricher](./profiler-enricher.md) | Analisa cognitivamente o material | Passo 2 do pipeline Profiler | análise DISC/Enneagram/MBTI |
+| [@profiler-forge](./profiler-forge.md) | Gera Genome 4.0 e advisor | Passo 3 do pipeline Profiler | `genome.yaml`, advisor |
+| [@site-forge](./site-forge.md) | Clona, reconstrói ou extrai design de URL | Quando quer replicar ou inspirar-se num site | arquivos clonados, design skill |
+| [@design-hybrid-forge](./design-hybrid-forge.md) | Combina dois design skills num híbrido | Quer visual que não existe nos padrões | novo design skill |
+| [@orache](./orache.md) | Investigação de domínio e pesquisa estratégica | Antes de entrar num mercado novo | relatório de domínio |
+| [@copywriter](./copywriter.md) | Copy de conversão: landing pages, emails | Quando precisa de texto que converte | copy entregável |
+| [@discovery-design-doc](./discovery-design-doc.md) | Discovery + design doc combinados | Projetos que precisam dos dois de uma vez | `discovery.md` + `design-doc.md` |
+
+---
+
+## Como escolher o agente certo
+
+Se você não sabe qual agente invocar, use `@neo` — ele lê o estado do projeto e te orienta.
+
+Veja também:
+- [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md) — diagrama visual do ciclo de vida
+- [Decisões iniciais](../2-comecar/decisoes-iniciais.md) — MICRO, SMALL ou MEDIUM?
+- [Glossário](../1-entender/glossario.md) — definições de termos como Dossier, Handoff, Constitution

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

@@ -0,0 +1,111 @@
+# @analyst — Descubra o domínio antes de implementar
+
+> **Para quem é:** quem vai implementar uma feature e precisa saber exatamente o que existe no codebase e quais entidades estão envolvidas.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Qual o papel de `@analyst` no fluxo
+> - Quais artefatos ele produz e como downstream os usa
+
+---
+
+## Para que serve
+
+Implementar sem descobrir o domínio é como reformar um apartamento sem ver a planta: você pode quebrar uma parede que esconde encanamento.
+
+`@analyst` lê a spec produzida por `@product` e mergulha no codebase para descobrir: quais entidades já existem, quais fluxos já estão implementados, quais regras de negócio estão implícitas no código. Ele produz um mapa de domínio que impede o `@dev` de duplicar entidades, criar conflitos de schema, ou ignorar regras que já existem.
+
+Em projetos com `@discover` já rodado, o `@analyst` usa o cache semântico em vez de varrer o código todo — economizando muito contexto.
+
+---
+
+## Quando invocar
+
+- Logo após `@product`, em fluxos SMALL e MEDIUM.
+- Quando uma nova feature toca entidades existentes e você quer garantir que não há conflito.
+- Quando alguém novo entra no projeto e precisa entender o domínio rapidamente.
+- Quando a spec mudou e você quer sincronizar o mapeamento de domínio.
+
+---
+
+## Quando NÃO invocar
+
+- Projeto MICRO sem novas entidades → o `@dev` lê o contexto direto.
+- Você quer rever decisões técnicas (não de domínio) → invoke `@architect`.
+- A feature não toca modelo de dados e não tem fluxos novos → pule direto para `@architect`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @analyst
+
+@analyst > Lendo prd-checkout-stripe.md e spec-checkout-stripe.md...
+           Verificando se requirements-checkout-stripe.md já existe... não existe.
+           
+           Mapeando domínio...
+           
+           Entidades encontradas no codebase:
+           - Customer { id, email, name, tier }      ← já existe em src/models/customer.js
+           - Order { id, customer_id, total, status } ← já existe em src/models/order.js
+           - Payment                                  ← NÃO existe — nova entidade necessária
+           
+           Fluxos mapeados:
+           - Criação de pedido: Order ← Customer (many-to-one) ✓
+           - Pagamento: Payment ← Order (one-to-one) — a implementar
+           
+           Regras de negócio detectadas no código:
+           - Order.status aceita: ['pending','paid','cancelled'] — Payment deve respeitar isso
+           
+           Artefatos criados:
+           - .aioson/context/requirements-checkout-stripe.md
+           Próximo: @architect.
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/discovery.md` | Mapa de domínio geral do projeto (novo projeto) |
+| `.aioson/context/requirements-{slug}.md` | Entidades, regras, edge cases da feature |
+| `.aioson/context/architecture.md` | Contribuição de domínio (enriquecido junto com `@architect`) |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — stack, classificação
+- `.aioson/context/prd-{slug}.md` e `spec-{slug}.md` — escopo da feature
+- `.aioson/context/bootstrap/` — cache semântico do `@discover` (se existir)
+- `.aioson/rules/` — regras com `agents: analyst`
+- Código-fonte diretamente (models, schemas, services) — quando não há cache
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Verificar se requirements estão atualizados em relação ao PRD
+aioson plan:stale . --feature=checkout-stripe
+
+# Validar contexto antes de iniciar
+aioson context:validate .
+aioson workflow:status .
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@product`
+- **Vai para:** `@architect`
+
+---
+
+## Próximo passo
+
+- [Ficha do @architect](./architect.md)
+- [O que é o cache do @discover](../1-entender/glossario.md#discover)
+- [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)

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

@@ -0,0 +1,113 @@
+# @architect — Decida a estrutura técnica antes de escrever código
+
+> **Para quem é:** quem vai implementar e quer garantir que as decisões de stack, pastas e integração estejam tomadas antes de o `@dev` começar.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Que decisões `@architect` toma (e o que ele deixa para `@dev`)
+> - Como ele se conecta com `@analyst` e `@dev`
+
+---
+
+## Para que serve
+
+Um dev experiente não começa a codar antes de perguntar: "onde esse arquivo vai morar? quais libs vamos usar? como isso se integra com o que já existe?". Essas perguntas respondidas na ponta de um rascunho custam pouco. Respondidas depois de 300 linhas implementadas, custam refatoração.
+
+`@architect` transforma o mapa de domínio do `@analyst` em **decisões técnicas concretas**: estrutura de pastas, escolha de bibliotecas, estratégia de integração, padrões de código a seguir. Ele não escreve código — ele define as regras que o `@dev` vai seguir.
+
+Ele também contribui no `dossier` da feature, registrando os arquivos-chave no code map para que qualquer agente subsequente saiba onde olhar.
+
+---
+
+## Quando invocar
+
+- Após `@analyst`, em fluxos SMALL e MEDIUM.
+- Quando a feature envolve decisões de integração com APIs externas ou novos módulos.
+- Quando você quer garantir consistência com o padrão de pastas do projeto antes de implementar.
+- Quando há um plano Sheldon (`@sheldon` foi invocado antes) — `@architect` lê o plano por fases.
+
+---
+
+## Quando NÃO invocar
+
+- Feature MICRO sem decisões novas → `@dev` infere do contexto existente.
+- Você só quer adicionar um campo a uma entidade existente → `@dev` lida sozinho.
+- Você quer revisar a arquitetura geral do projeto (não de uma feature) → use `@sheldon`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @architect
+
+@architect > Lendo requirements-checkout-stripe.md e architecture.md...
+             
+             Decisões para a feature checkout-stripe:
+             
+             Estrutura:
+             - src/models/payment.js        ← nova entidade Payment
+             - src/services/payment-service.js  ← lógica de negócio isolada
+             - src/routes/checkout.js        ← rota POST /checkout
+             
+             Biblioteca de integração Stripe:
+             - stripe (npm) — padrão do ecossistema, sem alternativas
+             
+             Padrão de validação:
+             - validação manual em payment-service.js (Article VI — sem lib extra para 2 campos)
+             
+             Integração com Order:
+             - Order.status muda para 'paid' após confirmação Stripe (webhook)
+             
+             Registrando code map no dossier...
+             architecture.md atualizado.
+             Próximo: @dev.
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/architecture.md` | Decisões técnicas: pastas, libs, padrões |
+| `.aioson/context/implementation-plan-{slug}.md` | Plano de implementação (quando cria) |
+| `.aioson/context/features/{slug}/dossier.md` | Code map atualizado (via `dossier:add-codemap`) |
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/requirements-{slug}.md` — entidades e regras do `@analyst`
+- `.aioson/context/architecture.md` — estado atual da arquitetura
+- `.aioson/context/bootstrap/how-it-works.md` e `current-state.md` — quando existem
+- `.aioson/design-docs/*.md` — regras de estrutura de código e naming
+- `.aioson/rules/` — regras com `agents: architect`
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Checar dossier da feature
+aioson dossier:show . --slug=checkout-stripe
+
+# Adicionar arquivo ao code map do dossier
+aioson dossier:add-codemap . --slug=checkout-stripe \
+  --file=src/services/payment-service.js \
+  --role=service --coupling=medium --added-by=architect
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@analyst`
+- **Vai para:** `@ux-ui` (MEDIUM) ou `@dev` (SMALL/MICRO)
+
+---
+
+## Próximo passo
+
+- [Ficha do @dev](./dev.md) — quem executa as decisões
+- [Ficha do @ux-ui](./ux-ui.md) — próximo em MEDIUM
+- [Glossário: Dossier, Design Docs, Constitution](../1-entender/glossario.md)

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

@@ -0,0 +1,95 @@
+# @briefing — Estrutura ideias brutas antes de virar feature
+
+> **Para quem é:** quem tem anotações, planos soltos ou ideias não formalizadas e quer transformá-los em algo acionável.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que é um briefing e por que ele existe antes do PRD.
+> - Como o @briefing usa seus planos como matéria-prima.
+
+## Para que serve
+
+Existe um espaço em branco entre "tive uma ideia" e "vou criar uma feature no AIOSON". Esse espaço é onde muitos projetos erram: a ideia vai direto para `@product` sem estruturação, chegando como requisito vago, com gaps e riscos não identificados.
+
+O `@briefing` preenche esse espaço. Ele lê seus rascunhos em `plans/`, pesquisa o que for necessário, identifica gaps, mapeia riscos, e entrega um documento estruturado — o briefing — que o `@product` (e depois o `@sheldon`) podem usar como ponto de partida qualificado.
+
+Anteriormente chamado de `@cypher`, foi renomeado e enriquecido com frameworks de discovery em Abr/2026 (commit `0d40a4b`).
+
+## Quando invocar
+
+- Você tem arquivos em `plans/` com ideias, pesquisas ou esboços não formalizados.
+- A ideia ainda não está clara o suficiente para virar feature diretamente.
+- Você quer validar premissas de mercado ou técnicas antes de comprometer um PRD.
+- Equipe debateu uma ideia em reunião e as anotações estão soltas.
+
+## Quando NÃO invocar
+
+- A feature já tem spec definida — vá direto para `@product` ou `@analyst`.
+- A ideia é simples e óbvia (MICRO) — não precisa de briefing.
+- Você quer apenas verificar o estado do projeto — use `@neo`.
+
+## Diálogo típico
+
+```
+Você > @briefing
+
+@briefing > Encontrei 3 arquivos em plans/:
+             - plans/ideia-marketplace.md
+             - plans/pesquisa-concorrentes.md
+             - plans/fluxo-pagamentos.md
+
+             Quais devo usar como fonte? (todos ou lista específica)
+Você > Todos.
+
+@briefing > Lendo... Pesquisando validação de premissas técnicas...
+
+             Briefing gerado: .aioson/briefings/marketplace-v1/briefings.md
+
+             Resumo:
+             - Problema: vendedores sem canal de venda digital
+             - Hipóteses validadas: 2/4 (2 precisam de POC técnica)
+             - Gaps identificados: modelo de comissão não especificado,
+               regras de cancelamento ausentes
+             - Riscos: integração com correios pode ter latência alta
+             - Próximo passo recomendado: @product com este briefing como input
+
+             O briefing está pronto para aprovação. Deseja ajustar algo?
+```
+
+## Saídas em disco
+
+| Arquivo | O que contém |
+|---|---|
+| `.aioson/briefings/{slug}/briefings.md` | Briefing estruturado: problema, hipóteses, gaps, riscos, recomendações |
+| `.aioson/briefings/config.md` | Índice de todos os briefings com status (draft/approved/implemented) |
+
+## Como ele lê seu projeto
+
+1. `.aioson/briefings/config.md` — verifica briefings existentes (evita sobrescrever).
+2. `plans/*.md` — matéria-prima principal (seus rascunhos).
+3. `.aioson/context/project.context.md` — contexto do projeto.
+4. `.aioson/context/prd*.md` e `prds/*.md` — evita duplicar trabalho já comprometido.
+5. Web search quando há premissas que precisam de validação externa.
+
+## Handoff típico
+
+- **Vem de:** você, com anotações em `plans/` ou uma ideia conversacional.
+- **Vai para:** `@product` (que usa o briefing como contexto enriquecido no PRD).
+
+## Modo conversacional
+
+Se não existir nada em `plans/`, o `@briefing` entra em modo conversacional — ele te entrevista e constrói o briefing a partir das respostas. Útil quando a ideia ainda está só na sua cabeça.
+
+```
+Você > @briefing
+
+@briefing > Não encontrei arquivos em plans/. Quer planejar a ideia comigo
+            conversacionalmente? Vou fazer perguntas e montar o briefing.
+Você > Sim.
+@briefing > Qual o problema que você quer resolver?
+```
+
+## Próximo passo
+
+- Entender o fluxo completo → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Após o briefing aprovado → [@product](./product.md) *(ficha em construção)*
+- Termos como "gap" e "PRD" → [Glossário](../1-entender/glossario.md)