gemstack-ai 1.0.1

package/template/.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/template/.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/template/.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/template/.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/template/.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/template/.gemstack/learnings.md

@@ -0,0 +1,3 @@
+# Gemstack Learnings
+
+Empty state.

package/template/.gemstack/state.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.2.0",
+  "initialized": true
+}

package/template/docs/antigravity.md

@@ -0,0 +1,6 @@
+# Integración con Google Antigravity
+
+Gemstack aprovecha el ecosistema nativo de Antigravity:
+- **Rules (`.agents/rules/`)**: Mapea pseudo-comandos (ej. `/handoff`) para guiar a Gemini.
+- **Skills (`.agents/skills/`)**: Utiliza *Progressive Disclosure* mediante validaciones de frontmatter `triggers`.
+- **Compatibilidad Dual**: Scripts integrados garantizan que puedes testear el contexto y estado tanto desde Unix (`./bin/gemstack`) como de Windows de forma nativa (`.\bin\gemstack.ps1`).

package/template/docs/handoff.md

@@ -0,0 +1,9 @@
+# El Sistema Handoff
+
+El archivo `handoff.md` es la memoria de tu proyecto. 
+
+## Reglas
+1. Siempre se genera o actualiza al final de la sesión.
+2. Contiene 5 partes: Objetivo, Estado actual, Archivos tocados, Intentos fallidos y Próximos pasos.
+3. **Intentos Fallidos NUNCA se borran**: Previenen que Gemini cometa el mismo error (loops de debugging).
+4. **Archive**: Para evitar que consuma toda la ventana de contexto, el agente mueve las entradas antiguas a `handoff_archive.md` cuando la lista crece demasiado, pero mantiene siempre viva la referencia.

package/template/docs/qa/latest-qa.md

@@ -0,0 +1,25 @@
+# Latest QA Report
+**Date:** 2026-08-19
+
+## QA Flow: SecureDocs
+
+### Entorno de Prueba
+- Node.js (v18+)
+- Automatizado vía `npm run smoke`
+
+### Resultados de Smoke Tests
+Los smoke tests ejecutaron exitosamente los siguientes escenarios:
+- `[OK]` Users fetched correctly
+- `[OK]` Alice created document
+- `[OK]` Bob blocked from reading Alice's doc (Status 404)
+- `[OK]` Bob blocked from deleting Alice's doc (Status 404)
+- `[OK]` Bob created doc with malicious payload
+- `[OK]` Malicious payload ignored: Doc does not belong to Alice
+- `[OK]` Malicious payload ignored: Doc belongs to Bob safely
+
+### Casos de Prueba Ejecutados Manualmente / API
+1. **[PASS] Selección de Usuario:** Cambiar en el `<select>` entre Alice y Bob recarga exitosamente la lista de documentos (`loadDocs`).
+2. **[PASS] Testing XSS Básico:** Se inyectó `<script>alert("Hacked")</script>` en el título. El documento se listó en la UI de Alice como un string literal gracias a la codificación DOM generada por `textContent`.
+
+### Conclusión
+- Todos los smoke tests pasan con exit code `0`. Sin bugs bloqueantes detectados. El QA confirma la mitigación de IDOR.

package/template/docs/qa-browser.md

@@ -0,0 +1,7 @@
+# QA & Browser Testing
+
+Usa `/qa` o `/qa-only` para validar tu código contra el `spec.md`.
+
+## Herramientas Visuales
+Si desarrollas frontend, puedes pedirle a Antigravity que abra el navegador usando su comando nativo `/browser` para navegar por el sitio local y validar el UI manualmente.
+Alternativamente, si tienes pruebas e2e automatizadas con **Playwright** o **Cypress**, Gemstack puede ejecutarlas y parsear sus resultados durante la fase de QA.

package/template/docs/quickstart.md

@@ -0,0 +1,21 @@
+# Gemstack Quickstart
+
+1. **Inicializa el entorno**: 
+   - *Unix:* `./bin/gemstack init`
+   - *Windows:* `.\bin\gemstack.ps1 init`
+2. **Valida la instalación**:
+   - *Unix:* `./bin/gemstack doctor`
+   - *Windows:* `.\bin\gemstack-doctor.ps1`
+3. **Tu primera sesión**:
+   - Inicia con `/office-hours` para discutir la arquitectura.
+   - Escribe `/specify quiero añadir autenticación con JWT`.
+   - Revisa `specs/current/spec.md`.
+   - Escribe `/plan` para generar la estrategia técnica.
+   - Escribe `/tasks` para desglosar la implementación.
+   - Escribe `/review` para chequear tu código.
+4. **Validación y Cierre**:
+   - Corre `/cso` y `/qa`.
+   - Escribe `/ship` para preparar los commits.
+5. **Pausa**: Escribe `/handoff` al final de la sesión.
+6. **Retorno**: Abre chat limpio y escribe:
+   > "Lee handoff.md y continúa desde los próximos pasos"

package/template/docs/release.md

@@ -0,0 +1,10 @@
+# Release Flow (Ship)
+
+El flujo de liberación `/ship` se asegura de que todo esté en orden:
+
+1. **Tests**: El agente valida que se pasen las pruebas.
+2. **Review**: Ejecución de linting, typechecking y revisión humana de las especificaciones de `specs/current/`.
+3. **Doctor Check**: Antes de preparar un release local, se debe validar el entorno con al menos uno de estos caminos:
+   - **Unix/Git Bash:** `./bin/gemstack-doctor`
+   - **PowerShell:** `.\bin\gemstack-doctor.ps1`
+4. **Deploy**: **Regla estricta:** el agente JAMÁS hará un `git push`, merge o lanzará un script de deploy sin explícita aprobación humana.

package/template/docs/reviews/latest-review.md

@@ -0,0 +1,19 @@
+# Latest Review
+**Date:** 2026-08-19
+
+## Overview
+Revisión de la implementación de `demo-app/` (SecureDocs) incluyendo los nuevos Smoke Tests.
+
+## Archivos Revisados
+- `smoke-test.js`: Script Node nativo impecable. Utiliza `child_process.spawn` para ciclo de vida de servidor y `http.request` emulando fetch para evitar dependencias.
+- `server.js`: Se añadió `/api/health`. Mantiene la robustez en validación de `user_id`.
+- `database.js`: Estable.
+- `package.json`: Actualizado correctamente con script `smoke`.
+- `.gitignore`: Confirmado. Ignora `node_modules/` y `*.sqlite`.
+
+## Hallazgos
+- **Fixed:** El script `smoke-test.js` no usa dependencias de terceros ni emojis, previniendo mojibakes en consola.
+- **Not blocking:** No se añadió librería externa de testeo como Jest/Mocha. Aceptable dado el requerimiento de zero-deps y ser una demo simple.
+- **Follow-up for v0.2:** Desacoplar la DB y el Server en la inicialización para permitir testeo en memoria sin levantar un puerto real (Supertest-like nativo).
+
+**Decisión**: APPROVED para v0.1 release.

package/template/docs/security/latest-security-audit.md

@@ -0,0 +1,37 @@
+# Latest Security Audit
+**Date:** 2026-08-19
+
+## CSO Report: SecureDocs Demo
+
+### 1. IDOR (Insecure Direct Object Reference)
+- **Status:** [Fixed]
+- **Severity:** Critical
+- **Detail:** Verificado por test automatizado `smoke-test.js`. Endpoint `/api/docs/:id` devuelve 404 al intentar cruzar scopes. Además, se validó que inyectar explícitamente `{"user_id": 1}` en el body de POST `/api/docs` es ignorado a favor del user extraído del header mock.
+
+### 2. SQL Injection
+- **Status:** [Fixed]
+- **Severity:** High
+- **Detail:** Se utilizan sentencias preparadas de `sqlite3` (`db.run(..., [params])`).
+
+### 3. Headers & XSS
+- **Status:** [Fixed]
+- **Severity:** Medium
+- **Detail:** Middleware in-line aplica `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, y `Content-Security-Policy`. Uso de `textContent` en Vanilla JS neutraliza XSS reflejado/almacenado probado.
+
+### 4. Database File Handling
+- **Status:** [Fixed]
+- **Severity:** High
+- **Detail:** `securedocs.sqlite` explícitamente añadido a `.gitignore`. Previene fuga de datos en Git.
+
+### 5. Authentication Mock
+- **Status:** [Manual review required]
+- **Severity:** Informational
+- **Detail:** Se usa un header `X-Mock-User-Id` en texto plano.
+- **Decisión:** Riesgo documentado y aceptado (by design) en el alcance de la demo.
+
+### 6. CORS / Rate Limiting
+- **Status:** [Not applicable]
+- **Severity:** Low
+- **Detail:** No hay librerías de CORS habilitadas lo cual restringe el dominio cruzado por defecto a *same-origin*. No hay Rate Limiting pero siendo una demo local no presenta superficie de ataque expuesta a internet.
+
+**Decisión General**: APPROVED. Smoke tests automatizados garantizan mitigación de los riesgos top reportados.

package/template/docs/security.md

@@ -0,0 +1,17 @@
+# Seguridad Práctica en Gemstack (CSO)
+
+Gemstack incluye el skill `gemstack-cso`, que actúa como tu Chief Security Officer virtual.
+
+Invócalo mediante `/cso` (para una revisión general) o mediante sus sub-comandos para revisiones específicas.
+
+## Módulos de Revisión:
+1. `/security-idor`: Control de acceso y pertenencia de recursos.
+2. `/security-api`: CORS, Rate Limiting, y autenticación.
+3. `/security-deps`: Análisis de `package.json` o `requirements.txt`.
+4. `/security-uploads`: Validación rigurosa de magic bytes en subidas.
+5. `/security-sql`: Prevención de Inyección SQL.
+6. `/security-sessions`: Revisión de estrategias de tokens y cookies.
+7. `/security-webhooks`: Verificación de firmas de Stripe/PayPal.
+8. `/security-headers`: CSP y protección XSS.
+
+**Guardrail:** El CSO puede corregir código trivial de seguridad, pero cambios mayores (migraciones, auth) requieren un Plan de Seguridad y tu aprobación explícita.

package/template/docs/skills.md

@@ -0,0 +1,17 @@
+# Skills & Pseudo-comandos
+
+Gemstack vincula pseudo-comandos a Skills específicos:
+
+- `/handoff` -> `gemstack-handoff`
+- `/resume` -> `gemstack-resume`
+- `/office-hours` -> `gemstack-office-hours`
+- `/specify` -> `gemstack-spec`
+- `/plan` -> `gemstack-plan`
+- `/tasks` -> `gemstack-tasks`
+- `/review` -> `gemstack-review`
+- `/investigate` -> `gemstack-investigate`
+- `/cso`, `/security-*` -> `gemstack-cso`
+- `/qa`, `/qa-only` -> `gemstack-qa`
+- `/ship` -> `gemstack-ship`
+- `/learn` -> `gemstack-learn`
+- `/careful`, `/freeze`, `/guard`, `/unfreeze` -> `gemstack-guard`

package/template/docs/spec-driven-development.md

@@ -0,0 +1,10 @@
+# Spec-Driven Development (SDD) en Gemstack
+
+Inspirado en Spec Kit, Gemstack obliga a pensar antes de teclear.
+
+1. **El Qué (`spec.md`)**: Requisitos funcionales, criterios de aceptación (checkboxes) y casos límite. No tiene detalles de implementación.
+2. **El Cómo (`plan.md`)**: Arquitectura, esquema de base de datos, rutas, y dependencias necesarias.
+3. **El Cuándo (`tasks.md`)**: Pasos lógicos a seguir para construirlo.
+
+Usa `/specify` para comenzar este ciclo.
+Una vez que el spec esté aprobado por el usuario, usa `/plan` y luego `/tasks`.

package/template/handoff.md

@@ -0,0 +1,11 @@
+# Handoff
+
+## 1. Objetivo
+
+## 2. Estado actual
+
+## 3. Archivos y cambios
+
+## 4. Intentos fallidos
+
+## 5. Próximos pasos

package/template/handoff_archive.md

@@ -0,0 +1,3 @@
+# Handoff Archive
+
+Archived entries will be moved here.

package/template/specs/current/plan.md

@@ -0,0 +1,5 @@
+# Plan Template
+
+## Architecture
+
+## Files

package/template/specs/current/spec.md

@@ -0,0 +1,7 @@
+# Spec Template
+
+## Goal
+
+## Acceptance Criteria
+
+## Edge Cases

package/template/specs/current/tasks.md

@@ -0,0 +1,3 @@
+# Tasks Template
+
+- [ ] Task 1

package/template/specs/templates/plan.md

@@ -0,0 +1,38 @@
+# Plan de Implementación: [FEATURE]
+
+**Feature Branch**: `[###-feature-name]` | **Spec**: [ruta al spec.md]
+
+## 1. Summary & Technical Context
+- **Lenguaje/Versión**: [Ej. Node 18+ o NEEDS CLARIFICATION]
+- **Dependencias core**: [Ej. Express o NEEDS CLARIFICATION]
+- **Restricciones**: [Ej. Zero-deps en runtime]
+
+## 2. Constitution Check (Phase -1 Gates)
+<!-- VERIFICACIÓN DE REGLAS INMUTABLES -->
+### Simplicity Gate (Article VII)
+- [ ] ¿Se usan el mínimo número de carpetas/archivos posibles?
+- [ ] ¿No hay abstracciones prematuras (future-proofing)?
+
+### Anti-Abstraction Gate (Article VIII)
+- [ ] ¿Se usan las APIs nativas del framework sin wrappers innecesarios?
+
+### Test-First Imperative (Article III)
+- [ ] ¿El plan incluye la creación de tests antes que el código fuente?
+
+## 3. Entregables Satélites a Generar
+<!-- Además de este plan y las tareas, se deben documentar los siguientes si aplica: -->
+- `research.md`: [Opcional - Análisis de herramientas]
+- `data-model.md`: [Esquemas de datos y entidades]
+- `contracts/`: [Documentación de APIs y contratos (REST/Interfaces)]
+- `quickstart.md`: [Guía rápida de validación manual]
+
+## 4. Estructura de Archivos a Modificar / Crear
+```text
+ruta/archivo: [Razón]
+```
+
+## 5. Complexity Tracking
+<!-- Llenar SÓLO si las Gates de la Constitución fallan y se requiere justificar complejidad -->
+| Violación de Regla | Por qué es necesario | Alternativa simple rechazada por |
+|--------------------|----------------------|-----------------------------------|
+| [Ej. Wrapper]      | [Razón]              | [Razón]                           |

package/template/specs/templates/spec.md

@@ -0,0 +1,35 @@
+# Especificación de Funcionalidad: [NOMBRE_FEATURE]
+
+**Feature Branch**: `[###-feature-name]`
+
+## 1. User Scenarios & Testing (MVP)
+<!--
+  IMPORTANTE: Las historias de usuario deben estar PRIORIZADAS (P1, P2...).
+  Cada historia debe ser INDEPENDIENTEMENTE TESTEABLE, aportando un fragmento de valor MVP.
+-->
+### User Story 1 - [Título breve] (Prioridad: P1)
+[Describe el viaje del usuario en lenguaje claro]
+**Por qué esta prioridad:** [Valor que aporta]
+**Test Independiente:** [Cómo se prueba de forma autónoma]
+
+**Escenarios de Aceptación:**
+1. **Dado** [estado], **Cuando** [acción], **Entonces** [resultado]
+
+## 2. Requerimientos Funcionales
+<!--
+  Anota requerimientos explícitos.
+  SI HAY AMBIGÜEDAD, NO ADIVINES. Usa: [NEEDS CLARIFICATION: tu pregunta]
+-->
+- **FR-001**: El sistema DEBE [capacidad]
+- **FR-002**: [NEEDS CLARIFICATION: método de implementación no definido]
+
+## 3. Criterios de Éxito (Measurable Outcomes)
+<!-- Definir métricas que no dependan de la tecnología -->
+- **SC-001**: [Métrica medible, ej. El proceso termina en < 2 seg]
+
+## 4. Casos Extremos (Edge Cases)
+- ¿Qué pasa cuando [condición de borde]?
+
+## 5. Entidades Clave (Data / Models)
+- **[Entidad 1]**: [Representación abstracta]
+- **[Entidad 2]**: [Relación]

package/template/specs/templates/tasks.md

@@ -0,0 +1,21 @@
+# Tareas de Implementación
+
+<!--
+  Instrucciones:
+  - Marca con `[P]` las tareas que sean seguras de paralelizar (por ej. si usas múltiples subagentes).
+  - Incluye la redacción y validación de TESTS ANTES de la implementación real.
+-->
+
+## Fase 1: Tests (Test-First Imperative)
+- [ ] 1.1 Redactar Unit Tests para [Módulo A].
+- [ ] 1.2 [P] Redactar Tests de Contrato/API para [Contrato B].
+- [ ] 1.3 Comprobar que los tests fallen (Fase Roja).
+
+## Fase 2: Implementación
+- [ ] 2.1 Implementar [Módulo A] para hacer pasar 1.1.
+- [ ] 2.2 [P] Implementar [Controlador B] para hacer pasar 1.2.
+
+## Fase 3: Integración y Validación
+- [ ] 3.1 Integrar módulos.
+- [ ] 3.2 Ejecutar suite de validación completa.
+- [ ] 3.3 Revisión de seguridad y dependencias.