Planning GameXP

Aplicación web para la gestión ágil de proyectos, siguiendo las prácticas de eXtreme Programming (XP).

🚀 Instalación Rápida

Tu propia instancia (fork)

Si quieres montar tu propio Planning Game XP con tu Firebase, haz un fork:

1. Haz fork en GitHub: https://github.com/AgilePlanning-io/planning-game-xp
2. Clona tu fork:

git clone https://github.com/TU-USUARIO/planning-game-xp.git
cd planning-game-xp

# Instalar dependencias
npm install && cd functions && npm install && cd ..

# Ejecutar asistente de configuración (guía interactiva)
npm run setup

El asistente te guiará paso a paso. Ver INSTALL.md para instrucciones detalladas.

Builds sin subida de versión: Los scripts build, build-prod y build-preview suben automaticamente la versión del proyecto (patch/minor/major según conventional commits). Si trabajas en un fork y no necesitas este comportamiento, usa las variantes build:no-bump, build-prod:no-bump o build-preview:no-bump. Ver la sección Scripts de Build para más detalles.

Contribuir al proyecto original

Si quieres contribuir con cambios al repositorio original, consulta CONTRIBUTING.md. El flujo es: fork → rama → PR contra el repo original.

🤖 Instalación con IA

¿Prefieres que una IA te guíe? Copia el prompt de AI_SETUP_PROMPT.md y dáselo a Claude.

Solo MCP (sin instalar la app)

Si ya tienes un Planning Game desplegado y solo quieres que tu IA (Claude Code, Cursor) gestione las tareas:

npm install -g planning-game-mcp
planning-game-mcp init

El wizard de configuración valida credenciales, detecta tu usuario, y registra el MCP en Claude Code. Solo necesitas el serviceAccountKey.json de tu proyecto Firebase.

• MCP Installation Guide
• Multi-instance Setup
• Full Documentation

---

📚 Documentación Principal

Documento	Descripción
INSTALL.md	Guía completa de instalación
ENV_VARIABLES.md	Todas las variables de entorno
NEWUSER.md	Cómo añadir nuevos usuarios
AI_SETUP_PROMPT.md	Prompt para instalación asistida por IA
CLAUDE.md	Instrucciones para desarrollo con IA
docs/MCP_INSTALLATION_GUIDE.md	Instalar solo el MCP Server

---

Versión Actual

Ver package.json para la versión actual. La versión se incrementa automaticamente en cada build segun conventional commits.

---

App Shell (partials)

La navegación interna usa un App Shell que carga parciales y ejecuta sus scripts al navegar. Las rutas se configuran en src/lib/app-shell-routes.js. Por defecto, las parciales se cachean en memoria. Si una ruta necesita HTML server-side dependiente de query/usuario, puedes desactivar el cache por ruta:

export const appShellRoutes = {
  '/projects/': { partial: '/partials/projects', cache: false },
  '/dashboard/': '/partials/dashboard'
};

---

Requisitos Previos

Antes de empezar, asegurate de tener instalado:

Herramienta	Version minima	Comprobar instalacion
Node.js	v18+	node --version
npm	v9+	npm --version
Git	cualquiera	git --version
Firebase CLI	ultima	firebase --version
Java	v11+	java --version (necesario para emuladores)

Si no tienes Firebase CLI:

npm install -g firebase-tools

---

Instalacion paso a paso

1. Hacer fork y clonar

1. Ve a https://github.com/AgilePlanning-io/planning-game-xp y haz click en Fork.
2. Clona tu fork:

git clone https://github.com/TU-USUARIO/planning-game-xp.git
cd planning-game-xp

Si solo quieres contribuir al proyecto original sin montar tu propia instancia, también puedes clonar directamente y enviar PRs desde tu fork. Ver CONTRIBUTING.md.

2. Instalar dependencias del proyecto

npm install

3. Configurar archivos de entorno

Los archivos de entorno contienen las credenciales de Firebase y NO estan en el repositorio.

Create them by running npm run setup or manually from the template in ENV_VARIABLES.md

Copiar estos archivos a la raiz del proyecto:

Archivo	Uso
.env	Variables base
.env.dev	Desarrollo local (emuladores)
.env.pre	Preproduccion
.env.prod	Produccion

Si vas a crear un proyecto Firebase nuevo (no usar el existente), ver la seccion Crear un proyecto Firebase nuevo.

4. Configurar Firebase

# Iniciar sesion en Firebase
firebase login

# Verificar que tienes acceso al proyecto
firebase projects:list

Run npm run setup to configure your Firebase project. The firebase.json is already configured in the repo.

5. Instalar dependencias de Cloud Functions

cd functions && npm install && cd ..

6. Iniciar desarrollo local

Necesitas dos terminales:

Terminal 1 — Emuladores Firebase:

npm run emulator

Esto arranca los emuladores con datos demo precargados. Veras:

• Emulator UI: http://localhost:4000
• Firestore: puerto 8080
• Realtime Database: puerto 9000
• Storage: puerto 9199

Terminal 2 — Servidor de desarrollo:

npm run dev

La app estara disponible en http://localhost:4321

Cuando los emuladores estan activos, la app muestra una barra roja arriba: "USANDO EMULADORES LOCALES"

---

Crear un proyecto Firebase nuevo

Si quieres replicar el proyecto en tu propio Firebase (no usar planning-gamexp):

1. Crear el proyecto en Firebase Console

1. Ve a https://console.firebase.google.com/
2. Click "Agregar proyecto"
3. Pon un nombre (ej: mi-planning-game)
4. Desactiva Google Analytics (no es necesario) o activalo si quieres

2. Activar servicios en Firebase Console

Activa estos servicios desde la consola web:

Servicio	Donde activarlo	Notas
Authentication	Build → Authentication	Habilitar proveedor "Microsoft" con tus credenciales Azure AD
Realtime Database	Build → Realtime Database	Crear base de datos en europe-west1
Firestore	Build → Firestore Database	Crear en modo produccion, region europe-west1
Storage	Build → Storage	Crear bucket por defecto
Hosting	Build → Hosting	Configurar sitio
Cloud Functions	Build → Functions	Requiere plan Blaze (pago por uso)
Cloud Messaging	Engage → Messaging	Para push notifications

3. Configurar Authentication con Microsoft

1. En Firebase Console → Authentication → Sign-in method
2. Habilitar "Microsoft"
3. Necesitas un App Registration en Azure AD:
   • Ve a https://portal.azure.com/ → Azure Active Directory → App registrations
   • Crear nueva app registration
   • Copiar Application (client) ID y crear un Client secret
   • En "Redirect URIs" añadir: https://TU-PROYECTO.firebaseapp.com/__/auth/handler
4. Pegar el Client ID y Secret en la config de Firebase Authentication

4. Generar Service Account Key

1. Firebase Console → Configuracion del proyecto (engranaje) → Cuentas de servicio
2. Click "Generar nueva clave privada"
3. Guardar el archivo como serviceAccountKey.json en la raiz del proyecto

IMPORTANTE: Este archivo contiene credenciales sensibles. NUNCA lo subas a git (ya esta en .gitignore).

5. Crear archivos de entorno

Crea .env.dev con esta estructura (reemplaza con tus valores):

# Firebase Config
PUBLIC_FIREBASE_API_KEY=tu-api-key
PUBLIC_FIREBASE_AUTH_DOMAIN=tu-proyecto.firebaseapp.com
PUBLIC_FIREBASE_DATABASE_URL=https://tu-proyecto-default-rtdb.europe-west1.firebasedatabase.app
PUBLIC_FIREBASE_PROJECT_ID=tu-proyecto
PUBLIC_FIREBASE_STORAGE_BUCKET=tu-proyecto.firebasestorage.app
PUBLIC_FIREBASE_MESSAGING_SENDER_ID=tu-sender-id
PUBLIC_FIREBASE_APP_ID=tu-app-id
PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX
PUBLIC_FIREBASE_VAPID_KEY=tu-vapid-key

# Emulator Config (no cambiar estos puertos)
USE_FIREBASE_EMULATOR=true
FIREBASE_EMULATOR_MESSAGING_PORT=5001
FIREBASE_EMULATOR_MESSAGING_HOST=localhost
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIRESTORE_EMULATOR_HOST=localhost:8081
FIREBASE_DATABASE_EMULATOR_HOST=localhost:9000
FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199

# Test user (para E2E tests)
TEST_USER_EMAIL=tu-usuario-test@dominio.com
TEST_USER_PASSWORD=tu-password

# Microsoft OAuth (Azure AD)
MS_CLIENT_ID=tu-client-id
MS_CLIENT_SECRET=tu-client-secret
MS_TENANT_ID=tu-tenant-id
MS_FROM_EMAIL=tu-email@dominio.com

# Super Admin
PUBLIC_SUPER_ADMIN_EMAIL=tu-admin@dominio.com

Para .env.prod, es lo mismo pero con USE_FIREBASE_EMULATOR=false y sin las lineas de emulador.

6. Actualizar .firebaserc

Reemplaza el contenido con tu proyecto:

{
  "projects": {
    "default": "tu-proyecto"
  },
  "targets": {
    "tu-proyecto": {
      "database": {
        "main": [
          "tu-proyecto-default-rtdb"
        ]
      }
    }
  }
}

7. Desplegar reglas de seguridad

firebase deploy --only firestore:rules,database,storage

8. Inicializar contadores de Firestore

Los contadores de Firestore se crean automaticamente al crear el primer proyecto desde la app. No necesitas hacer nada manual.

9. Crear el primer usuario

Sigue las instrucciones en NEWUSER.md para configurar permisos en la Realtime Database.

---

Servidor MCP — Usa la IA para desarrollar tareas del Planning Game

Este proyecto incluye un servidor MCP que conecta Claude Code (o Cursor) con la base de datos de Planning GameXP. Esto permite que la IA lea tus tareas, bugs y proyectos, y los desarrolle directamente en el repo donde estes trabajando.

Que es y como funciona

MCP (Model Context Protocol) es un protocolo que da herramientas extra a Claude Code/Cursor. NO es parte de la app web, NO tiene UI, y NO se despliega en ningun servidor. Es un proceso local que corre en tu maquina y conecta la IA con Firebase.

┌─────────────────┐  stdin/stdout  ┌─────────────┐  Firebase Admin  ┌──────────┐
│ Claude Code /   │ ◄────────────► │ MCP Server  │ ◄──────────────► │ Firebase │
│ Cursor          │                │ (local)     │                  │  (prod)  │
└─────────────────┘                └─────────────┘                  └──────────┘

Configuracion inicial (una sola vez)

Nota: El servidor MCP se encuentra en una ubicación global: ~/mcp-servers/planning-game/ Este servidor es compartido entre todos los proyectos y no forma parte del repositorio.

1. Obtener el Service Account Key

Download the serviceAccountKey.json from Firebase Console (Project Settings > Service accounts) and copy it to ~/mcp-servers/planning-game/.

2. Elegir el modo de uso

Tienes dos opciones segun como quieras usarlo:

---

OPCION A — Solo en este repo (automatico al clonar)

No necesitas hacer nada mas. El .mcp.json ya esta en el repo. Cuando abras Claude Code o Cursor en el directorio PlanningGameXP, detectara el MCP automaticamente.

Esta opcion solo funciona cuando trabajas DENTRO del directorio PlanningGameXP.

---

OPCION B — Global, para usar desde CUALQUIER repo (recomendado)

Ejecuta este comando una sola vez en tu terminal:

claude mcp add planning-game \
  -s user \
  -e GOOGLE_APPLICATION_CREDENTIALS=$HOME/mcp-servers/planning-game/serviceAccountKey.json \
  -e FIREBASE_DATABASE_URL=https://your-project-default-rtdb.europe-west1.firebasedatabase.app \
  -- node $HOME/mcp-servers/planning-game/index.js

Esto guarda la configuracion en tu ~/.claude.json. A partir de ahora, puedes abrir Claude Code en cualquier directorio (cualquier otro proyecto) y tendras acceso a las tareas del Planning Game.

Para Cursor: configura el MCP server en Settings → MCP Servers con los mismos datos.

---

4. Verificar que funciona

Reinicia Claude Code (Ctrl+C y volver a entrar) y ejecuta:

claude mcp list

Debe mostrar: planning-game: ... ✓ Connected

Que puedes hacer con el MCP

Una vez activo, puedes pedirle a la IA cosas como:

• "Lista los proyectos de Planning Game"
• "Que tareas tiene MyProject en estado To Do?"
• "Muestra el detalle de la card PRJ-TSK-0001"
• "Crea una tarea en MyProject con titulo X"
• "Cambia el status de esta card a Done"
• "Que sprints hay en MyProject para 2026?"
• "Lista los developers"

Caso de uso principal: Estas trabajando en el repo de tu proyecto. Le pides a Claude "lee la tarea PRJ-TSK-0001 y desarrollala". La IA lee la descripcion, acceptance criteria, y escribe el codigo directamente en el repo donde estas.

Tools disponibles

Tool	Descripcion
list_projects / get_project	Consultar proyectos
list_cards / get_card / create_card / update_card	Gestionar cards (tasks, bugs, epics, proposals, QA)
relate_cards	Crear relaciones entre cards
get_transition_rules	Ver reglas de transicion de estados
list_sprints / get_sprint / create_sprint	Gestionar sprints
list_developers / list_stakeholders	Consultar equipo
list_adrs / get_adr / create_adr	Architecture Decision Records
list_global_config / get_global_config	Configuraciones globales
get_mcp_status / update_mcp / setup_mcp_user	Estado y configuracion del MCP

Seguridad del MCP

• El MCP conecta a produccion — las operaciones de escritura son reales
• Las cards creadas via MCP se marcan con createdBy: "claude-code-mcp" para trazabilidad
• El serviceAccountKey.json esta en .gitignore y NUNCA debe subirse al repo
• El .mcp.json NO contiene credenciales (solo referencia al archivo de service account)
• La config --scope user es local a tu maquina — nadie mas la ve

---

Scripts Disponibles

Desarrollo

Comando	Descripcion
npm run dev	Servidor de desarrollo (puerto 4321)
npm run emulator	Emuladores Firebase con datos demo
npm run emulator:check	Verificar estado de emuladores
npm run emulator:export	Exportar datos del emulador
npm run preview	Previsualizar build generada

Build

Comando	Descripcion
npm run build	Build de produccion (con version bump automatico)
npm run build-prod	Build de produccion explicita (con version bump)
npm run build-preview	Build de preproduccion (con version bump)
npm run build:no-bump	Build de produccion sin subir version
npm run build-prod:no-bump	Build de produccion explicita sin subir version
npm run build-preview:no-bump	Build de preproduccion sin subir version
npm run generate-sw	Regenerar service worker

Version bump automatico: Los scripts build, build-prod y build-preview analizan los mensajes de commit (conventional commits) para decidir si suben major, minor o patch. Ademas, generan el CHANGELOG y hacen commit+push de los archivos de version. Si trabajas en un fork o no necesitas este comportamiento, usa las variantes :no-bump que solo ejecutan syntax check, security check, generacion del service worker y la build de Astro.

Testing

Comando	Descripcion
npm run test	Tests unitarios (Vitest)
npm run test:coverage	Tests con reporte de cobertura
npm run test:watch	Tests en modo watch
npm run test:e2e	Tests E2E (Playwright)
npm run test:e2e:ui	Tests E2E con interfaz visual
npm run test:e2e:headed	Tests E2E con navegador visible

Despliegue

Comando	Descripcion
npm run deploy	Desplegar todo a Firebase
npm run deploy:hosting	Solo hosting
npm run deploy:functions	Solo Cloud Functions
npm run deploy:rules	Solo reglas de seguridad
npm run security-check	Auditoria de seguridad

Seed y Migracion

Comando	Descripcion
node scripts/seed-global-config.js	Crear configs globales iniciales (agents, prompts, instructions)
node scripts/seed-adrs.js [projectId]	Crear ADRs de ejemplo para un proyecto
node scripts/migrate-add-year-field.js <input.json>	Migrar campo year a todas las cards

Ver GLOBAL_CONFIG.md para mas detalles sobre la configuracion global y ADRs.

---

Estructura del Proyecto

PlanningGameXP/
├── public/js/                # Codigo JavaScript del frontend
│   ├── services/             # Servicios centralizados (Firebase, Cards, Permisos...)
│   ├── controllers/          # Controladores de la app
│   ├── events/               # Sistema de delegacion de eventos
│   ├── wc/                   # Web Components (Lit)
│   ├── renderers/            # Renderizadores de vistas
│   ├── factories/            # Patron Factory (cards, vistas)
│   ├── filters/              # Sistema de filtros
│   ├── utils/                # Utilidades
│   └── constants/            # Constantes
├── src/
│   ├── pages/                # Paginas Astro (index, dashboard, sprintview...)
│   ├── layouts/              # Layouts de Astro
│   └── firebase/             # Config de Firebase
├── functions/                # Cloud Functions de Firebase
├── tests/                    # Tests unitarios (Vitest)
├── playwright/               # Tests E2E (Playwright)
├── tests/mcp-server/         # Tests del servidor MCP (ubicado en ~/mcp-servers/planning-game/)
├── scripts/                  # Scripts de mantenimiento y migracion
├── emulator-data/            # Datos demo para emuladores
├── dist/                     # Build generada (se despliega aqui)
├── .env.dev                  # Variables de entorno desarrollo (NO en git)
├── .env.pre                  # Variables de entorno preproduccion (NO en git)
├── .env.pro                  # Variables de entorno produccion (NO en git)
├── .mcp.json                 # Configuracion del MCP server
├── firebase.json             # Configuracion Firebase (emuladores, hosting, reglas)
├── .firebaserc               # Proyecto Firebase asociado
└── serviceAccountKey.json    # Credenciales Firebase Admin (NO en git)

---

Tecnologias

• Frontend: Astro v5 + Lit Web Components
• Backend: Firebase (Realtime Database, Firestore, Auth, Cloud Functions, Storage, FCM)
• Testing: Vitest (unit) + Playwright (E2E)
• Auth: Microsoft OAuth via Azure AD
• MCP: Model Context Protocol para integracion con Claude Code

---

Arquitectura

• Servicios Centralizados: Gestion unificada de permisos, filtros, modales y eventos
• Event Delegation: Un solo listener por tipo de evento, gestion centralizada
• Web Components: Lit-based, comunicacion via eventos, estilos separados
• Factory Pattern: CardFactory y ViewFactory para diferentes tipos/vistas
• Service-Oriented Architecture: Separacion de responsabilidades

Para mas detalles, consulta ARCHITECTURE.md.

---

Despliegue a Produccion

# 1. Build (incluye security check automatico + version bump)
npm run build

# O sin version bump (recomendado para forks):
npm run build:no-bump

# 2. Desplegar
npm run deploy

IMPORTANTE: El directorio de deploy es dist, NUNCA public. Astro usa public/ para archivos estaticos de desarrollo.

---

Solucion de Problemas

Emuladores

Problema	Solucion
El emulador no arranca	Verificar que los puertos 4000, 8080, 9000, 9199 no estan ocupados
No aparece la barra roja	Verificar .env.dev tiene USE_FIREBASE_EMULATOR=true
No carga datos demo	Los datos se importan desde emulator-data/ automaticamente
Error de Java	Instalar Java JDK 11+: sudo apt install openjdk-11-jdk

Build

Problema	Solucion
Security check falla	Ejecutar npm run security:fix
Falta .env	Run npm run setup to generate environment files
Deploy falla	Verificar firebase login y que tienes permisos en el proyecto

MCP Server

Problema	Solucion
MCP no encontrado	Verificar que ~/mcp-servers/planning-game/ existe con index.js y serviceAccountKey.json
Claude Code no detecta el MCP	Reiniciar Claude Code (Ctrl+C y volver a entrar)
Error "Can't determine Firebase Database URL"	Verificar que serviceAccountKey.json existe en la raiz
Error de autenticacion	El service account key puede estar expirado, regenerar desde Firebase Console

---

Documentación Adicional

Instalación y Configuración

Documento	Contenido
INSTALL.md	Guía completa de instalación paso a paso
ENV_VARIABLES.md	Todas las variables de entorno necesarias
AI_SETUP_PROMPT.md	Prompt para instalación asistida por IA
NEWUSER.md	Cómo dar de alta usuarios

Desarrollo

Documento	Contenido
CLAUDE.md	Instrucciones para Claude Code
ARCHITECTURE.md	Arquitectura detallada
GLOBAL_CONFIG.md	Configuración global de IA y ADRs
CONTRIBUTING.md	Guía para contribuir

Testing y Referencia

Documento	Contenido
playwright/README.md	Tests E2E con Playwright
FIREBASE_REALTIME_DATABASE_STRUCTURE.md	Estructura de la base de datos
functions/README.md	Cloud Functions
CHANGELOG.md	Registro de cambios
docs/MCP_INSTALLATION_GUIDE.md	Instalar MCP Server