@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/pt/site-forge.md

@@ -0,0 +1,309 @@
+# `site-forge`
+
+Agente de clonagem inteligente do AIOSON — estuda um site real e reconstrói como projeto Next.js, forja uma skill de design, ou ambos.
+
+## O que ele faz
+
+- recebe uma URL e guia você até o modo certo com um **questionário de onboarding**
+- captura screenshots, assets (img, background-image, srcset, lazy-loaded, video) via browser MCP
+- faz crawl de links internos para capturar assets e padrões de sub-páginas
+- extrai estrutura, comportamento e interações
+- forja design skills, mescla tokens, ou aplica skills existentes conforme o modo escolhido
+- constrói um projeto Next.js com worktrees paralelas
+
+## Pré-requisitos
+
+### 1. Browser MCP
+
+O agente precisa de automação de browser para navegar, capturar screenshots, disparar lazy loads e testar interações. Configure um antes de usar:
+
+```bash
+# Playwright MCP (recomendado)
+npx @playwright/mcp@latest
+
+# Puppeteer MCP (alternativa)
+npx @modelcontextprotocol/server-puppeteer
+```
+
+Adicione o browser MCP escolhido nas configurações de MCP do seu cliente AI. O agente detecta automaticamente qual está disponível.
+
+### 2. Design skill (quando aplicável)
+
+Modos que usam uma skill existente precisam de uma skill já instalada. Use uma das skills nativas:
+
+```text
+.aioson/skills/design/aurora-command-ui/
+.aioson/skills/design/cognitive-core-ui/
+.aioson/skills/design/glassmorphism-ui/
+.aioson/skills/design/bold-editorial-ui/
+.aioson/skills/design/neo-brutalist-ui/
+.aioson/skills/design/warm-craft-ui/
+.aioson/skills/design/clean-saas-ui/
+```
+
+Ou use uma skill gerada pelo `@design-hybrid-forge`:
+
+```text
+.aioson/installed-skills/{slug}/
+```
+
+## Modos de operação
+
+O agente tem **5 modos**. Se você não especificar o modo, ele roda o **onboarding inteligente** e te guia até o certo.
+
+| Modo | Entrada | Output |
+|------|---------|--------|
+| **A — Transform** | URL + skill | Site construído com a skill aplicada à estrutura clonada |
+| **B — Faithful clone** | URL | Réplica fiel + nova skill forjada do site |
+| **C — Content harvest** | URL + skill | Site construído com conteúdo/imagens do site + layout da skill |
+| **D — Skill only** | URL | Só a skill forjada — nenhum site é construído |
+| **E — Blend** | URL + skill + ratio | Site com tokens misturados entre o site e a skill |
+
+## Onboarding inteligente
+
+Quando você chamar `/site-forge` sem especificar o modo, o agente pergunta:
+
+```
+O que você quer fazer com este site?
+
+  A — Extrair conteúdo e imagens → construir um novo site com uma das suas skills
+  B — Clonar fielmente → réplica visual + forjar uma skill com o design do site
+  C — Extrair somente o design (CSS, animações) → criar uma skill reutilizável (sem construir o site)
+  D — Clonar com textos e imagens originais + mesclar com uma das suas skills (50/50)
+```
+
+Depois coleta os dados que faltam (URL, skill, ratio) e já avança.
+
+## Como invocar
+
+```text
+/site-forge <url> <skill>              → Modo A (transform)
+/site-forge <url>                      → Onboarding guiado
+/site-forge <url> --skill-only         → Modo D (só a skill)
+/site-forge <url> <skill> --blend      → Modo E (blend 50/50)
+/site-forge <url> <skill> --blend=70   → Modo E (70% site / 30% skill)
+```
+
+Com flags opcionais:
+
+```text
+--viewport=desktop    # só desktop (padrão: todos os três)
+--no-download         # pular download de assets
+--no-crawl            # pular crawl de links internos
+--crawl-depth=N       # seguir N níveis de links (padrão: 1)
+--output=./dir        # diretório customizado
+--verbose             # log detalhado
+```
+
+## Extração de assets melhorada
+
+O agente captura imagens de **todas as fontes**, não só `<img>`:
+
+- `<img>` com `srcset` e `data-src` (lazy loading)
+- `background-image` em **qualquer elemento** via `getComputedStyle`
+- `<picture> <source srcset>`
+- `<video poster>` e `<source>` de vídeo
+- `<use href>` de SVG externos
+- `style=""` com `background-image` inline
+- meta tags `og:image` e `twitter:image`
+
+Antes de extrair, o agente faz scroll completo pela página para **disparar todos os lazy loads**.
+
+## Crawl de links internos
+
+Por padrão o agente segue links internos para capturar assets e padrões de sub-páginas:
+
+| Modo | Links seguidos (padrão) |
+|------|------------------------|
+| A, C (content harvest) | até 10 |
+| B, D, E | até 5 |
+
+Use `--no-crawl` para desativar ou `--crawl-depth=N` para ajustar.
+
+## Fluxo por fase
+
+| Fase | O que acontece | Modos |
+|------|---------------|-------|
+| **0 — Preflight** | Browser MCP, skill, projeto Next.js | Todos |
+| **1 — Reconnaissance** | Screenshots, deep asset extraction, crawl, interações | Todos |
+| **2 — Extraction** | Spec de estrutura + conteúdo; valores estéticos (modos B/D/E) | Todos |
+| **3A — Transform** | Mapa componente → skill com tokens | A, C |
+| **3B — Skill forge** | Extrai design system e forja skill em `.aioson/installed-skills/` | B, D, E |
+| **3E — Blend** | Mescla tokens do site com tokens da skill no ratio definido | E |
+| **4 — Build** | Constrói componentes com worktrees, verifica `npm run build` | A, B, C, E |
+| **5 — QA** | Screenshot diff, testes de interação, fidelidade de tokens | A, B, C, E |
+
+**Modo D** termina após a Fase 3B — nenhum site é construído.
+
+## Output por modo
+
+```text
+Todos os modos:
+  docs/research/<hostname>/
+    reconnaissance.json        ← dados da navegação
+    crawl-manifest.json        ← URLs visitadas e assets por página
+    structure-spec.md          ← topologia e layout
+    interaction-spec.md        ← modelo de interação
+    qa-report.md               ← resultado do QA (modos A/B/C/E)
+
+Modo A, C:
+    component-map.md           ← mapeamento componente → skill
+
+Modo B, D, E:
+    aesthetics-raw.json        ← valores CSS extraídos
+
+Modo E:
+    blend-map.md               ← decisões de blend por token
+    blended-tokens.css         ← tokens mesclados prontos para uso
+
+Modos A, B, C, E (constrói site):
+  src/components/[todos os componentes]
+  src/app/page.tsx
+  src/app/globals.css
+  public/images/<hostname>/[assets baixados]
+
+Modos B, D, E (forja skill):
+  .aioson/installed-skills/<hostname>/
+    SKILL.md
+    references/design-tokens.md
+    references/components.md
+    references/patterns.md
+    references/motion.md
+    references/websites.md
+    .skill-meta.json
+```
+
+## Fluxo completo: forge + clone
+
+O caminho mais poderoso é criar uma skill sob medida com `design-hybrid-forge` e aplicá-la.
+
+### Passo 1 — Gerar o preset visual
+
+```bash
+aioson design-hybrid:options . --locale=pt-BR
+```
+
+### Passo 2 — Forjar a skill híbrida
+
+```text
+/design-hybrid-forge
+→ skills primárias: aurora-command-ui + cognitive-core-ui
+→ nome: aurora-cognitive-command
+```
+
+### Passo 3 — Aplicar no clone
+
+```text
+/site-forge https://datadog.com aurora-cognitive-command
+```
+
+Resultado: estrutura e interações do Datadog, visual da `aurora-cognitive-command`.
+
+---
+
+Veja a documentação completa do seletor interativo em: [`design-hybrid-forge.md`](design-hybrid-forge.md)
+
+---
+
+## Exemplos práticos
+
+### Modo A — Clone com skill existente
+
+```text
+/site-forge https://stripe.com aurora-command-ui
+```
+
+Estrutura e fluxo do Stripe, visual da `aurora-command-ui`.
+
+---
+
+### Modo B — Réplica fiel + nova skill
+
+```text
+/site-forge https://linear.app
+```
+
+Forja uma skill em `.aioson/installed-skills/linear.app/` e constrói uma réplica fiel.
+
+---
+
+### Modo C — Colher conteúdo + nova estrutura com skill
+
+Perguntar o modo via onboarding:
+
+```text
+/site-forge https://framer.com
+→ escolha A no onboarding
+→ skill: clean-saas-ui
+```
+
+Textos e imagens do Framer, layout e visual do `clean-saas-ui`.
+
+---
+
+### Modo D — Só a skill, sem construir
+
+```text
+/site-forge https://resend.com --skill-only
+```
+
+Forja `.aioson/installed-skills/resend.com/`. Nenhuma página é construída.
+
+---
+
+### Modo E — Blend 50/50
+
+```text
+/site-forge https://vercel.com neo-brutalist-ui --blend
+```
+
+Tokens mesclados 50% Vercel / 50% `neo-brutalist-ui`.
+
+---
+
+### Blend assimétrico (70% site)
+
+```text
+/site-forge https://notion.so glassmorphism-ui --blend=70
+```
+
+70% tokens do Notion, 30% tokens da `glassmorphism-ui`.
+
+---
+
+### Clone em projeto existente
+
+```bash
+cd meu-projeto-nextjs
+/site-forge https://loom.com cognitive-core-ui
+```
+
+O agente detecta o `package.json` com `next` e usa o projeto existente.
+
+## Diferença em relação a clonar manualmente
+
+| Aspecto | Clone manual | site-forge |
+|---------|-------------|--------------|
+| Extração de imagens | Só `<img>` visíveis | img + CSS bg + srcset + lazy + video + SVG |
+| Sub-páginas | Ignoradas | Crawl automático |
+| Estética | Replica o original | Skill tokens, blend, ou extração fiel |
+| Interações | Esquecidas facilmente | Mapeadas antes de construir |
+| Build | Erros no final | Verificado após cada worktree |
+| QA | Manual | Screenshot diff + checklist formal |
+
+## Nota sobre conteúdo e assets
+
+Os textos e imagens extraídos são apenas para estruturar o clone durante o desenvolvimento. **Substitua todo o conteúdo antes de publicar.** O agente avisa ao final da Fase 1.
+
+## Quando usar
+
+- você quer o comportamento/layout de um site de referência
+- quer prototipar rapidamente com estrutura testada
+- quer extrair o design de um site como skill reutilizável
+- quer mesclar o visual de um site com sua brand
+- o cliente mostrou um concorrente como referência de fluxo
+
+## Quando não usar
+
+- o site tem proteção pesada (SPA autenticada, bot protection agressivo)
+- você quer criar a estrutura do zero com total liberdade → use `/deyvin` ou `/dev`

package/docs/pt/skills.md

@@ -36,19 +36,27 @@ Estrutura:
 │   ├── ethereum-docs.md
 │   ├── solana-docs.md
 │   └── cardano-docs.md
-└── design/          ← design systems visuais
-    ├── cognitive-core-ui/
-    ├── interface-design/
-    └── premium-command-center-ui/
+├── design/          ← design systems visuais
+│   ├── cognitive-core-ui/
+│   ├── interface-design/
+│   └── premium-command-center-ui/
+└── process/         ← metodologia de fluxo e contratos entre agentes
+    └── aioson-spec-driven/
 ```
 
 **Carregamento condicional:** O agente `@dev` carrega apenas as skills que correspondem ao valor de `framework` em `project.context.md`. Exemplo: se `framework=Laravel`, carrega `laravel-conventions.md` e opcionalmente `tall-stack-patterns.md` se o stack for TALL.
 
+**Process skills** são carregadas pelos agentes de spec (`@product`, `@analyst`, `@architect`, `@sheldon`, `@dev`, `@deyvin`) no início de sessões de especificação, requirements e design — nunca todas de uma vez. Cada agente carrega o `SKILL.md` central e depois apenas o arquivo de `references/` relevante para sua fase atual.
+
 ### Skills instaladas (`.aioson/installed-skills/`)
 
-Skills de terceiros instaladas pelo usuário. São **versionadas com o projeto** (não gitignored), permitindo que toda a equipe use as mesmas skills.
+Skills versionadas com o projeto. Entram aqui em dois casos:
+
+- skills de terceiros instaladas pelo usuário via CLI
+- skills locais geradas dentro do próprio projeto por agentes/process skills
 
 Cada skill instalada contém um `SKILL.md` com frontmatter YAML descrevendo quando usá-la.
+Quando existir, o arquivo `.skill-meta.json` registra origem, autor e metadados do gerador/modelo.
 
 ## Instalando skills
 
@@ -61,7 +69,7 @@ aioson skill:install @tech-leads-club/agent-skills --skill coupling-analysis
 Isso:
 1. Baixa o pacote npm temporariamente
 2. Copia a skill para `.aioson/installed-skills/{nome}/`
-3. Distribui para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
+3. Distribui recursivamente para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
 4. Registra a skill na seção "Installed skills" do `AGENTS.md`
 
 ### Via aioson.com (registry cloud)
@@ -89,6 +97,7 @@ aioson skill:list
 ```
 
 Mostra todas as skills em `.aioson/installed-skills/` com nome, descrição e fonte.
+Quando a metadata existir, também pode mostrar autor e modelo gerador.
 
 ### Remover uma skill
 
@@ -150,6 +159,89 @@ Skills de design disponíveis:
 - `interface-design` — Design de interfaces (dashboards, apps, ferramentas)
 - `premium-command-center-ui` — UI premium para command centers
 
+## Skills de processo
+
+Skills de processo ensinam os agentes **como as fases do AIOSON se conectam** — não o que implementar, mas como sequenciar, quando aprofundar e como fazer handoff limpo entre agentes.
+
+Diferente das skills de framework (que são por stack) e das skills de design (que são por sistema visual), process skills são transversais: carregadas por qualquer agente de spec conforme a fase em que ele se encontra.
+
+### `aioson-spec-driven`
+
+Localização: `.aioson/skills/process/aioson-spec-driven/`
+
+A skill central de metodologia do AIOSON. Cobre:
+
+- **Sequência de fases** — quais fases existem, quais artefatos cada uma produz e quem é o agente responsável
+- **Profundidade por classificação** — MICRO usa fluxo mínimo, SMALL usa fluxo padrão, MEDIUM usa pacote completo
+- **Gates de aprovação** — Gate A (requirements), Gate B (design), Gate C (plan) — critérios do que deve estar pronto antes de avançar para a próxima fase
+- **Hardening lane** — como identificar quando um input ainda está em modo "exploratório/vibe" e o que fazer para convertê-lo em spec executável
+- **Manutenção e estado** — como escrever checkpoints úteis em `spec-{slug}.md` para que qualquer agente ou sessão futura possa retomar sem redescobrir o que já foi decidido
+
+**Estrutura:**
+
+```
+.aioson/skills/process/aioson-spec-driven/
+├── SKILL.md                          ← entry point curto — carregue sempre primeiro
+└── references/
+    ├── artifact-map.md               ← qual artefato fica onde e quem é o dono
+    ├── classification-map.md         ← profundidade de fase por MICRO/SMALL/MEDIUM
+    ├── approval-gates.md             ← critérios dos Gates A, B e C
+    ├── hardening-lane.md             ← quando endurecer vs quando explorar
+    └── maintenance-and-state.md      ← como escrever spec e checkpoints úteis
+```
+
+**Carregamento:** Os agentes `@product`, `@analyst`, `@architect`, `@sheldon`, `@dev` e `@deyvin` verificam automaticamente se esta skill está disponível e carregam `SKILL.md` + apenas o arquivo de `references/` relevante para a fase atual. Nunca carregam a pasta inteira de uma vez.
+
+### `design-hybrid-forge`
+
+Localização: `.aioson/skills/process/design-hybrid-forge/`
+
+Skill first-party para criar uma nova skill de design híbrida a partir de **2 skills primárias obrigatórias** e, opcionalmente, até 2 modificadores de escopo limitado. Em modo avançado, pode liberar um 3º modificador, ainda preso a lanes secundárias.
+
+Se você quer o fluxo completo em um só lugar, leia a página dedicada: [design-hybrid-forge](./design-hybrid-forge.md).
+
+Fluxo padrão:
+
+1. O usuário ativa `@design-hybrid-forge` no Codex ou `/design-hybrid-forge` no Claude
+2. Se quiser um overlay visual mais ousado, o usuário pode rodar `aioson design-hybrid:options` para gerar `.aioson/context/design-variation-preset.md`
+3. O comando usa `conversation_language` do projeto quando existir; `--locale` funciona como override manual
+4. O agente pede as 2 skills primárias, até 2 modificadores opcionais e lê o preset visual quando ele existir
+5. Se o usuário tiver criado o preset com `--advanced`, o agente pode aceitar um 3º modificador de escopo estreito
+6. O híbrido é gerado em `.aioson/installed-skills/{slug}/`
+7. O `AGENTS.md` é atualizado para que o Codex possa usar `@{slug}`
+8. O pacote também pode ser espelhado para `.claude/skills/`, `.cursor/skills/` e `.windsurf/skills/`
+
+Saída padrão:
+
+```
+.aioson/installed-skills/{slug}/
+  SKILL.md
+  .skill-meta.json
+  references/
+  previews/
+```
+
+Esse fluxo cria uma **skill local do projeto**. Se depois você quiser promover a skill para o core do AIOSON ou para um marketplace, trate isso como uma segunda etapa de curadoria, separada da geração local.
+
+O preset criado em `.aioson/context/design-variation-preset.md` é **temporário**:
+- ele serve como input para a próxima geração híbrida
+- depois da geração, deve ser removido ou movido do contexto ativo
+- uma cópia histórica fica em `.aioson/context/history/design-variation-presets/`
+- ele não redefine o layout padrão do projeto; quem continua mandando no projeto é a `design_skill` ativa
+
+O preset gerado por `design-hybrid:options` cobre direções como:
+- clássico / editorial
+- extravagante / maximalista
+- cinematográfico / imersivo
+- retrofuturista
+- motion-driven
+- CSS avançado (scroll-driven animations, View Transition API, masks, SVG filters, 3D)
+
+Recomendação de uso:
+- fluxo normal: até 2 modificadores
+- fluxo avançado: `aioson design-hybrid:options --advanced` para permitir até 3 modificadores
+- mesmo no modo avançado, modificadores não podem dominar substrato nem estrutura
+
 ## Skills de squad
 
 Squads podem ter suas próprias skills em `.aioson/squads/{squad-slug}/skills/`. Essas são carregadas automaticamente quando a tarefa pertence ao escopo do squad.