flyee 0.1.0

package/core/skills/clean-code/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
+allowed-tools: Read, Write, Edit
+version: 2.0
+priority: CRITICAL
+---
+
+# Clean Code - Pragmatic AI Coding Standards
+
+> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+
+---
+
+## Core Principles
+
+| Principle | Rule |
+|-----------|------|
+| **SRP** | Single Responsibility - each function/class does ONE thing |
+| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
+| **KISS** | Keep It Simple - simplest solution that works |
+| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
+| **Boy Scout** | Leave code cleaner than you found it |
+
+---
+
+## Naming Rules
+
+| Element | Convention |
+|---------|------------|
+| **Variables** | Reveal intent: `userCount` not `n` |
+| **Functions** | Verb + noun: `getUserById()` not `user()` |
+| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
+| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Rule:** If you need a comment to explain a name, rename it.
+
+---
+
+## Function Rules
+
+| Rule | Description |
+|------|-------------|
+| **Small** | Max 20 lines, ideally 5-10 |
+| **One Thing** | Does one thing, does it well |
+| **One Level** | One level of abstraction per function |
+| **Few Args** | Max 3 arguments, prefer 0-2 |
+| **No Side Effects** | Don't mutate inputs unexpectedly |
+
+---
+
+## Code Structure
+
+| Pattern | Apply |
+|---------|-------|
+| **Guard Clauses** | Early returns for edge cases |
+| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
+| **Composition** | Small functions composed together |
+| **Colocation** | Keep related code close |
+
+---
+
+## AI Coding Style
+
+| Situation | Action |
+|-----------|--------|
+| User asks for feature | Write it directly |
+| User reports bug | Fix it, don't explain |
+| No clear requirement | Ask, don't assume |
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Pattern | ✅ Fix |
+|-----------|-------|
+| Comment every line | Delete obvious comments |
+| Helper for one-liner | Inline the code |
+| Factory for 2 objects | Direct instantiation |
+| utils.ts with 1 function | Put code where used |
+| "First we import..." | Just write code |
+| Deep nesting | Guard clauses |
+| Magic numbers | Named constants |
+| God functions | Split by responsibility |
+
+---
+
+## 🔴 Before Editing ANY File (THINK FIRST!)
+
+**Before changing a file, ask yourself:**
+
+| Question | Why |
+|----------|-----|
+| **What imports this file?** | They might break |
+| **What does this file import?** | Interface changes |
+| **What tests cover this?** | Tests might fail |
+| **Is this a shared component?** | Multiple places affected |
+
+**Quick Check:**
+```
+File to edit: UserService.ts
+└── Who imports this? → UserController.ts, AuthController.ts
+└── Do they need changes too? → Check function signatures
+```
+
+> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
+> 🔴 **Never leave broken imports or missing updates.**
+
+---
+
+## Summary
+
+| Do | Don't |
+|----|-------|
+| Write code directly | Write tutorials |
+| Let code self-document | Add obvious comments |
+| Fix bugs immediately | Explain the fix first |
+| Inline small things | Create unnecessary files |
+| Name things clearly | Use abbreviations |
+| Keep functions small | Write 100+ line functions |
+
+> **Remember: The user wants working code, not a programming lesson.**
+
+---
+
+## 🔴 Self-Check Before Completing (MANDATORY)
+
+**Before saying "task complete", verify:**
+
+| Check | Question |
+|-------|----------|
+| ✅ **Goal met?** | Did I do exactly what user asked? |
+| ✅ **Files edited?** | Did I modify all necessary files? |
+| ✅ **Code works?** | Did I test/verify the change? |
+| ✅ **No errors?** | Lint and TypeScript pass? |
+| ✅ **Nothing forgotten?** | Any edge cases missed? |
+
+> 🔴 **Rule:** If ANY check fails, fix it before completing.
+
+---
+
+## Verification Scripts (MANDATORY)
+
+> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
+
+### Agent → Script Mapping
+
+| Agent | Script | Command |
+|-------|--------|---------|
+| **frontend-specialist** | UX Audit | `python .agent/skills/frontend-design/scripts/ux_audit.py .` |
+| **frontend-specialist** | A11y Check | `python .agent/skills/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist** | API Validator | `python .agent/skills/api-patterns/scripts/api_validator.py .` |
+| **mobile-developer** | Mobile Audit | `python .agent/skills/mobile-design/scripts/mobile_audit.py .` |
+| **database-architect** | Schema Validate | `python .agent/skills/database-design/scripts/schema_validator.py .` |
+| **security-auditor** | Security Scan | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py .` |
+| **seo-specialist** | SEO Check | `python .agent/skills/seo-fundamentals/scripts/seo_checker.py .` |
+| **seo-specialist** | GEO Check | `python .agent/skills/geo-fundamentals/scripts/geo_checker.py .` |
+| **performance-optimizer** | Lighthouse | `python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python .agent/skills/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Any agent** | Lint Check | `python .agent/skills/lint-and-validate/scripts/lint_runner.py .` |
+| **Any agent** | Type Coverage | `python .agent/skills/lint-and-validate/scripts/type_coverage.py .` |
+| **Any agent** | i18n Check | `python .agent/skills/i18n-localization/scripts/i18n_checker.py .` |
+
+> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
+> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
+
+---
+
+### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
+
+**When running a validation script, you MUST:**
+
+1. **Run the script** and capture ALL output
+2. **Parse the output** - identify errors, warnings, and passes
+3. **Summarize to user** in this format:
+
+```markdown
+## Script Results: [script_name.py]
+
+### ❌ Errors Found (X items)
+- [File:Line] Error description 1
+- [File:Line] Error description 2
+
+### ⚠️ Warnings (Y items)
+- [File:Line] Warning description
+
+### ✅ Passed (Z items)
+- Check 1 passed
+- Check 2 passed
+
+**Should I fix the X errors?**
+```
+
+4. **Wait for user confirmation** before fixing
+5. **After fixing** → Re-run script to confirm
+
+> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
+> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
+> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
+

package/core/skills/code-review-checklist/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: code-review-checklist
+description: Code review guidelines covering code quality, security, and best practices.
+allowed-tools: Read, Glob, Grep
+---
+
+# Code Review Checklist
+
+## Quick Review Checklist
+
+### Correctness
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error handling in place
+- [ ] No obvious bugs
+
+### Security
+- [ ] Input validated and sanitized
+- [ ] No SQL/NoSQL injection vulnerabilities
+- [ ] No XSS or CSRF vulnerabilities
+- [ ] No hardcoded secrets or sensitive credentials
+- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
+- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No unnecessary loops
+- [ ] Appropriate caching
+- [ ] Bundle size impact considered
+
+### Code Quality
+- [ ] Clear naming
+- [ ] DRY - no duplicate code
+- [ ] SOLID principles followed
+- [ ] Appropriate abstraction level
+
+### Testing
+- [ ] Unit tests for new code
+- [ ] Edge cases tested
+- [ ] Tests readable and maintainable
+
+### Documentation
+- [ ] Complex logic commented
+- [ ] Public APIs documented
+- [ ] README updated if needed
+
+## AI & LLM Review Patterns (2025)
+
+### Logic & Hallucinations
+- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
+- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
+- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
+
+### Prompt Engineering Review
+```markdown
+// ❌ Vague prompt in code
+const response = await ai.generate(userInput);
+
+// ✅ Structured & Safe prompt
+const response = await ai.generate({
+  system: "You are a specialized parser...",
+  input: sanitize(userInput),
+  schema: ResponseSchema
+});
+```
+
+## Anti-Patterns to Flag
+
+```typescript
+// ❌ Magic numbers
+if (status === 3) { ... }
+
+// ✅ Named constants
+if (status === Status.ACTIVE) { ... }
+
+// ❌ Deep nesting
+if (a) { if (b) { if (c) { ... } } }
+
+// ✅ Early returns
+if (!a) return;
+if (!b) return;
+if (!c) return;
+// do work
+
+// ❌ Long functions (100+ lines)
+// ✅ Small, focused functions
+
+// ❌ any type
+const data: any = ...
+
+// ✅ Proper types
+const data: UserData = ...
+```
+
+## Review Comments Guide
+
+```
+// Blocking issues use 🔴
+🔴 BLOCKING: SQL injection vulnerability here
+
+// Important suggestions use 🟡
+🟡 SUGGESTION: Consider using useMemo for performance
+
+// Minor nits use 🟢
+🟢 NIT: Prefer const over let for immutable variable
+
+// Questions use ❓
+❓ QUESTION: What happens if user is null here?
+```

package/core/skills/code-truth-validation/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: code-truth-validation
+description: Validação obrigatória de documentação contra código real. Previne inconsistências doc-vs-code em integrações, gateways, enums e arquivos referenciados.
+---
+
+# Code-Truth Validation
+
+> **Toda afirmação técnica em documentação DEVE ser verificada contra o código real.**
+
+---
+
+## 🎯 PROPÓSITO
+
+Garantir que documentação gerada (flow docs, TDD, handover) reflita o estado **real** do código — não o estado planejado, assumido, ou desatualizado.
+
+---
+
+## 🔴 REGRAS OBRIGATÓRIAS
+
+> [!CAUTION]
+> **ANTES de salvar qualquer doc técnico**, o agente DEVE executar a validação abaixo.
+> Documentação sem verificação contra código real gera inconsistências graves.
+
+### 1. Checklist de Validação por Tipo
+
+#### Integrações / Gateways / APIs externas
+
+- [ ] Arquivo/classe mencionado **existe** no codebase (`find_by_name` / `grep_search`)
+- [ ] Está **registrado** no enum/config correspondente
+- [ ] Se doc diz "ativo/implementado" → confirmar que código NÃO é stub/mock/placeholder
+- [ ] Se doc diz "será implementado" / "planejado" → marcar com `⏳ PLANEJADO` visível
+
+#### Componentes / Arquivos referenciados
+
+- [ ] CADA arquivo referenciado existe no path indicado
+- [ ] Funções/métodos citados existem na assinatura real
+
+#### Enums / Constantes / Configs
+
+- [ ] Valores referenciados confirmados contra o fonte real
+
+---
+
+### 2. Separação Estado Atual vs Estado Planejado
+
+**Se divergência detectada** — NÃO documentar o estado planejado como se fosse atual. Separar:
+
+```markdown
+## Estado Atual (verificado no código)
+
+[O que realmente existe — com referências a arquivos]
+
+## Estado Planejado / Decisão de Projeto
+
+> ⏳ **Ainda não implementado no código**
+> [O que deveria existir — com justificativa e referência à decisão]
+```
+
+- Registrar divergência como débito técnico na seção de débitos do doc
+
+---
+
+### 3. Cross-Scope Doc-vs-Code (para escopos anteriores)
+
+> [!WARNING]
+> Documentação de escopos anteriores pode conter **afirmações desatualizadas**
+> (ex: flow doc do `shop/` dizendo "gateway = Pagar.me" quando o código tem `Cielo.php`).
+
+Para cada **integração ou componente cross-scope** identificado:
+
+1. Verificar se o arquivo/classe referenciado **existe** no codebase do novo escopo
+2. Se doc anterior diz "ativo" → confirmar no código (não é stub?)
+3. Se doc anterior diz "planejado" → verificar se foi implementado
+4. Registrar divergências:
+
+```markdown
+### ⚠️ Divergências Doc → Código
+
+| Doc Fonte | Afirmação | Realidade no Código | Ação |
+|-----------|-----------|---------------------|------|
+| {arquivo.md} | {o que o doc diz} | {o que o código tem} | Corrigir doc / Registrar débito |
+```
+
+---
+
+### 4. Doc Impact Check (Pós-Implementação)
+
+> [!CAUTION]
+> **GATE POR TASK:** Após implementar e testar cada task que modifica código,
+> verificar se os arquivos modificados são referenciados em documentação existente.
+
+**Ações:**
+
+1. Listar os arquivos modificados pela task
+2. Buscar referências em `docs/flows/` e `docs/design/TDD-*.md`:
+   ```bash
+   grep -rl "{nome_do_arquivo}" docs/flows/ docs/design/ 2>/dev/null
+   ```
+3. Se **referências encontradas** → Abrir e verificar se descrição corresponde ao estado real
+4. Se **divergência** → Atualizar doc seguindo regras da seção 2
+5. Registrar:
+
+```markdown
+📄 DOC IMPACT — Task #{id}
+- Arquivos modificados: {lista}
+- Docs afetados: {lista ou "Nenhum"}
+- Docs atualizados: {lista ou "N/A"}
+```
+
+---
+
+### 5. Doc Freshness Gate (Pré-Publicação)
+
+> [!CAUTION]
+> **GATE BLOQUEANTE:** Antes de publicar documentação (Flyee ou entrega),
+> re-validar TODOS os docs gerados contra o código atual.
+> Fases de implementação podem ter alterado comportamento documentado.
+
+```markdown
+⚠️ DOC FRESHNESS GATE
+
+[ ] Re-executar CODE-TRUTH VALIDATION em CADA doc de `docs/flows/`
+[ ] Re-executar CODE-TRUTH VALIDATION em `docs/design/TDD-*.md`
+[ ] Divergências encontradas? → Docs atualizados com estado real
+[ ] Divergências registradas no arquivo de progresso
+[ ] Se nenhuma divergência → Registrar: "✅ Docs validados"
+
+❌ Se QUALQUER item desmarcado → NÃO publicar
+✅ TODOS marcados → Prosseguir
+```
+
+---
+
+#### Historical Lesson — Code-Truth Validation
+
+> 🔴 **FALHA (shop/ gateway):** Flow doc documentou "gateway = Pagar.me" quando o código
+> implementava `Cielo.php`. Divergência descoberta apenas na fase cross-scope seguinte.
+> **Causa raiz:** Agente documentou sem verificar enum `PaymentGatewayType.php`.
+
+---
+
+## 🔗 WORKFLOWS QUE USAM ESTA SKILL
+
+| Workflow | Quando usar |
+|----------|-------------|
+| `/legacy-project` | Phase 4 (flow docs), Phase 2.5 (cross-scope), Gate 7B→8 (freshness) |
+| `/document` | Antes de salvar qualquer flow doc |
+| `/new-task` | Quando modificando código documentado |
+| `/new-project` | Phase 5 (implementação com docs) |

package/core/skills/component-library-discovery/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: component-library-discovery
+description: Descoberta de componentes UI de bibliotecas externas (badtz-ui, uselayouts, lucide-animated). Tabelas por contexto + perguntas interativas.
+---
+
+# Component Library Discovery
+
+Skill para descobrir e selecionar componentes de bibliotecas UI externas compatíveis com shadcn/React projects.
+
+## 📚 Bibliotecas Suportadas
+
+| Biblioteca | Foco | Instalação |
+|------------|------|------------|
+| **badtz-ui** | Landing Pages, conversão | `npx shadcn@latest add https://badtz-ui.com/r/<comp>.json` |
+| **uselayouts** | Micro-interações, animações | `npx shadcn@latest add https://uselayouts.com/r/<comp>` |
+| **lucide-animated** | Ícones animados (350+) | Copy-paste |
+
+---
+
+## 🎯 PASSO 1: Tabela por Contexto
+
+### Landing Pages (badtz-ui)
+
+| Seção | Componente | Comando |
+|-------|------------|---------|
+| Hero | `hero-section` | `npx shadcn@latest add https://badtz-ui.com/r/hero-section.json` |
+| CTA Button | `glowing-button` | `npx shadcn@latest add https://badtz-ui.com/r/glowing-button.json` |
+| Pricing | `pricing-card` | `npx shadcn@latest add https://badtz-ui.com/r/pricing-card.json` |
+| Testimonials | `testimonial-card` | `npx shadcn@latest add https://badtz-ui.com/r/testimonial-card.json` |
+| Features | `feature-card` | `npx shadcn@latest add https://badtz-ui.com/r/feature-card.json` |
+| FAQ | `accordion-faq` | `npx shadcn@latest add https://badtz-ui.com/r/accordion-faq.json` |
+| Footer | `footer-section` | `npx shadcn@latest add https://badtz-ui.com/r/footer-section.json` |
+| Logo Cloud | `logo-cloud` | `npx shadcn@latest add https://badtz-ui.com/r/logo-cloud.json` |
+| Stats | `stats-section` | `npx shadcn@latest add https://badtz-ui.com/r/stats-section.json` |
+
+### Micro-interações (uselayouts)
+
+| Efeito | Componente | Comando |
+|--------|------------|---------|
+| Card 3D | `3d-book` | `npx shadcn@latest add https://uselayouts.com/r/3d-book` |
+| Card Flip | `flip-card` | `npx shadcn@latest add https://uselayouts.com/r/flip-card` |
+| Magnetic Button | `magnetic-button` | `npx shadcn@latest add https://uselayouts.com/r/magnetic-button` |
+| Stagger List | `stagger-list` | `npx shadcn@latest add https://uselayouts.com/r/stagger-list` |
+| Text Reveal | `text-reveal` | `npx shadcn@latest add https://uselayouts.com/r/text-reveal` |
+| Blur Fade | `blur-fade` | `npx shadcn@latest add https://uselayouts.com/r/blur-fade` |
+
+### Ícones Animados (lucide-animated)
+
+| Contexto | Ícones Recomendados |
+|----------|---------------------|
+| **Loading** | `loader-pinwheel`, `refresh-cw`, `hourglass`, `loader` |
+| **Success** | `check`, `check-check`, `circle-check`, `badge-check` |
+| **Error** | `x`, `circle-x`, `ban`, `alert-triangle` |
+| **Notifications** | `bell`, `mail-check`, `message-circle`, `inbox` |
+| **User Actions** | `heart`, `bookmark`, `star`, `thumbs-up` |
+| **Navigation** | `arrow-right`, `chevron-down`, `menu`, `search` |
+| **Media** | `play`, `pause`, `volume`, `mic` |
+| **Settings** | `settings`, `cog`, `sliders-horizontal` |
+
+**Como usar lucide-animated:**
+1. Acesse https://lucide-animated.com/
+2. Pesquise o ícone desejado
+3. Clique no ícone para ver código
+4. Copie e cole no seu componente
+
+---
+
+## 🤔 PASSO 2: Perguntas Interativas
+
+**Se o usuário não souber qual componente usar, fazer estas perguntas:**
+
+```markdown
+## 🔍 Descoberta de Componente
+
+Para recomendar o melhor componente, preciso saber:
+
+1. **Qual é o contexto?**
+   - [ ] Landing Page (hero, pricing, testimonials)
+   - [ ] Dashboard (cards, charts, stats)
+   - [ ] Formulários (inputs, selects, validation)
+   - [ ] Navegação (menu, sidebar, tabs)
+   - [ ] Feedback (loading, success, error)
+   - [ ] Outro: _________
+
+2. **Precisa de animação?**
+   - [ ] Sim, animação suave (micro-interações)
+   - [ ] Sim, atenção especial (destaque)
+   - [ ] Não, estático está ok
+
+3. **É um ícone ou componente completo?**
+   - [ ] Ícone
+   - [ ] Componente/Seção
+```
+
+**Após respostas, retornar:**
+
+```markdown
+## 💡 Recomendação
+
+Para **[contexto]** com **[animação]**, recomendo:
+
+| Opção | Biblioteca | Componente | Motivo |
+|-------|------------|------------|--------|
+| A | [lib] | [comp] | [porque] |
+| B | [lib] | [comp] | [alternativa] |
+
+**Comando para instalar opção A:**
+\`\`\`bash
+npx shadcn@latest add [url]
+\`\`\`
+```
+
+---
+
+## 🔗 PASSO 3: Catálogos Completos
+
+Se as tabelas acima não tiverem o que o usuário precisa:
+
+> **📚 Catálogos Completos:**
+> - [badtz-ui.com/docs](https://badtz-ui.com/docs) - Todos os componentes para LPs
+> - [uselayouts.com/docs](https://uselayouts.com/docs/introduction) - Todas as micro-interações
+> - [lucide-animated.com](https://lucide-animated.com) - Todos os 350+ ícones animados
+
+---
+
+## 🔄 Uso em Workflows
+
+Esta skill pode ser invocada em:
+
+| Workflow | Quando |
+|----------|--------|
+| `/new-project` | Phase 5.3 (UI Styling) - PASSO 4.6 |
+| `/new-task` | Quando adicionar componentes UI |
+| `/legacy-project` | Ao modernizar UI existente |
+| `/ui-ux-pro-max` | Após gerar Design System |
+
+**Invocação:**
+```markdown
+> [!TIP]
+> **Skill:** `component-library-discovery`
+> Consultar para encontrar componentes premium de bibliotecas externas.
+```
+
+---
+
+## ⚠️ Pré-requisitos
+
+1. **shadcn/ui inicializado** - As bibliotecas usam o registry do shadcn
+2. **Tailwind CSS** - Todas dependem de Tailwind
+3. **React 18+** - Compatibilidade com hooks modernos
+4. **Framer Motion** (para uselayouts) - Instalar se usar micro-interações:
+   ```bash
+   npm install framer-motion
+   ```