@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/1-entender/glossario.md

@@ -0,0 +1,288 @@
+# Glossário AIOSON
+
+> **Para quem é:** qualquer um lendo as outras docs e tropeçando em jargão.
+> **Tempo de leitura:** consulta — leia o que precisar.
+> **Como usar:** Ctrl+F é seu amigo.
+
+Termos em ordem alfabética. Cada um tem **definição curta** + **exemplo concreto** + **onde ver mais**.
+
+---
+
+## Agente
+
+**Definição:** um especialista virtual com prompt próprio, regras próprias e responsabilidade específica. Vive em `.aioson/agents/<nome>.md`.
+
+**Exemplo:** `@dev` é o agente que implementa código. `@qa` é o que escreve testes. `@pentester` é o que tenta quebrar a feature de propósito.
+
+**Como invocar:** digite `@nome` no seu cliente AI (Claude, Codex, Gemini, OpenCode) ou descreva a intenção em linguagem natural ("vamos implementar a feature").
+
+---
+
+## AIOSON
+
+**Definição:** o framework em si. Um pacote npm (`@jaimevalasek/aioson`) que instala uma estrutura de agentes, regras e ferramentas no seu projeto.
+
+**Exemplo:** rodando `npx @jaimevalasek/aioson init meu-app` cria a pasta `.aioson/` no seu projeto.
+
+---
+
+## AIOSON Cloud / aioson.com
+
+**Definição:** o serviço hospedado para publicar e instalar squads, genomes e skills entre projetos.
+
+**Exemplo:** você cria um squad de agentes para o domínio jurídico no seu projeto, roda `aioson system:publish`, e qualquer outro projeto pode rodar `aioson system:install <slug>`.
+
+**Onde ver mais:** doc em construção em `5-referencia/aioson-com-store.md`.
+
+---
+
+## Artefato
+
+**Definição:** qualquer arquivo que um agente cria ou atualiza como saída do seu trabalho.
+
+**Exemplos:**
+- `.aioson/context/project.context.md` — contexto do projeto (criado por `@setup`)
+- `.aioson/context/features/<slug>/spec.md` — especificação de uma feature (criada por `@product`/`@analyst`)
+- `.aioson/context/dossier/<slug>/` — dossier de feature (criado pelo agent-chain)
+
+**Por que importa:** Artigo III da Constitution diz que trabalho importante deixa artefato. Sem artefato, o trabalho "não aconteceu" oficialmente.
+
+---
+
+## Brains
+
+**Definição:** memória procedural de um agente — conhecimento estruturado em "nodes" (estilo Zettelkasten) que o agente carrega sob demanda.
+
+**Exemplo:** o `@site-forge` tem brains com 14 nodes sobre como o `pt.squarespace.com` estrutura suas páginas, usados quando você pede um clone.
+
+**Onde fica:** `.aioson/brains/<agente>/`.
+
+---
+
+## Briefing
+
+**Definição:** documento pré-PRD que enquadra um problema antes de virar feature. Saída do agente `@briefing` (antigo `@cypher`).
+
+**Exemplo:** você tem 5 anotações soltas sobre uma ideia. O `@briefing` as transforma num briefing estruturado com problema, hipóteses e *frames* de discovery.
+
+---
+
+## Classificação (MICRO / SMALL / MEDIUM)
+
+**Definição:** o tamanho do projeto, calculado a partir de 3 fatores (tipos de usuário, integrações externas, regras de negócio). Define quanta cerimônia o workflow vai aplicar.
+
+**Como funciona:**
+- 0–1 ponto → **MICRO** (`@setup → @product → @dev`)
+- 2–3 pontos → **SMALL** (`@setup → @product → @analyst → @architect → @dev → @qa`)
+- 4–6 pontos → **MEDIUM** (workflow completo, todos os gates, todos os artefatos)
+
+**Onde aparece:** `classification:` no frontmatter do `project.context.md`.
+
+---
+
+## Cliente AI
+
+**Definição:** o programa onde você de fato conversa com a IA. AIOSON é agnóstico — funciona com vários.
+
+**Suportados oficialmente:** Claude Code, Codex CLI, Gemini CLI, OpenCode.
+**Funciona também via terminal:** VS Code, Cursor, Windsurf, JetBrains IDEs, Zed, Antigravity (qualquer um que abra um terminal).
+
+**Onde ver mais:** `clientes-ai.md`.
+
+---
+
+## Committer
+
+**Definição:** o agente `@committer` que gera mensagens de commit profissionais a partir do diff e do contexto.
+
+**Exemplo:** depois de implementar uma feature, `@committer` lê o que mudou, propõe a mensagem, mostra um checkbox no terminal, e commita.
+
+---
+
+## Constitution
+
+**Definição:** os 6 (atualmente 7, com Zero Trust) princípios em `.aioson/constitution.md`. Nenhum agente pode contradizer um artigo.
+
+**Detalhe completo:** [Por que ele existe](./por-que-existe.md#os-6-princípios-da-constitution).
+
+---
+
+## Context Pack
+
+**Definição:** um conjunto mínimo, curado, de arquivos que um agente lê para fazer o seu trabalho — em vez de varrer o projeto todo.
+
+**Por que importa:** economiza janela de contexto. O `@dev` para uma feature de "adicionar campo no formulário" não precisa ler o projeto inteiro.
+
+---
+
+## Continuity (agent-chain-continuity)
+
+**Definição:** o sistema que garante que, se uma sessão cair no meio de uma feature, a próxima sessão consegue retomar sem perder contexto. Implementado em fases (1 a 8) ao longo de Mar–Mai 2026.
+
+**Componentes principais:** `dossier`, `dev-state.md`, `dev-resume`, `handoff-protocol.json` v2, drift detection.
+
+---
+
+## Design Skill
+
+**Definição:** um skill especializado em um sistema visual (cores, tipografia, espaçamento, componentes). Pode ser um skill nativo ou um híbrido criado pelo `@design-hybrid-forge`.
+
+**Exemplos prontos:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
+
+**Onde escolher:** durante o `aioson init`, no wizard.
+
+---
+
+## Dossier (Feature Dossier)
+
+**Definição:** uma pasta `.aioson/context/dossier/<slug>/` que contém **tudo** sobre uma feature em curso: spec, plano, decisões, código tocado, índice de pesquisas, status.
+
+**Por que importa:** é o ponto único para onde qualquer agente que entra na feature vai consultar. Substitui "vou reler o histórico inteiro".
+
+**Comandos:** `aioson dossier:init`, `dossier:show`, `dossier:add-research`, `dossier:audit`.
+
+---
+
+## Genome
+
+**Definição:** "DNA cognitivo" de uma persona — um YAML estruturado com traços de personalidade (DISC, Enneagram, Big Five, MBTI, HEXACO-H), estilo, tom, e instruções de advisor.
+
+**Para que serve:** criar advisors (assistentes personalizados) que falam como uma pessoa específica. Exemplo: gerar um advisor "estilo Steve Jobs" para revisar pitch decks.
+
+**Versão atual:** Genome 4.0 com `anchor_prompt`, `relations`, `hexaco_h`, `trait_interactions`.
+
+**Onde ver mais:** `5-referencia/genome-4.0-spec.md` (em construção).
+
+---
+
+## Handoff
+
+**Definição:** o momento em que um agente termina sua parte e passa para o próximo, deixando os artefatos prontos.
+
+**Onde fica registrado:** `.aioson/context/handoff-protocol.json` (v2).
+
+---
+
+## Live Session
+
+**Definição:** uma sessão "rastreada" — ou seja, um envelope que registra cada milestone no SQLite local para o dashboard mostrar.
+
+**Comandos:** `aioson live:start`, `live:status`, `live:handoff`, `live:close`.
+
+---
+
+## Memory
+
+**Definição:** a memória persistente do AIOSON. Recentemente ganhou uma camada de **active retrieval** — agentes podem buscar memórias relevantes, não só ler tudo.
+
+**Onde fica:** `.aioson/memory/` (no projeto) e `~/.claude/projects/<hash>/memory/` (no usuário, para Claude Code).
+
+---
+
+## Neo
+
+**Definição:** o agente `@neo` — roteador inteligente. Ele olha o estado do projeto e te diz qual agente faz sentido invocar agora.
+
+**Quando usar:** quando você não sabe por onde continuar ("show project status", "where do I start?"). Recentemente ganhou catálogo completo do ecossistema e modo *ecosystem-inquiry*.
+
+---
+
+## Pentester
+
+**Definição:** agente `@pentester` que faz revisão adversarial de segurança — varre OWASP Top 10, LLM Top 10, supply chain, e mapeia superfícies de ataque.
+
+**Quando usar:** antes de publicar feature em produção, ou quando precisar de um audit point específico.
+
+---
+
+## Pipeline / Workflow
+
+**Definição:** a sequência ordenada de agentes que o AIOSON aplica para uma feature, baseada na classificação.
+
+**Comando central:** `aioson workflow:next .` — mostra qual agente é o próximo.
+
+---
+
+## Plan
+
+**Definição:** documentos em `/plans/` (raiz do projeto) que descrevem uma execução planejada. Não são commitados (memória local).
+
+**Para que servem:** planejar antes de executar; servem como "plano-semente" para features.
+
+---
+
+## Profiler (researcher / enricher / forge)
+
+**Definição:** o pipeline em 3 etapas que cria um Genome a partir de uma pessoa pública.
+
+1. `@profiler-researcher` — coleta material bruto.
+2. `@profiler-enricher` — analisa cognitivamente.
+3. `@profiler-forge` — gera o Genome 4.0 e o advisor.
+
+---
+
+## Project Pulse
+
+**Definição:** arquivo `.aioson/context/project-pulse.md` — estado global vivo do projeto. Lido no início de cada sessão, atualizado no fim.
+
+**Para que serve:** dar a qualquer agente entrante uma visão "o que está acontecendo neste projeto agora?".
+
+---
+
+## Rules
+
+**Definição:** regras *hard* do projeto, em `.aioson/rules/*.md`. Ao contrário de instruções soltas no prompt, regras são lidas automaticamente por todos os agentes aplicáveis.
+
+**Exemplo:** `security-baseline.md` declara os controles `SEC-SBD-01..08` que `@dev` e `@qa` consomem.
+
+---
+
+## Skill
+
+**Definição:** um pacote plugável de instrução. Tipos:
+- **Process skills** — metodologias (ex: `aioson-spec-driven`)
+- **Design skills** — sistemas visuais (ex: `clean-saas-ui`)
+- **Static skills** — conhecimento de domínio fixo
+- **Dynamic skills** — geram instruções em tempo real
+
+**Onde ficam:** `.aioson/skills/` no projeto, ou globalmente.
+
+---
+
+## Squad
+
+**Definição:** um grupo de agentes customizados — feito sob medida para um domínio que o time padrão não cobre bem.
+
+**Exemplo:** squad "compliance jurídico" com agentes `@regulator`, `@attorney`, `@auditor`, sob comando do `@squad`.
+
+**Comandos:** `aioson squad:assemble`, `squad:agent-create`, `squad:refresh`.
+
+---
+
+## Tester
+
+**Definição:** agente `@tester` — engenharia de testes sistemática para apps já implementados. Usa quando o `@qa` regular não basta (legacy, brownfield, lacunas em 3+ módulos).
+
+**Recente:** ganhou *coverage quality tier* e *test smell audit*.
+
+---
+
+## Validator
+
+**Definição:** agente `@validator` — valida tecnicamente uma feature contra o contrato de sucesso definido na spec, antes do close-out.
+
+---
+
+## Workflow
+
+Ver **Pipeline / Workflow**.
+
+---
+
+## Zero Trust
+
+**Definição:** Artigo VII da Constitution. Segurança não é uma "feature opcional" — é o estado padrão. Toda feature passa por checks automáticos do baseline.
+
+---
+
+Não achou um termo? Procure no [Mapa do ecossistema](./mapa-do-ecossistema.md) ou no [guia de agentes](../agentes.md).

package/docs/pt/1-entender/mapa-do-ecossistema.md

@@ -0,0 +1,228 @@
+# Mapa do ecossistema AIOSON
+
+> **Para quem é:** quem quer ver o time inteiro de uma vez.
+> **Tempo de leitura:** 8 min.
+> **O que você vai sair sabendo:** quem são os 28 agentes, em que momento cada um entra, e como eles se conversam.
+
+---
+
+## Visão de alto nível
+
+```
+                       ┌──────────────────┐
+                       │   Você + cliente │
+                       │       AI         │
+                       └────────┬─────────┘
+                                │
+                ┌───────────────┼───────────────┐
+                ▼               ▼               ▼
+         ┌──────────┐    ┌──────────┐    ┌──────────┐
+         │  Setup   │    │   Neo    │    │ Briefing │
+         │  (boot)  │    │ (rotear) │    │ (pré-PRD)│
+         └────┬─────┘    └────┬─────┘    └────┬─────┘
+              │               │               │
+              └───────┬───────┴───────┬───────┘
+                      │               │
+                      ▼               ▼
+        ┌──────────────────────────────────────┐
+        │       NÚCLEO DE DESENVOLVIMENTO      │
+        │                                      │
+        │  Product → Sheldon → Analyst →       │
+        │  Architect → UX-UI → PM →            │
+        │  Orchestrator → Dev → QA →           │
+        │  Validator → Tester → Pentester      │
+        │                                      │
+        └──────────────────────────────────────┘
+                      │
+                      ▼
+        ┌──────────────────────────────────────┐
+        │      CONTINUIDADE & ENTREGA          │
+        │                                      │
+        │  Deyvin (pair) · Committer (git)     │
+        │  Discover (cache semântico)          │
+        │                                      │
+        └──────────────────────────────────────┘
+                      │
+                      ▼
+        ┌──────────────────────────────────────┐
+        │         ESPECIALIZAÇÕES              │
+        │                                      │
+        │  Squad · Genome · Profiler trio ·    │
+        │  Site-Forge · Design-Hybrid-Forge ·  │
+        │  Orache · Copywriter                 │
+        │                                      │
+        └──────────────────────────────────────┘
+```
+
+---
+
+## Os agentes, agrupados por papel
+
+### 1. Boot e roteamento
+
+| Agente | O que faz | Quando invocar |
+|---|---|---|
+| **`@setup`** | Onboarding do projeto: detecta stack, classifica MICRO/SMALL/MEDIUM, escreve `project.context.md` | Sempre primeiro num projeto novo |
+| **`@neo`** | Olha o estado e sugere o próximo agente | Quando você não sabe o que fazer agora |
+| **`@briefing`** | Transforma plans/anotações soltas em um briefing pré-PRD | Você tem ideias, não tem feature ainda |
+
+### 2. Núcleo de desenvolvimento (workflow oficial)
+
+A ordem padrão depende da classificação:
+
+**MICRO:** `@setup → @product (opcional) → @dev`
+**SMALL:** `@setup → @product → @sheldon (opcional) → @analyst → @architect → @dev → @qa`
+**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+
+> **Por que `@sheldon` aparece tão cedo?** Ele é o **PRD quality guardian** — roda *entre* `@product` e `@analyst` para detectar gaps, validar premissas técnicas com pesquisa web, e decidir entre enriquecer o PRD in-place ou criar um phased plan em `.aioson/plans/{slug}/`. Pode ser invocado N vezes no mesmo PRD. Pular essa etapa em features sérias custa caro lá na frente.
+
+| Agente | O que faz | Saída principal |
+|---|---|---|
+| **`@product`** | Define visão, escopo, PRD da feature | `prd.md`, `spec.md` |
+| **`@sheldon`** | PRD quality guardian — gap analysis, web research, sizing, decide in-place vs phased plan | `sheldon-enrichment-{slug}.md` ou `.aioson/plans/{slug}/` |
+| **`@analyst`** | Descobre domínio, entidades, fluxos no codebase | `architecture.md`, ER diagrams |
+| **`@architect`** | Decisões técnicas: estrutura, libs, integração | `architecture.md` (decisões) |
+| **`@ux-ui`** | Design system e specs de componentes (MEDIUM) | `design-doc.md`, `discovery.md` |
+| **`@pm`** | Backlog, user stories, ACs (MEDIUM) | `tasks.md`, user stories |
+| **`@orchestrator`** | Coordena lanes paralelas (MEDIUM) | `parallel/`, plano de execução |
+| **`@dev`** | Implementa a feature | Código + `dev-state.md` |
+| **`@qa`** | Escreve testes, valida ACs, ciclo autônomo de correção (cap 2) | `test-plan.md`, `qa-report-*.md` |
+| **`@validator`** | Valida tecnicamente contra `harness-contract.json` em sandbox de contexto | `.aioson/plans/{slug}/last-validator-output.json` (consumido por `harness:apply-validation`, atualiza `progress.json`) |
+| **`@tester`** | Engenharia sistemática de testes (legacy/brownfield) | `test-inventory.md`, coverage tier |
+| **`@pentester`** | Revisão adversarial de segurança (OWASP, LLM Top 10) | `security-findings-*.json` |
+
+### 3. Continuidade e entrega
+
+| Agente | O que faz | Quando invocar |
+|---|---|---|
+| **`@deyvin`** (alias `@pair`) | Pair-programming continuity-first — recupera estado com `confirmed/inferred`, trabalha em batches pequenos validados, scope gate automático (recusa greenfield e devolve para `@product`) | Retomar feature em curso após crash, debugar slice pequena, pair em tarefa já delimitada |
+| **`@committer`** | Gera mensagens de commit profissionais | Antes de commitar |
+| **`@discover`** | Constrói cache semântico do projeto: produz `bootstrap/` (estruturado por tipo de artefato, para agentes lerem) **e** `brains/` (Zettelkasten para cross-referência) | Onboarding rápido em codebase grande |
+
+### 4. Especializações
+
+| Agente | O que faz |
+|---|---|
+| **`@squad`** | Cria/gerencia squads customizados (`refresh`, `agent-create`) |
+| **`@genome`** | Cria e aplica genomes (DNA cognitivo de personas) |
+| **`@profiler-researcher`** | Coleta material bruto sobre uma pessoa pública |
+| **`@profiler-enricher`** | Analisa cognitivamente o material |
+| **`@profiler-forge`** | Gera o Genome 4.0 + advisor |
+| **`@site-forge`** | Clona, reconstrói ou extrai design de qualquer URL |
+| **`@design-hybrid-forge`** | Combina dois design skills em um híbrido |
+| **`@orache`** | Investigação de domínio e pesquisa estratégica |
+| **`@copywriter`** | Copy de conversão para landing pages, emails |
+| **`@discovery-design-doc`** | Discovery + design doc combinados (modo conjunto) |
+
+---
+
+## Como os agentes "conversam"
+
+Eles **não conversam diretamente entre si**. Eles conversam **através de artefatos** em disco. Esse é o coração da arquitetura.
+
+```
+┌─────────────┐  escreve   ┌──────────────────┐  lê   ┌──────────────┐
+│  @product   ├───────────▶│  spec.md         │◀──────┤  @architect  │
+└─────────────┘            │  prd.md          │       └──────────────┘
+                           └──────────────────┘
+                                    │
+                                    ▼ lê
+                           ┌──────────────────┐  lê   ┌──────────────┐
+                           │  @architect      │       │  @dev        │
+                           │  escreve →       ├──────▶│              │
+                           │  architecture.md │       └──────┬───────┘
+                           └──────────────────┘              │
+                                                              ▼ escreve
+                                                     ┌──────────────────┐
+                                                     │  dev-state.md    │
+                                                     │  (código)        │
+                                                     └────────┬─────────┘
+                                                              │ lê
+                                                              ▼
+                                                     ┌──────────────┐
+                                                     │  @qa         │
+                                                     └──────────────┘
+```
+
+**Vantagem:** se uma sessão cai, o próximo agente só precisa ler os artefatos. Não há "memória conversacional" perdida.
+
+---
+
+## Onde os artefatos vivem
+
+```
+seu-projeto/
+└── .aioson/
+    └── context/
+        ├── project.context.md      ← contexto global (criado por @setup)
+        ├── project-pulse.md        ← estado vivo, atualizado a cada sessão
+        ├── architecture.md         ← decisões de @analyst e @architect
+        ├── prd.md                  ← saída de @product
+        ├── design-doc.md           ← saída de @ux-ui
+        ├── tasks.md                ← saída de @pm
+        ├── dev-state.md            ← saída de @dev (status atual)
+        ├── test-plan.md            ← saída de @qa
+        ├── security-findings-*.json ← saída de @pentester
+        ├── handoff-protocol.json   ← último handoff entre agentes
+        ├── features/<slug>/        ← features em desenvolvimento
+        ├── done/                   ← features arquivadas (after feature:close)
+        └── dossier/<slug>/         ← dossier por feature (Phase 1+ do continuity)
+```
+
+---
+
+## "Eu não sei qual agente usar"
+
+Use o `@neo`. É literalmente o agente "estou perdido".
+
+```
+Você no Claude Code:
+> @neo
+
+@neo:
+> Lendo project-pulse.md... você está no projeto "minha-loja", classificação SMALL,
+  com a feature "checkout-stripe" em andamento. O @dev terminou ontem.
+> Próximo passo natural: @qa para escrever testes da feature.
+> Se quiser revisar segurança antes do QA: @pentester.
+> Se quiser fazer um pair antes: @deyvin.
+```
+
+---
+
+## Diálogo real — ciclo SMALL completo
+
+```
+─── Sessão 1 ───
+Você > @setup
+@setup > Detectei Node.js + Express + Postgres. Tipo de projeto? [api/web_app/site/...]
+Você > web_app
+@setup > Quantos tipos de usuário? Quantas integrações externas?
+Você > 2 / 3
+@setup > Classificado como SMALL. Idioma de interação? [en/pt-BR/es/fr]
+Você > pt-BR
+@setup > project.context.md criado. Próximo: @product.
+
+─── Sessão 1 (continua) ───
+Você > @product
+@product > Vamos começar uma feature. Como ela se chama? Qual o problema?
+Você > "checkout-stripe", finalizar pedido com cartão.
+@product > [...várias perguntas...] Spec criada em context/features/checkout-stripe/spec.md.
+@product > Próximo: @analyst para mapear o domínio.
+
+─── Sessão 2 (no dia seguinte) ───
+Você > @neo
+@neo > Você parou em @product. Próximo: @analyst.
+Você > @analyst
+@analyst > [lê spec.md, examina codebase] Mapeei: Order, Customer, Payment, OrderItem.
+@analyst > Decisão registrada em architecture.md. Próximo: @architect.
+
+─── e assim por diante até @qa ───
+```
+
+---
+
+## Próximo passo
+
+- Quer pôr em prática? → [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)
+- Confuso com algum termo? → [Glossário](./glossario.md)
+- Curioso sobre por que tudo isso? → [Por que ele existe](./por-que-existe.md)

package/docs/pt/1-entender/o-que-e-aioson.md

@@ -0,0 +1,94 @@
+# O que é o AIOSON
+
+> **Para quem é:** quem ainda não usou.
+> **Tempo de leitura:** 5 min.
+> **O que você vai sair sabendo:** o que é AIOSON, o que ele faz por você, e quando *não* usar.
+
+---
+
+## Em uma frase
+
+AIOSON transforma uma única IA genérica num **time de especialistas que se revezam** durante o seu projeto, cada um focado em uma etapa, com regras claras de quando começar e quando passar a tarefa para o próximo.
+
+## A analogia da orquestra
+
+Imagine que você quer construir uma casa.
+
+**Sem AIOSON:** você contrata um único profissional super-genérico e diz "faz minha casa". Ele tenta ser arquiteto, pedreiro, eletricista, encanador e fiscal de obra ao mesmo tempo. Às vezes acerta. Frequentemente esquece detalhes. Quando algo dá errado, ele não lembra mais por que tomou a decisão de duas horas atrás.
+
+**Com AIOSON:** você tem uma equipe.
+
+- O **Briefing** ouve sua ideia ainda crua (a "conversa de bar") e devolve um briefing estruturado, com riscos e perguntas em aberto, *antes* de virar projeto.
+- O **Product** entende o que você quer construir e por quê — e escreve o PRD.
+- O **Sheldon** revisa o PRD como um arquiteto sênior que já viu de tudo: aponta lacunas, pesquisa o que está obsoleto, lê o seu código real e decide se enriquece o PRD ou cria um plano em fases. Pode revisar várias vezes.
+- O **Analyst** descobre o que já existe no terreno (codebase) e o que precisa.
+- O **Architect** projeta a estrutura.
+- O **UX-UI** desenha como o morador vai viver lá.
+- O **Dev** constrói.
+- O **Deyvin** é o empreiteiro que retoma a obra quando você volta de viagem: lê o que está confirmado, marca o que é só inferência, e segue um passo pequeno de cada vez sem você precisar re-explicar nada.
+- O **QA** vistoria.
+- O **Pentester** testa as fechaduras (segurança).
+- O **Committer** escreve a ata da reforma (mensagem de commit).
+
+Cada um sabe quando entrar, quando sair, e que documento entregar para o próximo. Você fala com qualquer um deles digitando `@nome` no seu cliente AI.
+
+## O que isso muda na prática
+
+| Sem AIOSON | Com AIOSON |
+|---|---|
+| Um prompt enorme tentando fazer tudo | Vários prompts menores, cada um com escopo claro |
+| A IA "esquece" decisões antigas no meio do trabalho | Decisões viram **artefatos em disco** (specs, dossiers, planos) |
+| Você reescreve do zero quando troca de sessão | A próxima sessão lê os artefatos e continua de onde parou |
+| Difícil voltar e auditar o que foi feito | Cada agente deixa um rastro: o que decidiu, por quê, com base em quê |
+| Time grande discorda do estilo de cada IA | Toda equipe usa o mesmo conjunto de agentes e regras |
+
+## O que AIOSON instala no seu projeto
+
+Quando você roda `aioson init`, ele cria:
+
+```
+seu-projeto/
+├── .aioson/
+│   ├── agents/              ← os prompts de cada especialista
+│   ├── config.md            ← regras do projeto (tamanho, idioma, stack)
+│   ├── constitution.md      ← os 6 princípios que ninguém quebra
+│   ├── context/             ← contexto vivo: project.context.md, project-pulse.md
+│   ├── rules/               ← regras hard que agentes seguem (segurança, etc.)
+│   ├── skills/              ← pacotes plugáveis (design systems, processos)
+│   └── runtime/             ← telemetria local (SQLite)
+├── .claude/  .codex/  .gemini/  .windsurf/   ← integração com cada cliente AI
+├── CLAUDE.md  AGENTS.md  OPENCODE.md         ← instruções por cliente
+└── docs/                                      ← documentação opcional
+```
+
+Você abre seu cliente AI favorito e digita `@setup`, `@product`, `@dev` etc. — e os agentes assumem.
+
+## Cabe em qualquer cliente AI
+
+Funciona com **qualquer IDE que tenha um terminal**:
+
+- Claude Code · Codex CLI · Gemini CLI · OpenCode
+- VS Code, Google Antigravity, Cursor, Windsurf, JetBrains, Zed (com qualquer um dos clientes acima)
+
+Os agentes são *prompts*, não plugins. Eles vivem em arquivos `.md` e o cliente AI os lê quando você invoca via `@nome`.
+
+## Quando AIOSON brilha
+
+- **Projetos onde decisões importam** — você quer rastreio, não improviso.
+- **Times** — vários humanos e várias IAs precisam ler a mesma narrativa.
+- **Sessões longas ou retomadas** — você precisa parar hoje e voltar amanhã sem perder contexto.
+- **Quando você quer especialização** — segurança séria, UX cuidado, testes sistemáticos.
+
+## Quando *não* usar AIOSON
+
+- **Script de 20 linhas** que vai rodar uma vez. Use prompt direto, sem cerimônia.
+- **Você quer experimentar livremente** uma ideia em 5 minutos. AIOSON pede setup primeiro.
+- **Você não vai abrir o projeto de novo.** O valor está justamente em sessões repetidas.
+
+Para esses casos, o próprio AIOSON tem um caminho leve — a classificação **MICRO** (`@setup → @product → @dev`). Mas se nem isso for adequado, não force.
+
+## Próximo passo
+
+- Quer entender *por que* AIOSON foi feito desse jeito? → [Por que ele existe](./por-que-existe.md)
+- Quer ver o time todo de relance? → [Mapa do ecossistema](./mapa-do-ecossistema.md)
+- Quer começar agora? → [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)