# 📘 MANUAL DE OPERACIONES: ANTIGRAVITY MASTER TEMPLATE

**Antigravity Intelligence Layer — Centro de Orquestación Central**

Este repositorio es el **Cerebro Central** de tu ecosistema. Su propósito no es ejecutar aplicaciones, sino **Aprovisionar, Estandarizar y Orquestar** cualquier proyecto nuevo con calidad Staff Level.

---

## 🚀 1. Propósito del Repositorio

1. **Aprovisionamiento (Seed):** Copiar estructuras base a nuevos directorios.
2. **Inyección de Inteligencia:** Proveer agentes y reglas a proyectos "hoja".
3. **Estandarización:** Mantener stubs y cores (Laravel/Quasar) actualizados.

---

## 🏗️ 2. Componentes Maestros

### Stubs Universales (`stubs/`)
Contiene 54 archivos `.stub` altamente optimizados para Laravel. Se usan para que `php artisan make:...` genere código alineado con tus estándares.

### Laravel API God Core (`templates/laravel-api-god-core/`)
Este es el "corazón" de tus microservicios. Contiene:
- **`Traits/ApiResponser.php`**: Estandarización JSON.
- **`Traits/YajraDataTableTrait.php`**: Puente automático con el frontend.
- **`Resources/UserResource.php`**: Mapeo de Spatie.
- **`Controllers/NotificationController.php`**: Registro FCM.

*Uso:* Copia estos archivos a cualquier proyecto Laravel nuevo para dotarlo de capacidades Nivel Dios.

### Instaladores Modernos
- **`install.bat` / `install.ps1`**: Scripts para automatizar la configuración inicial de cualquier entorno Antigravity.

---

## ⚙️ 3. Flujo de Desarrollo: 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 (`/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 (`/02_dba`) — 🚨 BLUEPRINT OBLIGATORIO
* **Acción:** El DBA lee el archivo del PM y diseña la estructura de datos.
* **Resultado:** Genera/actualiza el archivo `draft.yaml` (Laravel Blueprint) previendo UUIDs, relaciones e índices.
* **⚠️ PROHIBIDO:** Crear migraciones PHP manualmente. Todo pasa por `draft.yaml`.
* **Comando a ejecutar:**
    ```bash
    php artisan blueprint:build
    ```
    *(Genera al instante Modelos, Migraciones, Controladores base, Requests y Factories usando tus Stubs personalizados Nivel Staff).*

### Paso 3: Lógica de Negocio (`/03_backend`)
* **Acción:** El Backend toma los archivos **autogenerados por Blueprint** y aplica "Edición Quirúrgica".
* **Resultado:** Inyecta protección Spatie, lógica Yajra DataTables (Server-Side) y DocBlocks de Scribe.
* **⚠️ Si necesita campos nuevos:** Actualiza `draft.yaml` y regenera. NO crea migraciones manuales.

### Paso 4: Interfaz Híbrida (`/04A_frontend_blade` o `/04B_frontend_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 (`/05_qa` y `/06_devops`)
* **Acción:** QA diseña pruebas asíncronas de Pest. DevOps prepara la subida *Zero-Downtime* a cPanel.

---

## 🚨 3.1 Política Blueprint: Zero Migraciones Manuales

**REGLA INQUEBRANTABLE:** En este ecosistema, todas las migraciones se generan desde `draft.yaml`.

| Operación | Flujo Correcto |
|-----------|---------------|
| Tabla nueva | Definir en `draft.yaml` → `php artisan blueprint:build` |
| Agregar columna | Actualizar `draft.yaml` → `php artisan blueprint:build` |
| Modificar tipo de columna | Actualizar `draft.yaml` → `php artisan blueprint:build` |
| Renombrar columna | ⚠️ EXCEPCIÓN: Migración manual con `// EXCEPCIÓN BLUEPRINT:` |
| Particionamiento | ⚠️ EXCEPCIÓN: SQL raw documentado |
| Triggers SQL | ⚠️ EXCEPCIÓN: SQL raw documentado |

Toda excepción DEBE registrarse en la tabla de excepciones de `AI_STATE.md`.

---

## 🧹 4. 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.

---

## 💻 5. 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).

---

## 🧩 6. 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.

---

## 🤖 7. Orquestador Maestro de Agentes

Tienes 10 flujos de trabajo en `.agent/workflows/`. Este repositorio contiene **todos** los agentes para el ciclo completo:

| Comando | Rol | Descripción |
|---------|-----|-------------|
| `/00_scout` | Reconocimiento | Diagnóstico global del sistema |
| `/01_product_manager` | Producto | Gestión de requerimientos |
| `/02_dba` | Base de Datos | Diseño y optimización con Blueprint |
| `/03_backend` | Backend | Lógica de negocio (Laravel/APIs) |
| `/04A_frontend_blade` | Frontend SSR | Interfaces Blade + AdminLTE |
| `/04B_frontend_vue` | Frontend SPA | Interfaces Vue + Capacitor |
| `/05_qa` | Calidad | Pruebas y destrucción |
| `/06_devops` | Infraestructura | Despliegue y escalabilidad |
| `/07_mikrotik` | Redes | Configuración MikroTik |
| `/08_orchestrator` | Coordinación | Sprint completo automatizado |

---

## 📐 8. Gobernanza de Reglas (Master Rules)

El archivo **`.antigravityrules`** define cómo se comportan los agentes de forma global. Las reglas modulares residen en `.agent/rules/` y se cargan según el stack del proyecto. Cualquier cambio en estos archivos impacta en la "sabiduría" base que se inyectará en los futuros proyectos.

---
> **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."*