wizz-method 1.4.1 → 1.5.0

package/src/skills-lib/implementation-planner/references/folder-structure-and-dependencies.md

@@ -0,0 +1,132 @@
+# Estrutura de pastas + dependências recomendadas
+
+Carregar ao montar a estrutura de pastas padrão (com notas de quando remover cada diretório) e a lista de dependências recomendadas por categoria (base, UI, motion, 3D, dashboard, forms, analytics), instalando apenas o que o projeto usa.
+
+## Estrutura de pastas padrão
+
+```
+app/
+  (site)/
+    page.tsx
+    layout.tsx
+  api/
+    contact/route.ts
+
+components/
+  sections/
+    Hero.tsx
+    Manifesto.tsx
+    Approach.tsx
+    SelectedWork.tsx
+    CaseDeepDive.tsx
+    Capabilities.tsx
+    Recognition.tsx
+    Conversation.tsx
+    FAQ.tsx
+    SiteFooter.tsx
+
+  ui/
+    Button.tsx
+    GhostButton.tsx
+    SectionHeader.tsx
+    EditorialCard.tsx
+    Marquee.tsx
+    Badge.tsx
+    MetricCard.tsx
+
+  motion/
+    TextReveal.tsx
+    SectionFade.tsx
+    MagneticButton.tsx
+    ScrollProgress.tsx
+    ParallaxLayer.tsx
+    ImageReveal.tsx
+
+  media/
+    HeroVideo.tsx
+    ResponsiveVideo.tsx
+    VideoFallback.tsx
+
+  three/
+    HeroScene.tsx
+    ParticleCluster.tsx
+    ShaderBackground.tsx
+    CanvasFallback.tsx
+
+lib/
+  motion/
+    easing.ts
+    variants.ts
+  device/
+    capability.ts
+  analytics/
+    events.ts
+  seo/
+    metadata.ts
+  content/
+    cases.ts
+    site.ts
+
+public/
+  images/
+  video/
+  posters/
+  logos/
+```
+
+**Ajustar de acordo com o projeto:**
+
+- Se não houver 3D real, **remover** `components/three/`.
+- Se não houver vídeo, **remover** `components/media/`.
+- Se não houver portfolio, **remover** `lib/content/cases.ts`.
+
+---
+
+## Dependências recomendadas
+
+Instalar **apenas o que o projeto usa**.
+
+**Base:**
+
+```bash
+npm install next react react-dom typescript
+```
+
+**UI:**
+
+```bash
+npm install tailwindcss lucide-react clsx tailwind-merge
+```
+
+**Motion:**
+
+```bash
+npm install framer-motion
+# ou, se o projeto usar Motion:
+npm install motion
+```
+
+**3D real (apenas se necessário):**
+
+```bash
+npm install three @react-three/fiber @react-three/drei
+```
+
+**Dashboard (apenas se necessário):**
+
+```bash
+npm install recharts
+```
+
+**Forms / validation (se necessário):**
+
+```bash
+npm install react-hook-form zod
+```
+
+**Analytics (se necessário):**
+
+```bash
+npm install @vercel/analytics @vercel/speed-insights
+```
+

package/src/skills-lib/implementation-planner/references/handoff-template.md

@@ -0,0 +1,34 @@
+# Handoff prompt para Claude Code / Codex
+
+Carregar ao fechar o plano — o template exato do prompt de handoff para desenvolvimento (Claude Code, Codex, ou dev manual).
+
+## Handoff para Claude Code / Codex
+
+Sempre terminar com um prompt pronto para desenvolvimento.
+
+**Template:**
+
+```
+You are a senior frontend engineer.
+
+Build this project using the implementation plan below.
+
+Requirements:
+- Follow the defined stack.
+- Do not add unnecessary dependencies.
+- Respect the motion path.
+- If the motion path is image-to-video, do not implement Three.js for the hero.
+- If the motion path is 3D real, implement R3F with mobile fallback.
+- Use semantic HTML.
+- Respect prefers-reduced-motion.
+- Keep performance budget in mind.
+- Build components according to the component map.
+- Use the provided file structure.
+- Mark missing assets as TODO.
+- Do not invent client names, metrics or case study data.
+
+Implementation plan:
+[paste plan]
+```
+
+---

package/src/skills-lib/implementation-planner/references/implementation-phases.md

@@ -0,0 +1,54 @@
+# Implementation Phases
+
+Carregar ao dividir o plano em fases. Template das 5 fases padrão: Foundation, Static Landing, Motion, 3D/Video (se aplicável), Polish.
+
+## Implementation Phases
+
+Sempre dividir em fases.
+
+**Fase 1 — Foundation**
+
+- setup do projeto;
+- Tailwind;
+- shadcn;
+- tokens;
+- typography;
+- layout;
+- componentes base.
+
+**Fase 2 — Static Landing**
+
+- seções principais;
+- copy;
+- responsive layout;
+- imagens;
+- CTA;
+- SEO inicial.
+
+**Fase 3 — Motion**
+
+- text reveal;
+- section transitions;
+- hovers;
+- magnetic CTA;
+- parallax;
+- microinterações.
+
+**Fase 4 — 3D / Video** (se aplicável)
+
+- video hero ou R3F;
+- fallback;
+- performance;
+- reduced motion;
+- mobile assets.
+
+**Fase 5 — Polish**
+
+- QA visual;
+- accessibility;
+- performance;
+- analytics;
+- deploy;
+- bug fixes.
+
+---

package/src/skills-lib/implementation-planner/references/implementation-types.md

@@ -0,0 +1,28 @@
+# Tipos de implementação — adaptação por tipo de projeto
+
+Carregar ao montar o plano, para saber o que incluir de acordo com o tipo de projeto: Landing page, Portfolio/Authority Site, SaaS Landing, SaaS Dashboard, ou 3D/Motion Site.
+
+## Tipos de implementação
+
+Adaptar o plano para o tipo de projeto.
+
+### 1. Landing page
+
+Incluir: page structure; sections; component map; copy integration; CTA logic; animations; responsive layout; SEO; analytics; deploy.
+
+### 2. Portfolio / Authority Site
+
+Incluir: selected work; case cards; case deep-dive; capabilities; recognition; manifesto; editorial CTA; content placeholders; **anti-invention rule** (não inventar nomes de clientes, métricas ou case studies); MDX ou content config para cases.
+
+### 3. SaaS Landing
+
+Incluir: hero; product mockup; features; use cases; pricing (se necessário); testimonials; integrations; FAQ (se necessário); CTA; analytics.
+
+### 4. SaaS Dashboard
+
+Incluir: app layout; sidebar; topbar; KPI cards; charts; tables; settings; billing; user profile; empty states; loading states; error states; responsive behavior; Recharts; mock data.
+
+### 5. 3D / Motion Site
+
+Incluir: motion path; assets; hero implementation; video implementation; R3F implementation (se necessário); fallback mobile; performance plan; reduced motion; lazy load; asset compression.
+

package/src/skills-lib/implementation-planner/references/motion-path-implementation.md

@@ -0,0 +1,57 @@
+# Motion Path Implementation Rules
+
+Carregar sempre — a implementação deve seguir o motion path escolhido pelo motion-3d-director. Cobre as regras e arquivos a planejar para cada um dos 4 paths: 3D real, image-to-video, hybrid motion, motion 2D premium.
+
+## Motion Path Implementation Rules
+
+A implementação **deve seguir o motion path escolhido** pelo `motion-3d-director`.
+
+### Se o path for 3D real
+
+**Usar:** React Three Fiber; Three.js; Drei; dynamic import; Suspense; poster fallback; reduced motion; dpr cap; pause offscreen.
+
+**Planejar arquivos:**
+
+- `components/three/HeroScene.tsx`
+- `components/three/ParticleCluster.tsx`
+- `components/three/ShaderBackground.tsx`
+- `components/three/CanvasFallback.tsx`
+- `lib/device/capability.ts`
+
+### Se o path for image-to-video
+
+**Não implementar R3F/Three.js para o hero principal.**
+
+**Usar:** `<video>`; WebM; MP4 fallback; poster image; mobile video; reduced motion fallback; lazy loading quando possível; preload controlado; overlay HTML para copy/CTA.
+
+**Planejar arquivos:**
+
+- `public/video/hero-desktop.webm`
+- `public/video/hero-desktop.mp4`
+- `public/video/hero-mobile.webm`
+- `public/video/hero-mobile.mp4`
+- `public/images/hero-poster.webp`
+- `components/media/HeroVideo.tsx`
+- `components/media/ResponsiveVideo.tsx`
+- `components/media/VideoFallback.tsx`
+
+### Se o path for hybrid motion
+
+**Combinar:**
+
+- vídeo / image-to-video no hero;
+- Framer Motion para texto e seções;
+- React Bits para microinterações;
+- hover effects;
+- scroll effects;
+- pequenos detalhes WebGL opcionais, se aprovados.
+
+**Separação clara:** vídeo para atmosfera; HTML/CSS para conteúdo; Framer Motion para narrativa; WebGL só se necessário.
+
+### Se o path for motion 2D premium
+
+**Usar:** Framer Motion; React Bits; CSS transitions; SVG animation; clip-path reveal; parallax leve; magnetic buttons.
+
+**Não usar Three.js.**
+
+---

package/src/skills-lib/implementation-planner/references/output-templates.md

@@ -0,0 +1,92 @@
+# Output templates — Component Map, Motion Map, Asset Map
+
+Carregar ao produzir os três mapas obrigatórios do output. Contém exemplos preenchidos de Component Map, Motion Map e Asset Map.
+
+## Component Map
+
+Sempre criar um mapa de componentes.
+
+**Exemplo:**
+
+```
+## Component Map
+
+### Hero
+File: components/sections/Hero.tsx
+Uses:
+- TextReveal
+- MagneticButton
+- HeroVideo or HeroScene
+- SectionFade
+
+### SelectedWork
+File: components/sections/SelectedWork.tsx
+Uses:
+- EditorialCard
+- ImageReveal
+- case data from lib/content/cases.ts
+
+### Conversation
+File: components/sections/Conversation.tsx
+Uses:
+- GhostButton
+- SectionHeader
+- Analytics event
+```
+
+---
+
+## Motion Map
+
+Sempre criar mapa de animações.
+
+**Exemplo:**
+
+```
+## Motion Map
+
+### Hero
+- headline: word reveal, stagger 60ms
+- subheadline: fade up after headline
+- CTA: magnetic hover
+- visual: video loop or 3D scene
+
+### Sections
+- section enter: fade + slide up
+- cards: stagger children
+- images: clip-path reveal
+
+### Reduced Motion
+- disable parallax
+- disable magnetic cursor
+- use opacity-only transitions
+```
+
+---
+
+## Asset Map
+
+Sempre criar mapa de assets.
+
+**Exemplo:**
+
+```
+## Asset Map
+
+### Hero
+- hero-desktop.webm
+- hero-desktop.mp4
+- hero-mobile.webm
+- hero-poster.webp
+
+### Logos
+- client-logo-01.svg
+- client-logo-02.svg
+
+### Cases
+- case-01-cover.webp
+- case-02-cover.webp
+```
+
+Marcar assets faltantes como `[needed]` ou `[editável]`.
+

package/src/skills-lib/implementation-planner/references/performance-plan.md

@@ -0,0 +1,52 @@
+# Performance Plan
+
+Carregar ao montar o plano de performance. Cobre: requisitos gerais para qualquer site, requisitos específicos para vídeo, requisitos específicos para 3D real, e os targets sugeridos (LCP/CLS/INP/Lighthouse).
+
+## Performance Plan
+
+### Para qualquer site
+
+- otimizar imagens;
+- usar `next/image`;
+- usar `next/font`;
+- evitar JS desnecessário;
+- lazy load abaixo da dobra;
+- reduzir bundle inicial;
+- usar semantic HTML;
+- evitar layout shift;
+- usar contrastes AA;
+- respeitar `prefers-reduced-motion`.
+
+### Para vídeo
+
+- WebM + MP4 fallback;
+- poster image;
+- preload controlado;
+- vídeo `muted playsInline loop`;
+- mobile crop separado;
+- compressão forte;
+- não bloquear LCP;
+- fallback poster em reduced motion.
+
+### Para 3D real
+
+- dynamic import com `ssr: false`;
+- Suspense fallback;
+- dpr cap;
+- redução de partículas mobile;
+- pause offscreen;
+- dispose de geometria/material;
+- evitar shadow pesado;
+- limitar luzes;
+- fallback poster;
+- `prefers-reduced-motion`.
+
+### Targets
+
+- LCP < 2.5s desktop;
+- LCP < 3.5s mobile;
+- CLS < 0.1;
+- INP < 200ms;
+- Lighthouse Performance 90+ quando possível.
+
+---