# Git Pills Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Construir o site interativo "Git Pills" — um dashboard dev newsletter que cataloga e explica 28 ferramentas/repos de Claude Code e AI com 4 views (Grid, Kanban, Grafo, Feed), animações e vídeos Remotion.

**Architecture:** SPA React 18 + Vite 6, estado global Zustand, componentes shadcn/ui, animações Framer Motion, grafo react-force-graph-2d, Remotion isolado para geração de MP4. Deploy via PM2 + EasyPanel.

**Tech Stack:** React 18, Vite 6, TypeScript 5.7, Tailwind 3.4, shadcn/ui, Framer Motion, react-force-graph-2d, Zustand 5, Remotion 4, Lucide React

---

## Chunk 1: Projeto Base + Dependências

### Task 1: Inicializar projeto React + Vite + TypeScript

**Files:**
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/package.json`
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/vite.config.ts`
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/tsconfig.json`
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/tailwind.config.ts`
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/postcss.config.js`
- Create: `/workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter/index.html`

```bash
cd /workspace/temp-orquestrador/users/5aaf347f-952f-4355-8513-ac3f4024b43e/projetos/githunter
npm init -y
npm install react react-dom react-router-dom framer-motion zustand lucide-react clsx class-variance-authority tailwind-merge react-force-graph-2d
npm install -D typescript vite @vitejs/plugin-react tailwindcss postcss autoprefixer tailwindcss-animate @types/react @types/react-dom
```

- [ ] Criar package.json com scripts e dependências
- [ ] Criar vite.config.ts com allowedHosts: 'all', CORS, porta 4100
- [ ] Criar tsconfig.json com strict mode
- [ ] Criar tailwind.config.ts com darkMode: 'class' + tailwindcss-animate
- [ ] Criar postcss.config.js com tailwind + autoprefixer
- Create index.html com root div e dark class

### Task 2: Setup do app shell

**Files:**
- Create: `src/main.tsx`
- Create: `src/App.tsx`
- Create: `src/index.css`

```tsx
// src/main.tsx
import { createRoot } from 'react-dom/client'
import { BrowserRouter } from 'react-router-dom'
import App from './App'
import './index.css'
// Inicializar dark mode padrão
document.documentElement.classList.add('dark')
createRoot(document.getElementById('root')!).render(
  <BrowserRouter>
    <App />
  </BrowserRouter>
)
```

- [ ] Criar main.tsx com BrowserRouter e dark mode padrão
- [ ] Criar App.tsx com PillsPage (sem componentes ainda, só placeholder)
- [ ] Criar index.css com @tailwind directives + CSS variables para cores dark/light
- [ ] Rodar `npx vite --host 0.0.0.0` para verificar build

---

## Chunk 2: Dados + Estado Global + Utilitários

**Pode rodar em paralelo com a Task 2**

### Task 3: Data Model + 28 Pills

**Files:**
- Create: `src/shared/data/pills.data.ts`
- Create: `src/shared/types/pills.types.ts`

```ts
// src/shared/types/pills.types.ts
export type PillType = 'github' | 'youtube' | 'twitter' | 'website'
export type PillCategory = 'claude-code-tools' | 'awesome-lists' | 'official' | 'media'
export type Difficulty = 'iniciante' | 'intermediário' | 'avançado'
export interface Pill {
  id: string; name: string; category: PillCategory; url: string; type: PillType
  stars?: number; tags: string[]; headline: string; problem: string; solution: string
  howToUse: string[]; useCases: string[]; difficulty: Difficulty
  highlight?: boolean; color: string; relatedIds?: string[]
}
```

- [ ] Criar pills.types.ts com tipos explícitos
- [ ] Criar pills.data.ts com as 28 pills completas (cada uma com headline, problem, solution, howToUse, useCases)
- Nota: Os dados devem ser pesquisados via web para cada repo antes de escrever

### Task 4: Zustand Store + Utilitários

**Files:**
- Create: `src/shared/store/pills.store.ts`
- Create: `src/shared/lib/utils.ts`

```ts
// src/shared/store/pills.store.ts
import { create } from 'zustand'
import type { Pill, PillCategory } from '../data/pills.types'

type ActiveView = 'grid' | 'kanban' | 'graph' | 'feed'

interface PillsStore {
  activeView: ActiveView
  setActiveView: (v: ActiveView) => void
  searchQuery: string
  setSearchQuery: (q: string) => void
  selectedCategories: PillCategory[]
  toggleCategory: (c: PillCategory) => void
  selectedPillId: string | null
  openDrawer: (id: string) => void
  closeDrawer: () => void
}

export const usePills = create<PillsStore>((set) => ({
  activeView: 'grid',
  setActiveView: (v) => set({ activeView: v }),
  searchQuery: '',
  setSearchQuery: (q) => set({ searchQuery: q }),
  selectedCategories: [],
  toggleCategory: (c) => set((s) => ({
    selectedCategories: s.selectedCategories.includes(c)
      ? s.selectedCategories.filter(x => x !== c)
      : [...s.selectedCategories, c]
  })),
  selectedPillId: null,
  openDrawer: (id) => set({ selectedPillId: id }),
  closeDrawer: () => set({ selectedPillId: null }),
}))
```

- [ ] Criar pills.store.ts com Zustand completo
- [ ] Criar utils.ts com cn helper, debounce util, filter logic

---

## Chunk 3: Componentes Base (shadcn/ui)

**Rodar em paralelo com Tasks 3-4**

### Task 5: UI Components

**Files:**
- Create: `src/shared/components/ui/badge.tsx`
- Create: `src/shared/components/ui/button.tsx`
- Create: `src/shared/components/ui/card.tsx`
- Create: `src/shared/components/ui/drawer.tsx`
- Create: `src/shared/components/ui/tabs.tsx`
- Create: `src/shared/components/ui/input.tsx`
- Create: `src/shared/components/ui/toggle.tsx`

- [ ] Criar badge.tsx (variant: default, outline, colorido por categoria)
- [ ] Criar button.tsx (variant: default, ghost, link)
- [ ] Criar card.tsx (Card, CardHeader, CardTitle, CardContent)
- [ ] Criar drawer.tsx (wrapper de Radix Dialog como drawer)
- [ ] Criar tabs.tsx (Tabs root, TabsList, TabTrigger, TabContent)
- [ ] Criar input.tsx (input com focus ring, dark mode)
- [ ] Criar toggle.tsx (toggle button para views e categorias)

### Task 6: Common Components

**Files:**
- Create: `src/shared/components/common/CategoryBadge.tsx`
- Create: `src/shared/components/common/DifficultyBadge.tsx`
- Create: `src/shared/components/common/TypeIcon.tsx`

```ts
// Category mapping:
// claude-code-tools → purple, awesome-lists → green, official → blue, media → orange
// difficulty: iniciante=green, intermediário=yellow, avançado=red
// typeIcon: GitHub=Octocat, YouTube=Play, Twitter=Bird, website=Globe
```

- [ ] Criar CategoryBadge com cores por categoria
- [ ] Criar DifficultyBadge com cores por dificuldade
- [ ] Criar TypeIcon com ícones Lucide por tipo

---

## Chunk 4: Features — Splash + Header + Pill Components

**Pode rodar em PARALELO por sub-agente:**
- Sub-agente A: Intro (SplashScreen)
- Sub-agente B: Filters (SearchBar, CategoryFilter, ViewToggle)
- Sub-agente C: Pill components (PillCard, PillCardCompact, PillDrawer)
- Sub-agente D: Views (GridView, KanbanView, FeedView, GraphView)

### Task 7: SplashScreen

**Files:**
- Create: `src/features/intro/SplashScreen.tsx`

- [ ] Criar SplashScreen com Framer Motion (logo scale + partículas de pills, 2.5s auto-dismiss ou ESC/click skip)
- [ ] Usar sessionStorage para não repetir na sessão

### Task 8: Filtros

**Files:**
- Create: `src/features/filters/SearchBar.tsx`
- Create: `src/features/filters/CategoryFilter.tsx`
- Create: `src/features/filters/ViewToggle.tsx`

- [ ] Criar SearchBar com debounce 200ms
- [ ] Criar CategoryFilter com multi-seleção toggle
- [ ] Criar ViewToggle com 4 ícones (grid, kanban, graph, list)

### Task 9: Pill Components

**Files:**
- Create: `src/features/pills/components/PillCard.tsx`
- Create: `src/features/pills/components/PillCardCompact.tsx`
- Create: `src/features/pills/components/PillNode.tsx`
- Create: `src/features/pills/components/PillDrawer.tsx`

- [ ] Criar PillCard com gradiente por cor, hover animation, click → openDrawer
- [ ] Criar PillCardCompact (1 linha: nome + headline)
- [ ] Criar PillNode (wrapper para react-force-graph com tooltip)
- [ ] Criar PillDrawer (sheet lateral com header, 3 tabs, footer)

### Task 10: Views

**Files:**
- Create: `src/features/pills/views/GridView.tsx`
- Create: `src/features/pills/views/KanbanView.tsx`
- Create: `src/features/pills/views/GraphView.tsx`
- Create: `src/features/pills/views/FeedView.tsx`
- Create: `src/features/pills/PillsPage.tsx`

- [ ] Criar GridView (responsive grid 4/3/2/1 colunas de PillCards)
- [ ] Criar KanbanView (4 colunas fixas por categoria com scroll)
- [ ] Criar GraphView (react-force-graph-2d com nodes por categoria)
- [ ] Criar FeedView (lista densa vertical com search highlight)
- [ ] Criar PillsPage.tsx (compor header + filters + active view + drawer)

---

## Chunk 5: Remotion

### Task 11: Remotion Setup

**Files:**
- Create: `remotion/package.json`
- Create: `remotion/Root.tsx`
- Create: `remotion/PillOfTheDay.tsx`
- Create: `remotion/render.ts`

- [ ] Criar remotion/package.json com @remotion/cli @remotion/bundler @remotion/player
- [ ] Criar PillOfTheDay.tsx (1080x1920, 30fps, 15s, timeline de animação)
- [ ] Criar Root.tsx com composition registration
- [ ] Criar render.ts (script para gerar MP4 via CLI)
- [ ] Criar script `npm run export-pills` no package.json raiz
- [ ] Testar: `cd remotion && npm install && npm run build -- --pill hermes-agent`

### Task 12: Vídeos na Home

**Files:**
- Create: `public/videos/.gitkeep`

---

## Chunk 6: Theme + Deep Link + App Composition

### Task 13: Theme Toggle + Deep Link

**Files:**
- Create: `src/shared/lib/theme.ts`
- Modify: `src/features/pills/PillsPage.tsx` (deep link integration)

```ts
// theme.ts
export function initTheme() {
  const saved = localStorage.getItem('git-pills-theme')
  const isDark = saved ? saved === 'dark' : true
  document.documentElement.classList.toggle('dark', isDark)
  return isDark
}
export function toggleTheme(): boolean {
  const isDark = document.documentElement.classList.toggle('dark')
  localStorage.setItem('git-pills-theme', isDark ? 'dark' : 'light')
  return isDark
}
```

- [ ] Criar theme.ts com init + toggle + localStorage
- [ ] Integrar deep link ?pill=<id> em PillsPage via useSearchParams

### Task 14: App.tsx Final

**Files:**
- Modify: `src/App.tsx`

- [ ] Compôr SplashScreen + PillsPage em App.tsx com lógica de splash flag

---

## Chunk 7: Build + Deploy + Docs

### Task 15: Build

- [ ] `npm run build` → verificar sem erros
- [ ] Corrigir quaisquer erros de TypeScript
- [ ] Verificar bundle size (não deve exceder 500KB gzipped)

### Task 16: Deploy

**Files:**
- Create: `project-infra.json`

- [ ] Verificar portas livres: `netstat -tlnp`
- [ ] Criar domínios via EasyPanel: gitpills + docs-gitpills
- [ ] Registrar em project-infra.json
- [ ] Iniciar frontend: `pm2 start npx --name "gitpills-frontend" -- vite preview --port 4100 --host 0.0.0.0`
- [ ] Iniciar docs: `pm2 start npx --name "docs-gitpills" -- serve docs/ -l 4101 --no-clipboard`
- [ ] Verificar acesso

### Task 17: Docs Portal

**Files:**
- Create: `docs/tasks/task-001-setup.md`
- Create: `docs/tasks/task-002-data-layer.md`
- Create: `docs/tasks/task-003-ui-components.md`
- Create: `docs/tasks/task-004-views.md`
- Create: `docs/tasks/task-005-remotion.md`
- Create: `docs/tasks/task-006-deploy.md`
- Create: `docs/guides/guia-uso.html`
- Create: `docs/index.html`
- Create: `docs/styles.css`

- [ ] Criar task files para cada chunk
- [ ] Criar portal de docs com index.html
- [ ] Criar guia de uso HTML

### Task 18: Browser Validation + Git

- [ ] Abrir https://gitpills.ddw1sl.easypanel.host e validar todos os 17 critérios de teste
- [ ] `git add . && git commit -m "feat: implementa Git Pills dashboard completo" && git push`

---

## Parallel Execution Strategy

```
BATCH 1 (paralelo total):
  Agent 1: Task 1 (projeto base)
  Agent 2: Task 3-4 (dados + store + utils)
  Agent 3: Task 5-6 (UI components + common components)

BATCH 2 (paralelo total):
  Agent 4: Task 7 (SplashScreen)
  Agent 5: Task 8 (Filters)
  Agent 6: Task 9 (Pill components)
  Agent 7: Task 10 (Views + PillsPage)

BATCH 3 (sequencial):
  Agent 8: Task 11-12 (Remotion)
  Agent 9: Task 13-14 (Theme + App composition)

BATCH 4 (sequencial):
  Task 15-18 (Build, Deploy, Docs, Tests)
```