@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/1-entender/por-que-existe.md

@@ -0,0 +1,107 @@
+# Por que o AIOSON existe
+
+> **Para quem é:** quem já usa IA para programar e quer entender o "porquê" do design.
+> **Tempo de leitura:** 7 min.
+> **O que você vai sair sabendo:** os 3 problemas que AIOSON resolve, e os 6 princípios da constitution.
+
+---
+
+## Os 3 problemas que motivaram o AIOSON
+
+### Problema 1 — O prompt-monolito
+
+Quando você abre uma IA e digita "monta um app SaaS de assinatura com Stripe, autenticação, painel admin e relatórios", está pedindo para ela ser **tudo ao mesmo tempo**: Product Manager, arquiteta, designer, dev backend, dev frontend, QA, especialista em segurança.
+
+Resultado típico:
+- Decisões importantes são tomadas implicitamente, sem você perceber.
+- A IA escolhe a primeira biblioteca que lhe vem à cabeça em vez da que faz sentido.
+- Quando você pede ajuste, ela refaz três coisas que já estavam OK.
+- Não dá para auditar: por que ela escolheu Postgres? Quando? Você não consegue achar.
+
+**Como AIOSON resolve:** divide o monolito em agentes especialistas. Cada um tem foco estreito, regras próprias, e produz um artefato verificável antes de passar adiante.
+
+### Problema 2 — A amnésia entre sessões
+
+Você programa uma feature por 2 horas com a IA, vai dormir, volta no dia seguinte. A IA "lembra" o quê?
+
+- Em IDEs sem memória persistente: **nada**.
+- Em IDEs com memória: um resumo aproximado, geralmente apagando os "porquês".
+
+**Como AIOSON resolve:** decisões e contexto viram **artefatos em disco** (`project.context.md`, `spec.md`, `dossier.md`, `dev-state.md`, `project-pulse.md`). A próxima sessão lê esses arquivos antes de qualquer coisa. É memória externa, não memória interna do modelo.
+
+### Problema 3 — Inconsistência no time
+
+Em time, cada pessoa tem um estilo de prompt. Cada IA cliente (Claude, Codex, Gemini) responde diferente. O resultado é um codebase costurado por estéticas e padrões diferentes.
+
+**Como AIOSON resolve:**
+- Os mesmos agentes (`.aioson/agents/`) são lidos por **qualquer** cliente AI.
+- Regras de projeto (`.aioson/rules/`) e governança (`.aioson/constitution.md`) são compartilhadas no Git.
+- Quem entra no time herda automaticamente o "como aqui se trabalha".
+
+---
+
+## Os 6 princípios da Constitution
+
+AIOSON é governado por seis artigos que **nenhum agente pode sobrescrever**. Eles vivem em `.aioson/constitution.md` e são citados pelos agentes quando precisam justificar uma decisão.
+
+### Artigo I — Spec First
+> Features começam como especificação, não como código. Implementação sem artefato de spec é exploração, não desenvolvimento.
+
+**Tradução prática:** o `@dev` se recusa a implementar antes de ler uma spec. Isso evita que você acorde com 800 linhas de código que resolvem o problema errado.
+
+### Artigo II — Right-Sized Process
+> MICRO, SMALL e MEDIUM não recebem a mesma profundidade de processo. Aplicar cerimônia de MEDIUM num projeto MICRO desperdiça mais do que protege.
+
+**Tradução prática:** a IA não vai te pedir um PRD de 30 páginas para um script de 50 linhas. Cada classificação tem o seu fluxo próprio.
+
+### Artigo III — Observable Work
+> Ações importantes deixam artefatos visíveis ou sinais em runtime. Trabalho que existe só no histórico de conversa é trabalho que pode se perder.
+
+**Tradução prática:** se um agente toma uma decisão importante, ela aparece num arquivo. Você pode revisar, vetar, voltar atrás.
+
+### Artigo IV — Testable Behavior
+> Critérios de aceitação devem ser verificáveis independentemente. "Funciona corretamente" não é um critério. "Retorna 403 quando o usuário A acessa o recurso do usuário B" é.
+
+**Tradução prática:** o `@qa` rejeita ACs vagos. Você é forçado a ser específico antes de aprovar.
+
+### Artigo V — Clean Handoffs
+> Artefatos devem ser auto-suficientes para o próximo agente começar sem reler toda a cadeia. Se o próximo agente precisar perguntar "por onde começo?", o handoff falhou.
+
+**Tradução prática:** o `dossier` de uma feature inclui tudo: spec, decisões, código tocado, status. Quando o `@dev` passa para o `@qa`, o `@qa` não precisa entrevistar o `@dev`.
+
+### Artigo VI — Simplicity Over Ceremony
+> Não adicione camadas, arquivos ou workflows a menos que reduzam ambiguidade lá na frente. Três linhas parecidas são melhor do que abstração prematura. Uma spec bem escrita é melhor do que cinco artefatos finos.
+
+**Tradução prática:** AIOSON luta o tempo todo contra a tentação de adicionar burocracia. **"Small project, small solution"** é o lema oficial.
+
+### Artigo VII — Zero Trust by Default
+> Segurança é baseline, não feature. Todo agente técnico (`@analyst`, `@architect`, `@dev`, `@qa`) consome o baseline declarado em `.aioson/rules/security-baseline.md`, com controles ID-versionados (`SEC-SBD-01..08`) que ninguém pode silenciosamente enfraquecer.
+
+**Tradução prática:** o `@dev` automaticamente sabe que precisa sanitizar input, validar autorização, redijir secrets. Não é um pedido extra seu — é o padrão.
+
+---
+
+## A regra de ouro
+
+Acima dos 6 artigos paira uma frase que aparece em quase todo prompt do AIOSON:
+
+> **Small project, small solution.**
+> Projeto pequeno, solução pequena.
+
+Se você tem que escolher entre um agente fazer mais coisas ou menos coisas — sempre menos. Se tem que escolher entre criar um artefato a mais ou se virar com o que já existe — sempre se virar. AIOSON é proativamente preguiçoso, e isso é uma feature.
+
+---
+
+## E o que NÃO está coberto pelos princípios
+
+- **Estilo de código pessoal.** AIOSON não tem opinião sobre tabs vs spaces, eslint config, etc. Isso fica nas suas regras (`.aioson/rules/`).
+- **Stack tecnológico.** Os agentes detectam o stack do projeto e se adaptam. AIOSON funciona em Node, Python, Go, Rust, PHP, Ruby, etc.
+- **Vendor lock-in.** Funciona com qualquer cliente AI que leia arquivos `.md` no projeto.
+
+---
+
+## Próximo passo
+
+- Ver o time inteiro mapeado: [Mapa do ecossistema](./mapa-do-ecossistema.md)
+- Vocabulário completo: [Glossário](./glossario.md)
+- Pôr em prática: [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)

package/docs/pt/2-comecar/decisoes-iniciais.md

@@ -0,0 +1,223 @@
+# Decisões iniciais — MICRO, SMALL ou MEDIUM? Qual cliente AI?
+
+> **Para quem é:** você está prestes a rodar `aioson init` e quer escolher bem.
+> **Tempo de leitura:** 6 min.
+> **O que você vai sair sabendo:** como AIOSON classifica seu projeto, e como escolher cliente AI / design / idioma.
+
+---
+
+## A classificação: MICRO, SMALL, MEDIUM
+
+AIOSON é o oposto de "tamanho único". Ele aplica **mais cerimônia em projetos maiores e menos em menores**. Isso é o Artigo II da Constitution: *Right-Sized Process*.
+
+### Como o número é calculado
+
+Soma de três fatores (cada um vale 0, 1 ou 2 pontos):
+
+| Fator | 0 pts | 1 pt | 2 pts |
+|---|---|---|---|
+| **Tipos de usuário** | 1 | 2 | 3+ |
+| **Integrações externas** | 0 | 1–2 | 3+ |
+| **Regras de negócio não-óbvias** | nenhuma | algumas | complexas |
+
+| Soma | Classificação |
+|---|---|
+| 0–1 | **MICRO** |
+| 2–3 | **SMALL** |
+| 4–6 | **MEDIUM** |
+
+### O que muda em cada uma
+
+#### MICRO — `@setup → @product (opcional) → @dev`
+
+- Para: scripts, automações, protótipos, apps pessoais simples.
+- Não há `@analyst` nem `@architect`. Você fala direto com `@dev`.
+- `@product` é opcional — você pode passar a spec direto no chat se quiser.
+- Sem `@qa` no fluxo padrão (você pode invocar manualmente).
+
+**Exemplos típicos:**
+- Script Python que processa CSV
+- Bot Telegram simples
+- Página estática de portfólio
+- Mini-API de 3 endpoints
+
+#### SMALL — `@setup → @product → @analyst → @architect → @dev → @qa`
+
+- Para: a maioria dos apps reais.
+- Tem o ciclo completo de discovery+desenvolvimento+QA.
+- Sem `@ux-ui`, `@pm` ou `@orchestrator` no fluxo padrão (você pode invocar pontualmente).
+
+**Exemplos típicos:**
+- App SaaS para um único persona
+- API com auth e algumas regras
+- Loja online simples
+- Blog com painel admin
+
+#### MEDIUM — workflow completo
+
+- Para: produtos com múltiplos tipos de usuário, várias integrações, regras complexas.
+- Adiciona `@ux-ui`, `@pm`, `@orchestrator`.
+- Gates de qualidade aplicados em cada handoff.
+- Lanes paralelas possíveis (`@orchestrator` coordena).
+- Threshold de contexto mais agressivo (55% — alerta cedo).
+
+**Exemplos típicos:**
+- Marketplace (vendedor + comprador + admin)
+- ERP / CRM
+- Plataforma multi-tenant com cobrança por tier
+- App fintech com KYC e compliance
+
+### Casos de fronteira
+
+| Situação | Sugestão |
+|---|---|
+| Projeto pessoal, mas com uma integração externa pesada | SMALL — a integração compensa o `@architect` |
+| Score 1, mas sei que vou crescer | Comece MICRO. Pode promover depois com `@setup` |
+| Score 4, mas time é só você | MEDIUM mesmo. As regras de negócio complexas se beneficiam dos artefatos |
+| Score 2, mas é greenfield e quero design caprichado | SMALL + ative o design skill no wizard |
+
+> **Verdade frequentemente esquecida:** AIOSON luta contra cerimônia desnecessária. Se você está em dúvida entre dois níveis, **escolha o menor**. Promover depois é fácil. Demover depois é doloroso.
+
+---
+
+## Escolhendo o cliente AI
+
+Você pode marcar **mais de um** no wizard — eles convivem no mesmo projeto.
+
+| Cliente | Forte para... | Marcas registradas |
+|---|---|---|
+| **Claude Code** | Agentes longos, refatorações, tarefas planejadas | Skills nativos, slash commands, hooks |
+| **Codex CLI** | Tarefas curtas, foco em código direto | Modo `@` para incluir arquivos |
+| **Gemini CLI** | Multi-modal, custo baixo em alguns planos | Janela de contexto generosa |
+| **OpenCode** | Open-source, integração com vários providers | Configuração granular |
+
+**Recomendação para iniciante:** comece com Claude Code, é o que tem mais paridade com AIOSON. Adicione outros depois com `aioson install --reconfigure`.
+
+---
+
+## Escolhendo Modo: Development vs Development + Squads
+
+### Development (padrão)
+
+Inclui os 28 agentes oficiais (product, analyst, dev, qa, etc.). Suficiente para 95% dos projetos.
+
+### Development + Squads
+
+Adiciona o sistema de squads — você pode criar squads customizados para domínios fora do padrão.
+
+**Exemplo prático:** seu projeto é jurídico. Você cria um squad "compliance" com agentes:
+- `@regulator` — entende regulação brasileira
+- `@attorney` — interpreta cláusulas
+- `@auditor` — checa conformidade
+
+```bash
+# Dentro do cliente AI
+> @squad assemble compliance
+
+# Ou via CLI
+npx @jaimevalasek/aioson squad:assemble compliance
+```
+
+**Quando ativar Squads:**
+- Você sabe que vai precisar de especialização fora do padrão
+- Time grande com domínios diferentes
+- Vai publicar squads no aioson.com (ver `system:publish`)
+
+**Quando NÃO ativar:**
+- Projeto pessoal MICRO
+- Você ainda não usou agentes padrão o suficiente para saber se precisa
+
+> Pode ativar depois com `aioson install --reconfigure`.
+
+---
+
+## Escolhendo o Design System
+
+Disponíveis no wizard:
+
+| Skill | Estilo | Casos |
+|---|---|---|
+| **Clean SaaS UI** | Limpo, tipografia clara, neutros | Painéis, dashboards |
+| **Aurora Command UI** | Dark, gradientes sutis, comando central | Tools de desenvolvedor |
+| **Cognitive Core UI** | Cards com peso, depth via sombras | Apps com muita info |
+| **Bold Editorial UI** | Tipografia editorial, hierarquia forte | Blogs, conteúdo |
+| **Warm Craft UI** | Cores quentes, textura suave | E-commerce artesanal |
+| **Glassmorphism UI** | Vidro, blur, translúcido | Apps modernos premium |
+| **Neo Brutalist UI** | Contornos pretos, cores fortes, sem sombra | Marcas marcantes |
+
+**Pular** é uma opção legítima. Você pode:
+- Escolher depois com `@ux-ui`
+- Clonar o design de um site real com `@site-forge`
+- Criar um híbrido com `@design-hybrid-forge` (ex: clean-saas + neo-brutalist)
+
+---
+
+## Escolhendo o idioma de interação
+
+| Idioma | Quando faz sentido |
+|---|---|
+| **English** | Times internacionais; quer máximo de qualidade nos prompts |
+| **Português (pt-BR)** | Time 100% PT; clientes finais leem PT |
+| **Español** | Time 100% ES |
+| **Français** | Time 100% FR |
+
+**Importante:** os arquivos de agente *internos* permanecem em inglês (são prompts, e o modelo performa melhor em inglês). O `interaction_language` muda apenas como o agente **fala com você** — perguntas, explicações, mensagens.
+
+Decisão deliberada do projeto: separar **idioma do prompt** (en, sempre) do **idioma da interação** (escolha sua). Essa separação aconteceu nos commits `efb0902` e `6629730`.
+
+---
+
+## Wizard skip — instalações relâmpago
+
+```bash
+# Tudo: todos os clientes, modo Squads, sem design, EN
+npx @jaimevalasek/aioson init meu-app --all
+
+# Sem nenhuma pergunta (defaults), idioma inglês
+npx @jaimevalasek/aioson install --no-interactive
+```
+
+---
+
+## Como mudo depois?
+
+| Quero mudar... | Comando |
+|---|---|
+| Adicionar Codex/Gemini ao mesmo projeto | `aioson install --reconfigure` |
+| Ativar Squads | `aioson install --reconfigure` (e marque) |
+| Trocar design skill | `@ux-ui` no cliente AI ou `aioson install --reconfigure` |
+| Mudar idioma de interação | Edite `interaction_language:` em `project.context.md` ou rode `@setup` de novo |
+| Mudar a classificação | Edite `classification:` em `project.context.md`. Próximas sessões respeitam. |
+
+---
+
+## Decisão final em 30 segundos
+
+```
+Tipo de coisa que você está construindo? Risco? Quantas integrações?
+                              │
+                              ▼
+                       Pequeno e simples?
+                       SIM → MICRO
+                       NÃO → ↓
+                              ▼
+                  3+ tipos de usuário OU 3+ integrações
+                       OU regras complexas?
+                       SIM → MEDIUM
+                       NÃO → SMALL
+
+Cliente AI principal? Claude Code (recomendado para começar)
+Squads? Não, por enquanto
+Design? Pular ou Clean SaaS UI
+Idioma? pt-BR
+
+Pronto. Rode aioson init.
+```
+
+---
+
+## Próximo passo
+
+- [Primeiro projeto do zero](./primeiro-projeto.md)
+- [Em projeto existente](./projeto-existente.md)
+- Curioso sobre os princípios? → [Por que ele existe](../1-entender/por-que-existe.md)

package/docs/pt/2-comecar/primeiro-projeto.md

@@ -0,0 +1,307 @@
+# Primeiro projeto do zero
+
+> **Para quem é:** quem nunca usou AIOSON e quer rodar uma vez para entender.
+> **Tempo de execução:** 30–45 min.
+> **O que você vai ter no fim:** um app web simples (lista de tarefas) com spec, código, testes e dossier — todos rastreáveis em disco.
+
+Vamos construir um **mini-app de TODO** usando o ciclo SMALL. Você verá cada agente entrar, fazer sua parte, e passar para o próximo.
+
+---
+
+## Pré-requisitos
+
+- **Node.js 18+** instalado
+- Um cliente AI configurado: **Claude Code**, **Codex CLI**, **Gemini CLI** ou **OpenCode**. Os exemplos aqui usam Claude Code; é trivial trocar.
+- Um terminal aberto
+
+Se você não tem cliente AI ainda: o Claude Code é o mais usado pela comunidade AIOSON. Veja [`clientes-ai.md`](../5-referencia/clientes-ai.md).
+
+---
+
+## Passo 1 — Criar o projeto
+
+```bash
+npx @jaimevalasek/aioson init meu-todo
+cd meu-todo
+```
+
+O wizard vai te perguntar:
+
+```
+? Quais ferramentas AI? › Claude Code
+? Modo? › Development (sem squads agora)
+? Design system? › (pular por enquanto)
+? Idioma dos agentes? › pt-BR
+```
+
+> **Dica leigo:** se quiser pular o wizard e instalar tudo, `--all`. Se for em CI, `--no-interactive`.
+
+O comando deixa essa estrutura:
+
+```
+meu-todo/
+├── .aioson/         ← agentes, regras, config
+├── .claude/         ← integração Claude Code
+├── CLAUDE.md        ← instruções automáticas para Claude Code
+├── AGENTS.md        ← instruções para Codex
+└── (vazio — sem package.json ainda)
+```
+
+---
+
+## Passo 2 — Abrir o cliente AI no projeto
+
+```bash
+claude .   # ou: codex .   ou: gemini .   ou: opencode .
+```
+
+A partir daqui, vamos conversar com a IA.
+
+---
+
+## Passo 3 — `@setup` faz o onboarding
+
+```
+Você > @setup
+```
+
+Diálogo esperado (pode variar):
+
+```
+@setup > Olá! Vou configurar o contexto deste projeto.
+@setup > Não detectei stack instalada ainda. Vamos do zero — qual o tipo?
+        [web_app · api · site · script · dapp · desktop_app]
+Você > web_app
+
+@setup > Stack preferido?
+Você > Node.js + Express + SQLite
+
+@setup > Quantos tipos de usuário?
+Você > 1
+
+@setup > Quantas integrações externas (APIs, gateways, etc.)?
+Você > 0
+
+@setup > Há regras de negócio não-óbvias (cálculos especiais, fluxos com muitas condições)?
+Você > Não
+
+@setup > [calcula] Score: 0+0+0 = 0 → MICRO. Mas você pediu spec/test...
+@setup > Recomendo SMALL para ter @qa no fim. Concorda?
+Você > Sim
+
+@setup > project.context.md criado.
+@setup > Próximo agente: @product (para definir a feature inicial).
+```
+
+Olha o que apareceu em disco:
+
+```bash
+cat .aioson/context/project.context.md
+```
+
+```yaml
+---
+project_name: "meu-todo"
+project_type: "web_app"
+profile: "developer"
+framework: "Node.js"
+classification: "SMALL"
+interaction_language: "pt-BR"
+...
+---
+```
+
+> **O que aconteceu:** o `@setup` te entrevistou e gravou as respostas num arquivo. **Esse arquivo é a memória externa** que todos os outros agentes vão ler.
+
+---
+
+## Passo 4 — `@product` define a primeira feature
+
+```
+Você > @product
+
+@product > Vamos definir a feature inicial. Qual o nome curto (slug)?
+Você > lista-todos
+
+@product > Em uma frase, qual o problema que ela resolve?
+Você > Permitir ao usuário criar e marcar tarefas como concluídas
+
+@product > Quais critérios de aceitação?
+Você > Criar tarefa com texto. Marcar como concluída. Listar pendentes e concluídas separadas. Persistir em SQLite.
+
+@product > [...detalhes...] Spec gravada em
+        .aioson/context/features/lista-todos/spec.md
+@product > Próximo: @analyst.
+```
+
+```bash
+cat .aioson/context/features/lista-todos/spec.md
+```
+
+Você verá uma spec estruturada com escopo, ACs e fora-de-escopo.
+
+---
+
+## Passo 5 — `@analyst` mapeia o domínio
+
+```
+Você > @analyst
+
+@analyst > Lendo spec... domínio: tarefas pessoais.
+@analyst > Entidades:
+        - Task { id, text, completed, created_at }
+@analyst > Não há outras entidades no escopo.
+@analyst > Domain map gravado em context/architecture.md.
+@analyst > Próximo: @architect.
+```
+
+---
+
+## Passo 6 — `@architect` decide a estrutura
+
+```
+Você > @architect
+
+@architect > Stack confirmado: Node + Express + SQLite.
+@architect > Decisões:
+        - Estrutura: src/{routes,db,server}.js
+        - Persistência: better-sqlite3 (SQLite síncrono, simples)
+        - Validação: pequena, manual (sem libs extras — Article VI)
+        - Sem framework de teste pesado: usar `node:test` (built-in)
+@architect > Decisões registradas em architecture.md.
+@architect > Próximo: @dev.
+```
+
+> **Atenção ao Artigo VI ("Simplicity Over Ceremony"):** o `@architect` evitou puxar libs desnecessárias.
+
+---
+
+## Passo 7 — `@dev` implementa
+
+```
+Você > @dev
+
+@dev > [lê spec, architecture, project.context]
+@dev > Vou criar:
+        package.json
+        src/db.js          (init schema)
+        src/routes.js      (POST /tasks, PATCH /tasks/:id, GET /tasks)
+        src/server.js
+        tests/tasks.test.js (placeholder — @qa cobre)
+
+@dev > [implementa]
+@dev > Implementação OK. Rodando smoke:
+        $ node src/server.js → escutando na 3000 ✓
+@dev > dev-state.md atualizado.
+@dev > Próximo: @qa.
+```
+
+Veja o que mudou:
+
+```bash
+ls src/
+# db.js  routes.js  server.js
+cat .aioson/context/dev-state.md
+```
+
+`dev-state.md` mostra exatamente o que foi feito, em que arquivos, e o status.
+
+---
+
+## Passo 8 — `@qa` testa
+
+```
+Você > @qa
+
+@qa > Lendo spec... 4 ACs identificados.
+@qa > Plano de teste:
+        AC-01: criar tarefa → POST retorna 201 e id
+        AC-02: marcar concluída → PATCH altera completed
+        AC-03: listar separados → GET /tasks?status=pending|done
+        AC-04: persistência → reiniciar processo, dados persistem
+@qa > Escrevendo tests/tasks.test.js... rodando...
+
+[Algum teste falhou? Ciclo autônomo QA→Dev (até 2 iterações):]
+@qa > AC-03 falhou: GET sem filtro retorna mistura.
+        Repassando para @dev (iteração 1/2)...
+@dev > Corrigindo... done.
+@qa > Re-rodando... 4/4 OK.
+@qa > test-plan.md e qa-report.md gravados. Feature pronta.
+```
+
+> **A novidade:** o ciclo *autônomo QA→Dev* (cap 2) deixa o @qa pedir correções pequenas sem você ter que reativar manualmente. Foi adicionado em Mai/2026.
+
+---
+
+## Passo 9 — Commit limpo com `@committer`
+
+```
+Você > @committer
+
+@committer > Lendo diff e dev-state...
+        Mensagem proposta:
+        ┌────────────────────────────────────────────────────┐
+        │ feat(tasks): add basic CRUD with SQLite            │
+        │                                                    │
+        │ - POST /tasks creates a task                       │
+        │ - PATCH /tasks/:id toggles completion              │
+        │ - GET /tasks supports status=pending|done filter   │
+        │                                                    │
+        │ Closes spec lista-todos. Tests: 4/4 pass.          │
+        └────────────────────────────────────────────────────┘
+        [✓] Aceitar  [ ] Editar  [ ] Cancelar
+Você > [Enter para aceitar]
+@committer > Commitado.
+```
+
+---
+
+## O que ficou rastreável
+
+```
+.aioson/context/
+├── project.context.md         ← visão do projeto (passo 3)
+├── architecture.md            ← decisões (passos 5+6)
+├── dev-state.md               ← o que o @dev fez (passo 7)
+├── test-plan.md               ← plano do @qa (passo 8)
+├── qa-report-test-coverage.md ← relatório de QA
+└── features/
+    └── lista-todos/
+        └── spec.md            ← spec original (passo 4)
+```
+
+Daqui a três meses, alguém (você ou outra IA) pode abrir esse projeto e entender **tudo** lendo só esses arquivos. Sem precisar do histórico de chat.
+
+---
+
+## E quando eu quiser uma feature nova?
+
+Volte para o passo 4. `@product` cria nova feature → `@analyst` → `@architect` → `@dev` → `@qa`. O `@setup` não precisa rodar de novo (já tem o contexto).
+
+Se você se perder no meio, lembre:
+
+```
+Você > @neo
+```
+
+Ele te diz quem é o próximo.
+
+---
+
+## Solução de problemas comuns
+
+| Problema | Solução |
+|---|---|
+| O agente "esqueceu" o contexto | Confira `cat .aioson/context/project.context.md`. Se faltar campos, rode `@setup` de novo. |
+| Quero retomar uma feature interrompida | Rode `@deyvin` — ele lê `dev-state.md` e continua. |
+| Não sei se a classificação certa é SMALL | Pergunte ao `@neo` — ele explica o cálculo. |
+| Falhou ao instalar | `npx @jaimevalasek/aioson doctor` — diagnostica e sugere fix. |
+| Quero adicionar Codex/Gemini depois | `npx @jaimevalasek/aioson install --reconfigure`. |
+
+---
+
+## Próximo passo
+
+- Tem um projeto que **já existe** e quer adicionar AIOSON nele? → [Em projeto existente](./projeto-existente.md)
+- Quer entender quando MICRO vs SMALL vs MEDIUM? → [Decisões iniciais](./decisoes-iniciais.md)
+- Quer ver o time inteiro? → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)