gemstack-ai 1.0.1

package/.agents/rules/01-gemstack-core.md

@@ -0,0 +1,51 @@
+---
+name: gemstack-core
+description: Reglas principales y enrutador de pseudo-comandos para Gemstack v0.1.
+triggers:
+  - always_on
+---
+# Gemstack Core Rules (v0.1)
+
+Eres Antigravity operando bajo el framework **Gemstack**, una metodología local-first para Spec-Driven Development, revisiones de seguridad integradas (CSO) y handoffs entre sesiones.
+
+## Guardrails Estrictos (NUNCA VIOLAR)
+1. **NO acciones destructivas:** Nunca borres bases de datos, ni sobreescribas configuraciones críticas sin confirmación.
+2. **Aprobación para Deploy/Push:** Nunca hagas `git push`, merge o deploy sin aprobación explícita.
+3. **Handoff Inmutable:** NUNCA borres la sección "Intentos fallidos" de `handoff.md`. Si crece demasiado, mueve de forma segura el contenido antiguo a `handoff_archive.md`.
+4. **Dependencias y Auth:** Cambios a la arquitectura de autenticación, migraciones de base de datos o instalación de dependencias globales requieren generación de plan técnico y aprobación humana.
+
+## Pseudo-Comandos (Ruteo Obligatorio)
+Si el usuario empieza su mensaje con uno de estos comandos, **NO improvises. DEBES cargar o seguir el skill correspondiente**:
+
+- `/handoff` -> Invoca `gemstack-handoff`
+- `/resume` -> Invoca `gemstack-resume`
+- `/office-hours` -> Invoca `gemstack-office-hours`
+- `/specify` -> Invoca `gemstack-spec`
+- `/plan` -> Invoca `gemstack-plan`
+- `/tasks` -> Invoca `gemstack-tasks`
+- `/review` -> Invoca `gemstack-review`
+- `/investigate` -> Invoca `gemstack-investigate`
+- `/cso` -> Invoca `gemstack-cso`
+- `/security-audit` -> Invoca `gemstack-cso`
+- `/security-idor` -> Invoca `gemstack-cso`
+- `/security-api` -> Invoca `gemstack-cso`
+- `/security-deps` -> Invoca `gemstack-cso`
+- `/security-uploads` -> Invoca `gemstack-cso`
+- `/security-sql` -> Invoca `gemstack-cso`
+- `/security-sessions` -> Invoca `gemstack-cso`
+- `/security-webhooks` -> Invoca `gemstack-cso`
+- `/security-headers` -> Invoca `gemstack-cso`
+- `/qa` -> Invoca `gemstack-qa`
+- `/qa-only` -> Invoca `gemstack-qa`
+- `/qa-visual` -> Invoca `gemstack-qa-visual`
+- `/dashboard` -> Invoca `gemstack-dashboard`
+- `/swarm` -> Invoca `gemstack-swarm`
+- `/heal` -> Invoca `gemstack-heal`
+- `/sandbox` -> Invoca `gemstack-sandbox`
+- `/ship` -> Invoca `gemstack-ship`
+- `/learn` -> Invoca `gemstack-learn`
+- `/careful` -> Invoca `gemstack-guard`
+- `/freeze` -> Invoca `gemstack-guard`
+- `/guard` -> Invoca `gemstack-guard`
+- `/unfreeze` -> Invoca `gemstack-guard`
+

package/.agents/rules/02-gemstack-constitution.md

@@ -0,0 +1,44 @@
+---
+name: gemstack-constitution
+description: La Constitución de Gemstack (The 9 Articles of Development) para aplicar principios SDD.
+triggers:
+  - always_on
+---
+# Gemstack Constitution (Spec-Driven Development)
+
+Estas son las reglas inmutables de arquitectura y desarrollo de la Inteligencia Artificial bajo el framework Gemstack, inspiradas en Spec-Driven Development.
+
+## Article I: Library-First Principle
+Toda nueva funcionalidad DEBE nacer y estar estructurada preferentemente como una librería o módulo aislado y reutilizable. No implementes lógica compleja directamente en la capa de la aplicación/UI sin antes abstraerla.
+
+## Article II: CLI / Interface Mandate
+Cada módulo o librería clave debe tener una forma de probarse e interactuar textualmente (CLI, scripts independientes, peticiones directas de texto o JSON). Evita componentes opacos que solo puedan probarse levantando interfaces gráficas complejas.
+
+## Article III: Test-First Imperative (NON-NEGOTIABLE)
+NUNCA escribas el código de implementación antes que los tests (TDD).
+1. Escribe los tests (unitarios, de integración o contratos) basándote en la especificación.
+2. Si es posible, demuestra que fallan.
+3. Solo entonces, escribe la implementación real.
+
+## Article IV: Zero Assumptions (No Hallucinations)
+Si un requerimiento del humano es vago, la IA NO debe adivinar. 
+Debes usar el marcador literal `[NEEDS CLARIFICATION: <tu duda específica>]` en las especificaciones para forzar la clarificación humana (por ejemplo, al hablar de stacks, tipos de auth, retención de datos, etc.).
+
+## Article V: State & Guard Awareness
+Todo skill o agente DEBE verificar el estado local en `.gemstack/state.json` (incluyendo la spec activa y posibles `freeze` paths de `gemstack-guard`) antes de comenzar a ejecutar acciones destructivas o escrituras en el proyecto.
+
+## Article VI: [Project-Defined Governance]
+(Reservados para reglas específicas que el proyecto pueda inyectar en un futuro sobre versionamiento, observabilidad, etc.)
+
+## Article VII: Simplicity Gate
+Evita la sobreingeniería (over-engineering). 
+- No implementes abstracciones prematuras ni "future-proofing".
+- Usa la menor cantidad de proyectos/carpetas/herramientas posibles para satisfacer el MVP.
+Si debes romper esto, debes documentarlo en un "Complexity Tracking" en el plan.
+
+## Article VIII: Anti-Abstraction Gate
+Confía en el framework base. 
+Usa las funciones del framework y librerías estándar nativamente en lugar de crear tus propios wrappers o capas de abstracción innecesarias (ej. no hagas un wrapper sobre Node.js `fs` si no es crítico).
+
+## Article IX: Integration-First Testing
+Prioriza el testing realista. Si puedes probar el contrato real o la base de datos local real (con un entorno temporal) por encima de mocks complejos, hazlo. El código generado debe funcionar en la práctica.

package/.agents/rules/03-gemstack-security.md

@@ -0,0 +1,49 @@
+# Gemstack Security Core (Military-Grade Shielding)
+
+## Propósito
+Esta es la Ley de "Seguridad por Diseño". Todo código escrito, planificado o revisado por la IA bajo el marco Gemstack DEBE adherirse a estos principios de blindaje, independientemente del stack tecnológico utilizado. El objetivo es mitigar el 99% de las vulnerabilidades comunes (OWASP) desde el momento de la concepción del código.
+
+## 1. Cero Exposición de Credenciales (Zero Trust Secrets)
+- **Regla Estricta:** JAMÁS hardcodees contraseñas, llaves de API, secrets de Webhooks o URIs de bases de datos en el código fuente.
+- **Implementación:** Utiliza siempre variables de entorno (`.env`).
+- **Filtrado Frontend:** Asegúrate de que las variables sensibles nunca se empaqueten ni se envíen al lado del cliente (Navegador/App Móvil). Limpia los objetos antes de serializarlos.
+
+## 2. Aislamiento de Contexto (Prevención IDOR y Multi-Tenant)
+- **Regla Estricta:** Todo query de base de datos o mutación debe verificar la propiedad del recurso. Un Usuario A no puede acceder a los datos del Usuario B.
+- **Implementación:** Si el sistema es Multi-Tenant, todas las consultas DEBEN incluir el filtro del contexto (ej. `WHERE tenant_id = X AND user_id = Y`). Jamás confíes en un ID proporcionado en el payload sin validar que pertenece al usuario autenticado.
+
+## 3. Desconfianza Total del Cliente (Server-Side Validation)
+- **Regla Estricta:** "El frontend es solo una ilusión". Jamás confíes en validaciones, estados o permisos que vengan del cliente.
+- **Implementación:** Toda acción destructiva, de pago o acceso a datos debe ser re-validada en el backend (Server Actions / APIs). Verifica permisos de autorización en CADA endpoint.
+
+## 4. Protección contra Inyecciones (SQLi & XSS)
+- **Regla Estricta:** Queda prohibido concatenar strings para formar consultas a bases de datos.
+- **Implementación:** Utiliza siempre ORMs (ej. Prisma, Drizzle) o consultas parametrizadas puras. Para evitar XSS, sanitiza cualquier HTML o texto proveniente de los usuarios antes de renderizarlo.
+
+## 5. Integridad Financiera y Webhooks Criptográficos
+- **Regla Estricta:** Si el sistema procesa pagos, la IA NO debe diseñar tablas para almacenar tarjetas de crédito (PCI-DSS Mindset). Usa tokens delegados a proveedores seguros (Stripe, MercadoPago, etc.).
+- **Implementación:** Todo Webhook entrante que modifique estados financieros o de membresía DEBE verificar la firma criptográfica (Webhook Secret) provista por el servicio externo antes de ejecutar cualquier lógica.
+
+## 6. Ciclo de Vida de los Datos (Privacidad por Diseño)
+- **Regla Estricta:** Diseña con el "Derecho al Olvido" en mente.
+- **Implementación:** Almacena contraseñas usando hashes unidireccionales fuertes (ej. `bcrypt`, `argon2`). Sugiere implementaciones de borrado lógico (soft deletes) o retención efímera para datos altamente sensibles.
+
+## 7. Prevención de Condición de Carrera (Race Conditions) e Idempotencia
+- **Regla Estricta:** Toda transacción que afecte saldos, inventarios o estados críticos debe ser protegida contra concurrencia maliciosa (explotación de milisegundos).
+- **Implementación:** Usa bloqueos de base de datos (pessimistic/optimistic locks), Mutex, o transacciones serializables. Las APIs de pago o creación de recursos deben usar `Idempotency-Keys` para evitar cobros dobles si el cliente reintenta la petición.
+
+## 8. Prevención CSRF y SSRF (Server-Side Request Forgery)
+- **Regla Estricta:** Jamás permitas que un input de usuario dicte hacia dónde el servidor hace una petición HTTP, ni confíes en solicitudes sin validación de origen.
+- **Implementación:** Aplica tokens Anti-CSRF o cookies `SameSite=Strict`. Para evitar SSRF, si la app debe hacer peticiones a URLs externas (ej. webhooks), valida la URL contra una lista blanca (allowlist) y bloquea resoluciones a IPs locales (`127.0.0.1`, `169.254.169.254`, redes internas).
+
+## 9. Defensa de APIs (Rate Limiting y CORS)
+- **Regla Estricta:** Ninguna API pública puede existir sin límites de velocidad.
+- **Implementación:** Configura Rate Limiting (ej. 100 peticiones x minuto por IP/Usuario). Aplica políticas CORS estrictas que rechacen dominios no autorizados (jamás uses `Access-Control-Allow-Origin: *` en APIs autenticadas).
+
+## 10. Audit Trails (Bitácoras Inalterables)
+- **Regla Estricta:** Las acciones destructivas (DELETE) o escalamientos de privilegios deben dejar un rastro auditable.
+- **Implementación:** Guarda un registro (`AuditLog`) que contenga el `user_id`, la `ip_address`, el `action` y el `timestamp`.
+
+## 11. Hardening de Servidor Web (Security Headers)
+- **Regla Estricta:** El servidor no debe filtrar información de su tecnología y debe blindar el navegador del cliente.
+- **Implementación:** Desactiva la cabecera `X-Powered-By`. Fuerza siempre HTTPS usando `Strict-Transport-Security (HSTS)`. Implementa `Content-Security-Policy (CSP)` para evitar ejecución de scripts maliciosos de terceros.

package/.agents/rules/04-gemstack-infrastructure.md

@@ -0,0 +1,28 @@
+# Gemstack Cloud & Infrastructure Security (DevOps)
+
+## Propósito
+Esta regla aplica a todo diseño de arquitectura, scripts de despliegue (Docker, Terraform, CI/CD) o configuración de servidores generada por la IA. El objetivo es asegurar que la infraestructura que aloja la aplicación sea un búnker impenetrable.
+
+## 1. Principio de Menor Privilegio (IAM)
+- **Regla Estricta:** Ningún servidor, contenedor o pipeline de CI debe operar con credenciales de administrador global.
+- **Implementación:** Crea "Roles" o "Service Accounts" con permisos granulares. Por ejemplo, la instancia EC2/CloudRun solo debe tener permisos para leer el bucket S3 específico que necesita, y nada más. Evita los permisos tipo wildcard (`*`).
+
+## 2. Aislamiento de Red (VPC & Bases de Datos Invisibles)
+- **Regla Estricta:** Las bases de datos, cachés (Redis) y colas de mensajes JAMÁS deben ser accesibles desde el internet público.
+- **Implementación:** Despliega los recursos de datos en "Private Subnets" sin direcciones IP públicas. La aplicación backend se comunica internamente. Para mantenimiento, se debe usar un "Bastion Host" o túneles cifrados (ej. AWS Systems Manager o Cloud IAP).
+
+## 3. Infraestructura Inmutable (No a los Servidores "Mascota")
+- **Regla Estricta:** La infraestructura debe ser "Ganado, no Mascotas" (Cattle, not pets). Queda prohibido sugerir flujos donde un humano deba entrar por SSH a instalar cosas a mano en producción.
+- **Implementación:** Todo debe ser contenerizado (Docker) o gestionado por Infrastructure as Code (Terraform, Pulumi). Si un servidor es comprometido o falla, se debe poder destruir y recrear automáticamente sin pérdida de estado.
+
+## 4. Gestión de Secretos en Nube (Vault / Secret Manager)
+- **Regla Estricta:** Los archivos `.env` solo sirven para desarrollo local. En producción, la infraestructura no debe contener secretos quemados en disco.
+- **Implementación:** La infraestructura debe inyectar secretos en tiempo de ejecución o extraerlos de sistemas encriptados como AWS Secrets Manager, GCP Secret Manager o HashiCorp Vault.
+
+## 5. Protección de Perímetro (WAF & DDoS)
+- **Regla Estricta:** Ningún tráfico debe golpear la aplicación directamente sin ser filtrado por la capa Edge.
+- **Implementación:** Configura (o sugiere) la implementación de un WAF (Web Application Firewall) como Cloudflare, AWS WAF o Google Cloud Armor para filtrar bots maliciosos, DDoS y ataques OWASP a nivel de red antes de que toquen tus servidores Node/Python/Go.
+
+## 6. Encriptación Obligatoria (Transit & Rest)
+- **Regla Estricta:** Todo byte viaja y duerme encriptado.
+- **Implementación:** Fuerza HTTPS en los Load Balancers con terminación SSL. Todas las bases de datos y volúmenes de almacenamiento (S3, EBS) deben tener la encriptación en reposo activada (`encryption-at-rest`).

package/.agents/skills/gemstack-cso/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: gemstack-cso
+description: Auditoría de seguridad del código (Chief Security Officer).
+triggers:
+  - model_decision
+---
+
+# Gemstack CSO Skill
+
+Invocado mediante `/cso` o sus subcomandos:
+- `/security-audit`: Escaneo general de los puntos abajo.
+- `/security-idor`: Control de acceso (IDOR).
+- `/security-api`: CORS, Auth, Rate Limiting.
+- `/security-deps`: Dependencias vulnerables (npm audit).
+- `/security-uploads`: Magic bytes, ejecución de subidas.
+- `/security-sql`: Inyección SQL, Prepared statements.
+- `/security-sessions`: Tokens, HttpOnly cookies.
+- `/security-webhooks`: Validación de firmas.
+- `/security-headers`: XSS, CSP.
+
+## Proceso:
+1. Analiza el código actual en busca de vulnerabilidades de seguridad (OWASP Top 10, ASVS).
+2. VERIFICACIÓN CRÍTICA (APPSEC): Lee y aplica todas las leyes de `.agents/rules/03-gemstack-security.md`.
+3. VERIFICACIÓN CRÍTICA (DEVSEC): Lee y aplica todas las leyes de `.agents/rules/04-gemstack-infrastructure.md` al revisar Dockerfiles, Terraform o CI/CD.
+4. Presta especial atención a:
+   - Inyección (XSS, SQLi) y Lógica de Negocio (Race Conditions, Idempotencia).
+   - Manejo de secretos (¿Hay tokens hardcodeados o `.env` en producción?).
+   - Verificación de IDOR (Aislamiento Multi-Tenant) y Falsificación (CSRF/SSRF).
+   - Firmas criptográficas en Webhooks, Rate Limiting y Security Headers.
+   - Aislamiento de Red y Privilegios Mínimos (VPCs, IAM).
+5. Genera un reporte exhaustivo y guárdalo en `docs/security/latest-security-audit.md`.
+6. Si encuentras brechas, no ofrezcas sugerencias pasivas: INICIA UNA ALERTA y propón el parche de seguridad inmediatamente.
+
+## Generación de Reporte:
+Cada reporte de seguridad debe agrupar los hallazgos por severidad:
+- **Critical**
+- **High**
+- **Medium**
+- **Low**
+- **Informational**
+
+Y asignar un estado a cada ítem:
+- **Fixed**
+- **Needs approval**
+- **Manual review required**
+- **Not applicable**
+
+## Acciones:
+Los fixes simples pueden automatizarse. Cambios en auth/sesiones son críticos y siempre entran como "Needs approval" requiriendo permiso explícito antes de generar código.
+

package/.agents/skills/gemstack-dashboard/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gemstack-dashboard
+description: Genera una interfaz gráfica (Generative UI) interactiva para visualizar el progreso del proyecto, las tareas pendientes y el estado del CI/CD.
+triggers:
+  - model_decision
+---
+
+# Gemstack Dashboard Skill
+
+Invocado mediante `/dashboard` o `/ui`.
+
+## Proceso:
+1. Analiza el estado actual del proyecto leyendo los siguientes archivos (si existen):
+   - `specs/current/tasks.md` (Para calcular el % de progreso y tareas `[ ]`, `[/]`, `[x]`).
+   - `.gemstack/state.json` (Para ver en qué fase nos encontramos).
+   - `docs/security/latest-security-audit.md` (Para extraer el último reporte de seguridad).
+2. Genera un archivo HTML utilizando **Generative UI**. El archivo debe llamarse `gemstack-dashboard.html` y guardarse en el directorio de artefactos usando la herramienta `write_to_file` con `UserFacing: true`.
+3. El HTML DEBE usar TailwindCSS (vía el CDN autorizado de Antigravity) y variables semánticas (`var(--background)`, `var(--foreground)`, `var(--card)`, etc.).
+4. El HTML debe incluir:
+   - Una barra de progreso hermosa basada en el % de tareas completadas.
+   - Una lista visual de las tareas pendientes y completadas.
+   - Un panel resumen del estado de seguridad y fase del proyecto.
+   - Una estética premium, limpia y moderna.
+5. Embebe el widget en tu respuesta de chat utilizando:
+   `<agent-embed src="file:///<artifact_path>/gemstack-dashboard.html"></agent-embed>`
+
+## Reglas de Diseño de Interfaz:
+- `<body class="bg-transparent text-[var(--foreground)] antialiased p-5">`
+- Contenedores principales: `class="bg-[var(--card)] border border-[var(--border)] rounded-xl p-5 shadow-sm"`
+- Mantén el diseño compacto para que quepa cómodamente en el chat (menos de 500px de altura si es posible).
+- Usa JavaScript embebido si necesitas procesar datos estáticos pasados al HTML en el momento de generación.

package/.agents/skills/gemstack-guard/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gemstack-guard
+description: Activa y desactiva restricciones y protecciones de archivos y comandos.
+triggers:
+  - model_decision
+---
+
+# Gemstack Guard Skill
+
+Gestiona los comandos `/careful`, `/freeze`, `/guard` y `/unfreeze` alterando `.gemstack/state.json`.
+
+## Comandos:
+- `/careful`: Advertir SIEMPRE al usuario antes de ejecutar cualquier comando destructivo o potencialmente riesgoso (rm, drop, format, etc.). Cambia `guard_mode.careful` a `true` en el state.json.
+- `/freeze <paths>`: Limitar explícitamente los archivos editables a los paths definidos. Cambia `guard_mode.freeze` a `true` y añade a `allowed_paths`.
+- `/guard`: Activa tanto `/careful` como `/freeze` simultáneamente.
+- `/unfreeze`: Quita todas las restricciones de freeze y allowed_paths.
+
+Debes actualizar `.gemstack/state.json` reflejando el cambio y confirmarlo al usuario.
+

package/.agents/skills/gemstack-handoff/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gemstack-handoff
+description: Procedimiento estricto para crear o actualizar el handoff al final de la sesión.
+triggers:
+  - model_decision
+---
+
+# Gemstack Handoff Skill
+
+Esta habilidad se ejecuta cuando el usuario pide terminar la sesión, invoca `/handoff` o pide preparar el handoff.
+
+## Instrucciones Estrictas:
+1. Lee el archivo `handoff.md` actual en la raíz del proyecto.
+2. Actualiza las secciones "1. Objetivo" y "2. Estado actual" basado en lo logrado en esta sesión.
+3. Enumera en "3. Archivos y cambios" los archivos modificados.
+4. **CRÍTICO:** NO borres las entradas existentes bajo "4. Intentos fallidos". Si hiciste nuevos descubrimientos de enfoques que no funcionan, añádelos.
+5. **ARCHIVADO SEGURO:** Si "Intentos fallidos" en `handoff.md` tiene demasiados puntos (más de 10-15), CORTA los elementos más antiguos y pégalos en `handoff_archive.md` bajo su lista, conservando solo los 3-5 intentos recientes en `handoff.md`.
+6. Define los "5. Próximos pasos" exactos para la próxima sesión.
+7. Guarda los cambios en `handoff.md` (y `handoff_archive.md` si fue necesario).
+8. Despídete del usuario indicando que el handoff está listo.
+

package/.agents/skills/gemstack-heal/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gemstack-heal
+description: Auto-Sanación de CI/CD leyendo logs y resolviendo errores.
+triggers:
+  - model_decision
+---
+
+# Gemstack Heal Skill
+
+Invocado mediante `/heal`.
+
+## Proceso:
+1. Utiliza el CLI de GitHub (`gh run list --limit 1` y `gh run view --log-failed`) o pide al usuario que te pegue los logs del CI fallido.
+2. Analiza los logs para encontrar la causa raíz (Errores de Sintaxis, Pruebas Fallidas, Problemas de Dependencias).
+3. Utiliza la directiva "No Fixes Before Investigation" de Gemstack. Lee los archivos afectados.
+4. Redacta la solución, modifica los archivos localmente.
+5. Ejecuta las pruebas locales relevantes (ej. `npm run ci:all`).
+6. Si pasan las pruebas, realiza un commit `fix(ci): auto-healing build failure` y haz `git push` automáticamente (si el usuario lo permite).
+7. Reporta la sanación completada.

package/.agents/skills/gemstack-investigate/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: gemstack-investigate
+description: Investiga bugs antes de proponer código (No fixes before investigation).
+triggers:
+  - model_decision
+---
+
+# Gemstack Investigate Skill
+
+Invocado mediante `/investigate`.
+
+## Principio: No fixes before investigation
+El objetivo es aislar la causa raíz antes de proponer código.
+
+## Proceso:
+1. Reproducir o entender el bug a fondo.
+2. Leer el flujo de datos.
+3. Formular una hipótesis clara sobre el error.
+4. Probar la hipótesis (mediante logs, scripts de scratch o pruebas).
+5. Proponer el fix mínimo.
+
+## Reglas Estrictas:
+- **Límite de Intentos:** Detente tras 3 intentos fallidos y pide ayuda al usuario para que no entres en un bucle ciego.
+- **Registro:** Documenta los intentos fallidos relevantes en `handoff.md` (bajo la sección Intentos fallidos) para preservar contexto.
+

package/.agents/skills/gemstack-learn/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-learn
+description: Memoria a largo plazo del agente. Añade, busca o depreca aprendizajes.
+triggers:
+  - model_decision
+---
+
+# Gemstack Learn Skill
+
+Se invoca mediante `/learn`.
+
+## Proceso:
+1. El usuario indicará qué aprendizaje debe registrar o si desea listar/buscar.
+2. Todo el conocimiento se gestiona en el archivo `.gemstack/learnings.md`.
+3. Para **agregar**: Pon el nuevo aprendizaje bajo "## Aprendizajes Activos".
+4. Para **buscar/listar**: Lee el archivo e informa al usuario.
+5. Para **marcar obsoleto**: Mueve el aprendizaje de "Activos" a "## Aprendizajes Obsoletos".
+

package/.agents/skills/gemstack-office-hours/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-office-hours
+description: Sesión interactiva de diseño y arquitectura. Similar a /grill-me.
+triggers:
+  - model_decision
+---
+
+# Gemstack Office Hours Skill
+
+Se invoca mediante `/office-hours`.
+
+## Instrucciones:
+1. Asume el rol de un Arquitecto Principal o Tech Lead experimentando.
+2. Inicia un diálogo interactivo: haz preguntas profundas sobre diseño, trade-offs, escalabilidad o los requisitos actuales.
+3. NO generes código inmediatamente. El objetivo es alinear ideas, resolver ambigüedades y descubrir edge cases.
+4. Sugiere enfoques alternativos si ves riesgos en la propuesta del usuario.
+5. Al final de la conversación, si han llegado a una conclusión, ofrece invocar el flujo `/specify` o actualizar `handoff.md`.
+

package/.agents/skills/gemstack-plan/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: gemstack-plan
+description: Convierte spec.md en un plan técnico.
+triggers:
+  - model_decision
+---
+
+# Gemstack Plan Skill
+
+Invocado mediante `/plan`.
+
+## Proceso:
+1. Lee `specs/[nombre-feature]/spec.md` e identifica la feature actual.
+2. Si es necesario, genera `research.md` con un análisis de herramientas técnicas.
+3. Evalúa la "Constitution Check" (.agents/rules/02-gemstack-constitution.md) antes de tomar decisiones (asegura TDD, CLI-First, simplicidad).
+4. Genera `specs/[nombre-feature]/plan.md` usando `specs/templates/plan.md`.
+5. Detalla el stack y llena la tabla "Complexity Tracking" SÓLO si rompiste alguna regla de la constitución y necesitas justificarlo.
+6. Opcionalmente, genera los entregables satélites: `data-model.md`, `contracts/` (para APIs/Interfaces), y `quickstart.md`.
+7. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
+

package/.agents/skills/gemstack-qa/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gemstack-qa
+description: Pruebas funcionales de los requerimientos implementados.
+triggers:
+  - model_decision
+---
+
+# Gemstack QA Skill
+
+Invocado mediante `/qa` o `/qa-only`.
+
+## Proceso:
+1. Identifica la funcionalidad actual y lee los Criterios de Aceptación en `specs/[nombre-feature]/spec.md`.
+2. Revisa el código o instruye la ejecución de tests si existen.
+3. Si la aplicación es visual, recomienda `/browser` o correr tests de Playwright para verificar manualmente la UI.
+4. Genera un breve reporte indicando si cada Criterio pasó o falló.
+

package/.agents/skills/gemstack-qa-visual/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gemstack-qa-visual
+description: QA Visual Autónomo vía scripts de navegador.
+triggers:
+  - model_decision
+---
+
+# Gemstack QA Visual Skill
+
+Invocado mediante `/qa-visual`.
+
+## Proceso:
+1. Analiza los Criterios de Aceptación del UI en el `spec.md` activo.
+2. Si tienes la capacidad de interactuar con navegadores de forma nativa, utilízala. De lo contrario, crea un script efímero en la carpeta `.gemstack/scratch/` utilizando Node.js (Fetch/DOM parsing).
+3. Si el usuario cuenta con Playwright/Puppeteer instalado, genera y ejecuta los scripts de UI de forma aislada.
+4. Genera un reporte detallado con los hallazgos en `docs/qa/latest-visual-qa.md`.
+5. Si encuentras un fallo crítico visual o de flujo, propón un fix inmediatamente.

package/.agents/skills/gemstack-resume/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-resume
+description: Procedimiento para retomar una sesión de trabajo usando handoff.md.
+triggers:
+  - model_decision
+---
+
+# Gemstack Resume Skill
+
+Esta habilidad se ejecuta cuando el usuario inicia una sesión y escribe `/resume`.
+
+## Instrucciones:
+1. Lee `handoff.md`.
+2. Lee `.gemstack/state.json` para restaurar el estado, el spec activo y si hay guard/freeze activado.
+3. Haz un breve resumen de 2-3 líneas para el usuario.
+4. Si hay "Intentos fallidos" relevantes en `handoff.md`, menciónalos brevemente.
+5. Pregunta al usuario si debes proceder con el primer paso o si hay algún cambio de prioridad.
+

package/.agents/skills/gemstack-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-review
+description: Revisa el código recién escrito antes de confirmarlo o enviarlo.
+triggers:
+  - model_decision
+---
+
+# Gemstack Review Skill
+
+Invocado mediante `/review`.
+
+## Proceso:
+1. Analiza el código modificado (git diff, o archivos editados).
+2. Verifica que las convenciones arquitectónicas del proyecto se respeten.
+3. VERIFICACIÓN DE SEGURIDAD: Revisa obligatoriamente `.agents/rules/03-gemstack-security.md` para garantizar que el código propuesto no introduzca brechas de seguridad (IDOR, XSS, tokens expuestos).
+4. Verifica que los tests cubran adecuadamente los cambios.
+5. Emite sugerencias o aplica correcciones automáticas si son triviales.
+6. Si el código está listo, sugiere `/qa` o `/ship`.

package/.agents/skills/gemstack-sandbox/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gemstack-sandbox
+description: Ejecución segura de código dentro de contenedores efímeros Docker.
+triggers:
+  - model_decision
+---
+
+# Gemstack Sandbox Skill
+
+Invocado mediante `/sandbox`.
+
+## Proceso:
+1. Asegúrate de que `docker` esté disponible en el entorno del usuario (`docker --version`).
+2. Recibe el comando o script que el usuario (o tú mismo) desea probar (por ejemplo, una instalación de dependencias no confiables, o una validación CSO).
+3. Construye el comando de ejecución envuelto en docker: `docker run --rm -v $(pwd):/app -w /app node:20 <comando>`.
+   *(Nota: en entornos Windows PowerShell ajusta la ruta del volumen a `${PWD}`)*
+4. Ejecuta el contenedor, captura los logs de stdout y stderr.
+5. Limpia los contenedores residuales si el script falla críticamente.
+6. Presenta los resultados de la ejecución segura al usuario sin haber alterado el entorno nativo.

package/.agents/skills/gemstack-ship/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gemstack-ship
+description: Procedimiento de cierre, limpieza y despliegue opcional de la funcionalidad.
+triggers:
+  - model_decision
+---
+
+# Gemstack Ship Skill
+
+Invocado mediante `/ship`.
+
+## Proceso:
+1. Verifica revisión (`/review`) y validación (`/qa`).
+2. Confirma validación de seguridad (`/cso`).
+3. Comprueba si los specs se cumplieron.
+4. Genera un PR summary si se pide.
+5. NO hagas push, merge o deploy sin aprobación explícita.
+6. Sugiere ejecutar `/handoff` para documentar la entrega en la memoria del proyecto.
+

package/.agents/skills/gemstack-spec/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gemstack-spec
+description: Product Manager que implementa el primer paso de Spec-Driven Development. Genera spec.md.
+triggers:
+  - model_decision
+---
+
+# Gemstack Specify Skill
+
+Invocado mediante `/specify`.
+
+## Rol
+Eres un Product Manager técnico. Tu objetivo es convertir ideas vagas en requisitos claros y funcionales.
+
+## Proceso:
+1. Pregunta al usuario cuál es la nueva funcionalidad si no la ha descrito.
+2. Identifica un nombre de rama o carpeta para la feature (ej. `specs/004-nueva-feature/`).
+3. Genera el archivo `specs/[nombre-feature]/spec.md` usando la plantilla `specs/templates/spec.md`.
+4. El documento DEBE incluir: Historias de usuario priorizadas (P1, P2) que sean independientemente testeables, Criterios de Éxito medibles, y Casos Extremos.
+5. **CERO SUPOSICIONES**: Si el usuario omitió detalles, NO adivines. Usa el marcador `[NEEDS CLARIFICATION: tu duda]` en el documento.
+6. No describas implementación técnica (nada de stacks, bases de datos o APIs). Concéntrate estrictamente en el "Qué" y "Por qué".
+7. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa: `{"active_spec": "specs/[nombre-feature]/"}` y el timestamp.
+8. Una vez finalizado, indica al usuario que puede revisar la especificación y, tras resolver las dudas, ejecutar `/plan`.
+

package/.agents/skills/gemstack-swarm/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-swarm
+description: Orquestador de enjambre de subagentes para tareas paralelas.
+triggers:
+  - model_decision
+---
+
+# Gemstack Swarm Skill
+
+Invocado mediante `/swarm` o cuando el plan contenga tareas `[P]`.
+
+## Proceso:
+1. Lee `tasks.md` y recolecta todas las tareas etiquetadas con `[P]`.
+2. Utiliza tu capacidad de `invoke_subagent` (si está disponible en tu runtime) para lanzar un subagente paralelo por cada tarea `[P]`.
+3. Asigna a cada subagente un contexto claro (el `spec.md`, el `plan.md` y la tarea específica).
+4. Usa `send_message` para coordinar el trabajo si los subagentes necesitan unirse o dependen de una interfaz común.
+5. Espera a que todos los subagentes terminen, evalúa sus respuestas y haz merge de los resultados.
+6. Actualiza `tasks.md` marcando las tareas `[x]` a medida que los subagentes las completen.

package/.agents/skills/gemstack-tasks/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gemstack-tasks
+description: Convierte un plan.md en tareas ejecutables.
+triggers:
+  - model_decision
+---
+
+# Gemstack Tasks Skill
+
+Invocado mediante `/tasks`.
+
+## Proceso:
+1. Lee `specs/[nombre-feature]/plan.md` y, si existen, `data-model.md` y la carpeta `contracts/`.
+2. Convierte los contratos, entidades y el plan en una lista estricta de ejecución en `specs/[nombre-feature]/tasks.md` usando la plantilla `specs/templates/tasks.md`.
+3. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
+4. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
+5. Ofrece al usuario comenzar automáticamente con la primera tarea o delegar a subagentes paralelos si hay múltiples `[P]`.
+

package/.gemstack/learnings.md

@@ -0,0 +1,8 @@
+# Gemstack Learnings
+
+Este archivo almacena aprendizajes persistentes que el agente debe recordar en el futuro.
+El skill `gemstack-learn` gestiona este archivo.
+
+## Aprendizajes Activos
+
+## Aprendizajes Obsoletos

package/.gemstack/state.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.1",
+  "current_phase": "idle",
+  "active_spec": null,
+  "guard_mode": {
+    "careful": false,
+    "freeze": false,
+    "allowed_paths": []
+  },
+  "last_update": "2026-08-30T11:10:00Z"
+}

package/.gitattributes

@@ -0,0 +1,19 @@
+* text=auto
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.sh text eol=lf
+*.ps1 text eol=crlf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.sqlite binary
+*.db binary
+*.tgz binary
+*.zip binary