flyee 0.1.0

package/core/skills/documentation-publishing/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: documentation-publishing
+description: Publicação de documentação técnica e manual do usuário no Flyee. Discovery de databases, upsert, mapeamento de fluxos para guias.
+---
+
+# Documentation Publishing
+
+> **Publicação estruturada de documentação no Flyee (ou local) ao final de ciclos de projeto.**
+
+---
+
+## 🎯 PROPÓSITO
+
+Garantir que ao concluir trabalho em um escopo/módulo:
+1. **Handover** e **Test Guide** são criados
+2. **Docs técnicos** são publicados para devs (Database "Documentação Técnica")
+3. **Guias de usuário** são publicados para operadores (Database "Manual do Usuário")
+4. **Modo Local** registra docs criados sem chamadas a APIs Flyee
+
+---
+
+## 🔴 REGRAS OBRIGATÓRIAS
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** A publicação tem **DUAS partes obrigatórias:**
+> 1. Criar HANDOVER + TEST-GUIDE para o escopo
+> 2. Publicar TODOS os docs (flow docs, TDD, DS, handover, test-guide)
+>
+> Uma sem a outra = **fase INCOMPLETA**.
+
+#### Historical Lesson — Publicação Incompleta
+
+> 🔴 **FALHA (api/ e admin/):** Agente criou HANDOVER + TEST-GUIDE mas **PULOU a publicação
+> dos flow docs/TDD/DS no Flyee** (Database "Documentação Técnica"). Devs ficaram sem acesso
+> à documentação completa. **Causa raiz:** instrução dizia "Documentação Final" sem mencionar
+> publicação Flyee — agente interpretou como "só criar handover".
+
+---
+
+### 1. Criação de Handover e Test Guide
+
+#### HANDOVER-{escopo}.md
+
+Caminho: `docs/handover/{escopo}/HANDOVER-{escopo}.md`
+
+| Seção | Conteúdo |
+|-------|----------|
+| Visão Geral | Stack, arquitetura, dependências |
+| Fluxos Críticos | Resumo dos flow docs |
+| Integrações | APIs externas, gateways, services |
+| Débitos Resolvidos | Lista de melhorias implementadas |
+| Débitos Pendentes | Itens não implementados do TDD |
+| Decisões Técnicas | Decisões tomadas durante o projeto |
+| Como Rodar | Setup local, env vars, comandos |
+| Referências | Links para docs detalhados |
+
+#### TEST-GUIDE-{escopo}.md
+
+Caminho: `docs/tests/{escopo}/TEST-GUIDE-{escopo}.md`
+
+| Seção | Conteúdo |
+|-------|----------|
+| Stack de Testes | Ferramentas, versões, config |
+| Estrutura | Diretórios e organização |
+| Mapa de Testes | Tests por domínio (cobertura atual) |
+| Como Executar | Comandos para rodar testes |
+| Patterns Usados | MSW, mocks, factories, etc |
+| Troubleshooting | Problemas comuns e soluções |
+| Expansão | Próximos testes prioritários |
+
+---
+
+### 2. Publicação de Documentação Técnica (Flyee)
+
+> [!NOTE]
+> **Se `Destino de Tasks = Local`:** Pular discovery e publicação Flyee.
+> Registrar docs criados no arquivo de progresso com caminhos dos arquivos.
+
+#### Passo 1: Discovery e Validação do Database
+
+```json
+// Buscar database "Documentação Técnica"
+{
+  "query": "Documentação Técnica",
+  "filter": { "property": "object", "value": "data_source" }
+}
+```
+
+> Se database ausente ou propriedades faltando → PARAR e notificar usuário.
+
+#### Passo 2: Coletar Artefatos
+
+| Fonte | Tipo | Publicar? |
+|-------|------|-----------|
+| Análise | Arquitetura (`CODEBASE-*.md`) | ✅ |
+| Flow docs | Fluxos (`docs/flows/**/*.md`) | ✅ |
+| TDD | Design (`docs/design/TDD-*.md`) | ✅ |
+| Design System | DS (`design-system/MASTER.md`) | ✅ (se UI) |
+| Testes | Cobertura (relatório) | ✅ |
+| Handover | Handover (`docs/handover/**/*.md`) | ✅ |
+| Test Guide | Testes (`docs/tests/**/*.md`) | ✅ |
+
+#### Passo 3: Para Cada Artefato — Publicar
+
+1. **Verificar upsert** — doc já existe no database? (query por Nome + Módulo)
+2. **Ler conteúdo** do arquivo local
+3. **Criar ou atualizar** página Flyee
+4. **Propriedades:** Nome, Módulo, Tipo, Status, Última Atualização, Arquivo Local, Tasks Relacionadas
+5. **Incluir histórico** referenciando tasks da database "Tarefas"
+
+#### Passo 4: Gate de Saída
+
+```
+[ ] Database "Documentação Técnica" validado
+[ ] Todos os artefatos publicados
+[ ] Upsert verificado (sem duplicatas)
+[ ] Histórico de atualizações em cada doc
+[ ] Tasks relacionadas referenciadas
+[ ] Arquivo de progresso atualizado
+```
+
+---
+
+### 3. Publicação do Manual do Usuário (Flyee)
+
+> [!CAUTION]
+> **REGRA BLOQUEANTE:** Para cada fluxo publicado, DEVE existir uma versão
+> em linguagem acessível. Sem código, sem jargão técnico.
+
+> [!NOTE]
+> **Se `Destino de Tasks = Local`:** Gerar guias como arquivos em
+> `docs/user-guides/{escopo}/` e registrar no arquivo de progresso.
+
+#### Passo 1: Discovery do Database
+
+```json
+{
+  "query": "Manual do Usuário",
+  "filter": { "property": "object", "value": "data_source" }
+}
+```
+
+> Se database ausente → PARAR e notificar usuário.
+
+#### Passo 2: Mapeamento Fluxo → Guia
+
+Para cada fluxo técnico publicado, gerar versão em linguagem simples.
+
+#### Passo 3: Para Cada Guia — Publicar
+
+1. **Verificar upsert** — guia já existe? (query por Nome)
+2. **Gerar conteúdo** em linguagem simples
+3. **Criar ou atualizar** página com template de guia
+4. **Propriedades:** Nome, Seção, Status, Público-alvo
+
+#### Passo 4: Gate de Saída
+
+```
+[ ] Database "Manual do Usuário" validado
+[ ] Todos os fluxos mapeados para guias
+[ ] Upsert verificado (sem duplicatas)
+[ ] Conteúdo sem jargão técnico
+[ ] Arquivo de progresso atualizado
+```
+
+---
+
+## 🔗 WORKFLOWS QUE USAM ESTA SKILL
+
+| Workflow | Quando usar |
+|----------|-------------|
+| `/legacy-project` | Phases 8 + 8.5 (handover + publicação) |
+| `/new-project` | Phase 7 (documentação final) |
+| `/document` | Publicação standalone de docs |

package/core/skills/documentation-templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: documentation-templates
+description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+allowed-tools: Read, Glob, Grep
+---
+
+# Documentation Templates
+
+> Templates and structure guidelines for common documentation types.
+
+---
+
+## 1. README Structure
+
+### Essential Sections (Priority Order)
+
+| Section | Purpose |
+|---------|---------|
+| **Title + One-liner** | What is this? |
+| **Quick Start** | Running in <5 min |
+| **Features** | What can I do? |
+| **Configuration** | How to customize |
+| **API Reference** | Link to detailed docs |
+| **Contributing** | How to help |
+| **License** | Legal |
+
+### README Template
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API Documentation Structure
+
+### Per-Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. Code Comment Guidelines
+
+### JSDoc/TSDoc Template
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### When to Comment
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|-----------------|
+| Why (business logic) | What (obvious) |
+| Complex algorithms | Every line |
+| Non-obvious behavior | Self-explanatory code |
+| API contracts | Implementation details |
+
+---
+
+## 4. Changelog Template (Keep a Changelog)
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI-Friendly Documentation (2025)
+
+### llms.txt Template
+
+For AI crawlers and agents:
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### MCP-Ready Documentation
+
+For RAG indexing:
+- Clear H1-H3 hierarchy
+- JSON/YAML examples for data structures
+- Mermaid diagrams for flows
+- Self-contained sections
+
+---
+
+## 7. Structure Principles
+
+| Principle | Why |
+|-----------|-----|
+| **Scannable** | Headers, lists, tables |
+| **Examples first** | Show, don't just tell |
+| **Progressive detail** | Simple → Complex |
+| **Up to date** | Outdated = misleading |
+
+---
+
+> **Remember:** Templates are starting points. Adapt to your project's needs.

package/core/skills/enhance-prompt/README.md

@@ -0,0 +1,34 @@
+# Stitch Enhance Prompt Skill
+
+## Install
+
+```bash
+npx add-skill google-labs-code/stitch-skills --skill enhance-prompt --global
+```
+
+## Example Prompt
+
+```text
+Enhance my prompt "make me a login page" for better Stitch generation results.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, workflow, and reference materials.
+
+```text
+enhance-prompt/
+├── SKILL.md           — Core instructions & workflow
+├── references/        — UI/UX vocabulary and adjective palettes
+└── README.md          — This file
+```
+
+## How it Works
+
+When activated, the agent follows a prompt enhancement pipeline:
+
+1. **Assessment**: Evaluates the input for missing elements (platform, structure, visual style, colors).
+2. **DESIGN.md Check**: Looks for an existing design system to inject; recommends creating one if missing.
+3. **Enhancement**: Applies UI/UX keywords, vibe adjectives, and structured page sections.
+4. **Formatting**: Outputs a Stitch-optimized prompt with design system block and numbered structure.
+5. **Delivery**: Returns enhanced text for user review, with optional file output.

package/core/skills/enhance-prompt/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: enhance-prompt
+description: Transforms vague UI ideas into polished, Stitch-optimized prompts. Enhances specificity, adds UI/UX keywords, injects design system context, and structures output for better generation results.
+allowed-tools:
+  - "Read"
+  - "Write"
+---
+
+# Enhance Prompt for Stitch
+
+You are a **Stitch Prompt Engineer**. Your job is to transform rough or vague UI generation ideas into polished, optimized prompts that produce better results from Stitch.
+
+## Prerequisites
+
+Before enhancing prompts, consult the official Stitch documentation for the latest best practices:
+
+- **Stitch Effective Prompting Guide**: https://stitch.withgoogle.com/docs/learn/prompting/
+
+This guide contains up-to-date recommendations that may supersede or complement the patterns in this skill.
+
+## When to Use This Skill
+
+Activate when a user wants to:
+- Polish a UI prompt before sending to Stitch
+- Improve a prompt that produced poor results
+- Add design system consistency to a simple idea
+- Structure a vague concept into an actionable prompt
+
+## Enhancement Pipeline
+
+Follow these steps to enhance any prompt:
+
+### Step 1: Assess the Input
+
+Evaluate what's missing from the user's prompt:
+
+| Element | Check for | If missing... |
+|---------|-----------|---------------|
+| **Platform** | "web", "mobile", "desktop" | Add based on context or ask |
+| **Page type** | "landing page", "dashboard", "form" | Infer from description |
+| **Structure** | Numbered sections/components | Create logical page structure |
+| **Visual style** | Adjectives, mood, vibe | Add appropriate descriptors |
+| **Colors** | Specific values or roles | Add design system or suggest |
+| **Components** | UI-specific terms | Translate to proper keywords |
+
+### Step 2: Check for DESIGN.md
+
+Look for a `DESIGN.md` file in the current project:
+
+**If DESIGN.md exists:**
+1. Read the file to extract the design system block
+2. Include the color palette, typography, and component styles
+3. Format as a "DESIGN SYSTEM (REQUIRED)" section in the output
+
+**If DESIGN.md does not exist:**
+1. Add this note at the end of the enhanced prompt:
+
+```
+---
+💡 **Tip:** For consistent designs across multiple screens, create a DESIGN.md 
+file using the `design-md` skill. This ensures all generated pages share the 
+same visual language.
+```
+
+### Step 3: Apply Enhancements
+
+Transform the input using these techniques:
+
+#### A. Add UI/UX Keywords
+
+Replace vague terms with specific component names:
+
+| Vague | Enhanced |
+|-------|----------|
+| "menu at the top" | "navigation bar with logo and menu items" |
+| "button" | "primary call-to-action button" |
+| "list of items" | "card grid layout" or "vertical list with thumbnails" |
+| "form" | "form with labeled input fields and submit button" |
+| "picture area" | "hero section with full-width image" |
+
+#### B. Amplify the Vibe
+
+Add descriptive adjectives to set the mood:
+
+| Basic | Enhanced |
+|-------|----------|
+| "modern" | "clean, minimal, with generous whitespace" |
+| "professional" | "sophisticated, trustworthy, with subtle shadows" |
+| "fun" | "vibrant, playful, with rounded corners and bold colors" |
+| "dark mode" | "dark theme with high-contrast accents on deep backgrounds" |
+
+#### C. Structure the Page
+
+Organize content into numbered sections:
+
+```markdown
+**Page Structure:**
+1. **Header:** Navigation with logo and menu items
+2. **Hero Section:** Headline, subtext, and primary CTA
+3. **Content Area:** [Describe the main content]
+4. **Footer:** Links, social icons, copyright
+```
+
+#### D. Format Colors Properly
+
+When colors are mentioned, format them as:
+```
+Descriptive Name (#hexcode) for functional role
+```
+
+Examples:
+- "Deep Ocean Blue (#1a365d) for primary buttons and links"
+- "Warm Cream (#faf5f0) for page background"
+- "Soft Gray (#6b7280) for secondary text"
+
+### Step 4: Format the Output
+
+Structure the enhanced prompt in this order:
+
+```markdown
+[One-line description of the page purpose and vibe]
+
+**DESIGN SYSTEM (REQUIRED):**
+- Platform: [Web/Mobile], [Desktop/Mobile]-first
+- Theme: [Light/Dark], [style descriptors]
+- Background: [Color description] (#hex)
+- Primary Accent: [Color description] (#hex) for [role]
+- Text Primary: [Color description] (#hex)
+- [Additional design tokens...]
+
+**Page Structure:**
+1. **[Section]:** [Description]
+2. **[Section]:** [Description]
+...
+```
+
+## Output Options
+
+**Default:** Return the enhanced prompt as text for the user to copy.
+
+**Optional file output:** If the user requests, write to a file:
+- `next-prompt.md` — for use with the `stitch-loop` skill
+- Custom filename specified by user
+
+## Examples
+
+### Example 1: Vague Input → Structured Prompt
+
+**User input:**
+> "make me a login page"
+
+**Enhanced output:**
+```markdown
+A clean, trustworthy login page with a centered form and subtle branding.
+
+**DESIGN SYSTEM (REQUIRED):**
+- Platform: Web, Desktop-first
+- Theme: Light, minimal, professional
+- Background: Clean White (#ffffff)
+- Surface: Soft Gray (#f9fafb) for form card
+- Primary Accent: Deep Blue (#2563eb) for submit button and links
+- Text Primary: Near Black (#111827) for headings
+- Text Secondary: Medium Gray (#6b7280) for labels
+- Buttons: Subtly rounded (8px), full-width on form
+- Cards: Gently rounded (12px), soft shadow for elevation
+
+**Page Structure:**
+1. **Header:** Minimal logo, centered
+2. **Login Card:** Centered form with email, password fields, "Forgot password?" link
+3. **Submit Button:** Primary blue "Sign In" button
+4. **Footer:** "Don't have an account? Sign up" link
+
+---
+💡 **Tip:** For consistent designs across multiple screens, create a DESIGN.md 
+file using the `design-md` skill.
+```
+
+### Example 2: Feature Request → Targeted Edit
+
+**User input:**
+> "add a search bar"
+
+**Enhanced output:**
+```markdown
+Add a search bar to the header navigation.
+
+**Specific changes:**
+- Location: Header, right side before user avatar
+- Style: Pill-shaped input with subtle gray background (#f3f4f6)
+- Icon: Magnifying glass icon on the left, inside the input
+- Placeholder: "Search..." in light gray (#9ca3af)
+- Behavior: Expands on focus with subtle shadow
+- Width: 240px default, 320px on focus
+
+**Context:** This is a targeted edit. Make only this change while preserving all existing elements.
+```
+
+## Tips for Best Results
+
+1. **Be specific early** — Vague inputs need more enhancement
+2. **Match the user's intent** — Don't over-design if they want simple
+3. **Keep it structured** — Numbered sections help Stitch understand hierarchy
+4. **Include the design system** — Consistency is key for multi-page projects
+5. **One change at a time for edits** — Don't bundle unrelated changes

package/core/skills/enhance-prompt/references/KEYWORDS.md

@@ -0,0 +1,114 @@
+# UI/UX Keywords Reference
+
+Progressive disclosure reference for common UI terminology and adjective palettes.
+
+## Component Keywords
+
+### Navigation
+- navigation bar, nav menu, header
+- breadcrumbs, tabs, sidebar
+- hamburger menu, dropdown menu
+- back button, close button
+
+### Content Containers
+- hero section, hero banner
+- card, card grid, tile
+- modal, dialog, popup
+- accordion, collapsible section
+- carousel, slider
+
+### Forms
+- input field, text input
+- dropdown, select menu
+- checkbox, radio button
+- toggle switch
+- date picker, time picker
+- search bar, search input
+- submit button, form actions
+
+### Calls to Action
+- primary button, secondary button
+- ghost button, text link
+- floating action button (FAB)
+- icon button
+
+### Feedback
+- toast notification, snackbar
+- alert banner, warning message
+- loading spinner, skeleton loader
+- progress bar, step indicator
+
+### Layout
+- grid layout, flexbox
+- sidebar layout, split view
+- sticky header, fixed footer
+- full-width, contained width
+- centered content, max-width container
+
+## Adjective Palettes
+
+### Minimal / Clean
+- minimal, clean, uncluttered
+- generous whitespace, breathing room
+- subtle, understated, refined
+- simple, focused, distraction-free
+
+### Professional / Corporate
+- sophisticated, polished, trustworthy
+- corporate, business-like, formal
+- subtle shadows, clean lines
+- structured, organized, hierarchical
+
+### Playful / Fun
+- vibrant, colorful, energetic
+- rounded corners, soft edges
+- bold, expressive, dynamic
+- friendly, approachable, warm
+
+### Premium / Luxury
+- elegant, luxurious, high-end
+- dramatic, bold contrasts
+- sleek, modern, cutting-edge
+- exclusive, boutique, curated
+
+### Dark Mode
+- dark theme, night mode
+- high-contrast accents
+- soft glows, subtle highlights
+- deep backgrounds, muted surfaces
+
+### Organic / Natural
+- earthy tones, natural colors
+- warm, inviting, cozy
+- textured, tactile, handcrafted
+- flowing, organic shapes
+
+## Color Role Terminology
+
+### Backgrounds
+- page background, canvas
+- surface color, card background
+- overlay, scrim
+
+### Text
+- primary text, heading color
+- secondary text, body copy
+- muted text, placeholder
+- inverse text (on dark backgrounds)
+
+### Accents
+- primary accent, brand color
+- secondary accent, highlight
+- success, error, warning colors
+- hover state, active state
+
+## Shape Descriptions
+
+| Technical | Natural Language |
+|-----------|------------------|
+| `rounded-none` | sharp, squared-off edges |
+| `rounded-sm` | slightly softened corners |
+| `rounded-md` | gently rounded corners |
+| `rounded-lg` | generously rounded corners |
+| `rounded-xl` | very rounded, pillow-like |
+| `rounded-full` | pill-shaped, circular |