flyee 0.1.0

package/core/workflows/ux-mobile-validate.md

@@ -0,0 +1,297 @@
+---
+description: Responsible for evaluating mobile-first usability of already composed pages or flows
+---
+
+## 1. Purpose (Authority Scope)
+
+Mobile-First UX Governance Workflow is responsible for **evaluating mobile-first usability** of already composed pages or flows, ensuring that:
+
+* The mobile viewport is treated as the primary experience
+* Touch interactions are safe, efficient, and predictable
+* Information hierarchy works vertically
+* No critical usability blockers exist on mobile devices
+
+### Explicitly NOT allowed:
+
+* Create or modify design tokens
+* Create or modify components
+* Rewrite or edit copy
+* Alter visual identity
+* Unlock UI progression on its own
+
+---
+
+## 2. Execution Preconditions
+
+```json
+{
+  "design_system": "validated",
+  "page": "exists",
+  "page_build": "completed",
+  "mode": "production | exploratory"
+}
+```
+
+❌ Cannot run if `/page-build` has not been completed
+❌ Cannot run on non-existent pages
+
+---
+
+## 3. Required Inputs
+
+```json
+{
+  "page": "/route",
+  "viewport": {
+    "min": 320,
+    "max": 767,
+    "primary": 375
+  },
+  "ux_focus": [
+    "layout",
+    "interaction",
+    "content",
+    "accessibility",
+    "perceived_performance"
+  ],
+  "control": {
+    "confidence_level": "low | medium | high",
+    "strict_mode": true
+  }
+}
+```
+
+### Notes:
+
+* `primary` defines the baseline breakpoint for validation
+* `strict_mode=true` enables **blocking issues**
+* `confidence_level` regulates recommendation strictness
+
+---
+
+## 4. Inspection Scope
+
+### 4.1 Layout & Hierarchy (Mobile-First)
+
+**Mandatory checks:**
+
+* Logical vertical reading order
+* Critical content visible above the fold
+* Excessive stacking (more than 6 consecutive blocks)
+* Grid structures that collapse incorrectly on mobile
+* Containers lacking minimum horizontal padding
+* Horizontal sections without scroll support
+
+---
+
+### 4.2 Touch Interaction
+
+**Mandatory checks:**
+
+* Touch targets ≥ 44px
+* Minimum spacing between clickable elements
+* CTAs not glued to screen edges
+* Sticky elements not covering content
+* Functional scrolling (no unintended overflow locks)
+* Clear active states for touch interactions
+
+---
+
+### 4.3 Content & Copy (Mobile Context)
+
+**Mandatory checks:**
+
+* Headings breaking poorly on small screens
+* Consecutive or duplicated CTAs
+* Truncated labels or buttons
+* Excessive text above the fold
+* Instructions relying on hover interactions
+
+⚠️ Detection only — never rewrites content
+
+---
+
+### 4.4 Mobile Accessibility
+
+Complementary to WCAG:
+
+* Visible focus states for touch and keyboard navigation
+* Logical tab order on mobile
+* Zoom support up to 200%
+* Inputs not blocked by virtual keyboards
+* Contrast remaining functional in outdoor conditions
+
+---
+
+### 4.5 Perceived Performance (UX-Driven)
+
+* Delayed loading of critical content
+* Noticeable layout shifts
+* Missing skeletons in key areas
+* Images not optimized for mobile
+* Excessive initial cognitive load
+
+---
+
+## 5. Issue Severity Model
+
+```json
+{
+  "severity_levels": {
+    "blocking": "Prevents correct mobile usage",
+    "major": "Significantly degrades UX or conversion",
+    "minor": "Recommended improvement"
+  }
+}
+```
+
+### Rules:
+
+* **Any `blocking` issue = FAIL**
+* Accumulated `major` issues may cause FAIL beyond thresholds
+* `minor` issues never block progression
+
+---
+
+## 6. Output Contract
+
+### 6.1 Overall Result
+
+```json
+{
+  "ux_mobile_validation": "PASS | FAIL",
+  "summary": {
+    "blocking": 2,
+    "major": 4,
+    "minor": 5
+  }
+}
+```
+
+---
+
+### 6.2 Issue List
+
+```json
+{
+  "issues": [
+    {
+      "id": "UXM-001",
+      "severity": "blocking",
+      "category": "interaction",
+      "description": "Primary CTA is below the fold on mobile",
+      "location": {
+        "section": "Hero",
+        "viewport": 375
+      },
+      "recommended_action": "Reorder content or reduce hero height",
+      "allowed_fix_scope": "page-build"
+    }
+  ]
+}
+```
+
+🔒 `allowed_fix_scope` is **never** `design-system` or `tokens`
+
+---
+
+### 6.3 Mandatory Next Step
+
+If **FAIL**:
+
+```json
+{
+  "next_step": {
+    "action": "/page-build",
+    "mode": "extend",
+    "scope": [
+      "Hero",
+      "Header"
+    ]
+  }
+}
+```
+
+If **PASS**:
+
+```json
+{
+  "next_step": {
+    "action": "continue"
+  }
+}
+```
+
+---
+
+## 7. Integration with `/next-step`
+
+### Formal Rule:
+
+```text
+/ux-mobile-validate
+→ PASS → continue
+→ FAIL → /page-build (extend)
+```
+
+❌ Validation cannot be skipped if `strict_mode=true`
+❌ Scope cannot be altered without explicit authorization
+
+---
+
+## 8. Logs & Audit Trail
+
+```json
+{
+  "audit": {
+    "validated_at": "ISO-8601",
+    "viewports_tested": [320, 375, 414, 767],
+    "design_system_version": "x.y.z",
+    "confidence_level": "medium"
+  }
+}
+```
+
+---
+
+## 9. Hard Constraints (Non-Negotiable)
+
+* Mobile UX **never** creates UI
+* Mobile UX **never** alters visual identity
+* Mobile UX **never** modifies tokens
+* Mobile UX **can block** progression
+* Mobile UX is **always mobile-first**
+
+---
+
+## 10. Final Project State
+
+After **PASS**:
+
+```json
+{
+  "ux_mobile": "validated"
+}
+```
+
+After **FAIL**:
+
+```json
+{
+  "ux_mobile": "failed"
+}
+```
+
+---
+
+## 11. Why This Works in Your System
+
+Because it:
+
+* Respects strict domain separation
+* Acts as a **UX auditor**, not a designer
+* Is predictable, explainable, and repeatable
+* Prevents subjective AI decisions
+* Complements Design System + WCAG without overlap
+
+---

package/engine-files/GEMINI.md

@@ -0,0 +1,69 @@
+# Flyee — AI Agent Framework
+
+> Este arquivo é gerado automaticamente pelo installer `flyee`.
+> Ele configura o comportamento do agente AI neste workspace.
+
+---
+
+## Agent Framework
+
+Este projeto utiliza o **Flyee Agent Framework** — um sistema de agentes especializados,
+skills modulares e workflows automatizados para desenvolvimento assistido por IA.
+
+### Estrutura
+
+```
+.agent/
+├── agents/      ← 22 agentes especializados
+├── skills/      ← 66+ skills modulares
+├── workflows/   ← 45+ workflows automatizados
+├── scripts/     ← Scripts de automação
+└── flyee-bridge/ ← Sync com Flyee Platform (opcional)
+```
+
+### Skill Loading Protocol
+
+Ao receber uma tarefa:
+1. Classificar o tipo de request (QUESTION, SIMPLE CODE, COMPLEX CODE, DESIGN/UI)
+2. Selecionar o agente apropriado via `.agent/agents/`
+3. Carregar skills relevantes via frontmatter do agente
+4. Aplicar rules e gates obrigatórios
+
+### Agent Routing
+
+| Domínio | Agente |
+|---------|--------|
+| Web Frontend | `frontend-specialist` |
+| Backend/API | `backend-specialist` |
+| Mobile | `mobile-developer` |
+| Security | `security-auditor` |
+| Debugging | `debugger` |
+| Planning | `project-planner` |
+| Multi-task | `orchestrator` |
+
+### Workflows Disponíveis
+
+Use `/comando` para ativar workflows:
+
+| Comando | Descrição |
+|---------|-----------|
+| `/new-task` | Adicionar feature com tracking |
+| `/execute` | Executar tasks |
+| `/task-complete` | Completar com verification gates |
+| `/debug` | Debugging sistemático |
+| `/test` | Gerar e rodar testes |
+| `/plan` | Planejamento estratégico |
+| `/deploy` | Deploy para produção |
+
+### Flyee Platform (Opcional)
+
+Se `flyee.json` existir na raiz, o agente sincroniza tarefas com a plataforma Flyee.
+Sem `flyee.json`, tudo funciona offline com estado local em `.flyee/`.
+
+### Rules
+
+1. Responda no idioma do usuário
+2. Código e comentários em inglês
+3. Leia o agente antes de implementar
+4. Siga os gates obrigatórios (Pre-Implementation, Verification)
+5. Clean code: sem over-engineering, sem comentários desnecessários

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "flyee",
+  "version": "0.1.0",
+  "description": "AI Agent Framework — 21 specialist agents, 65+ skills, 40+ workflows. All runtimes.",
+  "license": "MIT",
+  "author": "Bruno Santana <bruno@flyee.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BrunoSantanaDeveloper/flyee-agent.git"
+  },
+  "homepage": "https://flyee.dev",
+  "keywords": [
+    "ai",
+    "agent",
+    "coding-agent",
+    "ai-framework",
+    "multi-runtime",
+    "antigravity",
+    "claude",
+    "cursor",
+    "copilot",
+    "codex",
+    "windsurf",
+    "gemini"
+  ],
+  "type": "module",
+  "bin": {
+    "flyee": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "core/",
+    "engine-files/",
+    "runtime-adapters/",
+    "bridge/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/",
+    "lint": "echo 'TODO: add linter'",
+    "dry-run": "node bin/install.js --dry-run"
+  }
+}

package/runtime-adapters/antigravity.js

@@ -0,0 +1,26 @@
+/**
+ * Antigravity Runtime Adapter
+ * 
+ * The canonical format IS the Antigravity format, so this adapter
+ * is mostly a pass-through. Paths use .agent/ which is the default.
+ */
+
+export const config = {
+  name: 'antigravity',
+  dirName: '.agent',
+  engineFile: 'GEMINI.md',
+  pathMap: {
+    '{{AGENT_DIR}}': '.agent',
+    '{{GLOBAL_DIR}}': '~/.gemini/antigravity',
+    '{{ENGINE_FILE}}': 'GEMINI.md',
+    '{{BRIDGE_DIR}}': '.agent/flyee-bridge',
+  },
+};
+
+/**
+ * Convert canonical content to Antigravity format.
+ * Since canonical IS Antigravity, this is a no-op.
+ */
+export function convert(content, runtimeConfig) {
+  return content;
+}

package/runtime-adapters/claude.js

@@ -0,0 +1,57 @@
+/**
+ * Claude Code Runtime Adapter
+ * 
+ * Converts canonical (.agent/) content to Claude Code format (.claude/).
+ * Claude Code uses CLAUDE.md as engine file and different tool names.
+ */
+
+export const config = {
+  name: 'claude',
+  dirName: '.claude',
+  engineFile: 'CLAUDE.md',
+  pathMap: {
+    '.agent/': '.claude/',
+    '.agent\\b': '.claude',
+    'GEMINI.md': 'CLAUDE.md',
+    '~/.gemini/antigravity': '~/.claude',
+  },
+  toolMap: {
+    'read_file': 'Read',
+    'write_file': 'Write',
+    'replace_file_content': 'Edit',
+    'multi_replace_file_content': 'MultiEdit',
+    'run_command': 'Bash',
+    'grep_search': 'Grep',
+    'list_dir': 'Glob',
+    'view_file': 'Read',
+    'search_web': 'WebSearch',
+    'google_web_search': 'WebSearch',
+    'run_shell_command': 'Bash',
+    'search_file_content': 'Grep',
+  },
+};
+
+/**
+ * Convert canonical content to Claude Code format.
+ */
+export function convert(content, runtimeConfig) {
+  let result = content;
+
+  // Replace paths
+  for (const [from, to] of Object.entries(config.pathMap)) {
+    result = result.replaceAll(from, to);
+  }
+
+  // Replace tool names (only in code blocks and inline code)
+  for (const [from, to] of Object.entries(config.toolMap)) {
+    // Replace tool names that appear as identifiers (word boundaries)
+    const regex = new RegExp(`\\b${escapeRegex(from)}\\b`, 'g');
+    result = result.replace(regex, to);
+  }
+
+  return result;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/runtime-adapters/codex.js

@@ -0,0 +1,51 @@
+/**
+ * OpenAI Codex Runtime Adapter
+ * 
+ * Converts canonical (.agent/) content to Codex format (.codex/).
+ * Codex uses AGENTS.md as engine file.
+ */
+
+export const config = {
+  name: 'codex',
+  dirName: '.codex',
+  engineFile: 'AGENTS.md',
+  pathMap: {
+    '.agent/': '.codex/',
+    '.agent\\b': '.codex',
+    'GEMINI.md': 'AGENTS.md',
+    '~/.gemini/antigravity': '~/.codex',
+  },
+  toolMap: {
+    'read_file': 'read',
+    'write_file': 'write',
+    'replace_file_content': 'patch',
+    'multi_replace_file_content': 'patch',
+    'run_command': 'shell',
+    'grep_search': 'grep',
+    'list_dir': 'ls',
+    'view_file': 'read',
+    'search_web': 'web_search',
+    'google_web_search': 'web_search',
+    'run_shell_command': 'shell',
+    'search_file_content': 'grep',
+  },
+};
+
+export function convert(content, runtimeConfig) {
+  let result = content;
+
+  for (const [from, to] of Object.entries(config.pathMap)) {
+    result = result.replaceAll(from, to);
+  }
+
+  for (const [from, to] of Object.entries(config.toolMap)) {
+    const regex = new RegExp(`\\b${escapeRegex(from)}\\b`, 'g');
+    result = result.replace(regex, to);
+  }
+
+  return result;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/runtime-adapters/copilot.js

@@ -0,0 +1,51 @@
+/**
+ * GitHub Copilot Runtime Adapter
+ * 
+ * Converts canonical (.agent/) content to Copilot format (.github/).
+ * Copilot uses .github/copilot-instructions.md as engine file.
+ */
+
+export const config = {
+  name: 'copilot',
+  dirName: '.github',
+  engineFile: 'copilot-instructions.md',
+  pathMap: {
+    '.agent/': '.github/',
+    '.agent\\b': '.github',
+    'GEMINI.md': '.github/copilot-instructions.md',
+    '~/.gemini/antigravity': '~/.config/github-copilot',
+  },
+  toolMap: {
+    'read_file': 'read',
+    'write_file': 'edit',
+    'replace_file_content': 'edit',
+    'multi_replace_file_content': 'edit',
+    'run_command': 'execute',
+    'grep_search': 'search',
+    'list_dir': 'list',
+    'view_file': 'read',
+    'search_web': 'search_web',
+    'google_web_search': 'search_web',
+    'run_shell_command': 'execute',
+    'search_file_content': 'search',
+  },
+};
+
+export function convert(content, runtimeConfig) {
+  let result = content;
+
+  for (const [from, to] of Object.entries(config.pathMap)) {
+    result = result.replaceAll(from, to);
+  }
+
+  for (const [from, to] of Object.entries(config.toolMap)) {
+    const regex = new RegExp(`\\b${escapeRegex(from)}\\b`, 'g');
+    result = result.replace(regex, to);
+  }
+
+  return result;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/runtime-adapters/cursor.js

@@ -0,0 +1,51 @@
+/**
+ * Cursor Runtime Adapter
+ * 
+ * Converts canonical (.agent/) content to Cursor format (.cursor/).
+ * Cursor uses .cursorrules as engine file.
+ */
+
+export const config = {
+  name: 'cursor',
+  dirName: '.cursor',
+  engineFile: '.cursorrules',
+  pathMap: {
+    '.agent/': '.cursor/',
+    '.agent\\b': '.cursor',
+    'GEMINI.md': '.cursorrules',
+    '~/.gemini/antigravity': '~/.cursor',
+  },
+  toolMap: {
+    'read_file': 'read_file',
+    'write_file': 'write_file',
+    'replace_file_content': 'StrReplace',
+    'multi_replace_file_content': 'StrReplace',
+    'run_command': 'Shell',
+    'grep_search': 'search',
+    'list_dir': 'list_dir',
+    'view_file': 'read_file',
+    'search_web': 'web_search',
+    'google_web_search': 'web_search',
+    'run_shell_command': 'Shell',
+    'search_file_content': 'search',
+  },
+};
+
+export function convert(content, runtimeConfig) {
+  let result = content;
+
+  for (const [from, to] of Object.entries(config.pathMap)) {
+    result = result.replaceAll(from, to);
+  }
+
+  for (const [from, to] of Object.entries(config.toolMap)) {
+    const regex = new RegExp(`\\b${escapeRegex(from)}\\b`, 'g');
+    result = result.replace(regex, to);
+  }
+
+  return result;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/runtime-adapters/gemini-cli.js

@@ -0,0 +1,30 @@
+/**
+ * Gemini CLI Runtime Adapter
+ * 
+ * Converts canonical (.agent/) content to Gemini CLI format (.gemini/).
+ * Gemini CLI uses GEMINI.md as engine file (same as Antigravity).
+ */
+
+export const config = {
+  name: 'gemini-cli',
+  dirName: '.gemini',
+  engineFile: 'GEMINI.md',
+  pathMap: {
+    '.agent/': '.gemini/',
+    '.agent\\b': '.gemini',
+    '~/.gemini/antigravity': '~/.gemini',
+  },
+  toolMap: {
+    // Gemini CLI tool names are same as Antigravity
+  },
+};
+
+export function convert(content, runtimeConfig) {
+  let result = content;
+
+  for (const [from, to] of Object.entries(config.pathMap)) {
+    result = result.replaceAll(from, to);
+  }
+
+  return result;
+}