@jaimevalasek/aioson 1.8.0 → 1.9.1

package/docs/pt/3-receitas/continuidade-entre-sessoes.md

@@ -0,0 +1,303 @@
+# Receita: Continuidade entre sessões
+
+> **Para quem é:** qualquer desenvolvedor que trabalha em features longas distribuídas em múltiplas sessões — e não quer recomeçar do zero toda vez que abre o projeto.
+> **Tempo de execução:** 10 min de setup na primeira vez; quase zero nas sessões seguintes.
+> **O que você vai ter no fim:** toda feature com um dossier em disco — spec, plano, decisões, código tocado, status — que qualquer agente lê e retoma sem precisar reler o histórico de chat.
+
+---
+
+## Cenário
+
+Você estava implementando a feature de checkout com Stripe. Passou três horas com o `@dev`, chegou até 80%, e a sessão do Claude Code encerrou. No dia seguinte, você abre o projeto e pergunta à IA: "onde paramos?" A IA não sabe. Ela tem só o histórico recente, e o contexto de ontem foi compactado.
+
+Isso é o problema do **prompt-monolito**: toda a memória fica na conversa, que é temporária.
+
+O **Feature Dossier** (sistema de agent-chain continuity, implementado em 8 fases entre Mar–Mai/2026) resolve isso. Cada feature tem uma pasta com artefatos persistentes. Quando você retoma, o `@deyvin` lê o dossier e continua de onde parou — sem entrevistar você sobre o que já foi feito.
+
+---
+
+## Pré-requisitos
+
+- AIOSON instalado no projeto
+- Uma feature em andamento (ou prestes a começar)
+- Claude Code aberto no projeto
+
+---
+
+## Como um dossier é criado
+
+O dossier é inicializado automaticamente quando você começa uma feature via o workflow normal (`@product` → `@analyst` → `@dev`). Mas você também pode criá-lo manualmente:
+
+```bash
+npx @jaimevalasek/aioson dossier:init --slug=checkout-stripe
+```
+
+```
+Dossier inicializado em:
+.aioson/context/features/checkout-stripe/
+├── dossier.md          ← documento principal (spec, plano, decisões, trail)
+├── codemap/            ← mapa dos arquivos tocados pela feature
+└── research/           ← índice de pesquisas feitas durante a feature
+```
+
+---
+
+## Anatomy do dossier
+
+```
+.aioson/context/features/checkout-stripe/dossier.md
+```
+
+O arquivo tem seções padronizadas:
+
+```
+## Meta
+slug: checkout-stripe
+status: in_progress
+classification: SMALL
+agents_trail: [@product, @analyst, @architect, @dev]
+last_agent: @dev
+last_updated: 2026-05-06T14:32:00Z
+
+## Spec Summary
+[resumo da spec — o que a feature resolve, ACs principais]
+
+## Plan
+[passos do plano de implementação com checkboxes]
+- [x] Schema do banco (tabela payments)
+- [x] Rota POST /checkout/create-session
+- [ ] Webhook handler /webhooks/stripe
+- [ ] Página de confirmação
+
+## Decisions
+[decisões tomadas durante a feature com justificativa]
+- Usando Stripe Checkout (não Elements) — menor complexidade de PCI
+- Webhook verificado com stripe.webhooks.constructEvent
+
+## Code Map
+[arquivos que fazem parte desta feature]
+- src/routes/checkout.js       (criado)
+- src/services/stripe.js       (criado)
+- src/db/migrations/005_payments.js (criado)
+- src/routes/webhooks.js       (pendente)
+- app/pages/checkout/success.tsx (pendente)
+
+## Agent Trail
+[o que cada agente fez]
+@product: spec criada em 2026-05-05
+@analyst: Payment, Order mapeados
+@architect: Stripe Checkout escolhido, estrutura definida
+@dev: 3/5 passos do plano concluídos
+```
+
+---
+
+## Retomando uma feature — fluxo real
+
+### Sessão nova, agente `@deyvin`
+
+```
+Você > @deyvin
+
+@deyvin > Lendo project-pulse.md... feature checkout-stripe em andamento.
+           Lendo dossier.md...
+
+@deyvin > Aqui está onde você parou:
+
+           FEATURE: checkout-stripe
+           Status: in_progress (80%)
+           Último agente: @dev
+
+           CONCLUÍDO:
+           ✓ Schema payments (migration 005)
+           ✓ POST /checkout/create-session
+           ✓ Integração Stripe Checkout
+
+           PENDENTE:
+           ✗ Webhook handler /webhooks/stripe
+           ✗ Página de confirmação /checkout/success
+
+           DECISÕES REGISTRADAS:
+           - Stripe Checkout (não Elements)
+           - Verificação de webhook com constructEvent
+
+           Quer continuar implementando os 2 passos pendentes?
+Você > Sim, comece pelo webhook.
+
+@deyvin > [implementa src/routes/webhooks.js]
+           Webhook handler criado. Testando com stripe-cli...
+           Evento payment_intent.succeeded recebido ✓
+           Dossier atualizado: webhooks marcado como concluído.
+```
+
+---
+
+## Detectando drift
+
+O dossier tem **drift detection**: se o código mudou desde o último registro do agente, ele detecta a divergência antes de continuar.
+
+```
+@deyvin > Verificando drift...
+           Arquivo: src/services/stripe.js
+           Última versão conhecida: criado por @dev em 2026-05-05
+           Estado atual: modificado fora do agente (1 função adicionada)
+
+           Drift detectado. Antes de continuar, vou ler o que mudou...
+           [lê diff]
+           Mudança: função handleRefund() adicionada manualmente.
+           Vou incluir isso no codemap e continuar.
+```
+
+---
+
+## Adicionando pesquisas ao dossier
+
+Quando você (ou um agente) pesquisa algo importante para a feature, adicione ao índice de pesquisa:
+
+```bash
+npx @jaimevalasek/aioson dossier:add-research . \
+  --slug=checkout-stripe \
+  --url="https://stripe.com/docs/webhooks" \
+  --summary="Stripe requer verificação de signature em todos os webhooks. Usar constructEvent." \
+  --agent=dev
+```
+
+Isso fica em `research/` e futuros agentes encontram sem precisar reler a documentação.
+
+---
+
+## Auditoria do dossier
+
+Para verificar se o dossier está consistente com o estado real do código:
+
+```bash
+npx @jaimevalasek/aioson dossier:audit --slug=checkout-stripe
+```
+
+```
+Auditando checkout-stripe...
+
+✓ Todos os arquivos do codemap existem
+✓ Migration 005 aplicada (verificada via introspection)
+✗ src/routes/webhooks.js listado como pendente mas arquivo existe no disco
+
+  Possível inconsistência: arquivo criado mas dossier não atualizado.
+  Recomendação: rode @deyvin para sincronizar o status.
+```
+
+---
+
+## Ver estado atual do dossier
+
+```bash
+npx @jaimevalasek/aioson dossier:show --slug=checkout-stripe
+```
+
+```
+FEATURE: checkout-stripe
+Status: in_progress
+Agentes: @product, @analyst, @architect, @dev, @deyvin
+Progresso: 4/5 passos concluídos (80%)
+Arquivos: 5 (3 criados, 2 pendentes)
+Pesquisas: 1 (stripe webhooks)
+Última atualização: 2026-05-07 10:15
+```
+
+---
+
+## `dev-state.md` — o complemento do dossier
+
+Além do dossier, o `@dev` mantém `.aioson/context/dev-state.md` — um snapshot mais granular do estado de implementação:
+
+```
+## Dev State — checkout-stripe
+
+### Concluído
+- src/routes/checkout.js: POST /checkout/create-session → Stripe Checkout
+- src/services/stripe.js: createCheckoutSession, handleRefund
+- src/db/migrations/005_payments.js: tabela payments com campos Stripe
+
+### Em progresso
+- src/routes/webhooks.js: handler parcial, falta payment_intent.payment_failed
+
+### Bloqueado
+- (nenhum)
+
+### Próximos passos
+1. Completar webhook handler (caso .payment_failed)
+2. Criar página /checkout/success com query param session_id
+3. Ativar @qa para validar os ACs
+```
+
+---
+
+## O que acontece quando a feature é fechada
+
+Quando você roda `aioson feature:close --slug=checkout-stripe`, o dossier é movido para `.aioson/context/done/`. O feature archive guarda:
+
+```
+.aioson/context/done/
+└── checkout-stripe/
+    ├── dossier.md        ← estado final
+    ├── codemap/          ← todos os arquivos tocados
+    └── research/         ← pesquisas acumuladas
+```
+
+Isso cria um histórico auditável de todas as features — útil para onboarding de novos devs ou para o `@neo` entender o histórico do projeto.
+
+---
+
+## O que ficou em disco (rastreio)
+
+```
+.aioson/context/features/checkout-stripe/
+├── dossier.md           ← documento central (spec, plano, decisões, trail)
+├── codemap/
+│   └── files.json       ← arquivos, status (criado/modificado/pendente), agente
+└── research/
+    └── index.md         ← pesquisas indexadas com resumos
+
+.aioson/context/
+├── dev-state.md         ← estado granular de implementação
+└── project-pulse.md     ← estado global do projeto (feature ativa, próximo passo)
+```
+
+---
+
+## Quando NÃO usar o dossier
+
+- Feature de 1 hora que você termina na mesma sessão — overhead desnecessário.
+- Projeto MICRO com uma única feature — o `project.context.md` e o `dev-state.md` já bastam.
+- Exploração rápida de código — use `@deyvin` direto sem inicializar dossier.
+
+Para projetos SMALL e MEDIUM, o dossier é altamente recomendado. Projetos MEDIUM com `@orchestrator` usam dossier por padrão.
+
+---
+
+## Variações
+
+| Situação | Ajuste |
+|---|---|
+| Múltiplas features paralelas | Um dossier por feature slug. O `project-pulse.md` mostra qual está ativa. |
+| Time com vários devs | Commitam os dossiês no Git. Cada dev vê o estado de todas as features. |
+| Feature retomada por agente diferente | Qualquer agente lê o dossier. O trail de agentes fica registrado. |
+| Sessão caiu sem salvar `dev-state.md` | `@deyvin` usa o dossier + git diff para reconstituir o estado. |
+
+---
+
+## Solução de problemas
+
+| Problema | Solução |
+|---|---|
+| `@deyvin` não encontrou o dossier | Rode `dossier:show --slug=X` para confirmar que existe. Se não, `dossier:init`. |
+| Dossier desatualizado com o código | `dossier:audit` detecta inconsistências e orienta correção. |
+| `dev-state.md` foi sobrescrito | O Git tem o histórico. O dossier tem o trail de agentes. |
+| Drift detection disparou erro incorreto | Diga ao `@deyvin`: "o arquivo foi modificado intencionalmente, atualize o codemap". |
+
+---
+
+## Próximo passo
+
+- Quer começar com este fluxo num projeto legado? → [Integrar em codebase grande](./integracao-em-codebase-grande.md)
+- Quer entender o que mais o dossier rastreia? Consulte o [Glossário — Dossier](../1-entender/glossario.md).
+- Quer ver o mapa completo de artefatos? → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md).

package/docs/pt/3-receitas/da-ideia-ao-prd-via-briefing.md

@@ -0,0 +1,234 @@
+# Receita: Da ideia ao PRD via `@briefing`
+
+> **Para quem é:** quem tem uma ideia ainda vaga — anotações no celular, rascunho no Notion, conversa de reunião não formalizada.
+> **Tempo de execução:** 30 a 90 min (depende do quanto de material você já tem).
+> **O que você vai ter no fim:** um PRD gerado pelo `@product` com base num briefing enriquecido — sem gaps óbvios, com riscos mapeados.
+
+---
+
+## O problema que esta receita resolve
+
+Você foi direto para `@product` com uma ideia vaga e ouviu:
+
+> "Antes de criar um PRD, preciso entender melhor o problema. Qual o caso de uso principal?"
+
+Esse loop de perguntas acontece porque a ideia ainda não tem forma. O `@briefing` existe exatamente para essa etapa: ele estrutura o que existe antes do PRD, para que o `@product` chegue à conversa com base sólida.
+
+---
+
+## A trilha em uma linha
+
+```
+ideia vaga / anotações
+       ↓
+   @briefing   →  .aioson/briefings/{slug}/briefings.md
+       ↓
+aioson briefing:approve
+       ↓
+   @product   →  prd.md (ou prd-{slug}.md)
+       ↓
+ (opcional) @sheldon  →  enriquecimento + phased plan
+```
+
+---
+
+## Variante A — Você já tem rascunhos em `plans/`
+
+Este é o caso mais comum: você pesquisou, copiou texto, escreveu ideias, e agora tem arquivos soltos.
+
+### Passo 1 — Coloque o material em `plans/`
+
+```bash
+# Arquivos na raiz do projeto (gitignored por padrão)
+plans/
+├── ideia-notificacoes.md     ← esboço da ideia
+├── pesquisa-firebase.md      ← pesquisa técnica que você fez
+└── benchmark-concorrentes.md ← análise que você copiou de outro chat
+```
+
+> `plans/` é **somente-leitura para os agentes** — eles lêem mas nunca modificam. Seus arquivos ficam intactos.
+> Veja [Plans externos para @product](./plans-externos-para-product.md) para detalhes sobre esse fluxo.
+
+### Passo 2 — Ative `@briefing`
+
+```
+Você > @briefing
+
+@briefing > Encontrei 3 arquivos em plans/:
+             - plans/ideia-notificacoes.md
+             - plans/pesquisa-firebase.md
+             - plans/benchmark-concorrentes.md
+
+             Quais devo usar como fonte? (todos ou lista específica)
+Você > Todos.
+
+@briefing > Lendo e enriquecendo...
+             Validando premissas técnicas sobre Firebase push...
+
+             Briefing gerado: .aioson/briefings/notificacoes-push/briefings.md
+
+             Resumo:
+             - Problema: usuários perdem eventos importantes por falta de push
+             - Hipóteses validadas: 3/4
+             - Gap encontrado: frequência máxima de notificação não definida
+             - Risco: rate limit do Firebase em plano gratuito (5.000/dia)
+             - Próximo passo: aprovação via CLI → @product
+
+             O briefing está pronto. Deseja ajustar algo antes de aprovar?
+```
+
+**O que ficou em disco:**
+```
+.aioson/briefings/notificacoes-push/
+└── briefings.md    ← problema, hipóteses, gaps, riscos, perguntas abertas
+.aioson/briefings/
+└── config.md       ← índice de todos os briefings (status: draft)
+```
+
+### Passo 3 — Revise e aprove
+
+Leia `.aioson/briefings/notificacoes-push/briefings.md`. Se estiver bom:
+
+```bash
+aioson briefing:approve
+# ou especifique o slug:
+aioson briefing:approve --slug=notificacoes-push
+```
+
+O status muda de `draft` para `approved`. O `@product` detecta isso automaticamente.
+
+### Passo 4 — Ative `@product`
+
+```
+Você > @product
+
+@product > Detectei briefing aprovado: notificacoes-push (criado hoje).
+            Posso usá-lo como base para o PRD desta feature?
+Você > Sim.
+
+@product > [lê briefing, faz perguntas apenas sobre o que falta]
+            Qual o slug da feature?
+Você > push-notifications
+
+@product > ACs principais que vou incluir no PRD:
+            1. Usuário recebe push em ≤ 2s após evento
+            2. Rate limit respeitado (1 notif/min por usuário)
+            3. Desativação via configurações (LGPD)
+
+            Fora do escopo: notificações por email (briefing sinalizou para fase 2).
+
+            PRD criado: .aioson/context/prd-push-notifications.md
+            Próximo: @sheldon (recomendado — há 1 risco técnico aberto no briefing).
+```
+
+---
+
+## Variante B — A ideia está só na sua cabeça (modo conversacional)
+
+Sem arquivos. Nenhum rascunho. Só uma vontade de construir algo. Quando `plans/` está vazio, `@briefing` entra em **modo conversacional estruturado** — uma entrevista em 6 etapas que constrói o briefing pergunta por pergunta.
+
+```
+Você > @briefing
+
+@briefing > Não encontrei arquivos em plans/. Quer planejar a ideia comigo
+            conversacionalmente? Vou fazer perguntas e montar o briefing.
+Você > Sim.
+
+─── Etapa A — Contexto (o "por que agora?") ───
+@briefing > Me conta o contexto: qual a situação atual e o que mudou
+            recentemente que fez isso surgir agora? Sempre existe um
+            gatilho.
+Você > Clientes estão reclamando que perdem atualizações de pedido.
+       Tivemos 3 chamados na semana passada.
+
+─── Etapa B — Problema (framing JTBD) ───
+@briefing > Qual a dor específica que você quer resolver? Para quem?
+            O que eles não conseguem fazer hoje sem dar uma volta?
+Você > Cliente faz pedido, fecha o app, e fica sem saber se foi confirmado.
+
+@briefing > Deixa eu reformular como JTBD: "Quando faço um pedido e fecho
+            o app, quero saber que ele foi confirmado, para não precisar
+            voltar e checar." Faz sentido?
+Você > Sim, exatamente.
+
+─── Etapa C — Solução proposta ───
+@briefing > Que direções você está cogitando? Múltiplas é ok — é hipótese,
+            não compromisso.
+Você > Push notification. Talvez SMS para pedidos acima de R$500.
+
+─── Etapa D — Riscos (os 4 de Cagan + risco de não-fazer) ───
+@briefing > Vou perguntar em 4 passes:
+            1. Valor: usuários vão querer? (ou só toleram?)
+            2. Usabilidade: vão entender e configurar?
+            3. Viabilidade técnica: dá para construir?
+            4. Viabilidade de negócio: legal/LGPD/custo/marca?
+            E por fim: qual o custo de NÃO fazer?
+Você > [responde cada um]
+
+─── Etapa E — Gaps (estado atual vs desejado) ───
+@briefing > Para cada coisa indefinida, vamos enquadrar como:
+            "hoje temos X, queremos Y, o delta é Z (mensurável quando der)".
+            O que ainda está em aberto?
+Você > Frequência máxima de notif por dia. Hoje: indefinido. Queremos: ?
+
+─── Etapa F — Classificação de questões abertas ───
+@briefing > Vou marcar cada pergunta com uma tag:
+            [research-able]      → < 4h de pesquisa resolve
+            [testable]           → experimento de 1-2 dias
+            [decision-required]  → julgamento entre alternativas
+            [out-of-scope]       → parar agora, não bloqueia
+
+            Resultado:
+            1. Frequência máxima       [decision-required]
+            2. Engajamento real esperado [research-able]
+            3. SMS para pedidos altos  [out-of-scope — fase 2]
+
+@briefing > 6 etapas concluídas. Briefing gerado:
+            .aioson/briefings/notificacoes-pedido/briefings.md
+```
+
+> **Regra de qualidade:** se mais de 3 perguntas ficarem como `decision-required` ou vagas, `@briefing` faz outra rodada antes de escrever. Briefing apressado custa caro depois.
+
+O resto do fluxo é igual: aprovar via CLI → `@product`.
+
+---
+
+## O que o `@briefing` detecta que o `@product` não detectaria sozinho
+
+| O que ele identifica | Exemplo |
+|---|---|
+| Hipóteses de mercado não validadas | "Usuários vão usar push?" — ele pesquisa dados de engajamento |
+| Riscos técnicos do plano | Rate limits, latências, custos por volume |
+| Gaps de escopo | Frequência máxima de notificação não definida |
+| Contradições internas | Rascunho diz "em tempo real" mas pesquisa aponta custo proibitivo |
+| Decisões abertas que bloqueiam o PRD | "Firebase ou APNS nativo?" precisa ser resolvido antes |
+
+---
+
+## Quando pular o `@briefing`
+
+- Feature simples e clara: MICRO, sem ambiguidade — vá direto para `@product`.
+- Já tem um PRD anterior enriquecido — use `@sheldon` para refinar.
+- É uma continuação de feature já iniciada — use `@deyvin`.
+
+---
+
+## Arquivos criados por esta receita
+
+```
+plans/                              ← seus rascunhos (intocados)
+.aioson/briefings/{slug}/
+├── briefings.md                    ← output do @briefing
+└── {tema-especifico}.md            ← (opcional) temas complexos
+.aioson/briefings/config.md         ← índice de briefings
+.aioson/context/prd-{slug}.md       ← output do @product
+```
+
+---
+
+## Próximos passos
+
+- [Plans externos para @product](./plans-externos-para-product.md) — como usar ChatGPT/Claude.ai como fonte para `plans/`
+- [Feature completa com @sheldon](./feature-completa-com-sheldon.md) — quando o PRD está pronto e a trilha é SMALL/MEDIUM
+- [@briefing — ficha](../4-agentes/briefing.md) — referência técnica do agente
+- [@product — ficha](../4-agentes/product.md) — referência técnica do agente