flyee 0.1.0

package/core/skills/project-tracking-patterns/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: project-tracking-patterns
+description: Regras de atualização de progresso durante workflows. Atualização de PROJECT-PROGRESS.md, histórico, e Flyee sincronizado.
+---
+
+# Project Tracking Patterns
+
+> **Single Source of Truth** para rastrear progresso durante workflows longos.
+
+---
+
+## 🎯 PROPÓSITO
+
+Garantir que durante execução de workflows:
+1. **Arquivo de progresso** seja atualizado a cada fase
+2. **Histórico** seja registrado a cada ação
+3. **Flyee** seja sincronizado após cada task
+4. **Tasks individuais** sejam listadas e rastreadas
+
+---
+
+## 🔴 REGRAS OBRIGATÓRIAS
+
+> [!CAUTION]
+> **TODAS as regras abaixo são BLOQUEANTES.**
+> O workflow NÃO pode prosseguir sem cumpri-las.
+
+### 1. Atualização Após Cada Fase
+
+**Quando:** Ao completar qualquer fase de um workflow
+
+**Onde:** Arquivo de progresso (`PROJECT-PROGRESS.md`, `LEGACY-PROGRESS.md`, etc.)
+
+**O que atualizar:**
+- [ ] `Fase Atual` → Próxima fase
+- [ ] Status da fase concluída → `✅ Concluído`
+- [ ] Artefato gerado (se houver)
+- [ ] `Última atualização` → Data/hora atual
+
+```markdown
+## Exemplo de atualização:
+
+| Fase | Status | Artefato |
+|------|--------|----------|
+| 2. TDD Técnico | ✅ Aprovado | `docs/design/TDD-{nome}.md` |  ← ATUALIZADO
+| 3. Breakdown | 🟡 Em Progresso | - |  ← NOVA FASE ATUAL
+```
+
+---
+
+### 2. Registro no Histórico
+
+**Quando:** Após QUALQUER ação significativa
+
+**Formato:**
+```markdown
+| Data | Fase | Ação |
+|------|------|------|
+| 2026-02-02 12:30 | 3 | Breakdown iniciado |
+| 2026-02-02 12:35 | 3 | 10 tasks criadas no Flyee |
+| 2026-02-02 12:40 | 3 | Breakdown concluído |
+```
+
+**Ações que DEVEM ser registradas:**
+- Início de fase
+- Conclusão de fase
+- Criação de artefatos
+- Criação de tasks no Flyee
+- Aprovações humanas
+- Erros ou bloqueios
+
+---
+
+### 3. Atualização de Tasks Após Cada Item
+
+**Quando:** Ao trabalhar em Phase 4 (Testes) ou Phase 5 (Implementação)
+
+**Onde:** Seção `📝 Tasks` no arquivo de progresso
+
+**Template:**
+```markdown
+## 📝 Tasks (Phase 4-5)
+
+| # | Task | Teste | Código | Status |
+|---|------|-------|--------|--------|
+| 1 | Setup inicial | ✅ | ✅ | ✅ Completo |
+| 2 | Auth básica | ✅ | 🟡 | 🟡 Em Progresso |  ← ATUALIZAR AQUI
+| 3 | CRUD usuários | ⏳ | ⏳ | ⏳ Pendente |
+```
+
+---
+
+### 4. Sincronização de Tarefas (OBRIGATÓRIO) 🔴
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** As tarefas (Flyee ou Local) DEVEM ser atualizadas após cada épico/fase conforme a configuração de `Tracker de Tasks`.
+> NÃO prosseguir para próximo épico sem sincronizar o respectivo tracker.
+
+**Quando sincronizar:**
+| Momento | Ação |
+|---------|------|
+| 🔴 **ANTES de escrever código** | **CRIAR TASK no Flyee (`bridge.py --create-task`)** |
+| Ao iniciar implementação | Atualizar status → "Em Progresso" (`bridge.py --update-task`) |
+| Ao finalizar a implentação | Excutar workflow genérico `/task-complete` |
+
+> [!CAUTION]
+> É estritamente proibido iniciar a codificação (Phase 5 do `/new-project` ou Phase 3 do `/new-task`) sem antes gerar um Task ID no Tracker. 
+
+**Como sincronizar (Único caminho autorizado):**
+
+**1. Via Bridge CLI (Criação e Atualização):**
+```bash
+# 1. CRIAR TASK (Obrigatório antes de codar)
+python3 .agent/flyee-bridge/bridge.py --create-task \
+  --name "Título descritivo" \
+  --type implement_feature \
+  --description "Breve descrição" \
+  --priority normal
+
+# 2. STATUS EM PROGRESSO
+python3 .agent/flyee-bridge/bridge.py --update-task <task_id> --status running
+```
+
+> [!TIP]
+> Bridge CLI auto-detects if `flyee.json` exists. If project is not connected to Flyee, it skips silently.
+
+**2. Via Workflow (Conclusão - OBRIGATÓRIO):**
+```markdown
+# 3. FECHAMENTO DE TASK
+Para concluir uma tarefa, invoque obrigatoriamente o workflow genérico:
+`/task-complete`
+(Ele cuidará do logging de execução, cobertura e fechamento no Flyee)
+```
+
+---
+
+### 5. Gate de Sincronização por Épico 🔴
+
+> [!CAUTION]
+> **BLOQUEADOR:** Antes de iniciar próximo épico, verificar o **Modo de Tracking** do projeto:
+
+#### Se Tracker = Flyee:
+```markdown
+## Checklist de Sincronização - Épico {N}
+
+- [ ] Todas as tasks do épico atualizadas no Flyee
+- [ ] Status correto (Concluído/Em Progresso)
+- [ ] % Progresso atualizado
+- [ ] Comentário de conclusão adicionado
+
+> **SE NÃO SINCRONIZADO:** PARAR e sincronizar antes de prosseguir.
+```
+
+#### Se Tracker = Local (`docs/TASKS.md`):
+```markdown
+## Checklist de Sincronização - Épico {N}
+
+- [ ] Todas as tasks do épico marcadas com `[x]` no arquivo `docs/TASKS.md`
+
+> **SE NÃO SINCRONIZADO:** PARAR e atualizar arquivo antes de prosseguir.
+```
+
+**Mensagem obrigatória ao completar épico:**
+```markdown
+📊 **Épico {N} Concluído - Tracker Sync**
+
+| Task ID | Status | % |
+|---------|--------|---|
+| {id} | ✅ | 100% |
+| {id} | ✅ | 100% |
+
+✅ Flyee sincronizado. Prosseguindo para Épico {N+1}.
+```
+
+---
+
+### 6. Logging de Execução por Task 🔴
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** Ao completar verificação/execução de CADA task individual,
+> você DEVE exibir o log de execução ANTES de prosseguir para a próxima task.
+
+**Quando:** Após completar verificação ou execução de qualquer task
+
+**Template OBRIGATÓRIO:**
+```markdown
+### ✅ Task {ID}: {Nome}
+
+**Verificação:**
+- ✅ {arquivo/componente verificado}
+- ✅ {critério de aceitação atendido}
+- ✅ {teste passando, se aplicável}
+
+**Arquivos Relevantes:**
+- `{caminho/arquivo1.ts}`
+- `{caminho/arquivo2.tsx}`
+
+**Ação Flyee:**
+- Status: Não iniciado → Concluído
+- Última edição: {timestamp automático}
+
+**Tempo aproximado:** {X}min
+```
+
+**Exemplo Preenchido:**
+```markdown
+### ✅ Task 1.1: Setup Next.js 15 + App Router
+
+**Verificação:**
+- ✅ `package.json` contém `next@15.1.7`
+- ✅ `src/app/layout.tsx` existe com App Router
+- ✅ `npm run build` passa sem erros
+
+**Arquivos Relevantes:**
+- `package.json`
+- `src/app/layout.tsx`
+- `next.config.ts`
+
+**Ação Flyee:**
+- Status: Não iniciado → Concluído
+- Última edição: 2026-02-03T14:15:00
+
+**Tempo aproximado:** 2min
+```
+
+**Regras:**
+1. **NUNCA** pular este log - mesmo para tasks simples
+2. **SEMPRE** listar arquivos verificados/criados
+3. **SEMPRE** incluir critérios de aceitação verificados
+4. **ATUALIZAR** Flyee ANTES de prosseguir para próxima task
+
+---
+
+### 7. TASK SYNC — Template de Conclusão (Flyee) 🔴
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** O ÚNICO caminho autorizado para concluir uma task no Flyee é
+> o workflow `/task-complete`. Chamadas avulsas a `API-patch-page` SEM as etapas
+> completas são **PROIBIDAS** — são a causa raiz das falhas v1-v4.
+
+**Template canônico de nota de conclusão (Flyee API — `API-patch-block-children`):**
+
+```json
+{
+  "block_id": "{page_id}",
+  "children": [
+    { "type": "divider", "divider": {} },
+    {
+      "type": "callout",
+      "callout": {
+        "icon": { "type": "emoji", "emoji": "✅" },
+        "rich_text": [
+          { "type": "text", "text": { "content": "Concluído em {data}" } }
+        ]
+      }
+    },
+    {
+      "type": "bulleted_list_item",
+      "bulleted_list_item": {
+        "rich_text": [
+          { "type": "text", "text": { "content": "📋 {resumo da implementação}" } }
+        ]
+      }
+    },
+    {
+      "type": "bulleted_list_item",
+      "bulleted_list_item": {
+        "rich_text": [
+          { "type": "text", "text": { "content": "🧪 Testes: {resultado}" } }
+        ]
+      }
+    },
+    {
+      "type": "bulleted_list_item",
+      "bulleted_list_item": {
+        "rich_text": [
+          { "type": "text", "text": { "content": "📁 Arquivos: {lista de arquivos modificados}" } }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**Etapas obrigatórias do `/task-complete` (em ordem):**
+
+1. Log de Execução exibido
+2. Resumo de Execução (O que foi feito, Arquivos, Verificação, Decisões)
+3. `API-patch-page` — Status → Concluído + % Progresso → 100 + Tempo Gasto
+4. `API-patch-block-children` — Nota inline ✅ (template acima)
+5. `API-create-a-comment` — Comentário rico de conclusão
+6. Arquivo de progresso atualizado (LEGACY-PROGRESS.md / PROJECT-PROGRESS.md)
+7. Histórico de ações atualizado
+8. Mensagem de confirmação exibida
+
+> [!CAUTION]
+> 🚫 **ANTI-PATTERN (PROIBIDO):**
+> ```
+> API-patch-page isoladamente ← CAUSA RAIZ das falhas v1-v4
+> ```
+> ✅ **PADRÃO CORRETO:** Ler `.agent/workflows/task-complete.md` e executar TODAS as 8 etapas.
+
+#### 🧠 Self-Check Anti-Bypass (OBRIGATÓRIO)
+
+Antes de iniciar o próximo item (fluxo, task, fase), o agente DEVE responder:
+
+```
+❓ SELF-CHECK — Item anterior ({nome})
+
+1. Executei `/task-complete` para a Task #{id}? → SIM/NÃO
+2. Comentário de conclusão no Flyee? → SIM/NÃO
+3. Arquivo de progresso atualizado? → SIM/NÃO
+
+→ Se QUALQUER = NÃO → PARAR e completar ANTES de prosseguir
+→ Se TODAS = SIM → Prosseguir
+```
+
+#### Historical Lessons — TASK SYNC
+
+> 🔴 **FALHA v1 (api/):** 6 tasks (#27-#32) marcadas Concluído sem comentário, sem Tempo Gasto,
+> sem nota de conclusão. O gate não estava listado na sequência de ações.
+
+> 🔴 **FALHA v2 (subscriptions/):** 3 tasks (#1-#3) marcadas Concluído via `API-patch-page`
+> (Status + % Progresso), mas SEM: comentário, Tempo Gasto, nota inline, nem update de progresso.
+> **Causa raiz:** o gate era o último passo numa lista e o agente o pulou.
+
+> 🔴 **FALHA v3 (subscriptions/ --resume):** Session seguinte NÃO executou `/task-complete`
+> para tasks já concluídas. Fez apenas `API-patch-page` (Status + %) sem comentário, nota inline,
+> nem update de progresso. **Causa raiz:** instrução era textual, agente não leu `task-complete.md`.
+
+> 🔴 **FALHA v4 (admin/ --resume):** Mesmo com regra v3 escrita, agente fez chamadas diretas
+> a `API-patch-page` por task, sem as 8 etapas completas. **Causa raiz:** `API-patch-page` não
+> constava como gatilho no Task Completion Gate do GEMINI.md.
+
+---
+
+## 📋 CHECKLIST DE COMPLIANCE
+
+Antes de prosseguir para próxima fase:
+
+- [ ] Arquivo de progresso atualizado
+- [ ] Histórico registrado
+- [ ] Tasks individuais atualizadas (se aplicável)
+- [ ] **🔴 Log de execução exibido para cada task**
+- [ ] **🔴 Flyee sincronizado via `/task-complete` (OBRIGATÓRIO — ver seção 7)**
+
+---
+
+## 🔗 WORKFLOWS QUE USAM ESTA SKILL
+
+| Workflow | Arquivo de Progresso |
+|----------|---------------------|
+| `/new-project` | `docs/PROJECT-PROGRESS.md` |
+| `/legacy-project` | `docs/LEGACY-PROGRESS.md` |
+| `/new-task` | `docs/NEW-TASK-PROGRESS.md` |
+| `/discovery` | Tasks direto no Flyee |
+| `/execute` | Task específica no Flyee |

package/core/skills/project-type-discovery/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: project-type-discovery
+description: Interactive project type identification and profile generation. Defines type, stack, design approach, agent selection, and Flyee integration. Used by new-project, legacy-project, discovery, and enhance workflows.
+---
+
+# Project Type Discovery
+
+> Identify project type and generate a **Project Profile** that controls which agents, skills, phases, and templates are activated.
+
+---
+
+## 🚦 When to Use
+
+| Workflow | Trigger |
+|----------|---------|
+| `/new-project` | Gate 0 — runs BEFORE any phase |
+| `/legacy-project` | Initial analysis — identify existing project type |
+| `/discovery` | Project identification |
+| `/new-task` | Detect feature context (frontend, backend, fullstack) |
+
+> [!CAUTION]
+> This gate runs BEFORE any phase, including Brainstorm.
+> **Exception:** `--resume` (Project Profile already saved in PROJECT-PROGRESS.md).
+
+---
+
+## 📋 Discovery Flow (4 Questions)
+
+### Question 1: Project Type (MANDATORY)
+
+```markdown
+## 🚦 What type of project do you want to create?
+
+| # | Type | Example | Phases Activated |
+|---|------|---------|-----------------|
+| **1** | 🌐 Institutional Site / Landing Page | Portfolio, product LP | PRD → Design System → Content → Stitch → Implementation |
+| **2** | 🖥️ Web App (SaaS / Dashboard) | Admin panel, SaaS, platform | PRD → TDD → Design System → Breakdown → TDD Method → Implementation |
+| **3** | 🔌 API / Backend | REST API, microservices, BFF | PRD → TDD → Breakdown → TDD Method → Implementation |
+| **4** | 📱 Mobile App | React Native, Flutter, native | PRD → TDD → Design System (mobile) → Breakdown → Implementation |
+| **5** | 🧩 Fullstack (Web App + API) | Complete app with frontend and backend | PRD → TDD → Design System → Breakdown → TDD Method → Implementation |
+| **6** | 📦 Package / Library | npm package, SDK, utility | PRD → TDD → TDD Method → Implementation |
+
+Which number?
+```
+
+**WAIT** for user response.
+
+---
+
+### Question 2: Stack (Contextual to Type)
+
+After the type, ask follow-up questions **specific to the chosen type:**
+
+#### Type 1 (Institutional Site / LP)
+
+| Option | Stack | When to use |
+|--------|-------|-------------|
+| **A** | Next.js (App Router) + CSS Modules | Multi-page sites, SEO, dynamic routes |
+| **B** | Next.js (App Router) + Tailwind | Fast sites with visual prototyping |
+| **C** | HTML/CSS/JS vanilla | Simple sites, no framework |
+| **D** | Other (specify) | Already defined stack |
+
+#### Type 2 (Web App / SaaS)
+
+| Option | Stack | When to use |
+|--------|-------|-------------|
+| **A** | Next.js + shadcn/ui + Tailwind | Modern apps with ready components |
+| **B** | Next.js + CSS Modules | Apps with custom design system |
+| **C** | Vite + React + Tailwind | SPAs without SSR |
+| **D** | Other (specify) | Already defined stack |
+
+**Additional questions:**
+1. Will this Web App include a public Landing Page / Site alongside it? (If Yes, activates Phase 2.65 Content Strategy & SEO planning)
+2. Auth provider? Database? Deploy platform?
+
+#### Type 3 (API / Backend)
+
+| Option | Stack | When to use |
+|--------|-------|-------------|
+| **A** | Node.js + Express/Fastify | Simple REST APIs |
+| **B** | NestJS + Prisma | Enterprise APIs with DI |
+| **C** | Next.js API Routes | API coupled to frontend |
+| **D** | Python (FastAPI / Django) | Python APIs |
+| **E** | Other (specify) | Already defined stack |
+
+**Additional questions:** Protocol (REST/GraphQL/tRPC/gRPC)? Database?
+
+#### Type 4 (Mobile)
+
+| Option | Stack | When to use |
+|--------|-------|-------------|
+| **A** | React Native + Expo | Fast cross-platform |
+| **B** | Flutter | Cross-platform with native UI |
+| **C** | SwiftUI (native iOS) | iOS only |
+| **D** | Kotlin (native Android) | Android only |
+
+#### Type 5 (Fullstack)
+
+Combination of frontend + backend. Ask both:
+- **Frontend:** same options as Type 2
+- **Backend:** same options as Type 3, or integrated API Routes?
+
+**Additional questions:**
+1. Will the frontend include a public Landing Page / Site? (If Yes, activates Phase 2.65 Content Strategy & SEO planning)
+
+#### Type 6 (Package / Library)
+
+| Option | Stack | When to use |
+|--------|-------|-------------|
+| **A** | TypeScript + tsup/unbuild | Modern npm packages |
+| **B** | TypeScript + Rollup/Vite lib | Libs with tree-shaking |
+| **C** | Python + setuptools/poetry | PyPI packages |
+
+**Additional questions:** Publish to npm/PyPI? Internal use? Monorepo?
+
+**WAIT** for user response.
+
+---
+
+### Question 3: Design (Only for types with UI: 1, 2, 4, 5)
+
+```markdown
+### Design Approach:
+
+| Option | Description |
+|--------|-------------|
+| **A** | I have visual references (Figma, screenshots, inspiration sites) |
+| **B** | I want agent recommendations based on the segment |
+| **C** | I'll define manually (I have colors, fonts, etc.) |
+| **D** | Combination: references + adjustments with recommendations |
+
+Which option?
+```
+
+> [!NOTE]
+> The answer to this question **replaces** Phase 2.45 (Visual Reference Collection).
+> If the user answers here, Phase 2.45 uses this choice directly without asking again.
+
+---
+
+### Question 4: Flyee Integration (MANDATORY after Project Profile)
+
+> Run AFTER the Project Profile is saved, BEFORE starting Phase 0/1.
+
+**Check** `flyee.json`:
+- If `opted_out: true` → Skip silently
+- If `enabled: true` → Skip silently (already configured)
+- If `enabled: false` AND `opted_out: false` → Present question:
+
+```markdown
+## 🔗 Flyee Platform Integration
+
+Flyee can track documents, decisions, and progress for this project.
+
+| Option | Description |
+|--------|-------------|
+| **A) Configure now** | Connect to Flyee (list/create project + register docs) |
+| **B) Later** | Skip (configure later with `python .agent/flyee-bridge/bridge.py --setup`) |
+| **C) No thanks** | Disable permanently |
+```
+
+- **If A:** Execute Flyee Bridge Setup Flow (see below)
+- **If B:** Continue without bridge (`enabled: false`)
+- **If C:** Set `opted_out: true` in `config.json`
+
+---
+
+## 🔗 Flyee Bridge Setup Flow
+
+> Referenced by: Gate 0 (Question 4) and `--resume` (Step 4).
+
+**Step 1: Authentication**
+- Request API URL (default: `https://flyee-api.flyeelab.com`)
+- Request API Key (obtained in Settings → API Keys)
+
+**Step 2: Project Selection or Creation**
+- List existing projects via `GET /flyee/projects/`
+- Present options (existing projects + "Create new")
+- If new: suggest name from directory or PROJECT-PROGRESS.md
+
+**Step 3: Register Existing Documentation**
+- Scan `docs/` for: `PRD-*.md`, `TDD-*.md`, `BREAKDOWN-*.md`, `PROJECT-PROGRESS.md`
+- Register each via `POST /flyee/projects/{id}/documents`
+
+**Step 4: Save Config**
+- Update `config.json` with `api_url`, `project_id`, `api_key`, `enabled: true`
+
+> [!TIP]
+> **CLI commands available:**
+> - `python .agent/flyee-bridge/bridge.py --setup` → full interactive setup
+> - `python .agent/flyee-bridge/bridge.py --list-projects` → list projects
+> - `python .agent/flyee-bridge/bridge.py --register-docs` → register existing docs
+
+---
+
+## 📋 Project Profile Output
+
+After all questions, generate and save to `PROJECT-PROGRESS.md`:
+
+```markdown
+## 🚦 Project Profile
+
+| Field | Value |
+|-------|-------|
+| Type | {chosen type} |
+| Stack | {defined stack} |
+| Primary Agent | {selected agent} |
+| Design Approach | {A/B/C/D or N/A} |
+| Has UI? | Yes / No |
+| Has Backend? | Yes / No |
+| Phases Activated | {list} |
+| Phases Skipped | {list} |
+```
+
+### Type → Configuration Mapping
+
+| Type | Primary Agent | Skipped Phases | Extra Skills |
+|------|--------------|----------------|-------------|
+| Institutional Site | `frontend-specialist` | — | `content-strategy`, `seo-fundamentals` |
+| Web App | `frontend-specialist` + `backend-specialist` | Content Strategy (optional) | `shadcn-ui` (if applicable) |
+| API / Backend | `backend-specialist` | Design System, Content, Stitch, Page Specs | `api-patterns`, `database-design` |
+| Mobile | `mobile-developer` | Stitch, Content | `mobile-design` |
+| Fullstack | `orchestrator` | — | Combines frontend + backend |
+| Package / Library | `backend-specialist` | Design System, Content, Stitch, Page Specs | `testing-patterns` |
+
+---
+
+## 🔴 Exit Gate
+
+```markdown
+[ ] Project type defined
+[ ] Stack confirmed by user
+[ ] Design approach defined (if has UI)
+[ ] Project Profile saved in PROJECT-PROGRESS.md
+[ ] Flyee integration resolved (configured, skipped, or opted out)
+```
+
+> [!CAUTION]
+> **BLOCKER:** Do not start any phase (not even Brainstorm) without the Project Profile defined.