Manual Operativo
de Hypenosys

Hypenosys es un estudio indie que desarrolla videojuegos con Unreal Engine 5. Su web (hypenosys.github.io) funciona simultáneamente como sitio público, centro de mando operativo y plataforma de documentación interna, todo sobre GitHub Pages sin servidor tradicional.

Flujo de datos

Flujo de autenticación

Componentes principales

El dashboard es el núcleo de gestión del estudio. Requiere autenticación GitHub y pertenencia a la lista blanca del equipo. Funciona como un project management tool completo sobre el navegador.

Perfiles del Equipo

Modal con stats por miembro: tareas completadas, SP velocity, dependency impact, collaboration score, weekly SP velocity chart, contribución por tipo, rama distribution, tag intelligence badges. observado en frontend

Modales operativos

Crear tarea, editar tarea, mover a QA (asignar tester/resolutor), asignar equipo, ampliar imagen (lightbox), editar perfil, configuración del sistema, configuración API de IA.

Columnas / Estados

Estados internos de tarea

Campos de tarea

Las tareas del Kanban admiten imágenes adjuntas. observado en frontend: existe un lightbox para ampliar imágenes y controles de eliminación dentro del modal de tarea.

Recomendaciones futuras

• Comprimir imágenes con Canvas API antes de guardar
• Generar thumbnails para la vista de lista
• Usar GitHub Releases como CDN de assets
• Carpeta /assets/uploads/ con commits directos
• Lazy loading con loading="lazy" e IntersectionObserver
• Almacenamiento externo (Cloudinary, S3) a largo plazo

Configuraciones almacenadas

Proveedores IA soportados observado

Anthropic (Claude), OpenAI (ChatGPT), Google Gemini, Mistral AI, OpenRouter, Ollama (local), Custom OpenAI-compatible.

El sistema usa la GitHub Contents API (GET/PUT /repos/{owner}/{repo}/contents/{path}) para leer y escribir los archivos JSON de _data/ directamente desde el navegador.

Flujo de escritura

Troubleshooting de API

Buenas prácticas

• Siempre hacer GET → modificar → PUT en una sola operación secuencial
• Validar el JSON con JSON.parse() antes de codificar a base64 para el PUT
• Implementar lock optimista: si SHA en servidor ≠ SHA local, pedir confirmación al usuario
• Loguear cada commit en consola con ruta y SHA para facilitar debugging
• Nunca almacenar el SHA entre sesiones; siempre refrescarlo

Jules es el agente IA de Google (jules.google.com) que ejecuta tareas de programación de forma autónoma en ramas de repositorios GitHub. El Jules Panel de Hypenosys es una interfaz personalizada para controlarlo.

Dependencias

• Jules API Key — obtenida en jules.google.com/settings, guardada en localStorage
• GitHub PAT — necesario para acceso a repositorios privados
• Configuración de repositorio objetivo

Sección pública de documentación del proyecto. observado en frontend: contiene explorador de docs, sincronización con repositorio y múltiples categorías.

Botones de acción observados: Editar en GitHub (abre el archivo en github.com/edit), Abrir en Obsidian (usa el protocolo obsidian:// para abrir el vault local).

Ejemplo mínimo de tarea

{
  "id": "task-001",
  "title": "Implementar sistema de movimiento",
  "type": "Feature",
  "priority": "Major",
  "status": "Working",
  "milestone": "M1",
  "branch": "PRO",
  "storyPoints": 5,
  "completion": 0.4,
  "tags": ["gameplay", "ue5"],
  "assignedTo": "Alex",
  "createdAt": "2025-01-15T10:00:00Z"
}

Prerrequisitos

• Ruby ≥ 3.0 (ruby -v para verificar)
• Bundler (gem install bundler)
• Git

Setup

git clone https://github.com/hypenosys/hypenosys.github.io.git
cd hypenosys.github.io
bundle install
bundle exec jekyll serve --livereload

Acceder en http://localhost:4000. LiveReload recarga automáticamente al guardar cambios.

Alternativa sin Jekyll (solo páginas estáticas)

# Con Python 3
python -m http.server 8080

# Con Node.js (npx serve)
npx serve . -p 8080

Las páginas Liquid/Jekyll no renderizarán. Solo funcionan las páginas HTML puras (dashboard.html, pages/jules-panel.html, manual.html).

GitHub PAT mínimo recomendado (Fine-Grained)

• Repositorio: solo hypenosys/hypenosys.github.io
• Permisos: Contents: Read & Write, Metadata: Read
• Expiración: 90 días máximo, con renovación programada

Data-as-Code

Patrón arquitectónico donde los datos de aplicación se almacenan como archivos en un repositorio Git. El historial Git actúa como base de datos con versionado, auditoría y rollback gratuitos. Hypenosys usa _data/*.json comprometidos en GitHub.

GitHub Contents API

Endpoint REST de GitHub (GET/PUT /repos/{owner}/{repo}/contents/{path}) que permite leer y escribir archivos en un repositorio directamente desde el navegador, incluyendo la creación de commits automáticos. Docs: docs.github.com/en/rest/repos/contents

SHA (Secure Hash Algorithm)

En el contexto de GitHub API, el hash del objeto Git que representa el estado actual de un archivo. Necesario para actualizar archivos (PUT). Si el SHA enviado no coincide con el del servidor, la API devuelve 409 Conflict para prevenir sobrescrituras accidentales.

PAT (Personal Access Token)

Token de autenticación de GitHub que actúa como contraseña de API. Reemplaza a las contraseñas básicas. Puede ser Classic (acceso amplio por scopes) o Fine-Grained (permisos por repositorio específico). Docs: docs.github.com/en/authentication

OAuth

Protocolo de autorización estándar (OAuth 2.0) que permite a aplicaciones de terceros acceder a recursos en nombre del usuario sin compartir credenciales. GitHub OAuth Apps permiten el flujo de autorización web con redirect_uri.

Jules

Agente de IA de Google (jules.google.com) que ejecuta tareas de programación de forma autónoma en ramas de repositorios GitHub: lee código, implementa cambios, crea commits y opcionalmente abre PRs.

Kanban

Metodología de gestión visual de trabajo originada en Toyota. Las tareas se representan como tarjetas que fluyen entre columnas que representan estados del proceso (Backlog → En Progreso → QA → Completado).

QA Velocity Ratio

Métrica operativa de Hypenosys. Ratio entre bugs marcados como Fixed y bugs encontrados (Found) en el mismo período. Un ratio cercano a 1.0 indica que se resuelven los bugs tan rápido como se encuentran.

Story Points

Unidad relativa de estimación de esfuerzo en metodologías ágiles. No representan horas sino complejidad relativa. Se usan para calcular la velocidad del equipo (SP completados por sprint/semana).

Milestone

Hito o punto de entrega en la planificación del proyecto. En Hypenosys: M1, M2, M3. Agrupa tareas por objetivo de release y permite calcular el burndown chart.

Lightbox

Patrón UI donde al hacer clic en una imagen se muestra ampliada en una capa superpuesta (overlay) oscureciendo el fondo. Común en galerías y sistemas de adjuntos.

localStorage

API del navegador (window.localStorage) para almacenar pares clave-valor de forma persistente entre sesiones. Los datos persisten aunque se cierre el navegador. Accesible por cualquier JS del mismo origen. Límite ~5MB.

sessionStorage

Igual que localStorage pero los datos se eliminan al cerrar la pestaña o el navegador. Más seguro para datos de sesión temporal.

GitHub Pages

Servicio de hosting estático gratuito de GitHub. Publica automáticamente el contenido del repositorio (con o sin Jekyll) en https://{user}.github.io/{repo}. Sin servidor, sin base de datos, sin costes de hosting.

Jekyll

Generador de sitios estáticos (jekyllrb.com) escrito en Ruby, integrado nativamente con GitHub Pages. Procesa Markdown, Liquid templates, front matter YAML y la carpeta _data/ para generar HTML estático.

Checklist de Release

• Todas las tareas del milestone en estado Closed u OK
• QA Velocity Ratio ≥ 0.95 en el milestone
• No hay Blocker Health activos (tareas bloqueadas)
• CHANGELOG.html actualizado con número de versión y fecha
• Build de Jekyll pasa sin errores (revisar Actions en GitHub)
• Assets verificados en GitHub Pages (Network 200)
• Responsive verificado en mobile/tablet/desktop
• No hay tokens ni API keys en el código fuente
• Backup de _data/*.json confirmado (commit previo limpio)

Checklist de Auditoría

• Revisar localStorage en DevTools: ningún valor sensible sin cifrar
• Buscar console.log con tokens o datos de usuario en JS
• Verificar que el PAT tiene solo los scopes necesarios
• Comprobar que inputs de tareas pasan por sanitización
• Revisar que el lightbox tiene z-index correcto
• Validar que todos los JSON en _data/ son válidos (JSON.parse())
• Verificar que no hay rutas absolutas hardcodeadas que rompan en subpaths
• Comprobar que IDs de tareas se comparan siempre como String

Tabla de Archivos Críticos

Ejemplo de Commit Seguro (GitHub API)

// 1. Obtener estado actual con SHA
const getRes = await fetch(
  `https://api.github.com/repos/hypenosys/hypenosys.github.io/contents/_data/tasks.json`,
  { headers: { Authorization: `token ${pat}`, Accept: 'application/vnd.github.v3+json' } }
);
const current = await getRes.json();
const sha = current.sha;

// 2. Modificar datos
const tasks = JSON.parse(atob(current.content.replace(/\n/g, '')));
tasks.push(newTask);

// 3. Validar antes de guardar
const jsonStr = JSON.stringify(tasks, null, 2);
JSON.parse(jsonStr); // Lanza excepción si inválido

// 4. PUT con SHA
const putRes = await fetch(
  `https://api.github.com/repos/hypenosys/hypenosys.github.io/contents/_data/tasks.json`,
  {
    method: 'PUT',
    headers: { Authorization: `token ${pat}`, Accept: 'application/vnd.github.v3+json' },
    body: JSON.stringify({
      message: `ops: add task "${newTask.title}"`,
      content: btoa(unescape(encodeURIComponent(jsonStr))),
      sha: sha
    })
  }
);

Tabla de Riesgos