flyee 0.1.0

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

@@ -0,0 +1,441 @@
+---
+name: python-patterns
+description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Python Patterns
+
+> Python development principles and decision-making for 2025.
+> **Learn to THINK, not memorize patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for framework preference when unclear
+- Choose async vs sync based on CONTEXT
+- Don't default to same framework every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── API-first / Microservices
+│   └── FastAPI (async, modern, fast)
+│
+├── Full-stack web / CMS / Admin
+│   └── Django (batteries-included)
+│
+├── Simple / Script / Learning
+│   └── Flask (minimal, flexible)
+│
+├── AI/ML API serving
+│   └── FastAPI (Pydantic, async, uvicorn)
+│
+└── Background workers
+    └── Celery + any framework
+```
+
+### Comparison Principles
+
+| Factor | FastAPI | Django | Flask |
+|--------|---------|--------|-------|
+| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
+| **Async** | Native | Django 5.0+ | Via extensions |
+| **Admin** | Manual | Built-in | Via extensions |
+| **ORM** | Choose your own | Django ORM | Choose your own |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. Is this API-only or full-stack?
+2. Need admin interface?
+3. Team familiar with async?
+4. Existing infrastructure?
+
+---
+
+## 2. Async vs Sync Decision
+
+### When to Use Async
+
+```
+async def is better when:
+├── I/O-bound operations (database, HTTP, file)
+├── Many concurrent connections
+├── Real-time features
+├── Microservices communication
+└── FastAPI/Starlette/Django ASGI
+
+def (sync) is better when:
+├── CPU-bound operations
+├── Simple scripts
+├── Legacy codebase
+├── Team unfamiliar with async
+└── Blocking libraries (no async version)
+```
+
+### The Golden Rule
+
+```
+I/O-bound → async (waiting for external)
+CPU-bound → sync + multiprocessing (computing)
+
+Don't:
+├── Mix sync and async carelessly
+├── Use sync libraries in async code
+└── Force async for CPU work
+```
+
+### Async Library Selection
+
+| Need | Async Library |
+|------|---------------|
+| HTTP client | httpx |
+| PostgreSQL | asyncpg |
+| Redis | aioredis / redis-py async |
+| File I/O | aiofiles |
+| Database ORM | SQLAlchemy 2.0 async, Tortoise |
+
+---
+
+## 3. Type Hints Strategy
+
+### When to Type
+
+```
+Always type:
+├── Function parameters
+├── Return types
+├── Class attributes
+├── Public APIs
+
+Can skip:
+├── Local variables (let inference work)
+├── One-off scripts
+├── Tests (usually)
+```
+
+### Common Type Patterns
+
+```python
+# These are patterns, understand them:
+
+# Optional → might be None
+from typing import Optional
+def find_user(id: int) -> Optional[User]: ...
+
+# Union → one of multiple types
+def process(data: str | dict) -> None: ...
+
+# Generic collections
+def get_items() -> list[Item]: ...
+def get_mapping() -> dict[str, int]: ...
+
+# Callable
+from typing import Callable
+def apply(fn: Callable[[int], str]) -> str: ...
+```
+
+### Pydantic for Validation
+
+```
+When to use Pydantic:
+├── API request/response models
+├── Configuration/settings
+├── Data validation
+├── Serialization
+
+Benefits:
+├── Runtime validation
+├── Auto-generated JSON schema
+├── Works with FastAPI natively
+└── Clear error messages
+```
+
+---
+
+## 4. Project Structure Principles
+
+### Structure Selection
+
+```
+Small project / Script:
+├── main.py
+├── utils.py
+└── requirements.txt
+
+Medium API:
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── models/
+│   ├── routes/
+│   ├── services/
+│   └── schemas/
+├── tests/
+└── pyproject.toml
+
+Large application:
+├── src/
+│   └── myapp/
+│       ├── core/
+│       ├── api/
+│       ├── services/
+│       ├── models/
+│       └── ...
+├── tests/
+└── pyproject.toml
+```
+
+### FastAPI Structure Principles
+
+```
+Organize by feature or layer:
+
+By layer:
+├── routes/ (API endpoints)
+├── services/ (business logic)
+├── models/ (database models)
+├── schemas/ (Pydantic models)
+└── dependencies/ (shared deps)
+
+By feature:
+├── users/
+│   ├── routes.py
+│   ├── service.py
+│   └── schemas.py
+└── products/
+    └── ...
+```
+
+---
+
+## 5. Django Principles (2025)
+
+### Django Async (Django 5.0+)
+
+```
+Django supports async:
+├── Async views
+├── Async middleware
+├── Async ORM (limited)
+└── ASGI deployment
+
+When to use async in Django:
+├── External API calls
+├── WebSocket (Channels)
+├── High-concurrency views
+└── Background task triggering
+```
+
+### Django Best Practices
+
+```
+Model design:
+├── Fat models, thin views
+├── Use managers for common queries
+├── Abstract base classes for shared fields
+
+Views:
+├── Class-based for complex CRUD
+├── Function-based for simple endpoints
+├── Use viewsets with DRF
+
+Queries:
+├── select_related() for FKs
+├── prefetch_related() for M2M
+├── Avoid N+1 queries
+└── Use .only() for specific fields
+```
+
+---
+
+## 6. FastAPI Principles
+
+### async def vs def in FastAPI
+
+```
+Use async def when:
+├── Using async database drivers
+├── Making async HTTP calls
+├── I/O-bound operations
+└── Want to handle concurrency
+
+Use def when:
+├── Blocking operations
+├── Sync database drivers
+├── CPU-bound work
+└── FastAPI runs in threadpool automatically
+```
+
+### Dependency Injection
+
+```
+Use dependencies for:
+├── Database sessions
+├── Current user / Auth
+├── Configuration
+├── Shared resources
+
+Benefits:
+├── Testability (mock dependencies)
+├── Clean separation
+├── Automatic cleanup (yield)
+```
+
+### Pydantic v2 Integration
+
+```python
+# FastAPI + Pydantic are tightly integrated:
+
+# Request validation
+@app.post("/users")
+async def create(user: UserCreate) -> UserResponse:
+    # user is already validated
+    ...
+
+# Response serialization
+# Return type becomes response schema
+```
+
+---
+
+## 7. Background Tasks
+
+### Selection Guide
+
+| Solution | Best For |
+|----------|----------|
+| **BackgroundTasks** | Simple, in-process tasks |
+| **Celery** | Distributed, complex workflows |
+| **ARQ** | Async, Redis-based |
+| **RQ** | Simple Redis queue |
+| **Dramatiq** | Actor-based, simpler than Celery |
+
+### When to Use Each
+
+```
+FastAPI BackgroundTasks:
+├── Quick operations
+├── No persistence needed
+├── Fire-and-forget
+└── Same process
+
+Celery/ARQ:
+├── Long-running tasks
+├── Need retry logic
+├── Distributed workers
+├── Persistent queue
+└── Complex workflows
+```
+
+---
+
+## 8. Error Handling Principles
+
+### Exception Strategy
+
+```
+In FastAPI:
+├── Create custom exception classes
+├── Register exception handlers
+├── Return consistent error format
+└── Log without exposing internals
+
+Pattern:
+├── Raise domain exceptions in services
+├── Catch and transform in handlers
+└── Client gets clean error response
+```
+
+### Error Response Philosophy
+
+```
+Include:
+├── Error code (programmatic)
+├── Message (human readable)
+├── Details (field-level when applicable)
+└── NOT stack traces (security)
+```
+
+---
+
+## 9. Testing Principles
+
+### Testing Strategy
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | pytest |
+| **Integration** | API endpoints | pytest + httpx/TestClient |
+| **E2E** | Full workflows | pytest + DB |
+
+### Async Testing
+
+```python
+# Use pytest-asyncio for async tests
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_endpoint():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.get("/users")
+        assert response.status_code == 200
+```
+
+### Fixtures Strategy
+
+```
+Common fixtures:
+├── db_session → Database connection
+├── client → Test client
+├── authenticated_user → User with token
+└── sample_data → Test data setup
+```
+
+---
+
+## 10. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about framework preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Decided async vs sync?**
+- [ ] **Planned type hint strategy?**
+- [ ] **Defined project structure?**
+- [ ] **Planned error handling?**
+- [ ] **Considered background tasks?**
+
+---
+
+## 11. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Default to Django for simple APIs (FastAPI may be better)
+- Use sync libraries in async code
+- Skip type hints for public APIs
+- Put business logic in routes/views
+- Ignore N+1 queries
+- Mix async and sync carelessly
+
+### ✅ DO:
+- Choose framework based on context
+- Ask about async requirements
+- Use Pydantic for validation
+- Separate concerns (routes → services → repos)
+- Test critical paths
+
+---
+
+> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.

package/core/skills/qa-test-generation/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: qa-test-generation
+description: Heuristics for generating comprehensive test checklists by change type. Used by /task-complete Etapa 1.7 to auto-create test steps.
+---
+
+# QA Test Generation
+
+> Generate structured test checklists from acceptance criteria + modified files.
+> Output: `TestStep[]` for `task.meta.test_checklist`.
+
+---
+
+## 🎯 PURPOSE
+
+Automatically produce a comprehensive, multi-path test checklist when a task is being completed. The checklist covers **happy path, error cases, edge cases, boundary values, empty states, and permissions** — never just the happy path.
+
+---
+
+## 🔍 HEURISTICS BY CHANGE TYPE
+
+### 1. UI Component Changes
+
+**Detect:** Files matching `*.tsx`, `*.css`, `*.module.css` in `components/`, `features/`, `pages/`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | Component renders without errors | auto | unit |
+| 2 | All interactive elements are clickable (cursor: pointer) | manual | visual |
+| 3 | Responsive: renders correctly on mobile (≤640px) | manual | visual |
+| 4 | Responsive: renders correctly on tablet (641–1024px) | manual | visual |
+| 5 | Dark mode: colors adapt correctly | manual | visual |
+| 6 | Empty state: shows fallback when no data | manual | e2e |
+| 7 | Loading state: shows skeleton/spinner during fetch | manual | visual |
+| 8 | Error state: shows error message on API failure | manual | e2e |
+| 9 | Hover/focus states match DS tokens | manual | visual |
+| 10 | Accessibility: keyboard navigable (Tab/Enter/Escape) | manual | manual |
+| 11 | Text content does not overflow containers | manual | visual |
+
+### 2. API Endpoint Changes
+
+**Detect:** Files matching `api/*.py`, `routes/*.ts`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | Returns 200 with valid input | auto | integration |
+| 2 | Returns 400 with invalid/missing fields | auto | integration |
+| 3 | Returns 404 for non-existent resource | auto | integration |
+| 4 | Returns 401/403 without authentication | auto | integration |
+| 5 | Handles empty request body | auto | integration |
+| 6 | Handles duplicate/conflict data (409) | auto | integration |
+| 7 | Response schema matches TypeScript types | auto | unit |
+| 8 | Pagination works correctly (if applicable) | auto | integration |
+| 9 | Large payload doesn't timeout | manual | integration |
+
+### 3. Backend Logic Changes
+
+**Detect:** Files matching `crud/*.py`, `services/*.py`, `utils/*.py`, `schemas/*.py`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | Function returns expected result for valid input | auto | unit |
+| 2 | Function raises/returns error for invalid input | auto | unit |
+| 3 | Edge case: empty/null/zero values handled | auto | unit |
+| 4 | Edge case: boundary values (max int, empty string) | auto | unit |
+| 5 | Concurrent operations don't corrupt data | manual | integration |
+| 6 | Database constraints enforced (unique, foreign key) | auto | integration |
+
+### 4. Styling Changes
+
+**Detect:** Files matching `*.css`, `*.module.css`, `tokens.*`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | Uses DS tokens (not hardcoded values) | auto | unit |
+| 2 | Color contrast ratio ≥ 4.5:1 (AA) | manual | visual |
+| 3 | Animations are smooth (no jank) | manual | visual |
+| 4 | No layout shifts on load | manual | visual |
+
+### 5. SDK/Type Changes
+
+**Detect:** Files matching `sdk/*.ts`, `types.ts`, `domain/*.ts`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | TypeScript build passes (`tsc --noEmit`) | auto | unit |
+| 2 | New types are exported from index | auto | unit |
+| 3 | SDK method calls correct API endpoint | auto | integration |
+| 4 | Response type matches API schema | auto | unit |
+
+### 6. Workflow/Skill Changes
+
+**Detect:** Files matching `workflows/*.md`, `skills/*/SKILL.md`
+
+| # | Test Step Template | Type | Category |
+|---|-------------------|------|----------|
+| 1 | Markdown syntax is valid | auto | unit |
+| 2 | Referenced files/paths exist | auto | unit |
+| 3 | Referenced commands run without error | manual | integration |
+| 4 | Workflow steps are in logical order | manual | manual |
+
+---
+
+## 📋 GENERATION PROCESS
+
+```
+1. Read acceptance criteria from task body/meta
+2. Read list of modified files from Resumo de Execução
+3. For each file:
+   a. Classify by change type (UI/API/Backend/Styling/SDK/Workflow)
+   b. Select applicable heuristic table
+   c. Generate TestStep for each row, customizing description to actual change
+4. Add acceptance-criteria-specific steps (from task body)
+5. Deduplicate (same test from different files → keep one)
+6. Assign IDs: ts-1, ts-2, ...
+7. Save via bridge.py --generate-tests OR direct API
+```
+
+---
+
+## ⚙️ OUTPUT FORMAT
+
+Each generated step follows this schema:
+
+```json
+{
+  "id": "ts-1",
+  "description": "OKR card renders without errors when key_results is empty",
+  "type": "auto",
+  "category": "unit",
+  "status": "pending",
+  "result_comment": null,
+  "tested_by": null,
+  "tested_at": null
+}
+```
+
+---
+
+## 🚫 ANTI-PATTERNS
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Generate only happy path tests | Cover error, edge, boundary, empty states |
+| Generic descriptions ("test UI") | Specific ("OKRCardExpanded shows 0% when no KRs") |
+| All tests as `manual` | Classify auto vs manual based on tooling |
+| Skip styling/visual tests | Include visual checks even if manual |
+| Over-generate for trivial changes | Scale tests proportionally to change complexity |
+
+---
+
+## 🔗 USED BY
+
+| Workflow | Step |
+|----------|------|
+| `/task-complete` | Etapa 1.7 (QA Test Checklist Gate) |
+| `/fix-tests` | Step 2 (Analyze + regenerate if needed) |

package/core/skills/react-components/README.md

@@ -0,0 +1,36 @@
+# Stitch to React Components Skill
+
+## Install
+
+```bash
+npx add-skill google-labs-code/stitch-skills --skill react:components --global
+```
+
+## Example Prompt
+
+```text
+Convert my Landing Page screen in my Podcast Stitch Project to a React component system.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, validation scripts, and design tokens.
+
+```text
+skills/react-components/
+├── SKILL.md           — Core instructions & workflow
+├── package.json       — Validator dependencies
+├── scripts/           — Networking & AST validation
+├── resources/         — Style guides & API references
+└── examples/          — Gold-standard code samples
+```
+
+## How it Works
+
+When activated, the agent follows a high-fidelity engineering pipeline:
+
+1. **Retrieval**: Uses a system-level `curl` script to bypass TLS/SNI issues on Google Cloud Storage.
+2. **Mapping**: Cross-references Stitch metadata with the local `style-guide.json` to ensure token consistency.
+3. **Generation**: Scaffolds components using a strict Atomic Design pattern.
+4. **Validation**: Runs an automated AST check using `@swc/core` to prevent hardcoded hex values or missing interfaces.
+5. **Audit**: Performs a final self-correction check against a 20-point architecture checklist.

package/core/skills/react-components/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: react:components
+description: Converts Stitch designs into modular Vite and React components using system-level networking and AST-based validation.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+  - "web_fetch"
+---
+
+# Stitch to React Components
+
+You are a frontend engineer focused on transforming designs into clean React code. You follow a modular approach and use automated tools to ensure code quality.
+
+## Retrieval and networking
+1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
+2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
+3. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
+   - Use the `Bash` tool to run: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"`.
+   - This script handles the necessary redirects and security handshakes.
+4. **Visual audit**: Check `screenshot.downloadUrl` to confirm the design intent and layout details.
+
+## Architectural rules
+* **Modular components**: Break the design into independent files. Avoid large, single-file outputs.
+* **Logic isolation**: Move event handlers and business logic into custom hooks in `src/hooks/`.
+* **Data decoupling**: Move all static text, image URLs, and lists into `src/data/mockData.ts`.
+* **Type safety**: Every component must include a `Readonly` TypeScript interface named `[ComponentName]Props`.
+* **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React components.
+* **Style mapping**:
+    * Extract the `tailwind.config` from the HTML `<head>`.
+    * Sync these values with `resources/style-guide.json`.
+    * Use theme-mapped Tailwind classes instead of arbitrary hex codes.
+
+## Execution steps
+1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
+2. **Data layer**: Create `src/data/mockData.ts` based on the design content.
+3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace all instances of `StitchComponent` with the actual name of the component you are creating.
+4. **Application wiring**: Update the project entry point (like `App.tsx`) to render the new components.
+5. **Quality check**:
+    * Run `npm run validate <file_path>` for each component.
+    * Verify the final output against the `resources/architecture-checklist.md`.
+    * Start the dev server with `npm run dev` to verify the live result.
+
+## Troubleshooting
+* **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
+* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles.