# 🚀 Guía de Operaciones: Ecosistema Multi-Agente Nivel Staff

Esta guía documenta el flujo de trabajo ultra-optimizado para el **Google Antigravity IDE**. Al seguir este protocolo, garantizas un desarrollo rápido, seguro (Spatie), altamente concurrente (Yajra) y con un consumo mínimo de tokens de IA.

---

## ⚙️ 1. Flujo de Desarrollo Paso a Paso (El Sprint)

Todo nuevo requerimiento (ej. Módulo de Gimnasios, Proveedores) debe seguir esta estricta cadena de mando a través del archivo `AI_STATE.md`:

### Paso 1: Definición del Producto (Rol 01 - Product Manager)
* **Acción:** Le explicas la idea al Product Manager.
* **Resultado:** Genera un archivo `.md` en `/soluciones/` con el MVP, Casos Límite y la **Matriz de Seguridad Spatie**.
* **Pase de Testigo:** Actualiza `AI_STATE.md` para llamar al DBA.

### Paso 2: Diseño de Datos YAML (Rol 02 - DBA)
* **Acción:** El DBA lee el archivo del PM y diseña la estructura de datos.
* **Resultado:** Genera el archivo `draft.yaml` (Laravel Blueprint) previendo UUIDs, relaciones e índices para alto rendimiento.
* **Comando a ejecutar por ti:**
    ```bash
    php artisan blueprint:build
    ```
    *(Este comando genera al instante Modelos, Migraciones, Controladores base, Requests y Factories usando tus Stubs personalizados Nivel Staff).*

### Paso 3: Lógica de Negocio (Rol 03 - Backend)
* **Acción:** El Backend toma los archivos autogenerados y aplica "Edición Quirúrgica".
* **Resultado:** Inyecta protección Spatie, lógica Yajra DataTables (Server-Side) y DocBlocks de Scribe mediante **Unified Diffs**.

### Paso 4: Interfaz Híbrida (Rol 04A Blade / 04B Vue)
* **Acción:** Tú disparas tu *Snippet* en el IDE (`v-cap-page` o componentes de AdminLTE) para generar el cascarón de la vista en 1 segundo.
* **Resultado:** La IA solo provee el interior lógico (`<script setup>` o directivas `@can` de Spatie), conectando el frontend a la API.

### Paso 5: Destrucción y Despliegue (Rol 05 QA / Rol 06 DevOps)
* **Acción:** QA diseña pruebas asíncronas de Pest. DevOps prepara la subida *Zero-Downtime* a cPanel.

---

## 🧹 2. Protocolo de Archivado (Poda de Contexto)

**⚠️ CRÍTICO PARA AHORRAR TOKENS Y PREVENIR ALUCINACIONES:**

Al finalizar un módulo (ej. Control de Miembros):
1. El Agente DevOps o QA declara el fin del Sprint en el `AI_STATE.md`.
2. **Tu trabajo:** Mover el archivo del requerimiento desde `/soluciones/` hacia `/soluciones/historico/`.
3. Tu archivo `.antigravityignore` ocultará esta carpeta histórica, reseteando la memoria de la IA para que el próximo sprint empiece desde cero.

---

## 💻 3. Comandos de Consola Vitales

### 🔨 Generación y Arquitectura
* `php artisan blueprint:build` -> Genera el CRUD completo leyendo tu `draft.yaml`.
* `php artisan blueprint:erase` -> Deshace la última generación de Blueprint si hubo un error.
* `php artisan stub:publish` -> Expone los Stubs del framework (ya lo hicimos para inyectar Spatie, Yajra, y UUIDs por defecto).

### 🛡️ Calidad y Estándares (Git Hooks pre-commit)
* `vendor/bin/pint` -> Formatea el código PHP a los estándares PSR-12 automáticamente.
* `vendor/bin/phpstan analyse` -> Busca errores lógicos estrictos (Nivel Staff) antes de ejecutar el código.
* `vendor/bin/pest` -> Ejecuta la suite de pruebas y Test de Arquitectura.

### 💾 Datos Falsos Realistas (Yajra Stress-Test)
Tus Factories y Seeders ya nacen configurados con `$faker->locale('es_VE')` para generar identidades reales (cédulas, números venezolanos).
* `php artisan migrate:fresh --seed` -> Destruye y recrea la BD con datos de estrés.

### 📄 Documentación API (Scribe)
* `php artisan scribe:generate` -> Lee los controladores backend y autogenera una página web hermosa con la documentación de tu API (y el `openapi.json` para el Frontend).

---

## 🧩 4. Snippets y Componentes de Interfaz

**En Backend (Blade / AdminLTE):**
Nunca permitas que la IA escriba HTML puro. Oblígala a usar tu directorio de componentes:
* `<x-admin-card title="Gestión">`
* `<x-admin-table id="miembros-table">`

**En Mobile / SPA (Vue 3 + Capacitor):**
Usa tu atajo de teclado configurado en el IDE:
* Escribe `v-cap-page` + `TAB`.
* *Resultado:* Genera la vista Vue 3 con Tailwind, Pinia, e inyección de *Safe Area* `env(safe-area-inset-top)` nativo para móviles.

---

> **Filosofía del CTO:** *"La IA no es tu mecanógrafa, es tu cerebro auxiliar. Usa Blueprint y Snippets para el código repetitivo, y deja a la IA orquestar la seguridad y el rendimiento."*