flyee 0.1.0

package/core/workflows/tdd.md

@@ -0,0 +1,344 @@
+---
+description: Workflow completo de SDD (Software Design Document). Cria, valida e transforma SDD em tarefas executáveis. O termo TDD neste workflow refere-se à metodologia Test-Driven Development (RED-GREEN-REFACTOR), não ao documento.
+skills: context-gathering-patterns, document-registry
+---
+
+# /tdd - Software Design Document Workflow
+
+> **Nota de nomenclatura:** O comando `/tdd` gera **SDD (Software Design Document)** — documentos de design técnico salvos como `SDD-*.md`.
+> As referências a "TDD" neste workflow referem-se exclusivamente à **metodologia** Test-Driven Development (Phase 5 — RED-GREEN-REFACTOR).
+
+$ARGUMENTS
+
+---
+
+## 🔴 WORKFLOW OVERVIEW
+
+O fluxo TDD segue o padrão **RPI (Research, Plan, Implement)** com validação humana obrigatória.
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│   DISCOVERY  │───▶│   VALIDATE   │───▶│   APPROVE    │───▶│  IMPLEMENT   │
+│  (IA + Human)│    │ (IA Review)  │    │   (Human)    │    │  (IA Code)   │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+```
+
+---
+
+## 🧩 SUBCOMMANDS
+
+| Comando | Ação |
+|---------|------|
+| `/tdd new [nome]` | Cria novo SDD a partir do template |
+| `/tdd validate [arquivo]` | Valida completude do SDD |
+| `/tdd breakdown [arquivo]` | Transforma SDD em tarefas |
+| `/tdd status` | Mostra status dos SDDs do projeto |
+
+---
+
+## Phase 1: DISCOVERY (`/tdd new`)
+
+### Trigger
+```
+/tdd new [nome-da-feature]
+```
+
+### Ações
+1. **Verificar PRD existente** - Buscar `docs/PRD-*.md` relacionado
+2. **Copiar template** de `.agent/templates/sdd-template.md`
+3. **Criar arquivo** em `docs/design/SDD-{nome-da-feature}.md`
+4. **Preencher campo obrigatório:**
+   ```markdown
+   PRD Fonte: docs/PRD-{nome}.md
+   ```
+5. **Iniciar brainstorming** usando skill `brainstorming`
+6. **Registry:** `document-registry` — criar entry `SDD-{nome}` no INDEX.md com status `draft`
+
+### Agentes Envolvidos
+- `project-planner` - Estruturação inicial
+- `product-owner` - Definição de MVP
+
+### Socratic Gate (OBRIGATÓRIO)
+Antes de preencher o SDD, perguntar:
+
+1. 🎯 **Qual problema estamos resolvendo?** (referência: PRD seção 2.1)
+2. 👥 **Quem são os usuários afetados?** (referência: PRD seção 3)
+3. 📦 **O que é MVP vs. nice-to-have?** (referência: PRD seção 6.1)
+4. ⚠️ **Quais os riscos conhecidos?** (referência: PRD seção 8)
+5. 🔗 **Quais integrações externas são necessárias?**
+
+> [!TIP]
+> Se o PRD já foi aprovado, use-o como base para responder as perguntas.
+
+### Output Esperado
+```
+[OK] SDD criado: docs/design/SDD-{nome}.md
+[OK] PRD Fonte: docs/PRD-{nome}.md
+[OK] Status: Rascunho
+[OK] INDEX.md entry criada: SDD-{nome} (draft)
+[NEXT] Execute /tdd validate docs/design/SDD-{nome}.md
+```
+
+---
+
+## Phase 2: VALIDATE (`/tdd validate`)
+
+### Trigger
+```
+/tdd validate docs/design/SDD-{nome}.md
+```
+
+### Ações
+1. **Ler TDD** completo
+2. **Verificar completude** usando skill `tdd-validation`
+3. **Reportar gaps** e itens INDEFINIDOS
+
+### Agente Envolvido
+- `tdd-reviewer` - Análise de completude
+
+### Validações Realizadas
+
+| Categoria | Verificação |
+|-----------|-------------|
+| **Estrutura** | Todas as seções obrigatórias existem? |
+| **MVP** | Há itens DEFINIDO suficientes para MVP? |
+| **Bloqueadores** | Há itens INDEFINIDO que bloqueiam? |
+| **Arquitetura** | SDD alinha com ARCHITECTURE.md? |
+| **Riscos** | Riscos identificados têm mitigação? |
+| **Ambientes** ⭐ | Environment Strategy definida (dev/staging/prod)? |
+
+### Output Esperado
+```markdown
+## TDD Validation Report
+
+### ✅ Seções Completas
+- [x] Contexto e Motivação
+- [x] Glossário
+- [x] Fluxo Técnico
+
+### ⚠️ Itens Indefinidos
+- [ ] Tratamento de Erros (Fase 3)
+- [ ] Estratégia de Retry
+
+### ❌ Seções Faltando
+- [ ] Webhooks não documentados
+
+### 📊 Score: 75% Completo
+
+### 🔴 BLOQUEADORES
+1. Definir estratégia de retry antes de implementar
+
+### Recomendação
+Resolver bloqueadores antes de aprovar.
+```
+
+---
+
+## Phase 3: APPROVE (Humano)
+
+### Trigger
+Após validação, o **humano** deve:
+
+1. **Revisar** o relatório de validação
+2. **Resolver** itens INDEFINIDOS (ou movê-los para futuro)
+3. **Aprovar** marcando o checkbox no TDD:
+   ```markdown
+   - [x] **Aprovado para Implementação**
+   ```
+
+### 🔴 REGRA DE OURO
+> A IA **NÃO** pode prosseguir para implementação sem aprovação humana explícita.
+
+---
+
+## Phase 4: BREAKDOWN (`/tdd breakdown`)
+
+### Trigger
+```
+/tdd breakdown docs/design/SDD-{nome}.md
+```
+
+### Pré-condição
+- SDD deve estar marcado como `Aprovado`
+- Nenhum item INDEFINIDO bloqueando MVP
+
+### Ações
+1. **Ler SDD aprovado**
+2. **Extrair tarefas** da seção "Detalhamento da Solução"
+3. **Criar plan file** `{feature-name}.md` no root
+4. **Criar tasks no Tracker** usando obrigatoriamente `bridge.py --create-task` e popular body (User Story, ACs)
+5. **Atribuir agentes** a cada tarefa
+6. **Registry:** `document-registry` — atualizar status de `SDD-{nome}` no INDEX.md para `approved`
+
+### Agente Envolvido
+- `project-planner` - Quebra em tarefas
+
+### Output Esperado
+```markdown
+## Task Breakdown: {Feature Name}
+
+**Source of Truth:** docs/design/SDD-{nome}.md
+**Status:** Ready for Implementation
+
+### Tasks
+
+- [ ] **Task 1: Setup Credenciais** → `devops-engineer`
+  - Ref: SDD Fase 1
+  - Verify: `.env.example` atualizado
+
+- [ ] **Task 2: Criar Entidade** → `backend-specialist`
+  - Ref: SDD Fase 2
+  - Verify: Endpoint POST funcionando
+
+[PARALLELIZABLE]
+- [ ] **Task 3: Frontend Form** → `frontend-specialist`
+- [ ] **Task 4: Testes Unitários** → `test-engineer`
+```
+
+#### 🔔 FLYEE BRIDGE: Decision Hook (Condicional)
+
+> Se `flyee.json` existe E `enabled: true` — registrar decisões do SDD:
+
+```bash
+# Registrar decisão arquitetural do SDD aprovado:
+python3 .agent/flyee-bridge/bridge.py --create-decision \
+  --decision "SDD {nome} aprovado: {resumo da arquitetura}" \
+  --category architecture \
+  --reason "Aprovação do SDD na Phase 3 do /tdd" \
+  --impact "Implementação da feature {nome} — {N} tasks criadas"
+```
+
+> Se bridge não configurado → Pular silenciosamente.
+
+---
+
+## Phase 5: TDD METODOLOGIA (Testes Primeiro)
+
+> [!IMPORTANT]
+> **Antes de implementar código, escrever testes.**
+> Skill de referência: `tdd-workflow`
+
+### Trigger
+Após breakdown aprovado e antes do `/create`:
+```
+/test [task]
+```
+
+### Ciclo RED-GREEN-REFACTOR
+
+| Fase | Ação | Verificação |
+|------|------|-------------|
+| 🔴 RED | Escrever teste que falha | Teste falha corretamente |
+| 🟢 GREEN | Implementar código mínimo | Teste passa |
+| 🔵 REFACTOR | Melhorar código | Testes continuam passando |
+
+### Para CADA Task do Breakdown:
+1. **Escrever testes** baseados nos critérios de aceite do TDD
+2. **Implementar** código mínimo para passar
+3. **Refatorar** mantendo testes verdes
+4. **Verificar cobertura** >= 80%
+
+---
+
+## Phase 6: IMPLEMENT
+
+### Trigger
+Após testes escritos (Phase 5 concluída):
+```
+/create
+```
+ou
+```
+/orchestrate
+```
+
+### Regras de Implementação
+
+> [!CAUTION]
+> **GATE OBRIGATÓRIO POR TASK:** Seguir skill `context-gathering-patterns` → seção "PROCESSO DE CONTEXT GATHERING"
+> ANTES de implementar cada task. Ler SDD + docs de fluxo + persistir checklist de evidência.
+
+1. **Context Gathering** (skill `context-gathering-patterns`) — obrigatório a cada nova task
+2. **Rodar testes** antes de cada commit
+3. **Não inventar** features não documentadas no SDD
+4. **Seguir** exatamente o que está DEFINIDO
+5. **Ignorar** o que está FORA DE ESCOPO
+
+### Verificação de Cobertura (GATE)
+
+> [!CAUTION]
+> **Cobertura mínima:** 80% antes de considerar task completa.
+
+```bash
+/test coverage
+```
+
+Se cobertura < 80%:
+1. Identificar áreas não cobertas
+2. Adicionar testes faltantes
+3. Repetir verificação
+
+---
+
+## 📁 Estrutura de Arquivos
+
+```
+projeto/
+├── docs/
+│   ├── INDEX.md                          # Document Registry
+│   └── design/
+│       ├── SDD-payment-integration.md
+│       └── SDD-user-authentication.md
+├── payment-integration.md             # Plan file (após breakdown)
+└── user-authentication.md             # Plan file (após breakdown)
+```
+
+---
+
+## 🔄 Status Lifecycle
+
+```
+[Rascunho] → [Em Revisão] → [Aprovado] → [Em Implementação] → [Concluído]
+```
+
+| Status | Significado |
+|--------|-------------|
+| Rascunho | Sendo escrito, não validado |
+| Em Revisão | Validação em andamento |
+| Aprovado | Pronto para implementação |
+| Em Implementação | Tasks sendo executadas |
+| Concluído | Todas as tasks finalizadas |
+
+---
+
+## 🔴 REGRAS CRÍTICAS
+
+1. **SDD é Imutável após aprovação** - Não modificar sem nova revisão
+2. **Humano aprova, IA executa** - Nunca auto-aprovar
+3. **INDEFINIDO = BLOQUEADOR** - Resolver antes de implementar
+4. **Uma feature = Um SDD** - Não misturar features
+5. **Environment Strategy obrigatória** - SDD sem separação de ambientes (dev/prod) = BLOQUEADOR ⭐
+
+> [!CAUTION]
+> **FALHA QUE GEROU REGRA 5:** SDD aprovado sem seção de Environment Strategy.
+> Resultado: 10 sprints com `.env.local` apontando para Supabase produção.
+> SDD DEVE conter `## Environment Strategy` com: ambientes, serviços por ambiente,
+> arquivos `.env` mapeados, e credenciais separadas por ambiente.
+
+---
+
+## Usage Examples
+
+```bash
+# Criar novo SDD para integração de pagamentos
+/tdd new payment-integration
+
+# Validar o SDD criado
+/tdd validate docs/design/SDD-payment-integration.md
+
+# Após aprovação humana, quebrar em tarefas
+/tdd breakdown docs/design/SDD-payment-integration.md
+
+# Ver status de todos os SDDs
+/tdd status
+```

package/core/workflows/test.md

@@ -0,0 +1,251 @@
+---
+description: Test generation and test running command. Creates and executes tests for code.
+---
+
+# /test - Test Generation and Execution
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command generates tests, runs existing tests, or checks test coverage.
+
+**Agentes Envolvidos:**
+- `test-engineer` - Geração e execução de testes
+- `backend-specialist` / `frontend-specialist` / `mobile-developer` - Para testes específicos de domínio
+- `debugger` - Para análise de testes falhando
+
+---
+
+## Sub-commands
+
+```
+/test                - Run all tests
+/test [file/feature] - Generate tests for specific target
+/test coverage       - Show test coverage report
+/test watch          - Run tests in watch mode
+```
+
+---
+
+## Behavior
+
+### Generate Tests
+
+When asked to test a file or feature:
+
+1. **Analyze the code**
+   - Identify functions and methods
+   - Find edge cases
+   - Detect dependencies to mock
+
+2. **Generate test cases**
+   - Happy path tests
+   - Error cases
+   - Edge cases
+   - Integration tests (if needed)
+
+3. **Write tests**
+   - Use project's test framework (Jest, Vitest, etc.)
+   - Follow existing test patterns
+   - Mock external dependencies
+
+---
+
+## Output Format
+
+### For Test Generation
+
+```markdown
+## 🧪 Tests: [Target]
+
+### Test Plan
+| Test Case | Type | Coverage |
+|-----------|------|----------|
+| Should create user | Unit | Happy path |
+| Should reject invalid email | Unit | Validation |
+| Should handle db error | Unit | Error case |
+
+### Generated Tests
+
+`tests/[file].test.ts`
+
+[Code block with tests]
+
+---
+
+Run with: `npm test`
+```
+
+### For Test Execution
+
+```
+🧪 Running tests...
+
+✅ auth.test.ts (5 passed)
+✅ user.test.ts (8 passed)
+❌ order.test.ts (2 passed, 1 failed)
+
+Failed:
+  ✗ should calculate total with discount
+    Expected: 90
+    Received: 100
+
+Total: 15 tests (14 passed, 1 failed)
+```
+
+### 🔔 FLYEE BRIDGE EMIT (Condicional)
+
+> Se `flyee.json` existe E `enabled: true`:
+
+```bash
+python .agent/flyee-bridge/bridge.py emit "dev.test_run" '{"passed": {N_passed}, "failed": {N_failed}, "skipped": {N_skipped}, "total": {N_total}, "target": "{file_or_feature}"}'
+```
+
+> Se bridge não configurado → Pular silenciosamente.
+
+---
+
+## Examples
+
+```
+/test src/services/auth.service.ts
+/test user registration flow
+/test coverage
+/test fix failed tests
+```
+
+---
+
+## Test Patterns
+
+### Unit Test Structure
+
+```typescript
+describe('AuthService', () => {
+  describe('login', () => {
+    it('should return token for valid credentials', async () => {
+      // Arrange
+      const credentials = { email: 'test@test.com', password: 'pass123' };
+      
+      // Act
+      const result = await authService.login(credentials);
+      
+      // Assert
+      expect(result.token).toBeDefined();
+    });
+
+    it('should throw for invalid password', async () => {
+      // Arrange
+      const credentials = { email: 'test@test.com', password: 'wrong' };
+      
+      // Act & Assert
+      await expect(authService.login(credentials)).rejects.toThrow('Invalid credentials');
+    });
+  });
+});
+```
+
+---
+
+## Key Principles
+
+- **Test behavior not implementation**
+- **One assertion per test** (when practical)
+- **Descriptive test names**
+- **Arrange-Act-Assert pattern**
+- **Mock external dependencies**
+
+---
+
+## ⏸️ Tratamento de Testes Skipped
+
+> [!CAUTION]
+> **Testes skipped NÃO são sucesso.** Eles representam cobertura incompleta e devem ser tratados.
+
+### Quando há testes skipped, SEMPRE:
+
+1. **Listar todos os testes skipped** com motivo
+2. **Analisar cada um** e categorizar a ação necessária
+3. **Perguntar ao usuário** qual ação tomar
+
+### Output Format para Skipped Tests
+
+```markdown
+✅ [N] testes passaram
+⏸️ [M] testes skipped:
+
+| Teste Skipped | Motivo | Ação Sugerida |
+|---------------|--------|---------------|
+| [nome do teste] | [motivo do skip] | [o que fazer] |
+
+📋 **Ação Necessária:**
+
+❓ Deseja que eu:
+1. **Implemente** os [M] testes skipped agora?
+2. **Documente** como TODO na task do Flyee?
+3. **Ignore** (aceitar coverage atual com justificativa)?
+```
+
+### Classificação de Skipped Tests
+
+| Tipo de Skip | Ação Recomendada |
+|--------------|------------------|
+| **Mock faltando** | Implementar mock e habilitar teste |
+| **API externa indisponível** | Criar fake/stub e habilitar teste |
+| **Edge case não mapeado** | Definir cenário com usuário |
+| **Formato de resposta desconhecido** | Investigar API e implementar |
+| **Dependência de ambiente** | Criar environment mock |
+| **Temporariamente desabilitado** | Definir prazo para reabilitar |
+
+### Regras para Skipped
+
+> [!IMPORTANT]
+> 1. **NUNCA ignorar silenciosamente** testes skipped
+> 2. **SEMPRE perguntar** ao usuário qual ação tomar
+> 3. **Se há mais de 10% de skips**, alertar como problema de cobertura
+> 4. **Documentar motivo** do skip no código e na task
+
+---
+
+## 🔗 Flyee Integration
+
+> [!IMPORTANT]
+> Após executar testes, **SEMPRE** perguntar sobre atualização do Flyee.
+
+### Se executado dentro de `/execute`:
+
+A atualização do Flyee é automática via Fase 6 do workflow `/execute`.
+
+### Se executado standalone (`/test` direto):
+
+Após testes passarem, perguntar:
+```
+✅ Testes passaram: 15/15
+
+📋 Atualizar task no Tracker?
+Se estes testes são parte de uma task existente, informe o ID para atualizar:
+
+> /task-update <id> progress "Implementar testes E2E"
+```
+
+### Mapeamento de Progresso
+
+| Resultado | Sugestão |
+|-----------|----------|
+| Todos passaram (0 skipped) | `/task-update <id> progress "msg"` (+15%) |
+| Todos passaram (com skipped) | **Tratar skips primeiro** ou documentar como TODO |
+| Alguns falharam | Corrigir primeiro, não atualizar Tracker |
+| Cobertura atingida | `/task-update <id> done "msg"` (100%) |
+
+---
+
+## ⚠️ REGRAS
+
+1. **Nunca atualizar Tracker se testes falharem**
+2. **Nunca ignorar testes skipped** - sempre perguntar ação ao usuário
+3. **Sempre sugerir /task-update após sucesso** (se há task relacionada)
+4. **Documentar testes skipped** como TODOs na task com prazo
+5. **Se >10% skipped**, alertar como problema de cobertura