flyee 0.1.0

package/core/skills/tdd-validation/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: tdd-validation
+description: Validação de Technical Design Documents. Verifica completude, identifica gaps e cruza com arquitetura do projeto.
+allowed-tools: Read, Glob, Grep
+---
+
+# TDD Validation Skill
+
+> Valida Technical Design Documents antes da implementação.
+
+---
+
+## 1. Overview
+
+Este skill permite validar TDDs (Technical Design Documents) para garantir que estão completos e prontos para implementação.
+
+### Quando Usar
+- Antes de aprovar um TDD para implementação
+- Quando o `/tdd validate` é executado
+- Como parte do pipeline de revisão
+
+---
+
+## 2. Validation Categories
+
+### 2.1 Estrutura (Seções Obrigatórias)
+
+| Seção | Obrigatória? | Peso |
+|-------|--------------|------|
+| Informações Gerais | ✅ Sim | 5% |
+| Contexto e Motivação | ✅ Sim | 10% |
+| Glossário | ✅ Sim | 10% |
+| Recursos e APIs Externas | 🟡 Se aplicável | 10% |
+| Fluxo Técnico - MVP | ✅ Sim | 20% |
+| Detalhamento da Solução | ✅ Sim | 20% |
+| **Environment Strategy** | ✅ Sim ⭐ | 5% |
+| Riscos e Mitigação | ✅ Sim | 10% |
+| Roadmap | ✅ Sim | 5% |
+| Checklist de Validação | ✅ Sim | 5% |
+
+### 2.2 Conteúdo (Qualidade)
+
+| Verificação | Critério |
+|-------------|----------|
+| **MVP Definido** | Pelo menos 1 item marcado como `✅ DEFINIDO` |
+| **Sem Bloqueadores** | Nenhum `⚠️ INDEFINIDO` em tasks críticas |
+| **Fluxo Documentado** | Diagrama mermaid presente |
+| **APIs Mapeadas** | Endpoints listados se houver integração |
+| **Riscos Mitigados** | Cada risco tem ação de mitigação |
+| **Ambientes Separados** ⭐ | Seção `Environment Strategy` define dev vs prod |
+
+### 2.3 Alinhamento Arquitetural
+
+| Verificação | Fonte |
+|-------------|-------|
+| **Stack Compatível** | Cruza com `CODEBASE.md` ou `package.json` |
+| **Padrões Seguidos** | Cruza com `ARCHITECTURE.md` |
+| **Dependências Válidas** | Bibliotecas existem e são compatíveis |
+
+---
+
+## 3. Validation Algorithm
+
+```
+FUNCTION validate_tdd(file_path):
+    tdd = READ(file_path)
+    score = 0
+    issues = []
+    
+    # 1. Check structure
+    FOR section IN required_sections:
+        IF section NOT IN tdd:
+            issues.append(MISSING: section)
+        ELSE:
+            score += section.weight
+    
+    # 2. Check MVP items
+    defined_items = COUNT(tdd, status="DEFINIDO")
+    undefined_items = COUNT(tdd, status="INDEFINIDO")
+    
+    IF defined_items == 0:
+        issues.append(BLOCKER: "No MVP items defined")
+    
+    IF undefined_items > 0:
+        FOR item IN undefined_items:
+            IF item.is_critical:
+                issues.append(BLOCKER: item)
+            ELSE:
+                issues.append(WARNING: item)
+    
+    # 3. Check architecture alignment
+    IF EXISTS("ARCHITECTURE.md"):
+        arch = READ("ARCHITECTURE.md")
+        mismatches = COMPARE(tdd.tech_stack, arch.tech_stack)
+        issues.extend(mismatches)
+    
+    # 4. Calculate readiness
+    readiness = score / max_score * 100
+    IF any(issues.type == BLOCKER):
+        status = "NOT_READY"
+    ELIF readiness >= 80:
+        status = "READY"
+    ELSE:
+        status = "NEEDS_WORK"
+    
+    RETURN ValidationReport(score, issues, status)
+```
+
+---
+
+## 4. Output Format
+
+### Validation Report Structure
+
+```markdown
+# TDD Validation Report
+
+**File:** docs/design/TDD-{name}.md
+**Date:** YYYY-MM-DD
+**Status:** [READY | NEEDS_WORK | NOT_READY]
+**Score:** XX%
+
+---
+
+## ✅ Passed Checks
+
+- [x] Contexto e Motivação presente
+- [x] Glossário definido
+- [x] MVP com 5 itens DEFINIDO
+
+---
+
+## ⚠️ Warnings
+
+- [ ] Tratamento de Erros marcado como INDEFINIDO
+- [ ] Roadmap sem datas específicas
+
+---
+
+## ❌ Blockers
+
+- [ ] Seção "Riscos e Mitigação" ausente
+- [ ] Nenhum diagrama de fluxo
+
+---
+
+## 📊 Summary
+
+| Categoria | Status |
+|-----------|--------|
+| Estrutura | 80% |
+| Conteúdo | 70% |
+| Arquitetura | 100% |
+| **Total** | **83%** |
+
+---
+
+## 🎯 Recommendations
+
+1. **P0:** Adicionar seção de Riscos
+2. **P1:** Criar diagrama mermaid do fluxo
+3. **P2:** Definir datas no Roadmap
+```
+
+---
+
+## 5. Status Definitions
+
+| Status | Significado | Ação |
+|--------|-------------|------|
+| `READY` | TDD completo e pronto | Pode aprovar |
+| `NEEDS_WORK` | Pequenos ajustes necessários | Corrigir warnings |
+| `NOT_READY` | Bloqueadores críticos | Resolver antes de prosseguir |
+
+---
+
+## 6. Integration Points
+
+### Com Outros Skills
+| Skill | Integração |
+|-------|------------|
+| `brainstorming` | Validação invoca se TDD incompleto |
+| `plan-writing` | Recebe TDD validado para breakdown |
+| `architecture` | Cruza TDD com padrões do projeto |
+
+### Com Agentes
+| Agente | Papel |
+|--------|-------|
+| `tdd-reviewer` | Executa validação |
+| `project-planner` | Recebe resultado para planning |
+
+---
+
+## 7. Best Practices
+
+### Para Quem Escreve TDD
+1. **Preencha todas as seções** - Não deixe placeholders
+2. **Seja explícito sobre MVP** - Marque status de cada item
+3. **Documente riscos** - Mesmo os óbvios
+4. **Use diagramas** - Mermaid para fluxos
+
+### Para Validação
+1. **Não auto-aprovar** - Sempre revisão humana
+2. **Bloqueador = Stop** - Não prosseguir com blockers
+3. **Warnings são importantes** - Resolver antes de implementar
+4. **Re-validar após mudanças** - TDD é vivo até aprovação
+
+---
+
+## 8. Checklist Rápido
+
+```markdown
+## Quick Validation Checklist
+
+### Estrutura
+- [ ] Título e metadados preenchidos
+- [ ] Contexto explica o "porquê"
+- [ ] Glossário define termos de domínio
+- [ ] Fluxo técnico com diagrama
+- [ ] Tarefas com status (DEFINIDO/INDEFINIDO)
+- [ ] Riscos com mitigações
+- [ ] Roadmap com datas
+
+### MVP
+- [ ] Pelo menos 3 itens DEFINIDO
+- [ ] Nenhum INDEFINIDO crítico
+- [ ] Fora de escopo marcado
+
+### Qualidade
+- [ ] Revisado por Tech Lead
+- [ ] Revisado por PM
+- [ ] Alinhado com arquitetura
+
+### Environment Strategy ⭐
+- [ ] Ambientes listados (dev/staging/prod)
+- [ ] Serviços externos mapeados por ambiente
+- [ ] Arquivos `.env` documentados
+- [ ] `.env.local` ≠ produção
+```
+
+---
+
+> **Lembre-se:** Um TDD bem validado economiza horas de retrabalho na implementação.

package/core/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: tdd-workflow
+description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# TDD Workflow
+
+> Write tests first, code second.
+
+---
+
+## 1. The TDD Cycle
+
+```
+🔴 RED → Write failing test
+    ↓
+🟢 GREEN → Write minimal code to pass
+    ↓
+🔵 REFACTOR → Improve code quality
+    ↓
+   Repeat...
+```
+
+---
+
+## 2. The Three Laws of TDD
+
+1. Write production code only to make a failing test pass
+2. Write only enough test to demonstrate failure
+3. Write only enough code to make the test pass
+
+---
+
+## 3. RED Phase Principles
+
+### What to Write
+
+| Focus | Example |
+|-------|---------|
+| Behavior | "should add two numbers" |
+| Edge cases | "should handle empty input" |
+| Error states | "should throw for invalid data" |
+
+### RED Phase Rules
+
+- Test must fail first
+- Test name describes expected behavior
+- One assertion per test (ideally)
+
+---
+
+## 4. GREEN Phase Principles
+
+### Minimum Code
+
+| Principle | Meaning |
+|-----------|---------|
+| **YAGNI** | You Aren't Gonna Need It |
+| **Simplest thing** | Write the minimum to pass |
+| **No optimization** | Just make it work |
+
+### GREEN Phase Rules
+
+- Don't write unneeded code
+- Don't optimize yet
+- Pass the test, nothing more
+
+### UI Components in GREEN Phase
+
+> For components with UI, use Design System during GREEN phase:
+
+| Step | Action |
+|------|--------|
+| 1 | Load `design-system/{project}/MASTER.md` |
+| 2 | Use CSS variables (e.g., `var(--bg-card)`) |
+| 3 | Follow skill `design-system-enforcement` |
+| 4 | No hardcoded colors or values |
+| 5 | Use Lucide/Heroicons, not emojis |
+
+---
+
+
+## 5. REFACTOR Phase Principles
+
+### What to Improve
+
+| Area | Action |
+|------|--------|
+| Duplication | Extract common code |
+| Naming | Make intent clear |
+| Structure | Improve organization |
+| Complexity | Simplify logic |
+
+### REFACTOR Rules
+
+- All tests must stay green
+- Small incremental changes
+- Commit after each refactor
+
+---
+
+## 6. AAA Pattern
+
+Every test follows:
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify expected outcome |
+
+---
+
+## 7. When to Use TDD
+
+| Scenario | TDD Value |
+|----------|-----------|
+| New feature | High |
+| Bug fix | High (write test first) |
+| Complex logic | High |
+| Exploratory | Low (spike, then TDD) |
+| UI layout | Low |
+
+---
+
+## 8. Test Prioritization
+
+| Priority | Test Type |
+|----------|-----------|
+| 1 | Happy path |
+| 2 | Error cases |
+| 3 | Edge cases |
+| 4 | Performance |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Skip the RED phase | Watch test fail first |
+| Write tests after | Write tests before |
+| Over-engineer initial | Keep it simple |
+| Multiple asserts | One behavior per test |
+| Test implementation | Test behavior |
+
+---
+
+## 10. AI-Augmented TDD
+
+### Multi-Agent Pattern
+
+| Agent | Role |
+|-------|------|
+| Agent A | Write failing tests (RED) |
+| Agent B | Implement to pass (GREEN) |
+| Agent C | Optimize (REFACTOR) |
+
+---
+
+> **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.
+
+---
+
+## 11. Anti-Mock Validation
+
+> [!CAUTION]
+> Tests that validate mock data in production pages/routes are INVALID.
+> A test passing with `const mockProject = {...}` hardcoded in the page does NOT guarantee the page works with real database data.
+
+**Rules for valid tests:**
+
+| Test Type | MUST Validate | NOT Valid |
+|-----------|--------------|-----------|
+| **Page (server component)** | DB query returns data → renders | Manually passed mock props |
+| **API route** | Request → INSERT/UPDATE in DB → real Response | `return NextResponse.json(mockData)` |
+| **Client component** | onClick → calls function → side effect | `onSubmit={() => {}}` as handler |
+| **Form** | Submit → API call → user feedback | Form renders but doesn't submit |
+
+**Anti-Mock checklist (before GREEN):**
+
+```markdown
+⚠️ ANTI-MOCK CHECK — Task: {title}
+
+[ ] Page/route queries REAL database (not hardcoded)?
+[ ] API route persists data (INSERT/UPDATE), not returning mock?
+[ ] Click/submit handlers execute REAL action, not noop?
+[ ] Test validates END-TO-END behavior, not just rendering?
+
+❌ Mock detected in production → Rewrite with real data
+✅ All OK → Valid GREEN
+```
+
+**Grep patterns to detect mock violations:**
+
+```bash
+# Run in src/ (pages, routes, components):
+grep -rn "mockData\|mock_data\|const mock\|// TODO\|// MVP:" src/
+grep -rn "() => {}\|onSubmit={() =>" src/
+grep -rn "hardcoded\|placeholder" src/
+```
+
+> **Historical Lesson:** Project created 140+ tests in ~2h. ALL passed because they tested mock props rendering,
+> not real integration. Result: 7 pages marked as "implemented" were completely non-functional with real data.
+
+---
+
+## 12. E2E Core Loop Smoke Test
+
+> [!CAUTION]
+> Verification is NOT just test coverage. The agent MUST verify that the product's **CORE LOOP
+> works end-to-end** with REAL data, not just that unit tests pass.
+
+**What is the Core Loop?**
+
+Consult PRD section "Core Flow" or "Main Journey" to identify the product's main flow:
+```
+[Action 1] → [Action 2] → [Action 3] → [Final Result]
+```
+
+**Mandatory verification for each Core Loop step:**
+
+```markdown
+⚠️ E2E CORE LOOP SMOKE TEST — {project name}
+
+Core Loop from PRD: {describe flow}
+
+| # | Step | Page/Route | Mock? | DB Query? | Functional? |
+|---|------|-----------|-------|-----------|-------------|
+| 1 | {action 1} | {file} | [ ] | [ ] | [ ] |
+| 2 | {action 2} | {file} | [ ] | [ ] | [ ] |
+| 3 | {action 3} | {file} | [ ] | [ ] | [ ] |
+
+For EACH step:
+[ ] No mock data in production?
+[ ] Real DB queries (supabase.from() / prisma)?
+[ ] Handlers connected to real actions (not noop)?
+[ ] Previous step → current step flow works?
+
+❌ ANY step fails → FIX before deploy
+✅ Core Loop 100% functional → Ready for deploy
+```
+
+> [!TIP]
+> Run the smoke test in the browser (dev server) when possible, not only via unit tests.
+> This catches issues that isolated component tests miss.
+
+> **Historical Lesson:** Project had 140+ passing tests and >80% coverage, but core loop
+> (create project → create decision → portal → approve) was 100% broken because no test
+> verified real integration.
+
+**Decision table:**
+
+| Verification | Action |
+|-------------|--------|
+| Coverage >= 80% | ✅ Proceed |
+| Coverage < 80% | ❌ Add missing tests |
+| **E2E Smoke Test FAILED** | ❌ **FIX — main flow is broken** |
+
+---
+
+## 13. Pós-TDD: Sync com Flyee (OBRIGATÓRIO)
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** Após GREEN passar, ANTES de notificar usuário, DEVE:
+> 1. Atualizar task no Flyee (Status → "Concluído", Tempo Gasto, % Progresso → 100)
+> 2. Adicionar nota de conclusão no corpo da task
+> 3. Seguir skill `Flyee API` seção "Gate de Sync Flyee" (linhas 167-263)
+
+### Checklist Pós-GREEN
+
+| Ação | API |
+|------|-----|
+| Status → Concluído | `Flyee API: update_task()` |
+| Preencher Tempo Gasto | `Flyee API: update_task()` |
+| Nota de Conclusão | `Flyee API: update_task() (output)` |
+
+> [!WARNING]
+> **📜 HISTÓRICO DE FALHA (2026-02-08):**
+> - **Gap detectado:** Agente completou TDD para Task #1 mas não syncou com Flyee
+> - **Causa raiz:** Esta skill não referenciava `Flyee API`
+> - **Correção aplicada:** Adicionada seção 11 com regra bloqueante
+

package/core/skills/testing-patterns/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: testing-patterns
+description: Testing patterns and principles. Unit, integration, mocking strategies.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Testing Patterns
+
+> Principles for reliable test suites.
+
+---
+
+## 1. Testing Pyramid
+
+```
+        /\          E2E (Few)
+       /  \         Critical flows
+      /----\
+     /      \       Integration (Some)
+    /--------\      API, DB queries
+   /          \
+  /------------\    Unit (Many)
+                    Functions, classes
+```
+
+---
+
+## 2. AAA Pattern
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify outcome |
+
+---
+
+## 3. Test Type Selection
+
+### When to Use Each
+
+| Type | Best For | Speed |
+|------|----------|-------|
+| **Unit** | Pure functions, logic | Fast (<50ms) |
+| **Integration** | API, DB, services | Medium |
+| **E2E** | Critical user flows | Slow |
+
+---
+
+## 4. Unit Test Principles
+
+### Good Unit Tests
+
+| Principle | Meaning |
+|-----------|---------|
+| Fast | < 100ms each |
+| Isolated | No external deps |
+| Repeatable | Same result always |
+| Self-checking | No manual verification |
+| Timely | Written with code |
+
+### What to Unit Test
+
+| Test | Don't Test |
+|------|------------|
+| Business logic | Framework code |
+| Edge cases | Third-party libs |
+| Error handling | Simple getters |
+
+---
+
+## 5. Integration Test Principles
+
+### What to Test
+
+| Area | Focus |
+|------|-------|
+| API endpoints | Request/response |
+| Database | Queries, transactions |
+| External services | Contracts |
+
+### Setup/Teardown
+
+| Phase | Action |
+|-------|--------|
+| Before All | Connect resources |
+| Before Each | Reset state |
+| After Each | Clean up |
+| After All | Disconnect |
+
+---
+
+## 6. Mocking Principles
+
+### When to Mock
+
+| Mock | Don't Mock |
+|------|------------|
+| External APIs | The code under test |
+| Database (unit) | Simple dependencies |
+| Time/random | Pure functions |
+| Network | In-memory stores |
+
+### Mock Types
+
+| Type | Use |
+|------|-----|
+| Stub | Return fixed values |
+| Spy | Track calls |
+| Mock | Set expectations |
+| Fake | Simplified implementation |
+
+---
+
+## 7. Test Organization
+
+### Naming
+
+| Pattern | Example |
+|---------|---------|
+| Should behavior | "should return error when..." |
+| When condition | "when user not found..." |
+| Given-when-then | "given X, when Y, then Z" |
+
+### Grouping
+
+| Level | Use |
+|-------|-----|
+| describe | Group related tests |
+| it/test | Individual case |
+| beforeEach | Common setup |
+
+---
+
+## 8. Test Data
+
+### Strategies
+
+| Approach | Use |
+|----------|-----|
+| Factories | Generate test data |
+| Fixtures | Predefined datasets |
+| Builders | Fluent object creation |
+
+### Principles
+
+- Use realistic data
+- Randomize non-essential values (faker)
+- Share common fixtures
+- Keep data minimal
+
+---
+
+## 9. Best Practices
+
+| Practice | Why |
+|----------|-----|
+| One assert per test | Clear failure reason |
+| Independent tests | No order dependency |
+| Fast tests | Run frequently |
+| Descriptive names | Self-documenting |
+| Clean up | Avoid side effects |
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Test implementation | Test behavior |
+| Duplicate test code | Use factories |
+| Complex test setup | Simplify or split |
+| Ignore flaky tests | Fix root cause |
+| Skip cleanup | Reset state |
+| Test only existence | Test interaction too |
+
+---
+
+## 11. UI Interaction Testing
+
+> [!IMPORTANT]
+> Para testes de componentes interativos (botões, forms), consultar skill `integration-completeness`.
+
+Testes de existência são insuficientes:
+
+| ❌ Incompleto | ✅ Completo |
+|---------------|-------------|
+| "button exists" | "clicking button calls handler" |
+| "form renders" | "submitting form sends data" |
+
+**Skill relacionada:** `integration-completeness`
+
+---
+
+> **Remember:** Tests are documentation. If someone can't understand what the code does from the tests, rewrite them.
+