specleap-framework 2.0.0

package/.commands/documentar.md

@@ -0,0 +1,285 @@
+# Comando: documentar
+
+**Sintaxis:** `documentar` o `documentar [archivo]`
+
+**Objetivo:** Actualizar documentación técnica (context/) cuando hay cambios importantes.
+
+**Motor:** Usa Git para analizar cambios + actualización manual guiada.
+
+---
+
+## Flujo
+
+### 1. Identificar Qué Documentar
+
+**Opción A: Archivo específico**
+```
+documentar context/architecture.md
+```
+
+**Opción B: Análisis automático**
+```
+documentar
+```
+→ Analiza cambios recientes y determina qué actualizar
+
+---
+
+### 2. Analizar Cambios Recientes (Git)
+
+```bash
+cd [directorio-proyecto]
+
+# Ver commits recientes
+git log --oneline -20
+
+# Ver archivos modificados
+git diff HEAD~10..HEAD --name-only
+
+# Ver cambios en dependencias
+git diff HEAD~10..HEAD package.json composer.json
+```
+
+**Identificar:**
+- ✅ Nuevas features implementadas
+- ✅ Cambios arquitectónicos
+- ✅ Nuevas dependencias
+- ✅ Decisiones técnicas tomadas
+
+---
+
+### 3. Leer Documentación Actual
+
+```bash
+cd proyectos/[proyecto]/context/
+
+# Leer todos los archivos
+cat brief.md
+cat architecture.md
+cat tech-stack.md
+cat conventions.md
+cat decisions.md
+```
+
+---
+
+### 4. Determinar Actualizaciones Necesarias
+
+**Checklist:**
+
+**brief.md:**
+- [ ] Cambió el propósito del proyecto
+- [ ] Hay nuevos módulos completados
+- [ ] Cambió el estado (% progreso)
+
+**architecture.md:**
+- [ ] Nueva capa/componente agregado
+- [ ] Cambió estructura de directorios
+- [ ] Modificó patrón arquitectónico
+- [ ] Nuevas dependencias entre módulos
+
+**tech-stack.md:**
+- [ ] Nueva dependencia (npm/composer)
+- [ ] Actualización de versión importante
+- [ ] Cambió herramienta (ej: Webpack → Vite)
+- [ ] Nuevo servicio externo
+
+**conventions.md:**
+- [ ] Nuevo patrón de código establecido
+- [ ] Cambió naming convention
+- [ ] Nueva regla de testing
+
+**decisions.md:**
+- [ ] Decisión técnica importante tomada
+- [ ] Alternativas evaluadas
+- [ ] Decisión pendiente resuelta
+
+---
+
+### 5. Actualizar Archivos
+
+Para cada archivo que necesita actualización:
+
+**A) Mostrar contenido actual:**
+```markdown
+📄 **Contenido actual de [archivo]:**
+
+[Mostrar primeras 30 líneas]
+
+...
+
+¿Qué quieres actualizar?
+```
+
+**B) Esperar input del usuario:**
+
+Ejemplos:
+- "Agrega que ahora usamos Redis para cache"
+- "Actualiza la versión de Laravel a 11.x"
+- "Agrega decisión sobre usar PostgreSQL en lugar de MySQL"
+
+**C) Aplicar cambios:**
+
+Editar el archivo con los cambios especificados.
+
+**D) Mostrar diff:**
+```bash
+git diff context/[archivo]
+```
+
+```markdown
+**Cambios en [archivo]:**
+
+[Mostrar diff con colores]
+
+¿Aprobar cambios? (s/n)
+```
+
+---
+
+### 6. Confirmar y Commitear
+
+Si el usuario aprueba:
+
+```bash
+git add context/*.md
+git commit -m "docs: update context/ documentation
+
+Updated:
+- [archivo1]: [cambio1]
+- [archivo2]: [cambio2]
+
+Refs: [commits que motivaron la actualización]"
+```
+
+```markdown
+✅ **Documentación actualizada**
+
+**Archivos modificados:**
+- context/architecture.md
+- context/tech-stack.md
+- context/decisions.md
+
+**Commit:** docs: update context/ documentation
+
+¿Pushear cambios? (s/n)
+```
+
+---
+
+## Ejemplo Completo
+
+```
+Usuario: "documentar"
+
+IA:
+🔍 Analizando cambios recientes...
+
+git log --oneline -20:
+  a1b2c3d feat: implement Redis cache
+  d4e5f6g feat: upgrade Laravel to 11.x
+  g7h8i9j refactor: move to PostgreSQL
+
+📋 **Cambios detectados:**
+1. Redis implementado para cache (commit a1b2c3d)
+2. Laravel actualizado a 11.x (commit d4e5f6g)
+3. Migración a PostgreSQL (commit g7h8i9j)
+
+**Archivos a actualizar:**
+- ✅ context/tech-stack.md (Redis + Laravel 11.x + PostgreSQL)
+- ✅ context/architecture.md (nueva capa de cache)
+- ✅ context/decisions.md (decisión PostgreSQL vs MySQL)
+
+¿Actualizar estos archivos? (s/n)
+
+Usuario: "s"
+
+IA:
+📝 Actualizando context/tech-stack.md...
+
+**Agregando:**
+- Laravel: 10.x → 11.x
+- Cache: Redis 7.x (nuevo)
+- Database: MySQL 8.0 → PostgreSQL 16.x
+
+✅ tech-stack.md actualizado.
+
+📝 Actualizando context/decisions.md...
+
+**Agregando decisión:**
+## 2026-02-26: Migración a PostgreSQL
+
+**Contexto:** MySQL presentaba limitaciones con JSON queries.
+
+**Alternativas evaluadas:**
+1. MySQL 8.0 con JSON
+2. PostgreSQL 16
+3. MongoDB
+
+**Decisión:** PostgreSQL 16
+
+**Razones:**
+- JSON nativo + mejor performance
+- JSONB indexable
+- Full-text search integrado
+- Compatibilidad Laravel excelente
+
+✅ decisions.md actualizado.
+
+📝 Actualizando context/architecture.md...
+
+**Agregando capa:**
+## Cache Layer (Redis)
+
+Implementado para reducir carga en base de datos.
+
+**Cache keys:**
+- `user:{id}` — Datos de usuario (TTL: 1h)
+- `product:{id}` — Datos de producto (TTL: 30min)
+- `categories` — Árbol de categorías (TTL: 24h)
+
+✅ architecture.md actualizado.
+
+💾 **Commiteando cambios...**
+
+git commit -m "docs: update context/ - Redis cache + Laravel 11.x + PostgreSQL"
+
+✅ Commit realizado.
+
+¿Pushear? (s/n)
+
+Usuario: "s"
+
+git push origin main
+
+✅ Documentación actualizada y pusheada.
+```
+
+---
+
+## Comandos/Herramientas Usados
+
+| Comando | Propósito |
+|---------|-----------|
+| `git log --oneline -20` | Ver commits recientes |
+| `git diff HEAD~10..HEAD --name-only` | Archivos modificados |
+| `git diff HEAD~10..HEAD package.json` | Cambios en dependencias |
+| `git diff context/[archivo]` | Preview de cambios |
+| `git add context/*.md` | Preparar commit |
+| `git commit -m "..."` | Commitear |
+
+---
+
+## Reglas
+
+1. **Siempre usar Git** para detectar cambios reales
+2. **Mostrar diff** antes de commitear
+3. **Pedir aprobación** al usuario
+4. **Commits atómicos** (documentación separada de código)
+5. **Referencias** a commits que motivaron la actualización
+
+---
+
+## Próximo Comando
+
+- `explicar [concepto]` — Explicar código/arquitectura existente

package/.commands/explicar.md

@@ -0,0 +1,234 @@
+# Comando: explicar
+
+**Sintaxis:** 
+- `explicar [concepto]`
+- `explicar @archivo.php`
+- `explicar esta función`
+
+**Objetivo:** Explicar código, arquitectura o decisiones técnicas de forma clara.
+
+**Motor:** Usa lectura directa de archivos + análisis contextual.
+
+---
+
+## Flujo
+
+### 1. Identificar Qué Explicar
+
+Analiza el argumento:
+
+- **Concepto general** — "cómo funciona el carrito"
+- **Archivo específico** — "@ProductController.php"
+- **Función/método** — "esta función" (contexto previo)
+- **Arquitectura** — "por qué usamos services"
+- **Decisión técnica** — "por qué PostgreSQL"
+
+---
+
+### 2. Leer Contexto Relevante
+
+**Para Conceptos/Arquitectura:**
+```bash
+cat proyectos/[proyecto]/CONTRATO.md
+cat proyectos/[proyecto]/context/architecture.md
+cat proyectos/[proyecto]/context/tech-stack.md
+cat proyectos/[proyecto]/context/decisions.md
+```
+
+**Para Código Específico:**
+```bash
+# Encontrar archivo
+find [directorio-proyecto] -name "[archivo]"
+
+# Leer archivo
+cat [ruta-archivo]
+
+# Ver imports/dependencias
+grep -E "^use |^import " [ruta-archivo]
+```
+
+**Para Decisiones Técnicas:**
+```bash
+# Buscar en decisions.md
+grep -A 10 "[tecnología/decisión]" context/decisions.md
+```
+
+---
+
+### 3. Generar Explicación
+
+**Estructura:**
+
+```markdown
+# Explicación: [Concepto/Archivo/Función]
+
+## Resumen
+[1-2 párrafos: qué es y para qué sirve]
+
+## ¿Cómo Funciona?
+[Explicación paso a paso]
+
+## Código Relevante
+[Fragmentos de código con explicación]
+
+## Relaciones
+[Qué otros componentes están relacionados]
+
+## Decisiones Técnicas
+[Por qué se hizo de esta manera]
+
+## Referencias
+[Enlaces a docs, CONTRATO.md, context/]
+```
+
+---
+
+### 4. Ejemplo Completo
+
+```
+Usuario: "explicar cómo funciona el sistema de autenticación"
+
+IA:
+🔍 Leyendo contexto del proyecto...
+
+cat proyectos/app-tienda/CONTRATO.md:
+  Sistema de Usuarios → Autenticación: Laravel Sanctum (SPA)
+
+cat proyectos/app-tienda/context/tech-stack.md:
+  Autenticación: Laravel Sanctum 4.x
+  Frontend: React 18 con axios
+
+cat proyectos/app-tienda/context/architecture.md:
+  API stateless, tokens en localStorage
+
+---
+
+# Explicación: Sistema de Autenticación
+
+## Resumen
+
+El proyecto usa **Laravel Sanctum** para autenticación SPA (Single Page Application).
+
+Es un sistema **stateless** basado en tokens: el frontend (React) envía credenciales al backend (Laravel), recibe un token, y lo incluye en cada request posterior.
+
+## ¿Cómo Funciona?
+
+### 1. Login (Frontend → Backend)
+
+Usuario ingresa email + password:
+
+```javascript
+// LoginForm.tsx
+const response = await axios.post('/api/login', {
+  email: 'user@example.com',
+  password: 'secreto123'
+});
+
+const token = response.data.token;
+localStorage.setItem('auth_token', token);
+```
+
+### 2. Backend Valida Credenciales
+
+```php
+// AuthController.php
+public function login(Request $request)
+{
+    $credentials = $request->validate([
+        'email' => 'required|email',
+        'password' => 'required',
+    ]);
+
+    if (!Auth::attempt($credentials)) {
+        return response()->json(['error' => 'Invalid credentials'], 401);
+    }
+
+    $user = Auth::user();
+    $token = $user->createToken('auth_token')->plainTextToken;
+
+    return response()->json(['token' => $token]);
+}
+```
+
+### 3. Requests Autenticados
+
+Frontend incluye el token en cada request:
+
+```javascript
+axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+
+// Ahora todas las requests llevan el token
+const products = await axios.get('/api/products');
+```
+
+### 4. Backend Verifica Token
+
+Laravel Sanctum valida automáticamente el token:
+
+```php
+// routes/api.php
+Route::middleware('auth:sanctum')->group(function () {
+    Route::get('/products', [ProductController::class, 'index']);
+    Route::post('/products', [ProductController::class, 'store']);
+});
+```
+
+## Relaciones
+
+- **Frontend:** LoginForm.tsx, ProtectedRoute.tsx, axiosConfig.js
+- **Backend:** AuthController.php, User model, Sanctum middleware
+- **Base de Datos:** personal_access_tokens table (guarda tokens)
+
+## Decisiones Técnicas
+
+**¿Por qué Sanctum y no JWT/Passport?**
+
+Referencia: context/decisions.md línea 45
+
+**Decisión:** Laravel Sanctum
+
+**Razones:**
+1. Más simple que Passport
+2. Integrado nativamente en Laravel
+3. Perfecto para SPAs
+4. No requiere OAuth server
+
+**Alternativas evaluadas:**
+- JWT (tymon/jwt-auth) — Más complejo
+- Laravel Passport — Overkill para SPA simple
+
+## Referencias
+
+- CONTRATO.md: "Sistema de Usuarios" sección
+- context/tech-stack.md: Laravel Sanctum 4.x
+- context/decisions.md: Línea 45-60
+- Docs oficiales: https://laravel.com/docs/11.x/sanctum
+```
+
+---
+
+## Comandos/Herramientas Usados
+
+| Comando | Propósito |
+|---------|-----------|
+| `cat proyectos/[proyecto]/CONTRATO.md` | Leer contrato |
+| `cat context/*.md` | Leer contexto |
+| `find . -name "[archivo]"` | Buscar archivo |
+| `grep -A 10 "[patrón]" [archivo]` | Buscar en archivo |
+| `cat [archivo]` | Leer código |
+
+---
+
+## Reglas
+
+1. **Siempre leer contexto** antes de explicar
+2. **Ejemplos de código** cuando ayude
+3. **Referencias** a archivos/líneas específicas
+4. **No inventar** — Si no hay info, decir "No lo sé"
+5. **Claridad** sobre precisión técnica excesiva
+
+---
+
+## Próximo Comando
+
+- `refinar SCRUM-XX` — Refinar user story para implementación