@jaimevalasek/aioson 1.3.0

package/docs/pt/genome-3.0-spec.md

@@ -0,0 +1,296 @@
+# Genoma 3.0 — Especificação de Formato
+
+> Versão: 3.0  
+> Status: Ativo  
+> Compatibilidade: retrocompatível com Genoma 2.0  
+> Data: 2026-03-13
+
+---
+
+## Visão geral
+
+O Genoma 3.0 estende o Genoma 2.0 com suporte a profiling de persona baseado em evidências. O objetivo é representar não só o que um domínio exige, mas como uma pessoa específica pensa sobre esse domínio.
+
+O formato mantém as 10 seções canônicas do Genoma 2.0 e adiciona seções específicas para:
+
+- perfil cognitivo
+- estilo de comunicação
+- vieses e blind spots
+- resolução de conflito entre personas, quando houver multi-persona
+
+---
+
+## Tipos de genoma
+
+| Tipo | Versão mínima | Descrição |
+|------|---------------|-----------|
+| `domain` | 2.0 | Conhecimento de domínio puro |
+| `function` | 2.0 | Capacidade funcional específica |
+| `persona` | 3.0 | Perfil cognitivo de pessoa real |
+| `hybrid` | 2.0+ | Combinação de tipos |
+
+### Modos de `hybrid`
+
+| Modo | Versão | Descrição |
+|------|--------|-----------|
+| `domain-function` | 2.0 | Domínio + função |
+| `single-persona` | 3.0 | Persona + domínio |
+| `multi-persona` | 3.0 | Múltiplas personas com papéis atribuídos |
+
+---
+
+## Frontmatter
+
+### Campos base
+
+```yaml
+---
+genome: [slug]
+domain: [human-readable]
+type: [domain|function|persona|hybrid]
+language: [en|pt-BR|es|fr|other]
+depth: [surface|standard|deep]
+version: [2|3]
+format: [genome-v2|genome-v3]
+evidence_mode: [inferred|evidenced|hybrid]
+generated: [YYYY-MM-DD]
+sources_count: [int]
+mentes: [int]
+skills: [int]
+---
+```
+
+### Campos adicionais de persona
+
+Obrigatórios quando `type: persona` e recomendados em `hybrid` com persona:
+
+```yaml
+persona_source: "[Full Name]"
+persona_sources: ["Name 1", "Name 2"]
+disc: "[XY]"
+enneagram: "[XwY]"
+big_five: "O:[H] C:[M] E:[L] A:[L] N:[M]"
+mbti: "[XXXX]"
+confidence: [low|medium|high]
+profiler_report: ".aioson/profiler-reports/[slug]/enriched-profile.md"
+hybrid_mode: [domain-function|single-persona|multi-persona]
+```
+
+### Exemplo de frontmatter persona
+
+```yaml
+---
+genome: stefan-georgi-copywriting
+domain: "Stefan Georgi — Direct Response Copywriting"
+type: persona
+language: pt-BR
+depth: deep
+version: 3
+format: genome-v3
+evidence_mode: evidenced
+generated: 2026-03-13
+sources_count: 27
+mentes: 4
+skills: 8
+persona_source: "Stefan Georgi"
+disc: "DI"
+enneagram: "3w4"
+big_five: "O:H C:H E:H A:M N:L"
+mbti: "ENTJ"
+confidence: medium
+profiler_report: ".aioson/profiler-reports/stefan-georgi/enriched-profile.md"
+---
+```
+
+---
+
+## Seções canônicas
+
+### Obrigatórias em todo genoma
+
+| Seção | Descrição |
+|-------|-----------|
+| `## O que saber` | Nós de conhecimento do domínio |
+| `## Filosofias` | Crenças e axiomas operacionais |
+| `## Modelos mentais` | Lentes cognitivas reutilizáveis |
+| `## Heurísticas` | Atalhos de decisão |
+| `## Frameworks` | Processos estruturados |
+| `## Metodologias` | Abordagens amplas |
+| `## Mentes` | Perspectivas cognitivas acionáveis |
+| `## Skills` | Capacidades operacionais |
+| `## Evidence` | Fontes e rastreabilidade |
+| `## Application notes` | Notas de uso e combinação |
+
+### Obrigatórias em persona
+
+| Seção | Obrigatória | Descrição |
+|-------|-------------|-----------|
+| `## Perfil Cognitivo` | Sim | Resumo psicométrico inferido com evidência |
+| `## Estilo de Comunicação` | Sim | Voz, persuasão e padrões retóricos |
+| `## Vieses e Pontos Cegos` | Sim | Biases, erros recorrentes e compensações |
+| `## Conflict Resolution` | Só multi-persona | Hierarquia e desempate entre personas |
+
+---
+
+## Estrutura recomendada das novas seções
+
+### `## Perfil Cognitivo`
+
+Use esta ordem:
+
+1. aviso explícito de que o perfil é inferido
+2. tabela de resumo psicométrico
+3. tendências cognitivas
+4. hierarquia de valores
+5. Schwartz Values inferidos
+
+Exemplo:
+
+```markdown
+## Perfil Cognitivo
+
+> PERFIL INFERIDO. Não é avaliação psicométrica formal.
+
+### Psychometric Summary
+
+| Framework | Profile | Confidence | Key Evidence |
+|-----------|---------|------------|--------------|
+| DISC | DC — D:8 I:5 S:3 C:8 | medium | alta assertividade + frameworks |
+| Enneagram | 3w4 | medium | foco em performance e diferenciação |
+| Big Five | O:H C:H E:M A:L N:L | medium | discurso ambicioso e baixo hedge |
+| MBTI | ENTJ | low | visão estratégica + decisão direta |
+```
+
+### `## Estilo de Comunicação`
+
+Cobrir:
+
+- tom
+- registro
+- assertividade
+- humor
+- palavrão
+- padrão de frase
+- metáforas
+- uso de dados
+- uso de histórias
+- padrão de persuasão
+- expressões recorrentes
+- comportamento sob pressão
+
+Exemplo:
+
+```markdown
+## Estilo de Comunicação
+
+### Voice Profile
+
+| Dimension | Value | Evidence |
+|-----------|-------|----------|
+| Tone | direto | calls e entrevistas |
+| Register | técnico-acessível | breakdowns públicos |
+| Assertiveness | high | pouca linguagem hedging |
+```
+
+### `## Vieses e Pontos Cegos`
+
+Cobrir:
+
+- vieses cognitivos observados
+- padrões típicos de erro
+- áreas de excesso de confiança
+- áreas de subconfiança
+- guidance compensatório para agentes que aplicarem o genoma
+
+### `## Conflict Resolution`
+
+Obrigatória quando `hybrid_mode: multi-persona`.
+
+Cobrir:
+
+- domínio que cada persona lidera
+- regra de desempate
+- como resolver conflito de framework
+- como resolver conflito de estilo
+- princípio geral de tiebreaker
+
+---
+
+## Regras de compatibilidade
+
+### Leitura por sistema 2.0
+
+Um leitor de Genoma 2.0 deve conseguir:
+
+- ignorar campos extras no frontmatter
+- ignorar seções extras
+- continuar lendo normalmente as 10 seções canônicas
+
+Isso torna o Genoma 3.0 retrocompatível por adição.
+
+### Migração de 2.0 para 3.0
+
+Quando um genoma 2.0 recebe camada de persona:
+
+1. preservar o slug base quando fizer sentido
+2. elevar `version` para `3`
+3. trocar `format` para `genome-v3`
+4. adicionar os campos de persona no frontmatter
+5. manter as 10 seções canônicas
+6. acrescentar as novas seções sem remover conteúdo anterior útil
+
+### Quick mode
+
+Quando um genoma persona for gerado sem profiler completo:
+
+- `evidence_mode: inferred`
+- `confidence: low`
+- incluir disclaimer explícito em `## Application notes`
+
+---
+
+## Meta file recomendado
+
+Além do markdown, recomenda-se um `.meta.json` correspondente com:
+
+```json
+{
+  "genome": "stefan-georgi-copywriting",
+  "domain": "Stefan Georgi — Direct Response Copywriting",
+  "type": "persona",
+  "version": 3,
+  "format": "genome-v3",
+  "language": "pt-BR",
+  "depth": "deep",
+  "evidence_mode": "evidenced",
+  "persona_source": "Stefan Georgi",
+  "disc": "DI",
+  "enneagram": "3w4",
+  "big_five": "O:H C:H E:H A:M N:L",
+  "mbti": "ENTJ",
+  "confidence": "medium",
+  "profiler_report": ".aioson/profiler-reports/stefan-georgi/enriched-profile.md"
+}
+```
+
+---
+
+## Regras de qualidade
+
+- separar expertise real de opinião superficial
+- ancorar claims principais em evidência
+- deixar explícito o que é inferência
+- não tratar psicometria como verdade clínica
+- expor limitações e contextos onde a persona falha
+
+---
+
+## Ordem recomendada de geração
+
+1. consolidar `enriched-profile.md`
+2. transformar expertise em `## O que saber`
+3. transformar crenças em `## Filosofias`
+4. transformar frameworks e heurísticas em blocos aplicáveis
+5. gerar `## Mentes` como modos cognitivos acionáveis
+6. preencher as seções novas de persona
+7. fechar com `## Evidence` e `## Application notes`

package/docs/pt/guia-engineer.md

@@ -0,0 +1,226 @@
+# Guia do Engenheiro: Pair Programming com IA
+
+> Baseado na metodologia de Fabio Akita — ["Do Zero à Pós-Produção em 1 Semana"](https://akitaonrails.com/2026/02/20/do-zero-a-pos-producao-em-1-semana-como-usar-ia-em-projetos-de-verdade-bastidores-do-the-m-akita-chronicles/)
+
+Este guia não é sobre agentes — é sobre **como você trabalha com eles**. A diferença entre um desenvolvedor que usa IA com eficiência e um que perde tempo é quase sempre a qualidade das instruções e a disciplina do processo, não a IA em si.
+
+---
+
+## O mito do one-shot prompt
+
+Você não vai resolver um problema real de software com um único prompt bem construído. Isso é mito.
+
+A IA é como um programador extremamente esforçado que:
+- Executa ordens explícitas e sem ambiguidade com alta precisão
+- Comete erros frequentes quando as instruções são vagas
+- Não conhece o seu negócio, seu cliente, sua história de decisões
+- Toma decisões arquiteturais ruins sem contexto suficiente
+- Perde o fio da meada em sessões longas sem documentação
+
+**A sua spec é a sua proteção.** Quando algo der errado — e vai dar — a primeira pergunta não é "a IA errou?", mas: "minha instrução estava clara o suficiente?"
+
+---
+
+## Squad mode vs Engineer mode
+
+O AIOSON oferece dois modos de trabalho. Escolha o que se encaixa no momento:
+
+| | Squad mode | Engineer mode |
+|---|---|---|
+| **O que é** | Pipeline sequencial de agentes | Pair programming iterativo |
+| **Quando usar** | Greenfield, times, iniciantes, feature grande | Dev experiente com visão clara do que fazer |
+| **Documento central** | `discovery.md` → `architecture.md` → `prd.md` | `spec.md` (vivo, evolui com o projeto) |
+| **Cadência** | Feature completa por ciclo de agentes | Passos atômicos, commit por passo |
+| **Ideal para** | "Não sei exatamente o que o projeto precisa" | "Sei o que preciso, quero executar rápido" |
+
+Os dois modos **coexistem**. Você pode usar o squad para descobrir e arquitetar, depois usar o engineer mode para implementar rapidamente.
+
+---
+
+## O spec.md: a spec viva
+
+O `spec.md` é o documento mais importante para projetos que duram mais de uma sessão. É o único que evolui — os outros são estáticos.
+
+### Por que não o project.context.md?
+
+`project.context.md` captura o **início** do projeto: stack, classificação, framework. Não muda.
+
+`spec.md` captura o **presente**: o que está feito, o que está em andamento, as decisões tomadas hoje, os bloqueios atuais. Muda toda sessão.
+
+### Quando usar
+
+- Projetos SMALL e MEDIUM que duram mais de um dia
+- Quando você para e retoma o projeto dias depois
+- Quando há decisões técnicas que precisam ser preservadas entre sessões
+
+### Como manter
+
+1. Crie via `/setup` (o agente vai perguntar) ou manualmente
+2. Atualize ao final de cada sessão com `*update-spec`
+3. Releia no início de cada sessão antes de qualquer prompt
+
+O `spec.md` fica em `.aioson/context/spec.md` e **não é obrigatório** — para projetos MICRO e sessões curtas, não precisa.
+
+---
+
+## O ritual de sessão
+
+A diferença entre sessões produtivas e sessões onde você "ficou dando voltas" quase sempre está no início.
+
+### Início (2 minutos)
+
+```
+1. Ler project.context.md
+2. Ler spec.md (se existir)
+3. Definir UMA coisa a fazer nessa sessão
+4. Escrever em texto simples o que espera ao final
+```
+
+Não comece sem saber onde quer chegar. "Vou trabalhar no projeto" não é um objetivo.
+
+### Durante
+
+- Um passo de cada vez
+- Valide antes de avançar
+- Commite cada passo que funciona
+- Documente decisões no spec.md enquanto estão frescas
+
+### Fim (3 minutos)
+
+```
+1. Resumir o que foi feito
+2. Listar o que ficou pendente
+3. Digitar *update-spec para o @orchestrator atualizar o spec.md
+4. Fazer o commit final se necessário
+```
+
+---
+
+## Anatomia de uma instrução eficaz
+
+### Prompt ruim
+
+```
+Crie o sistema de notificações
+```
+
+Por que é ruim: deixa tudo em aberto — onde fica o código, que tipo de notificação, qual padrão seguir, o que não criar. A IA vai inventar.
+
+### Prompt bom
+
+```
+Preciso criar um Job chamado SendNotificationJob em app/Jobs/ que usa a
+interface NotificationChannel (já existe em app/Contracts/). O job deve
+receber $userId e $message, buscar o usuário via User::find(), e chamar
+$channel->send($user, $message). Deve implementar ShouldBeUnique com
+uniqueId() baseado em $userId. Não crie nenhuma migration nem modifique
+o model User.
+```
+
+Por que é bom: localização exata, dependências nomeadas, comportamento esperado, e o que **não** fazer.
+
+### Template para qualquer instrução
+
+```
+Preciso [ação] chamado [nome] em [localização].
+Deve [comportamento esperado].
+Depende de: [dependências existentes].
+Não crie/modifique: [o que está fora do escopo].
+```
+
+---
+
+## A checklist de clarificação (antes de codar)
+
+Use isso antes de pedir implementação de qualquer feature:
+
+```
+[ ] O que exatamente precisa ser feito? (comportamento esperado)
+[ ] Quem usa isso? (contexto de usuário/ator)
+[ ] Qual o critério de "pronto"? (definição de done)
+[ ] Isso quebra algo existente? (impacto)
+[ ] Existe uma forma mais simples? (YAGNI check)
+[ ] Quais arquivos/classes serão criados ou modificados?
+[ ] Precisa de migration? Job? Event?
+[ ] O padrão está alinhado com o architecture.md?
+```
+
+Se você não consegue responder todas, pergunte ao @analyst antes de ir para @dev.
+
+---
+
+## Execução atômica
+
+A instrução ao @dev foi incorporada ao agente, mas o conceito vale para qualquer interação:
+
+**Regra:** Um passo de cada vez. Valide antes de avançar.
+
+```
+Sessão típica com @dev:
+
+[você] Próximo passo: criar a migration da tabela appointments.
+[dev]  Migration criada. [mostra código]
+[você] OK. Próximo: criar o model Appointment com os relacionamentos.
+[dev]  Model criado. [mostra código]
+[você] OK. Próximo: criar o CreateAppointmentAction.
+```
+
+Nunca: "Crie a migration, o model, a action, o controller e os testes."
+
+Por quê? Porque se a action estiver errada, você vai ter que refazer o controller e os testes junto. E a IA vai misturar decisões entre os arquivos de formas que você não pediu.
+
+---
+
+## Quando a IA diverge do esperado
+
+1. **Não discuta** — corrija com precisão
+2. Errado: "Isso não está certo, tente de novo"
+3. Certo: "Você criou a classe em `app/Services/` mas o padrão deste projeto é `app/Domain/{Modulo}/Services/`. Mova para lá."
+4. Se acontecer duas vezes, adicione uma regra explícita ao `spec.md` ou `architecture.md`
+
+---
+
+## Vigilância permanente
+
+Estas áreas exigem revisão sua — não delegue cegamente:
+
+| Área | Por quê revisar |
+|---|---|
+| Segurança | Auth, autorização, sanitização: a IA não conhece seu modelo de ameaças |
+| Performance | N+1 queries, falta de índices, cache ausente |
+| Concorrência | Race conditions em Jobs, falta de locks |
+| Arquitetura global | A IA vê o arquivo, não o sistema. Você vê o todo |
+| Regras de negócio edge cases | Ela não conhece seu cliente como você |
+
+Estas áreas são confiáveis para delegação:
+
+| Área | Por quê confiar |
+|---|---|
+| Boilerplate com padrão definido | Sem ambiguidade, resultado previsível |
+| Transformações de dados com spec clara | Input/output bem definidos |
+| Testes unitários para lógica delimitada | Escopo fechado |
+| Refactoring com instrução precisa | "Mova X para Y seguindo o padrão Z" |
+| Documentação de código existente | Não há o que inventar |
+
+---
+
+## Métricas que importam
+
+Ao final de um projeto ou sprint:
+
+| Métrica | O que revela |
+|---|---|
+| Features em produção estáveis | Qualidade real do processo |
+| Retrabalho por sessão | Clareza das instruções |
+| Decisões documentadas no spec.md | Maturidade do processo |
+| Commits por sessão | Cadência de entrega |
+
+Uma feature bem feita vale mais que dez features quebradas.
+
+---
+
+## Veja também
+
+- [Cenários práticos](./cenarios.md) — exemplos por stack com todos os agentes
+- [Guia de agentes](./agentes.md) — o que cada agente faz
+- [Início rápido](./inicio-rapido.md) — primeiros passos

package/docs/pt/inicio-rapido.md

@@ -0,0 +1,138 @@
+# Início Rápido
+
+> Instale, configure e use os agentes de IA em menos de 10 minutos.
+
+## Pré-requisitos
+
+- Node.js 18+
+- Um projeto de software (existente ou novo)
+- Claude, Codex, Gemini ou OpenCode configurado no seu editor
+
+---
+
+## 1. Instalação
+
+### Novo projeto (recomendado)
+
+```bash
+mkdir meu-projeto && cd meu-projeto
+npx @jaimevalasek/aioson init
+```
+
+### Projeto existente
+
+```bash
+cd meu-projeto
+npx @jaimevalasek/aioson install
+```
+
+Isso cria a pasta `.aioson/` com todos os arquivos de configuração, agentes e contexto.
+
+Se o projeto já for brownfield e você quiser gerar um panorama inicial da base, rode depois:
+
+```bash
+npx @jaimevalasek/aioson scan:project . --folder=src
+```
+
+O scanner cria estes arquivos localmente:
+
+- `.aioson/context/scan-index.md`
+- `.aioson/context/scan-folders.md`
+- `.aioson/context/scan-<pasta>.md`
+- `.aioson/context/scan-aioson.md`
+
+Se você também quiser gerar `discovery.md` e `skeleton-system.md`, ative a etapa opcional com LLM:
+
+```bash
+npx @jaimevalasek/aioson scan:project . --folder=src --with-llm --provider=openai
+```
+
+---
+
+## 2. Configure o contexto do projeto
+
+```bash
+npx @jaimevalasek/aioson setup:context
+```
+
+O CLI vai fazer perguntas sobre seu projeto:
+
+```
+? Nome do projeto: minha-loja
+? Tipo de projeto: web_app
+? Framework principal: Laravel
+? Framework instalado? Sim
+? Classificação: SMALL
+? Idioma de conversa: pt-BR
+```
+
+Isso gera `.aioson/context/project.context.md` — o arquivo que orienta todos os agentes.
+
+---
+
+## 3. Abra seu AI IDE e comece
+
+No **Claude Code** (CLAUDE.md já configurado):
+```
+/aioson/setup
+```
+
+No **Codex** (AGENTS.md já configurado — sem slash commands):
+```
+use the @setup agent to onboard this project
+```
+
+No **Gemini CLI** (`.gemini/commands/` já configurado):
+```
+/aios-setup
+```
+
+O agente `@setup` detecta o framework, faz as perguntas e gera o `project.context.md`.
+
+> Cada CLI tem uma forma diferente de invocar agentes. Consulte o [Guia de CLIs de IA](./clientes-ai.md) para exemplos detalhados de Claude Code, Codex e Gemini.
+
+---
+
+## Qual sequência usar?
+
+| Tamanho do projeto | Sequência de agentes |
+|---|---|
+| **MICRO** — 0–1 ponto | `@setup → @dev` |
+| **SMALL** — 2–3 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @dev → @qa` |
+| **MEDIUM** — 4–6 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa` |
+
+### Atalho recomendado quando o escopo ainda está nebuloso
+
+Se a demanda ainda estiver vaga, se a feature for grande ou se houver risco alto de retrabalho, use:
+
+```text
+@setup -> @discovery-design-doc -> proximo agente recomendado
+```
+
+Exemplos:
+- projeto novo ainda mal definido
+- feature grande em sistema existente
+- integrações sensíveis como billing, webhooks, Stripe ou permissões
+
+Esse passo de `@discovery-design-doc` é **recomendado quando agrega clareza**, não obrigatório.
+Se o pedido já estiver claro e pequeno, siga o fluxo normal.
+
+**Não sabe o tamanho?** Responda 3 perguntas:
+1. Quantos tipos de usuário? (1=0pt, 2=1pt, 3+=2pt)
+2. Quantas integrações externas? (0=0pt, 1-2=1pt, 3+=2pt)
+3. Regras de negócio complexas? (nenhuma=0pt, algumas=1pt, muitas=2pt)
+
+- 0–1 pontos → **MICRO**
+- 2–3 pontos → **SMALL**
+- 4–6 pontos → **MEDIUM**
+
+---
+
+## Próximos passos
+
+- [Referência completa dos comandos do CLI](./comandos-cli.md)
+- [Como usar com Claude Code, Codex e Gemini](./clientes-ai.md)
+- [Cenários completos com exemplos práticos](./cenarios.md)
+- [Guia de agentes: quando usar cada um](./agentes.md)
+- [Suporte a projetos Web3](./web3.md)
+- [Orquestração paralela para projetos MEDIUM](../en/parallel.md)