@jaimevalasek/aioson 1.8.0 → 1.9.0

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

@@ -0,0 +1,108 @@
+# @committer — Mensagens de commit profissionais e commit seguro
+
+> **Para quem é:** quem quer commitar sem escrever mensagem de commit na mão e sem risco de enviar arquivos errados.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que o @committer faz além de gerar mensagem.
+> - Por que ele existe como agente separado.
+
+## Para que serve
+
+Escrever uma boa mensagem de commit leva tempo e exige disciplina. Na prática, acabam virando "fix", "update", "wip" — inúteis para quem lê depois. E pior: o commit pode incluir arquivos que não deveriam estar lá (`.env`, `node_modules`, logs, artefatos de build).
+
+O `@committer` resolve os dois problemas. Ele é um **portão de segurança** antes do commit: lê o diff, verifica o que está staged, bloqueia arquivos proibidos (via `git:guard`), e só então gera a mensagem no padrão Conventional Commits. Você aprova, ele commita.
+
+A mensagem de commit é sempre em inglês (padrão técnico universal). A comunicação com você é em pt-BR.
+
+## Quando invocar
+
+- Depois de implementar qualquer fatia e querer commitar.
+- Quando você quer garantir que só os arquivos certos estão no commit.
+- Antes de um PR — a mensagem vai aparecer no histórico público.
+
+## Quando NÃO invocar
+
+- Você ainda não terminou a implementação — commite só quando a fatia está pronta.
+- Quer fazer `git add .` de tudo sem revisar — o @committer vai bloquear isso.
+
+## Diálogo típico
+
+```
+Você > @committer
+
+@committer > Rodando git status...
+             Rodando commit:prepare...
+
+             Arquivos modificados detectados:
+             ✓ src/webhooks/stripe.js
+             ✓ src/routes/checkout.js
+             ✗ .env (BLOQUEADO — contém secrets)
+             ✗ .aioson/runtime/ (BLOQUEADO — telemetria local)
+
+             Staged proposto (excluindo bloqueados):
+             [✓] src/webhooks/stripe.js
+             [✓] src/routes/checkout.js
+             [ ] Selecione outros se quiser
+
+             Mensagem de commit proposta:
+             ┌──────────────────────────────────────────────────┐
+             │ feat(checkout): add Stripe webhook handler       │
+             │                                                  │
+             │ Handle checkout.session.completed event,         │
+             │ confirm order and queue confirmation email.      │
+             │ Idempotency key added to prevent duplicate runs. │
+             └──────────────────────────────────────────────────┘
+
+             [Enter] Aceitar   [E] Editar   [C] Cancelar
+Você > [Enter]
+
+@committer > Commitado: abc1234
+```
+
+## Saídas em disco
+
+| Arquivo | O que contém |
+|---|---|
+| `.aioson/context/commit-prep.json` | Metadados do commit preparado (diff, staged, guard result) — válido por 30 min |
+
+## Como ele lê seu projeto
+
+1. `.aioson/context/commit-prep.json` — se existir e for recente, pula a etapa de preparação.
+2. `git status --short` — arquivos modificados.
+3. `aioson commit:prepare` — prepara stage, roda guard, coleta diff.
+4. `.aioson/git-guard.json` — política de arquivos bloqueados do projeto.
+5. `.aioson/context/project-pulse.md` e plano relevante — para enriquecer a mensagem com contexto.
+
+## Comandos CLI relacionados
+
+```bash
+# Preparar commit interativamente (terminal UI)
+npx @jaimevalasek/aioson commit:prepare .
+
+# Preparar em modo headless (automação/agent)
+npx @jaimevalasek/aioson commit:prepare . --agent-safe --staged-only --mode=headless
+
+# Verificar arquivos staged
+npx @jaimevalasek/aioson git:guard . --json
+
+# Instalar pre-commit hook (bloqueia commits manuais inseguros)
+npx @jaimevalasek/aioson git:guard . --install-hook
+```
+
+## Handoff típico
+
+- **Vem de:** `@dev`, `@deyvin`, ou qualquer momento pós-implementação.
+- **Vai para:** nenhum — é terminal no fluxo de commit. Próximo passo é você: `git push` ou PR.
+
+## Sobre o formato da mensagem
+
+Segue **Conventional Commits**: `tipo(escopo): descrição`.
+
+Tipos comuns: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`.
+
+O @committer gera corpo da mensagem quando há contexto suficiente (mudanças não-triviais, breaking changes, ou múltiplos arquivos com lógica diferente).
+
+## Próximo passo
+
+- Ver todo o ciclo de uma feature → [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)
+- Commit bloqueado? Verifique `.aioson/git-guard.json`

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

@@ -0,0 +1,279 @@
+# @copywriter — Escrever copy de conversão para páginas e campanhas
+
+> **Para quem é:** quem precisa de copy que converta — landing pages, sales letters, VSLs, anúncios pagos, emails — sem escrever linha a linha.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:**
+> - Quais tipos de copy o agente entrega e em que formato
+> - Como ele usa contexto do projeto para personalizar tom e voz
+> - Como escolher entre diferentes "mestres" copywriters (Brunson, Georgi, Diogo Gomes)
+> - Quais estruturas narrativas estão disponíveis (5-Act, Tríade, KSTK, CPGC ads)
+
+---
+
+## Para que serve
+
+Copy genérico não converte. O `@copywriter` não é um formatador de texto — é um estrategista de conversão que lê o contexto do projeto, pesquisa a audiência real, aplica frameworks de persuasão provados, e escreve copy que faz o leitor se sentir entendido, elimina objeções, e direciona para uma ação clara.
+
+Ele escreve no idioma da audiência — se o projeto é PT-BR, o copy sai em PT-BR sem precisar pedir.
+
+A grande diferença em relação a um "prompt de copy genérico" é que ele tem **mentes selecionáveis** (genomes), **estruturas selecionáveis**, e **vozes selecionáveis** — você compõe o tipo de copywriter que melhor serve seu projeto.
+
+---
+
+## Quando invocar
+
+- Você precisa de copy para landing page, página de vendas, email ou campanha
+- O `@ux-ui` detectou que o projeto `project_type=site` e o copy ainda está faltando (copy gate dispara automático)
+- Você precisa de VSL (Video Sales Letter) — Mode 5
+- Você precisa de anúncios para Facebook/Instagram (CPGC)
+- Um executor de squad precisa de copy especializado num domínio
+- Você quer revisar copy existente com critério técnico — Mode 3
+
+---
+
+## Quando NÃO invocar
+
+- Você precisa de documentação técnica — use `@dev` ou o próprio agente de domínio
+- Você quer microcopy de UI (labels, tooltips, error messages) — o `@ux-ui` cobre isso dentro do design system
+- Você quer pesquisa de mercado profunda sem copy — use `@orache`
+
+---
+
+## Os 5 modos
+
+| Modo | Quando usar | Output |
+|------|-------------|--------|
+| **1. Full page** | Escrever todas as seções de uma página do zero | `copy-{slug}.md` completo |
+| **2. Section** | Apenas hero, benefits, FAQ, CTA, ou outra seção específica | append em `copy-{slug}.md` |
+| **3. Review & rewrite** | Você tem copy existente e quer análise + reescrita | `copy-review-{slug}.md` |
+| **4. Squad executor** | Atuando como executor dentro de um squad, segue o genome do squad | conforme manifest do squad |
+| **5. VSL Script** | Roteiro completo de Video Sales Letter | `vsl-script-{slug}.md` |
+
+---
+
+## Selecionar a mente do copywriter (genomes)
+
+Quando há múltiplos genomes de mestres instalados, o `@copywriter` pergunta qual perspectiva aplicar. **8 mestres disponíveis** organizados em 2 hemisférios:
+
+### Mestres universais (US, em inglês — adaptam-se ao idioma do projeto)
+
+| Genome | Filosofia | Melhor para |
+|--------|-----------|-------------|
+| **`copywriting-schwartz`** | Foundational: 5 Awareness Levels + 5 Sophistication Stages + Mass Desire (channel, not create) | **Camada base** — combine com qualquer mestre aplicado para diagnóstico de awareness/sofisticação |
+| **`copywriting-halbert`** | Direct mail school: Starving Crowd + A-Pile/B-Pile + Market First | Direct mail, long-form sales letters, audiências comprovadamente "famintas" |
+| **`copywriting-kennedy`** | No B.S.: 10 Rules + Magnetic Marketing Triangle + premium positioning | Premium positioning, magnetic marketing systems, small business direct response |
+| **`copywriting-brunson`** | Storytelling/funil + stack de valor + quebra de 3 crenças + comunidade | Cursos, infoprodutos, coaching, comunidades pagas, audiência aspiracional |
+| **`copywriting-georgi`** | RMBC (Research → Mechanism → Brief → Copy) + big idea | VSLs, sales letters longas, health/wealth/weight loss |
+
+### Mestres brasileiros (pt-BR, voz preservada com translations side-by-side)
+
+| Genome | Escola BR | Filosofia | Melhor para |
+|--------|-----------|-----------|-------------|
+| **`copywriting-ladeira`** | Mainstream | VTSD + Light Copy 3 Cs + KSTK + Stories 10x + irreverente | BR mainstream, infoprodutos acessíveis, daily content, Instagram-first |
+| **`copywriting-icaro-de-carvalho`** | Intelectual | Contraste + Vulnerabilidade Calculada + 20/80 storytelling + polarização autoral | BR intelectual/premium, content autoral, thought leadership polarizante |
+| **`copywriting-diogo-gomes`** | Periferia | Validated recombination + mapa do tesouro + 4 lead variations + pragmatismo agressivo | BR periferia, VSLs agressivas, infoprodutos performance, renda extra |
+
+### Como escolher entre os 3 BR
+
+```
+            Mainstream         Intelectual         Periferia
+            (Ladeira)          (Ícaro)             (Diogo)
+            ─────────          ──────────          ──────────
+Audiência   B/C massivo        B+ premium          C/D/E asp.
+Vocabulário acessível          articulado          quebrada
+Tom         "vamos lá"         "transformando..."  "foda-se ser"
+Estratégia  daily-system       contraste/polariz.  recombinação
+```
+
+Escolha pela **audience match**, não pela preferência pessoal — cada um cobre um segmento BR distinto.
+
+### Regra de combinação
+
+- **Schwartz + 1 mestre aplicado:** ✅ permitido (Schwartz é camada base)
+- **2 mestres aplicados na mesma peça:** ❌ proibido (filosofias colidem — ex: Brunson aspiracional vs Georgi sóbrio; Ladeira mainstream vs Ícaro polarizante)
+- **Diferentes mestres em diferentes peças do mesmo projeto:** ✅ permitido (com hierarquia explícita)
+
+> Os 3 personas BR são **Genome 3.0 + Track 4.1** — incluem Decision Weights numéricos, Meta-Axiomas, e Perfil Cognitivo decomposto em Voice DNA / Thinking DNA / Identity Core. Os 5 mestres US são **Genome 2.0 + Track 4.1 partial** (Decision Weights metodológicos + Meta-Axioms, sem DNA split por não serem personas).
+
+---
+
+## Selecionar a estrutura narrativa
+
+Cinco estruturas disponíveis. Pick **uma** por peça.
+
+| Estrutura | Quando usar |
+|-----------|-------------|
+| **5-Act** (default) | Sales pages e landing pages tradicionais — Hero / Authority / Mechanism / Offer / Close |
+| **Tríade Narrativa** | Storytelling profundo — Background (30%) / Emotional (40%) / Discovery (30%) |
+| **KSTK Narrativo** | Short-form story-driven — Ken / Shu / Ten / Ketsu (4 atos compactos) |
+| **KSTK Argumentativo** | Short-form lógico — premissas → conclusão inevitável |
+| **CPGC** | Anúncios FB/IG — Copy + Persona + Gancho + Corpo + CTA |
+
+**Compatibilidade estrutura × mestre:**
+
+| Estrutura | Brunson | Georgi | Diogo Gomes |
+|-----------|---------|--------|-------------|
+| 5-Act | ✅ | ✅ | ✅ |
+| Tríade | ✅ (storytelling forte) | parcial | ✅ |
+| KSTK Narrativo | ✅ | parcial | ✅ |
+| KSTK Argumentativo | parcial | ✅ (RMBC fit) | parcial |
+| CPGC ads | ✅ | ✅ | ✅ |
+| VSL (5-Act adaptado) | ✅ | ✅ (mestres VSL) | ✅ (mestres VSL) |
+
+---
+
+## Selecionar a voz (LightCopy styles, opcional)
+
+Quando o projeto pede tom específico além do default, o `@copywriter` carrega `lightcopy-styles.md` com 4 vozes selecionáveis:
+
+| Voz | Quando usar |
+|-----|-------------|
+| **Narrativo Surpreendente** | Audiência fria, scroll fácil — abre com história inesperada |
+| **Autenticidade Estratégica** | Audiência cética de "experts" — vulnerabilidade calculada |
+| **Observador Perspicaz** | Audiência experiente que se sente incompreendida |
+| **Comandos Indiretos** | Audiência resistente a "tom de venda" — premissas → conclusão |
+
+---
+
+## Avatar gate (Phase 1.5)
+
+Antes de escrever, o `@copywriter` verifica se o projeto tem **avatar profundo** definido:
+
+- Se existe `.aioson/context/avatar-{slug}.md` ou avatar bem definido no PRD → carrega e segue
+- Se avatar é shallow ou ausente → carrega `avatar-construction.md` e roda o framework multi-camada (Identity + Empathy Map 6 dimensões + Decision Triggers + Copy Application)
+
+O avatar é gravado em `.aioson/context/avatar-{slug}.md` e reutilizável por outros squads (vendas, atendimento, suporte).
+
+---
+
+## Diálogo típico (Mode 1 — Full page)
+
+```
+Você > @copywriter landing page do meu app de finanças pessoais para millennials BR
+
+@copywriter > Lendo project.context.md... projeto "finwise", project_type=site, pt-BR.
+              Genomes detectados: copywriting-brunson, copywriting-georgi, copywriting-diogo-gomes.
+
+@copywriter > Qual perspectiva você quer aplicar?
+              1. Brunson (storytelling/funnel — cursos, comunidades)
+              2. Georgi (RMBC/mechanism — VSLs, sales letters)
+              3. Diogo Gomes (BR direct response — VSLs Brasil, infoprodutos)
+              4. Baseline (sem mestre)
+
+Você > 3 (Diogo Gomes — fala direto, audiência periferia/aspiração)
+
+@copywriter > Carregando copywriting-diogo-gomes (Genome 3.0 + Track 4.1)...
+              Avatar shallow detectado no PRD. Rodando avatar-construction.md...
+              [coleta Identity + Empathy Map + Decision Triggers]
+              Avatar gravado em .aioson/context/avatar-finwise.md.
+
+@copywriter > Pesquisa PMS:
+              Dores: dívida cartão, mês não fecha, vergonha de pedir ajuda
+              Mitos: "preciso ganhar mais para sobrar dinheiro"
+              Sonhos: respirar no fim do mês, viajar sem culpa, parar de esconder dívida
+
+@copywriter > Escolha de estrutura:
+              Recomendo 5-Act adaptado (sales page completa) ou Tríade Narrativa
+              (founder story se você tem história). Qual?
+
+Você > 5-Act
+
+@copywriter > One Belief construído:
+              "Sair das dívidas é o resultado de mapear cada centavo —
+               não de ganhar mais — e isso é possível em 5 minutos por dia
+               com o sistema do Finwise."
+
+@copywriter > Escrevendo copy completa...
+              Hero: "Você sabe que deveria guardar dinheiro. Mas o mês acaba antes do salário."
+              [...]
+
+@copywriter > Copy completo salvo em .aioson/context/copy-finwise.md.
+              Próximo: @ux-ui para encaixar no layout.
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/context/
+├── copy-{slug}.md              ← copy completo (Mode 1) ou seção (Mode 2)
+├── copy-review-{slug}.md       ← revisão anotada (Mode 3)
+├── vsl-script-{slug}.md        ← roteiro VSL (Mode 5)
+├── avatar-{slug}.md            ← avatar gerado pelo avatar gate (se aplicado)
+└── copy-multiplier-{slug}.md   ← 63 variações geradas via content-multiplier (opcional)
+
+researchs/{slug}/
+├── pms-map-{date}.md           ← mapeamento Problemas/Mitos/Sonhos
+└── copy-intelligence-{date}.md ← inteligência competitiva
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — idioma, tipo de projeto, tom, design skill
+- `.aioson/context/prd.md` ou `prd-{slug}.md` — proposta de valor e escopo
+- `.aioson/context/avatar-{slug}.md` — avatar (se já existir)
+- Cache de pesquisas em `researchs/{slug}/` — se existir e <7 dias, reutiliza
+- Genomes em `.aioson/genomes/copywriting-*.md` — mestres disponíveis
+
+---
+
+## Skills/references carregados sob demanda
+
+O `@copywriter` carrega references somente quando precisa, para economizar contexto:
+
+**Foundational (sempre):** `copywriting.md` (genome geral)
+
+**Phase 1 (research):**
+- `avatar-construction.md` — quando avatar é shallow
+- `pms-research.md` — mapeamento de dores/mitos/sonhos
+- `market-intelligence.md` — escaneamento competitivo
+
+**Phase 4 (estratégia + escrita):**
+- `one-belief.md` — construção da crença central
+- `five-acts.md` — estrutura padrão
+- `triade-narrativa.md` — alternativa storytelling
+- `kstk-structure.md` — alternativa short-form
+- `ads-cpgc.md` — anúncios FB/IG
+- `patterns.md` + `anti-patterns.md` — fórmulas e validação
+- `offer-structure.md` + `fascinations.md` — construção de oferta
+- `lightcopy-styles.md` — seleção de voz
+
+**Multipliers:**
+- `vsl-craft.md` — Mode 5 VSL
+- `content-multiplier.md` — gerar 63 variações para teste/calendário
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@ux-ui` (copy gate automático para `project_type=site`), `@product` (handoff para `project_type=site`), ou pedido direto
+- **Vai para:** `@ux-ui` (encaixar no layout) → `@dev` (implementar no frontend) → `@qa` (validar)
+
+---
+
+## Reuso além do `@copywriter`
+
+Os genomes e skills criados para o copywriter são reutilizáveis por outros agentes/squads:
+
+| Skill / Genome | Reuso |
+|----------------|-------|
+| `avatar-construction.md` | Squad vendas/atendimento/suporte, `@orache`, `@product` (PRD) |
+| `triade-narrativa.md` | Squad sales executors |
+| `copywriting-brunson/georgi/diogo-gomes` | Squad executors de vendas, marketing, performance |
+| `content-multiplier.md` | Squad content/marketing |
+| `ads-cpgc.md` | Squad performance-marketing |
+
+Para bind um genome em um squad existente, use `@genome` com Option 4 (Apply to existing squad/agent).
+
+---
+
+## Próximo passo
+
+- Para montar um squad com executor de copywriter aplicando um genome de mestre: `@squad`
+- Para enriquecer um dos 8 genomes existentes via profiler (subir fidelity de 0.65 para 0.85+): pipeline `@profiler-researcher` → `@profiler-enricher` → `@profiler-forge`
+- Para gerar genome de outro copywriter ainda não na biblioteca (ex: Erico Rocha, Pedro Sobral, Eugene Schwartz já existe): `@genome` ou pipeline profiler completo
+- Para clonar visualmente o estilo de outra landing: `@site-forge` ou `@design-hybrid-forge`
+- Para descobrir o que mais existe: ficha [neo.md](./neo.md) ou [agentes.md](../agentes.md)

package/docs/pt/4-agentes/design-hybrid-forge.md

@@ -0,0 +1,116 @@
+# @design-hybrid-forge — Combinar dois design skills num híbrido original
+
+> **Para quem é:** quem tem dois design skills mas quer o melhor dos dois mundos num único sistema visual coerente.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Como o processo de fusão funciona
+> - O que "tensão criativa" significa na prática
+
+---
+
+## Para que serve
+
+Nenhum design skill pronto cobre exatamente o que você precisa. O Clean SaaS UI é limpo demais para a sua marca assertiva. O Neo Brutalist é forte demais para os seus clientes corporativos. O `@design-hybrid-forge` funde dois skills primários — respeitando regras de compatibilidade entre pares — e gera um **terceiro skill instalável** com identidade própria, tokens definidos, e previews HTML para aprovação visual.
+
+O hybrid resultante é local ao seu projeto (em `.aioson/installed-skills/`) por padrão. Você pode promovê-lo ao aioson.com se quiser compartilhar.
+
+---
+
+## Quando invocar
+
+- Nenhum skill nativo atende sozinho
+- Você quer criar uma identidade visual diferenciada para o projeto
+- Você tem um preset de variação definido em `design-variation-preset.md`
+
+---
+
+## Quando NÃO invocar
+
+- Um skill nativo já cobre — criar hybrid sem necessidade gera overhead de manutenção
+- Você quer clonar o visual de um site real — use `@site-forge` (modo D ou B)
+- Você não sabe quais skills usar — peça ajuda ao `@ux-ui` antes
+
+---
+
+## Diálogo típico
+
+```
+Você > @design-hybrid-forge
+
+@design-hybrid-forge > Skills disponíveis:
+                       - clean-saas-ui
+                       - aurora-command-ui
+                       - cognitive-core-ui
+                       - bold-editorial-ui
+                       - warm-craft-ui
+                       - glassmorphism-ui
+                       - neo-brutalist-ui
+                       + installed-skills/...
+
+                       Escolha 2 primários para fundir:
+Você > bold-editorial-ui + clean-saas-ui
+
+@design-hybrid-forge > Verificando compatibilidade...
+                       Par válido. Tensão criativa:
+                       Bold: tipografia grande, hierarquia forte, ausência de neutralidade
+                       Clean: espaço branco, clareza funcional, controle
+                       Substrate winner: Clean (estrutura de layout)
+                       Acento Bold: peso tipográfico e cor de destaque
+
+                       Nome sugerido: "editorial-saas-ui"
+Você > aceito
+
+@design-hybrid-forge > Gerando...
+                       .aioson/installed-skills/editorial-saas-ui/SKILL.md       ✓
+                       .aioson/installed-skills/editorial-saas-ui/previews/*.html ✓
+                       Mirrored para .claude/skills/editorial-saas-ui/            ✓
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/installed-skills/{hybrid-name}/
+├── SKILL.md
+├── references/
+├── previews/{hybrid-name}.html
+├── previews/{hybrid-name}-website.html
+└── .skill-meta.json
+
+.claude/skills/{hybrid-name}/       ← mirror Claude Code
+.cursor/skills/{hybrid-name}/       ← mirror Cursor (se existir)
+.windsurf/skills/{hybrid-name}/     ← mirror Windsurf (se existir)
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/skills/design/` e `.aioson/installed-skills/` — lista de skills disponíveis
+- `.aioson/context/design-variation-preset.md` — preset de variação (se existir, é carregado antes de qualquer pergunta)
+- `references/pair-compatibility.md` — regras de compatibilidade entre pares
+- `references/crossover-protocol.md` — protocolo de fusão
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Ver opções de variação disponíveis
+aioson design-hybrid:options
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@ux-ui` (quando nenhum skill nativo serve) ou pedido direto
+- **Vai para:** `@dev` ou `@site-forge` — o skill híbrido é usado como design system nas implementações
+
+---
+
+## Próximo passo
+
+- Para clonar design de um site real: [site-forge.md](./site-forge.md)
+- Para aplicar o skill num build: ficha `ux-ui.md` (em construção)

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

@@ -0,0 +1,136 @@
+# @dev — Implemente a feature seguindo a spec
+
+> **Para quem é:** quem quer que a IA implemente código depois que o planejamento está feito.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:**
+> - Como `@dev` usa os artefatos dos agentes anteriores
+> - O ciclo autônomo QA→Dev e como o `dev-resume` funciona
+
+---
+
+## Para que serve
+
+Você passou por `@product`, `@analyst`, `@architect`. A spec existe, as decisões técnicas estão em disco. Agora é hora de escrever código — mas de forma que o próximo agente (`@qa`, `@validator`) consiga verificar o que foi feito sem perguntar "o que você implementou?".
+
+`@dev` lê os artefatos, implementa, e grava um `dev-state.md` com o resumo do que foi feito, quais arquivos foram tocados, e qual é o próximo passo. Isso é o que permite continuar de onde parou em outra sessão, sem depender do histórico de chat.
+
+**Regra dura de contexto:** ele carrega no máximo 5 arquivos antes de escrever a primeira linha de código. Se precisar de mais, para e pergunta o que priorizar. Isso evita "contexto inchado" que leva a decisões confusas.
+
+---
+
+## Quando invocar
+
+- Após `@architect` (SMALL/MEDIUM) ou `@product` (MICRO).
+- Para retomar uma feature interrompida — `@dev` lê `dev-state.md` e sabe onde parou.
+- Para correções apontadas pelo `@qa` (ciclo autônomo, até 2 iterações).
+
+---
+
+## Quando NÃO invocar
+
+- A spec ainda não existe → volte para `@product`.
+- Você quer revisar o código já escrito → use `@qa` ou `@sheldon`.
+- Você quer pair-programming em cima de trabalho em andamento → use `@deyvin`.
+
+---
+
+## Diálogo típico (cold start)
+
+```
+Você > @dev
+
+@dev > Verificando dev-state.md... não encontrado. Cold start.
+       Lendo project.context.md... Node.js, SMALL, checkout-stripe.
+       Lendo spec-checkout-stripe.md e implementation-plan-checkout-stripe.md...
+       
+       Plano aprovado. Implementando:
+       
+       1. db/migrations/add-payment-table.sql       ← Payment schema
+       2. src/models/payment.js                     ← model com validação básica
+       3. src/services/payment-service.js           ← lógica: criar cobrança Stripe
+       4. src/routes/checkout.js                    ← POST /checkout
+       
+       [implementa...]
+       
+       Smoke test: node -e "require('./src/routes/checkout')" → OK
+       
+       dev-state.md atualizado:
+         status: implemented
+         files_touched: [db/migrations/..., src/models/..., src/services/..., src/routes/...]
+         next_step: @qa
+       
+       Próximo: @qa.
+```
+
+## Diálogo típico (retomada via dev-resume)
+
+```
+Você > @dev
+
+@dev > dev-state.md encontrado.
+       Carregando context_package: spec-checkout-stripe.md, src/routes/checkout.js
+       next_step: "adicionar webhook de confirmação Stripe"
+       Retomando... [continua sem perguntas]
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/context/dev-state.md` | Status, arquivos tocados, próximo passo |
+| Código implementado | onde `@architect` determinou |
+
+---
+
+## Como ele lê seu projeto
+
+Depende do modo:
+
+| Modo | O que carrega (máx. 5 arquivos) |
+|---|---|
+| MICRO | `project.context.md` + `prd-{slug}.md` |
+| SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` |
+| Retomada | Apenas o `context_package` do `dev-state.md` |
+
+**Nunca carrega** arquivos de outros agentes (`.aioson/agents/`), specs de outras features, ou mais de 5 arquivos antes do primeiro código.
+
+---
+
+## Detalhes recentes
+
+**Ciclo autônomo QA→Dev (cap 2, Mai 2026):** quando o `@qa` encontra falhas pequenas (testes falhando, AC não atendido), ele pode enviar correções diretamente ao `@dev` sem você precisar reativar manualmente. O ciclo se repete no máximo 2 vezes. Na terceira falha, ele sobe para você decidir.
+
+**dev-resume helper:** se o `dev-state.md` existe mas está inconsistente com o código (drift detection), o `@dev` detecta a divergência e te avisa antes de continuar.
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Ver estado atual do dev
+cat .aioson/context/dev-state.md
+
+# Verificar preflight antes de implementar
+aioson preflight . --agent=dev --feature=checkout-stripe
+aioson context:validate .
+
+# Pedir resumo de memória das últimas sessões
+aioson memory:summary . --last=5
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@architect` (SMALL/MEDIUM) ou `@product` (MICRO)
+- **Vai para:** `@qa`
+
+---
+
+## Próximo passo
+
+- [Ficha do @qa](./qa.md) — valida o que `@dev` implementou
+- [Ficha do @deyvin](./deyvin.md) — pair-programming em cima do trabalho do `@dev`
+- [Glossário: dev-state, Dossier, Handoff](../1-entender/glossario.md)