Communitygithub.com

wuongg/wait_skills

Contrato de handoff entre `landing-page-composition-architect` (planejador) e `cinematic-landing-page` (construtor). Define o schema JSON do Blueprint, o mapeamento de layout-family → visual-archetype, os invariantes que o construtor deve preservar e os modos de falha que ambos os lados devem recusar. Leia isto sempre que um Blueprint de Composição estiver sendo transferido ou quando o construtor estiver prestes a codificar uma página sem um blueprint bloqueado.

O que é wait_skills?

Este é um contrato de integração que define a interface entre dois agentes de IA especializados: o `landing-page-composition-architect` (planejador) e o `cinematic-landing-page` (construtor). O planejador decide a estrutura e a ordem das seções de uma landing page, emitindo um Blueprint de Composição em JSON bloqueado. O construtor, por sua vez, é responsável por traduzir esse blueprint em um Build Spec, escolhendo arquétipos visuais, animações e a pilha de tecnologia. A skill ajuda a manter a separação de responsabilidades: o planejador nunca toca no design visual, e o construtor nunca altera a estrutura. É útil para times de desenvolvimento que desejam automatizar o pipeline de criação de páginas estáticas com múltiplos agentes, garantindo que não haja conflitos ou mudanças inesperadas. O contrato inclui regras de validação, protocolos de revisão e modos de falha que ambos os agentes devem recusar. Funciona como um guardrail para a colaboração entre agentes de IA em ferramentas como Claude Code, Cursor e Codex, permitindo uma integração suave e previsível.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/wuongg/wait_skills/tree/HEAD/.cursor/skills/landing-page-skills-integration

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidades de Landing Page — Contrato de Integração v1

Duas habilidades, um pipeline:

Brief do usuário
   │
   ▼
[ landing-page-composition-architect ]   ← decide O QUE & ORDEM
   │  emite: Composition Blueprint (bloqueado)
   ▼
[ INTEGRATION.md  ← este arquivo ]          ← traduz blueprint → build spec
   │  emite: Build Spec (arquétipo + movimento + pilha)
   ▼
[ cinematic-landing-page ]               ← decide COMO FICA & SE MOVE, escreve código
   │
   ▼
Página publicada

Regra de ouro. O planejador é dono da estrutura. O construtor é dono da superfície. Nenhum dos dois pode cruzar a linha. Este arquivo é como eles se mantêm honestos.


1. O ARTEFATO DE HANDOFF — Composition Blueprint (JSON)

O artefato final do planejador DEVE ser renderizável como este JSON, mesmo que tenha sido apresentado ao usuário como uma tabela. O construtor lê este JSON literalmente.

{
  "blueprint_version": "1.0",
  "page": {
    "intent": "I1 | I2 | I3 | I4 | I5 | I6",
    "intent_name": "Lançamento | Conversão | Marca | Portfólio | História do Produto | Campanha",
    "awareness": "frio | morno | quente",
    "traffic": "anúncios | orgânico | social | indicação | direto",
    "narrative_spine": "Gancho -> Valor -> Prova -> CTA",
    "pace": "rápido | equilibrado | lento",
    "density": "mínimo | equilibrado | rico",
    "primary_emotion": "string (uma palavra)",
    "total_sections": 5
  },
  "sections": [
    {
      "index": 1,
      "slot": "S1",
      "name": "Hero",
      "jtbd": "chamar atenção + definir tom",
      "why_here": "primeira impressão",
      "layout_family": "full-bleed hero",
      "content_required": ["headline", "subcopy", "hero_media"],
      "visual_weight": "muito alto",
      "cta_role": "suave"
    }
  ],
  "rhythm_rules": [
    "Duas seções de peso 'muito alto' não podem ser adjacentes.",
    "Após qualquer hero full-bleed ou mood gallery, a próxima deve ser centered statement ou editorial block.",
    "CTA primário aparece exatamente uma vez."
  ],
  "kill_list": [
    "Sem FAQ",
    "Sem grade de 6 cards",
    "Sem faixa de métricas"
  ],
  "handoff_note": "Um parágrafo: emoção a preservar, quais slots querem tratamento cinematográfico, quais ficam quietos.",
  "locked": true
}

Invariantes.

  • sections.length ∈ [4, 9]; 5–8 para intents padrão.
  • Cada slot ∈ {S1..S16}, único por página.
  • layout_family ∈ lista fechada (ver §3).
  • locked: true é uma promessa: o construtor NÃO DEVE reordenar, adicionar, remover ou renomear seções.

2. O QUE O CONSTRUTOR PODE DECIDIR (e o que NÃO PODE)

Construtor pode decidir

  • Arquétipo cinematográfico (A/B/C/D/E/F de cinematic-landing-page).
  • Assinaturas de movimento, curvas de easing, comportamento de scroll.
  • Clima de cor, tipografia, escala de espaçamento.
  • Tratamento de mídia (granulação, desfoque, enquadramento, recortes).
  • Pilha de tecnologia (V1 vanilla vs V2 React+Vite+Tailwind).
  • Polimento de microcópia (desde que preserve a intenção).

Construtor NÃO PODE decidir

  • Número de seções.
  • Ordem das seções.
  • Qual slot mapeia para qual posição.
  • Se uma seção existe ou não.
  • Renomear o propósito de um slot (o nome visível ao usuário pode mudar; o JTBD não).
  • Adicionar seções que não estão no blueprint (sem banner de CTA surpresa, sem bloco de newsletter surpresa).
  • Remover o CTA primário ou duplicá-lo.

Se o construtor sentir que o blueprint está errado, deve parar e solicitar um replanejamento, não mutar silenciosamente.


3. MAPEAMENTO LAYOUT FAMILY → VISUAL ARCHETYPE

O planejador fala em famílias de layout. O construtor fala em arquétipos cinematográficos (A–F). Esta é a tabela de tradução.

Layout family (planejador)Archetype primário (construtor)FallbackNotas
full-bleed heroA (Fixed-Viewport Hero)BVariação framed-canvas se o clima = premium
split heroA (padrão: split)DCópia à esquerda / mídia à direita
centered statementD section OR A (centered)—Baixo movimento, alta legibilidade
benefit railD card row—3–4 itens, sem cards mais pesados que ícone+título+linha
card gridD grid—Máx. 6 tiles; desabilitar hover motion em I3
staggered stackD asymmetric sectionBLinhas alternadas de imagem/texto
editorial blockD editorialF (se tipo display)Texto longo; evitar UI de card
mood galleryB (sticky scroll) ou E (switcher)—Escolher por ritmo: lento→B, equilibrado→E
logo stripD quiet row—Sem movimento além de marquee se solicitado
metric bandD big-number row—Animação de contagem apenas se ritmo ≠ lento
quote panelD ou A single-scene—Uma citação de destaque > carrossel
accordion listD accordion—Banido para I3 (veja kill list)
CTA bandD centered CTAACTA primário vive aqui
sticky footer CTAD sticky footer—Apenas se ritmo = rápido
soft footerD minimal footer—Saída silenciosa no final da página

Limite de arquétipos por página.

  • Máx. 2 arquétipos principais por página (herdado da regra de cinematic-landing-page).
  • A seção hero escolhe o arquétipo dominante. Outras seções usam execução estilo D por padrão, a menos que o handoff_note do planejador solicite explicitamente tratamento cinematográfico para elas.

Defaults de arquétipo baseados em intenção (quando o planejador não deu dicas):

IntentArchetype dominanteSegundo archetype (opcional)
I1 LançamentoAE
I2 ConversãoA (split)— (manter-se quieto)
I3 Editorial de MarcaF ou BE
I4 PortfólioF ou CB
I5 História do ProdutoA + B (scroll story)—
I6 Campanha / TeaserA ou F—

4. BUILD SPEC — o artefato que o construtor emite antes de codificar

Antes de escrever uma única linha de código, o construtor DEVE produzir um Build Spec derivado do Blueprint. Este é o segundo contrato no pipeline.

{
  "build_spec_version": "1.0",
  "blueprint_ref": "locked",
  "stack": "V1 vanilla | V2 react-vite-tailwind",
  "dominant_archetype": "A | B | C | D | E | F",
  "second_archetype": "A | B | C | D | E | F | null",
  "mood": "Cinematográfico Escuro | Editorial Quente | Neo-Tech | Minimalista Claro | Editorial Claro | Vidro Suave",
  "sections": [
    {
      "index": 1,
      "slot": "S1",
      "layout_family": "full-bleed hero",
      "archetype": "A",
      "pattern": "framed-canvas",
      "motion": ["hero_fade_in_800ms", "subcopy_delay_200ms"],
      "media": {"type": "imagem | vídeo | nenhum", "asset_ref": "…"},
      "notes": "por que este arquétipo foi escolhido para este slot"
    }
  ],
  "acceptance_criteria": [
    "Primeiro viewport = apenas composição S1.",
    "CTA primário em S15 exatamente uma vez.",
    "Nenhuma seção de peso 'muito alto' adjacente.",
    "Contagem de movimento na página <= 2 assinaturas."
  ]
}

O construtor valida o Build Spec contra o Blueprint (veja §6) ANTES de codificar. Falhe fechado.


5. REGRAS DE TRADUÇÃO (planejador → construtor)

Aplicadas em ordem.

T1. A ordem das seções é lei. sections[i].index no blueprint = posição na página. O construtor nunca reordena.

T2. Elegibilidade slot → archetype. Use a tabela §3. Se uma família de layout aparecer cujo arquétipo primário conflita com o arquétipo dominante já escolhido para o hero, use o fallback.

T3. Peso → orçamento de movimento.

Visual weightOrçamento de movimento
muito altoaté 2 interações de assinatura
alto1 interação de assinatura
médioapenas micro-interações (hover, pequenos fades)
baixoapenas fades
muito baixoestático

T4. Papel do CTA → tratamento de superfície.

Papel do CTATratamento
primáriobotão completo + formulário/âncora, alto contraste
hardbotão, alto contraste, sem formulário
suavelink de texto com seta
nenhumnenhum elemento de CTA renderizado

T5. Emoção → mapeamento de clima (consultivo).

primary_emotion (planejador)Clima sugerido (construtor)
reverência, calma, luxoCinematográfico Escuro / Vidro Suave
clareza, confiança, precisãoMinimalista Claro / Neo-Tech
calor, humano, históriaEditorial Quente / Editorial Claro
energia, urgência, hypeNeo-Tech / Cinematográfico Escuro

T6. Ritmo → comprimento de scroll.

RitmoScroll total (desktop)
rápido≤ 2.5 viewports
equilibrado3–5 viewports
lento5–8 viewports

T7. Densidade → escolha de componente.

  • mínimo → preferir seções apenas com tipo, amplo espaço em branco.
  • equilibrado → tipo + mídia misturados.
  • rico → pesado em editorial block; ainda respeitar kill list.

T8. Kill list é absoluta. Qualquer coisa em kill_list é proibida no Build Spec e no código, mesmo que "ficaria legal".


6. PORTÃO DE VALIDAÇÃO (executado antes de qualquer código ser escrito)

O construtor executa esta lista de verificação contra o Build Spec. Todos devem passar.

  • Cada seção do blueprint tem exatamente uma linha em build_spec.sections.
  • Valores de index são consecutivos, começando em 1.
  • Nenhuma seção adicionada, removida, reordenada ou mesclada.
  • layout_family por linha corresponde ao blueprint.
  • Archetype dominante é usado pelo hero (index: 1).
  • Total de arquétipos de assinatura na página ≤ 2.
  • Soma de "interações de assinatura" em todas as seções ≤ 2.
  • Contagem de CTA primário = 1 (ou 0 apenas se intent = I3 com soft-footer fechado).
  • Nenhum item de kill_list está presente no spec.
  • Portão de consciência respeitado: frio ⇒ S2 existe logo após S1.
  • Nenhuma adjacência proibida (S6+S9, S11+S13, etc.).

Falha → retornar ao planejador com uma revision_request (veja §7). NÃO codifique contornando um portão falho.


7. PROTOCOLO DE REVISÃO

Se o construtor precisar recusar, ele emite uma solicitação estruturada, não texto livre:

{
  "revision_request": {
    "reason": "conflito_de_layout | ativo_ausente | orçamento_de_movimento_excedido | kill_list_impossível | violação_de_adjacência",
    "affected_sections": [3, 4],
    "explanation": "um parágrafo curto",
    "suggested_fix": "trocar ordem de S6 e S9 | remover S13 | rebaixar peso de S1 para alto"
  }
}

O planejador responde com um novo blueprint bloqueado, não uma nota de patch. Blueprints são reemitidos inteiros, versionados por incremento de blueprint_version.


8. MODOS DE FALHA QUE AMBOS OS LADOS DEVEM RECUSAR

O planejador deve recusar:

  • Emitir um blueprint desbloqueado.
  • Emitir menos de 4 ou mais de 9 seções.
  • Incluir um slot com content_required que o usuário não pode fornecer.
  • Reutilizar um ID de slot.
  • Pular S1 ou (geralmente) S15.
  • Escolher uma família de layout fora da lista fechada em §3.

O construtor deve recusar:

  • Codificar sem um blueprint bloqueado.
  • Codificar sem um Build Spec que passou na §6.
  • Adicionar uma seção "porque a página parecia vazia".
  • Remover uma seção "porque parecia redundante".
  • Usar mais de 2 arquétipos de assinatura.
  • Ignorar a kill list.
  • Rebaixar silenciosamente um CTA primary para soft.

Se um usuário solicitar diretamente uma violação, responda uma vez com a compensação, depois só cumpra se ele confirmar explicitamente — e registre no Build Spec como "user_override": true na linha afetada.


9. EXEMPLO MÍNIMO DE PONTA A PONTA

Blueprint (saída do planejador, condensada)

  • Intent: I2 Conversão, frio, anúncios, ritmo equilibrado, densidade equilibrada.
  • Seções: S1 → S2 → S4 → S5 → S6 → S12 → S13 → S15
  • Kill list: sem S8, sem S9, sem S14, sem S11.
  • Emoção primária: clareza.

Build Spec (saída do construtor, condensada)

  • Pilha: V2 (React + Vite + Tailwind + framer-motion).
  • Arquétipo dominante: A (split hero). Segundo arquétipo: nenhum.
  • Clima: Minimalista Claro.
  • Orçamento de movimento usado: 2 / 2 (revelação split do hero + contagem de métricas).
  • S1 = A split hero. S2 = D centered statement. S4 = D editorial block. S5 = D staggered stack. S6 = D card grid (4 tiles). S12 = D metric band. S13 = D quote panel (citação única). S15 = D CTA band com formulário.
  • Aceitação: CTA primário uma vez (S15); sem adjacência S6/S9; scroll total ≈ 4 viewports.

Validação

Todas as verificações da §6 passam. Construtor prossegue para codificação.


10. O QUE DIZER AO USUÁRIO (trechos de script)

Ao fazer handoff do planejador:

"Blueprint bloqueado. Mudar para a skill de construção (cinematic-landing-page)? Essa skill vai escolher arquétipo visual + movimento + código, sem alterar a ordem das seções."

Quando o construtor rejeita um blueprint:

"Este blueprint tem um conflito na seção {n} — {motivo}. Vou devolver ao planejador para emitir uma nova versão, em vez de corrigir por conta própria."

Quando o usuário insiste em uma substituição:

"Se você insistir nisso, vou marcar user_override: true naquela seção. A página ainda será construída, mas a regra de ritmo será quebrada — você confirma?"


Fim do contrato de integração.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas