@jaimevalasek/aioson 1.7.2 → 1.9.0

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

@@ -0,0 +1,245 @@
+# Adicionar AIOSON num projeto existente
+
+> **Para quem é:** você já tem um codebase e quer trazer AIOSON para ele.
+> **Tempo de execução:** 20–60 min, depende do tamanho do projeto.
+> **O que você vai ter no fim:** AIOSON instalado, contexto inicial mapeado, e a primeira feature da nova era pronta para rodar.
+
+---
+
+## A primeira regra: nada será sobrescrito
+
+`aioson install` é **aditivo**. Ele cria os diretórios `.aioson/`, `.claude/` etc., e adiciona arquivos `CLAUDE.md`, `AGENTS.md`, `OPENCODE.md` no root. Ele **não toca**:
+
+- Seu código (`src/`, `app/`, etc.)
+- Seu `package.json` / `pyproject.toml` / `Gemfile`
+- Seu `.gitignore` (em updates)
+- Sua infra (`Dockerfile`, CI configs)
+
+Se algum dia você quiser sair, é só apagar `.aioson/` e os arquivos `CLAUDE.md`/`AGENTS.md`/`OPENCODE.md`.
+
+---
+
+## Passo 1 — Instalar
+
+```bash
+cd meu-projeto-existente
+npx @jaimevalasek/aioson install
+```
+
+O wizard interativo aparece:
+
+```
+? Quais ferramentas AI? ›
+   ◉ Claude Code
+   ◉ Codex CLI
+   ◯ Gemini CLI
+   ◯ OpenCode
+
+? Modo? ›
+   ◉ Development
+   ◯ Development + Squads
+
+? Design system? ›
+   ◯ Clean SaaS UI
+   ◯ Aurora Command UI
+   ◯ (mais opções...)
+   ◉ Pular
+
+? Idioma dos agentes? ›
+   ◯ English
+   ◉ Português
+   ◯ Español
+   ◯ Français
+```
+
+> **Dica:** o `--all` instala tudo sem wizard (todas as ferramentas, modo Development+Squads). `--no-interactive` para CI.
+
+---
+
+## Passo 2 — Escanear o projeto
+
+```bash
+npx @jaimevalasek/aioson scan:project
+```
+
+O scan vai:
+- Detectar linguagem, framework, gerenciador de pacotes
+- Mapear estrutura de pastas
+- Listar dependências
+- Salvar em `.aioson/context/scan-*.md`
+
+> Não confunda `scan:project` com `@discover` — o **scan** é estático (análise de arquivos). O **`@discover`** vai além: cria um cache semântico, com índice de busca.
+
+---
+
+## Passo 3 — Rodar `@setup`
+
+```bash
+claude .   # ou: codex . / gemini . / opencode .
+```
+
+Dentro do cliente AI:
+
+```
+Você > @setup
+
+@setup > Detectei: Node.js + Next.js + Postgres + Prisma. Confirma?
+Você > Sim
+
+@setup > Quantos tipos de usuário existem hoje no projeto?
+Você > Admin, customer, supplier (3)
+
+@setup > Integrações externas?
+Você > Stripe, SendGrid, S3 (3)
+
+@setup > Regras de negócio complexas (cálculos, fluxos condicionais)?
+Você > Sim — política de descontos por tier de cliente, regras de comissão
+
+@setup > Score: 2 + 2 + 2 = 6 → MEDIUM.
+@setup > Idioma de interação? › pt-BR
+
+@setup > project.context.md criado com classificação MEDIUM.
+@setup > Como você já tem código rodando, recomendo:
+        - Rodar @discover para criar o cache semântico
+        - Depois @analyst para mapear o domínio existente
+        - Só então começar a próxima feature via @product
+```
+
+---
+
+## Passo 4 — `@discover` indexa o conhecimento
+
+```
+Você > @discover
+
+@discover > Indexando .aioson/context/bootstrap...
+        - 1.247 arquivos analisados
+        - 84 entidades semânticas extraídas
+        - 23 fluxos identificados
+        - Cache pronto em .aioson/brains/discover/
+@discover > Quando algum agente precisar de algo do codebase, ele consulta esse cache em vez de varrer tudo. Economiza muito contexto.
+```
+
+Esse passo é **opcional para projetos pequenos**, mas crítico em codebases médios e grandes (>5k arquivos).
+
+---
+
+## Passo 5 — `@analyst` mapeia o domínio que já existe
+
+```
+Você > @analyst
+
+@analyst > [lê scan + cache do @discover]
+        Identifiquei:
+        - Customer, Supplier, Order, OrderItem, Payment, Discount, Commission
+        - Auth via NextAuth
+        - Webhook Stripe ativo
+        - Tabela de tiers em customer.tier (free|pro|enterprise)
+@analyst > Domain map gravado em architecture.md.
+@analyst > Pronto para a próxima feature.
+```
+
+> **Por que isso importa:** quando você criar a próxima feature com `@product`, ela já vai nascer com **contexto**. O agente sabe que já existe Customer, não vai sugerir criar de novo.
+
+---
+
+## Passo 6 — Primeira feature da nova era
+
+```
+Você > @product
+
+@product > Já temos a base mapeada. Qual feature?
+Você > "cancelamento-pedido" — permitir cancelar pedido em até 1h
+
+@product > Critérios de aceitação?
+Você > [...]
+
+@product > Spec gravada. Próximo: @analyst.
+```
+
+A partir daí o fluxo é o mesmo do [primeiro-projeto.md](./primeiro-projeto.md).
+
+---
+
+## Casos especiais
+
+### Tenho legacy sem testes
+
+Use **`@tester`** (não só `@qa`) — ele faz engenharia sistemática de testes para apps já implementados. Recentemente ganhou *coverage quality tier* e *test smell audit*.
+
+```
+Você > @tester
+
+@tester > Coverage atual: 12%. Quality tier: BAIXO.
+@tester > Estratégia: cobrir os 5 módulos mais críticos primeiro
+        (auth, payments, orders, discounts, webhook handler).
+```
+
+### Quero auditar segurança antes de tocar em qualquer coisa
+
+```
+Você > @pentester
+
+@pentester > Mapeando superfícies de ataque (OWASP Top 10 + LLM Top 10 + supply chain).
+        ...
+        Findings:
+        - HIGH: rota /admin/* sem rate-limit
+        - MEDIUM: dependência X com CVE conhecido
+        - LOW: log de erros vaza email
+        Salvo em context/security-findings-project.json
+```
+
+### Quero migrar entendimento entre clientes AI
+
+Os arquivos `.aioson/` são **agnósticos**. Hoje você usa Claude Code, amanhã pode usar Codex no mesmo projeto:
+
+```bash
+npx @jaimevalasek/aioson install --reconfigure
+# Marque também Codex CLI no wizard
+```
+
+Os `.codex/` e `AGENTS.md` aparecem. Os agentes lêem os mesmos arquivos.
+
+### Tenho regras de código que preciso impor
+
+Crie `.aioson/rules/<nome>.md`. Exemplo:
+
+```markdown
+# .aioson/rules/no-direct-db-from-controllers.md
+
+Controllers nunca acessam o ORM diretamente. Sempre via service layer.
+```
+
+Todo agente técnico (`@dev`, `@qa`, etc.) carrega essas regras automaticamente. Veja [Governança de Design Docs](../5-referencia/design-docs-governance.md) (atualizado).
+
+### Equipe inteira no mesmo projeto
+
+Comite o `.aioson/`. Cada dev terá o mesmo time de agentes, as mesmas regras, a mesma constitution. Mantenha apenas `.aioson/runtime/` no `.gitignore` (telemetria local).
+
+---
+
+## Verificação rápida
+
+Depois do install, esses comandos devem funcionar:
+
+```bash
+# 1. Diagnóstico geral
+npx @jaimevalasek/aioson doctor
+
+# 2. Estado do projeto
+npx @jaimevalasek/aioson workflow:next .
+
+# 3. Confirmar que o contexto está OK
+cat .aioson/context/project.context.md
+
+# 4. Dentro do cliente AI
+> @neo
+```
+
+---
+
+## Próximo passo
+
+- Quer entender qual classificação faz sentido? → [Decisões iniciais](./decisoes-iniciais.md)
+- Como funciona a continuidade entre sessões? → *(em construção, Fase B — `3-receitas/continuidade-entre-sessoes.md`)*
+- Visão geral do time → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)

package/docs/pt/3-receitas/README.md

@@ -0,0 +1,28 @@
+# Receitas — exemplos prontos para copiar
+
+Cada receita é um guia end-to-end com diálogos simulados, exemplos rodáveis e solução de problemas. Escolha pelo seu cenário:
+
+## Trilhas canônicas (recomendadas para começar)
+
+Estas três trilhas mostram **como features chegam ao desenvolvimento** no AIOSON. Você quase sempre cai em uma delas.
+
+| Trilha | Quando usar | Agentes-chave |
+|---|---|---|
+| **[Feature completa com @sheldon](./feature-completa-com-sheldon.md)** | Você tem PRD em mente e quer a trilha canônica completa (a mais usada) | @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa |
+| [Da ideia ao PRD via @briefing](./da-ideia-ao-prd-via-briefing.md) | Sua ideia ainda é vaga, várias anotações soltas | @briefing → @product |
+| [Plans externos para @product](./plans-externos-para-product.md) | Você já planejou em outro chat (ChatGPT, Claude.io, Gemini Web) | @product (lê `/plans/`) |
+
+## Receitas por cenário
+
+| Receita | Cenário | Agentes principais |
+|---|---|---|
+| [Landing page](./landing-page.md) | Criar página de apresentação com copy e design | @product, @copywriter, @ux-ui, @dev, @qa |
+| [App SaaS do zero](./app-saas-do-zero.md) | SaaS completo: auth, billing Stripe, admin | Workflow MEDIUM completo + @orchestrator |
+| [Integração em codebase grande](./integracao-em-codebase-grande.md) | Instalar AIOSON em legado de 10k–100k linhas | @discover, @analyst |
+| [Refatoração grande](./refatoracao-grande.md) | Reescrever módulo crítico sem quebrar nada | @sheldon, @tester, @dev, @qa |
+| [Auditoria de segurança](./auditoria-seguranca.md) | Revisar vulnerabilidades antes de produção | @pentester |
+| [Publicar no aioson.com](./publicar-no-aioson-com.md) | Distribuir squad, skill ou genome | system:package, system:publish |
+| [Clonar design de site](./clonar-design-de-site.md) | Extrair visual de site ou combinar dois estilos | @site-forge, @design-hybrid-forge |
+| [Continuidade entre sessões](./continuidade-entre-sessoes.md) | Retomar feature após sessão encerrada | @deyvin, dossier, dev-state |
+
+Volte ao portal principal: [docs/pt/README.md](../README.md)

package/docs/pt/3-receitas/app-saas-do-zero.md

@@ -0,0 +1,324 @@
+# Receita: App SaaS do zero (classificação MEDIUM)
+
+> **Para quem é:** desenvolvedor ou time montando um SaaS com auth, billing e painel admin.
+> **Tempo de execução:** 2–4 horas (processo distribuído em múltiplas sessões).
+> **O que você vai ter no fim:** SaaS funcional com autenticação, planos de assinatura via Stripe, painel de admin, testes e artefatos completos de spec/arquitetura/QA.
+
+---
+
+## Cenário
+
+Você quer construir um SaaS: usuários se cadastram, escolhem um plano pago (Stripe), e acessam um painel com as funcionalidades. Tem também um admin para gerenciar usuários e assinaturas.
+
+Isso é um projeto **MEDIUM** (3 tipos de usuário: visitante, subscriber, admin — e integrações externas: Stripe, email). O AIOSON aplica o workflow completo, incluindo `@orchestrator` para coordenar lanes paralelas, o que permite que backend e frontend se desenvolvam em paralelo após o alinhamento de arquitetura.
+
+Se você nunca viu o AIOSON em ação, comece pela receita [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md) antes desta.
+
+---
+
+## Pré-requisitos
+
+- Node.js 18+, conta Stripe (modo teste é suficiente)
+- Claude Code ou Codex
+- `npx @jaimevalasek/aioson init meu-saas` já executado
+- Modo: Development + Squads (não obrigatório, mas recomendado para MEDIUM)
+
+---
+
+## Passo 1 — Setup classifica o projeto como MEDIUM
+
+```bash
+cd meu-saas
+claude .
+```
+
+```
+Você > @setup
+
+@setup > Qual o tipo? [web_app · api · site · ...]
+Você > web_app
+
+@setup > Stack?
+Você > Next.js + Prisma + PostgreSQL + Stripe
+
+@setup > Tipos de usuário?
+Você > Visitante (público), Subscriber (pago), Admin (interno) — 3 tipos
+
+@setup > Integrações externas?
+Você > Stripe (billing) + SendGrid (email) — 2
+
+@setup > Regras de negócio não-óbvias?
+Você > Sim — degrade de plano, trial de 14 dias, acesso por feature flag por plano
+
+@setup > Score: 2 + 1 + 2 = 5 → MEDIUM.
+@setup > project.context.md criado. Próximo: @product.
+```
+
+---
+
+## Passo 2 — `@product` define escopo e PRD
+
+```
+Você > @product
+
+@product > Qual o nome do produto e o problema que ele resolve?
+Você > Senty — ferramenta de monitoramento de uptime para devs independentes
+
+@product > Features no MVP?
+Você > Monitor de URL (ping a cada 5min), alerta por email se cair, histórico 30 dias,
+       plano Free (3 monitores) e Pro (20 monitores, alertas SMS)
+
+@product > Critérios de aceitação do MVP?
+Você > [lista detalhada de ACs]
+
+@product > PRD gravado em context/prd.md. Spec do MVP em features/mvp/spec.md.
+           Próximo: @sheldon para revisão antes de implementar, ou @analyst.
+```
+
+> **Quando usar `@sheldon` aqui:** se o PRD tiver decisões difíceis (ex: billing por uso vs. por assento, multi-tenant vs. single-tenant), o `@sheldon` detecta lacunas e enriquece antes do `@analyst`. Para fluxos claros, pode pular.
+
+---
+
+## Passo 3 — `@analyst` mapeia o domínio
+
+```
+Você > @analyst
+
+@analyst > Entidades identificadas:
+           - User { id, email, plan, trial_ends_at, stripe_customer_id }
+           - Monitor { id, user_id, url, interval_min, active }
+           - Check { id, monitor_id, status, latency_ms, checked_at }
+           - Incident { id, monitor_id, started_at, resolved_at }
+           - Subscription { id, user_id, stripe_subscription_id, plan, status }
+
+@analyst > Fluxos críticos:
+           1. Signup → trial → plano Pro (webhook Stripe)
+           2. Check engine (cron) → Incident → notificação email
+           3. Admin: listar users, suspender, ver histórico
+
+@analyst > Domain map em architecture.md. Próximo: @architect.
+```
+
+---
+
+## Passo 4 — `@architect` decide a estrutura técnica
+
+```
+Você > @architect
+
+@architect > Decisões:
+             - Monorepo: Next.js app (app router) + worker separado para checks
+             - DB: PostgreSQL via Prisma (Supabase recomendado para hospedagem fácil)
+             - Auth: NextAuth v5 com provider email magic-link
+             - Billing: Stripe Checkout + webhooks em /api/webhooks/stripe
+             - Email: SendGrid via Resend SDK (mais simples na DX)
+             - Worker: BullMQ + Redis para fila de checks
+             - Feature flags: middleware Next.js verificando plan no session
+
+@architect > Decisões em architecture.md. Próximo: @ux-ui.
+```
+
+---
+
+## Passo 5 — `@ux-ui` especifica o sistema visual
+
+```
+Você > @ux-ui
+
+@ux-ui > Projeto: SaaS de monitoring. Design skill: Aurora Command UI (dark, técnico).
+          Mapeando telas necessárias:
+          - /login, /signup, /onboarding (escolha de plano)
+          - /dashboard (lista de monitores + status)
+          - /monitors/new, /monitors/[id] (detalhes + histórico)
+          - /billing (plano atual, upgrade, portal Stripe)
+          - /admin (tabela de users com filtros)
+
+@ux-ui > Especificando componentes: StatusBadge, MonitorCard, IncidentTimeline,
+          UptimeChart, PlanSelector, BillingPortalButton, AdminTable.
+          design-doc-mvp.md criado.
+```
+
+---
+
+## Passo 6 — `@pm` cria o backlog e user stories
+
+```
+Você > @pm
+
+@pm > Lendo PRD + spec + design-doc...
+       Quebrando em user stories:
+
+       Epic 1: Autenticação
+       US-01: Como visitante, quero criar conta com email para acessar o produto
+       US-02: Como usuário, quero entrar com magic link para não precisar de senha
+
+       Epic 2: Monitores
+       US-03: Como subscriber Free, quero adicionar até 3 monitores de URL
+       US-04: Como subscriber Pro, quero adicionar até 20 monitores
+
+       Epic 3: Billing
+       US-05: Como usuário Free, quero fazer upgrade para Pro via Stripe Checkout
+       US-06: Como sistema, quero processar webhooks Stripe para atualizar plano
+
+       [...mais stories...]
+
+@pm > tasks.md com 18 user stories, prioridade e estimativa. Próximo: @orchestrator.
+```
+
+---
+
+## Passo 7 — `@orchestrator` divide em lanes paralelas
+
+```
+Você > @orchestrator
+
+@orchestrator > Lendo implementação-plan, design-doc, tasks...
+                Projeto MEDIUM confirmado. Vou criar 3 lanes:
+
+                LANE 1 — Auth + DB schema
+                  Responsável: @dev (sessão A)
+                  Escopo: schema Prisma, NextAuth config, /login, /signup
+
+                LANE 2 — Core de monitores + worker
+                  Responsável: @dev (sessão B)
+                  Escopo: CRUD de monitors, BullMQ worker, cron checks, incidents
+
+                LANE 3 — Billing + Admin
+                  Responsável: @dev (sessão C)
+                  Escopo: Stripe Checkout, webhooks, /billing, /admin
+
+                Gate C: lanes 1+2 devem ter testes unitários passando antes do merge.
+
+@orchestrator > aioson parallel:init . executado.
+                Workspace em .aioson/context/parallel/.
+                Execute cada lane em uma sessão separada do cliente AI.
+```
+
+```
+Diagrama de dependências:
+┌───────────────┐    ┌───────────────────────┐    ┌────────────────┐
+│  LANE 1       │    │  LANE 2               │    │  LANE 3        │
+│  Auth + DB    │───▶│  Monitors + Worker    │    │  Billing +     │
+│               │    │  (depende do schema)  │    │  Admin         │
+└───────────────┘    └───────────────────────┘    └────────────────┘
+         │                      │                          │
+         └──────────────────────┴──────────────────────────┘
+                                │
+                         aioson parallel:merge
+```
+
+---
+
+## Passo 8 — Executar as lanes (em sessões separadas)
+
+Abra três terminais ou sessões do cliente AI. Em cada um:
+
+```bash
+# Sessão A (Lane 1)
+claude .
+```
+```
+Você > @dev
+@dev > [lê lane 1 em parallel/lane-01.md, implementa auth + schema]
+@dev > Lane 1 concluída. Tests: 12/12.
+```
+
+```bash
+# Sessão B (Lane 2)
+claude .
+```
+```
+Você > @dev
+@dev > [lê lane 2, implementa monitors + worker]
+@dev > Lane 2 concluída. Tests: 24/24.
+```
+
+```bash
+# Sessão C (Lane 3)
+claude .
+```
+```
+Você > @dev
+@dev > [lê lane 3, implementa billing + admin]
+@dev > Lane 3 concluída. Tests: 8/8.
+```
+
+---
+
+## Passo 9 — Merge e QA final
+
+```bash
+# De volta à sessão principal
+```
+```
+Você > aioson parallel:status .
+```
+```
+Lane 1: done  Lane 2: done  Lane 3: done  Gate C: PASS
+```
+```
+Você > aioson parallel:merge . --apply
+```
+```
+@orchestrator > Merge determinístico executado. Verificando conflitos... nenhum.
+```
+```
+Você > @qa
+
+@qa > Rodando suite completa: 44/44 testes passando.
+       Verificando ACs do PRD...
+       AC-Billing-01: webhook Stripe atualiza plano ✓
+       AC-Monitor-03: Free fica bloqueado no 4º monitor ✓
+       AC-Admin-01: admin vê tabela paginada ✓
+       Todos os 12 ACs passando. QA completo.
+```
+
+---
+
+## O que ficou em disco (rastreio)
+
+```
+.aioson/context/
+├── project.context.md        ← MEDIUM, web_app, Aurora Command UI
+├── prd.md                    ← PRD completo (@product)
+├── architecture.md           ← decisões técnicas (@analyst + @architect)
+├── design-doc-mvp.md         ← telas e componentes (@ux-ui)
+├── tasks.md                  ← 18 user stories (@pm)
+├── parallel/
+│   ├── lane-01.md            ← escopo lane Auth
+│   ├── lane-02.md            ← escopo lane Monitors
+│   └── lane-03.md            ← escopo lane Billing
+├── features/mvp/spec.md      ← spec original
+├── dev-state.md              ← status pós-merge
+└── qa-report-test-coverage.md
+```
+
+---
+
+## Variações
+
+| Situação | Ajuste |
+|---|---|
+| Não quer Stripe agora | Retire billing do escopo no `@product`. Lane 3 desaparece. |
+| Time de 3 pessoas | Cada pessoa executa uma lane. Os artefatos de `parallel/` são o contrato entre vocês. |
+| Quer começar pequeno e crescer | Classifique como SMALL agora. Quando o produto crescer, reabra `@setup` e reclassifique MEDIUM. |
+| Auth com OAuth (Google/GitHub) | Declare no `@architect`. NextAuth tem providers prontos. |
+
+---
+
+## Solução de problemas
+
+| Problema | Solução |
+|---|---|
+| `parallel:merge` relata conflito | `aioson parallel:doctor . --fix` — diagnostica e sugere resolução manual |
+| Webhooks Stripe não chegam em dev | Use Stripe CLI: `stripe listen --forward-to localhost:3000/api/webhooks/stripe` |
+| Lane 2 depende de schema ainda não migrado | Lane 1 deve terminar e rodar `prisma migrate dev` antes da Lane 2 começar |
+| `@qa` acha ACs vagos demais | Abra `spec.md`, torne os ACs mais específicos, reative `@qa` |
+
+---
+
+## Próximo passo
+
+- Quer auditar segurança antes de ir para produção? → [Auditoria de segurança](./auditoria-seguranca.md)
+- Quer publicar o SaaS no aioson.com? → [Publicar no aioson.com](./publicar-no-aioson-com.md)
+- Sessão caiu no meio de uma lane? → [Continuidade entre sessões](./continuidade-entre-sessoes.md)