pigmalion-setup 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# pigmalion-setup
+
+Utilidad NPX para inicializar un proyecto copiando `AGENTS.md`, `CODEX.md` y `SETUP.md`, y arrancar Codex usando `SETUP.md` como base del flujo.
+
+## Uso
+
+```bash
+npx pigmalion-setup
+```
+
+Requiere que el comando `codex` este disponible en `PATH`.
+
+## Comportamiento
+
+- Copia `AGENTS.md`, `CODEX.md`, `SETUP.md` en el directorio actual si no existen.
+- Ejecuta `codex` y le pasa el contenido de `SETUP.md` para iniciar la conversación.
+- Codex define documentación base y `ROADMAP.md` según el flujo de `SETUP.md`.
+
+
+# Desarrollo local
+
+Para probar la herramienta localmente sin publicarla, puedes usar `npm link`:
+
+```
+npm link
+```
+
+Esto hará que el comando `pigmalion-setup` esté disponible globalmente en tu sistema, apuntando a tu versión local del proyecto. Luego puedes ejecutar `npx pigmalion-setup` para probarlo.
+
+

package/bin/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import readline from "node:readline/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATE_DIR = path.join(__dirname, "..", "templates");
+const TARGET_DIR = process.cwd();
+
+const INITIAL_FILES = ["SETUP.md"];
+const POST_FILES = ["AGENTS.md", "CODEX.md"];
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function normalizePath(p) {
+  if (process.platform !== "win32") return p;
+  if (!p) return p;
+  const msysMatch = p.match(/^\/([a-zA-Z])\/(.*)/);
+  if (msysMatch) {
+    const drive = msysMatch[1].toUpperCase();
+    const rest = msysMatch[2].replace(/\//g, "\\");
+    return `${drive}:\\${rest}`;
+  }
+  return p;
+}
+
+function detectShell() {
+  const env = process.env;
+  const shell = (env.SHELL || "").toLowerCase();
+  if (shell.includes("bash")) return "bash";
+  const psModulePath = (env.PSModulePath || "").toLowerCase();
+  if (psModulePath.includes("powershell") || env.PSExecutionPolicyPreference) {
+    return "powershell";
+  }
+  const comspec = (env.COMSPEC || "").toLowerCase();
+  if (comspec.includes("cmd.exe")) return "cmd";
+  return "unknown";
+}
+
+function ensureWindowsExecutable(codexCmd) {
+  if (process.platform !== "win32") return codexCmd;
+  if (!codexCmd) return codexCmd;
+  const ext = path.extname(codexCmd);
+  if (ext) return codexCmd;
+  const candidates = [
+    `${codexCmd}.cmd`,
+    `${codexCmd}.ps1`,
+    `${codexCmd}.exe`,
+    codexCmd
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return codexCmd;
+}
+
+function canRunCodex(codexCmd) {
+  if (!codexCmd) return false;
+  const ext = path.extname(codexCmd).toLowerCase();
+  const useShell =
+    process.platform === "win32" && (!ext || ext === ".cmd" || ext === ".ps1");
+  const result = spawnSync(codexCmd, ["--version"], {
+    stdio: "ignore",
+    env: process.env,
+    shell: useShell
+  });
+  if (result.error && result.error.code === "ENOENT") return false;
+  if (result.error) return false;
+  return true;
+}
+
+async function fileExists(p) {
+  try {
+    await fsPromises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function confirmOverwrite(name) {
+  if (!process.stdin.isTTY) {
+    return true; // Asumir sí en modo no interactivo
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = await rl.question(
+      `- ${name} ya existe. ¿Sobrescribir? (s/N): `
+    );
+    const normalized = answer.trim().toLowerCase();
+    return normalized === "s" || normalized === "si" || normalized === "y";
+  } finally {
+    rl.close();
+  }
+}
+
+async function waitForEnter() {
+  if (!process.stdin.isTTY) {
+    log("Modo no interactivo detectado. Continuando...");
+    return;
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    await rl.question("Presiona Enter para continuar...");
+  } finally {
+    rl.close();
+  }
+}
+
+async function copyTemplates(files, { allowOverwrite } = { allowOverwrite: false }) {
+  for (const name of files) {
+    const src = path.join(TEMPLATE_DIR, name);
+    const dest = path.join(TARGET_DIR, name);
+    if (await fileExists(dest)) {
+      if (!allowOverwrite) {
+        log(`- ${name} ya existe, se omite`);
+        continue;
+      }
+      const shouldOverwrite = await confirmOverwrite(name);
+      if (!shouldOverwrite) {
+        log(`- ${name} ya existe, se omite`);
+        continue;
+      }
+    }
+    await fsPromises.copyFile(src, dest);
+    log(`- ${name} instalado`);
+  }
+}
+
+function resolveCodexJsFromCmd(codexCmd) {
+  if (!codexCmd.toLowerCase().endsWith(".cmd")) return null;
+  const binDir = path.dirname(codexCmd);
+  const candidate = path.join(
+    binDir,
+    "node_modules",
+    "@openai",
+    "codex",
+    "bin",
+    "codex.js",
+  );
+  if (fs.existsSync(candidate)) return candidate;
+  return null;
+}
+
+function buildCodexProcess(codexCmd, prompt) {
+  const codexJs = resolveCodexJsFromCmd(codexCmd);
+  if (codexJs) {
+    return {
+      cmd: process.execPath,
+      args: [codexJs],
+      options: { shell: false },
+    };
+  }
+  const ext = path.extname(codexCmd).toLowerCase();
+  const useShell =
+    process.platform === "win32" && (ext === ".cmd" || ext === ".ps1");
+  return { cmd: codexCmd, args: [], options: { shell: useShell } };
+}
+
+async function runCodex(codexCmd) {
+  const setupPath = path.join(TARGET_DIR, "SETUP.md");
+
+  log("");
+  log("Setup detectado. Para continuar con Codex:");
+  log(`Ejecuta: ${codexCmd}`);
+  log("");
+  log("Y pega el siguiente prompt:");
+  log("");
+  const prompt = [
+    `Lee y sigue estrictamente SETUP.md en: ${setupPath}`,
+    "Inicia el flujo base con el usuario para definir vision general, documentacion y ROADMAP.",
+    "No toques codigo todavia. Solo documentacion, roadmap y arquitectura.",
+    "Comienza ahora."
+  ].join("\n");
+  log(prompt);
+  log("");
+}
+
+function findCodexInBinDir(binDir) {
+  if (!binDir) return null;
+  const normalized = normalizePath(binDir);
+  const candidates = [
+    path.join(normalized, "codex"),
+    path.join(normalized, "codex.cmd"),
+    path.join(normalized, "codex.ps1"),
+    path.join(normalized, "codex.exe")
+  ];
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate);
+      return candidate;
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+function findCodexFromNpmGlobal() {
+  const npmPrefix = spawnSync("npm", ["prefix", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (npmPrefix.status !== 0 || !npmPrefix.stdout) {
+    return null;
+  }
+  const prefix = npmPrefix.stdout.trim();
+  const direct = findCodexInBinDir(prefix);
+  if (direct) return direct;
+  return findCodexInBinDir(path.join(prefix, "bin"));
+}
+
+function findCodexFromNpmPrefix() {
+  const npmPrefix = spawnSync("npm", ["prefix", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (npmPrefix.status === 0 && npmPrefix.stdout) {
+    const prefix = npmPrefix.stdout.trim();
+    const found = findCodexInBinDir(prefix);
+    if (found) return found;
+    const foundBin = findCodexInBinDir(path.join(prefix, "bin"));
+    if (foundBin) return foundBin;
+  }
+
+  const npmConfigPrefix = spawnSync("npm", ["config", "get", "prefix"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (npmConfigPrefix.status === 0 && npmConfigPrefix.stdout) {
+    const prefix = npmConfigPrefix.stdout.trim();
+    const found = findCodexInBinDir(prefix);
+    if (found) return found;
+    const foundBin = findCodexInBinDir(path.join(prefix, "bin"));
+    if (foundBin) return foundBin;
+  }
+
+  return null;
+}
+
+function findCodexFromLocalNodeModules() {
+  const localBin = path.join(TARGET_DIR, "node_modules", ".bin");
+  return findCodexInBinDir(localBin);
+}
+
+function findCodexFromWhere() {
+  const whereResult = spawnSync("where", ["codex"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (whereResult.status !== 0 || !whereResult.stdout) {
+    return null;
+  }
+  const lines = whereResult.stdout
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  return lines[0];
+}
+
+function findCodexFromWhich() {
+  const whichResult = spawnSync("which", ["codex"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (whichResult.status !== 0 || !whichResult.stdout) {
+    return null;
+  }
+  const lines = whichResult.stdout
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  const first = normalizePath(lines[0]);
+  const hasExt = path.extname(first).length > 0;
+  if (hasExt && fs.existsSync(first)) return first;
+  const candidates = [
+    `${first}.cmd`,
+    `${first}.ps1`,
+    `${first}.exe`,
+    first
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function findCodexFromShell() {
+  const shell = detectShell();
+  if (shell === "bash") return findCodexFromWhich();
+  if (shell === "powershell" || shell === "cmd") return findCodexFromWhere();
+  return null;
+}
+
+function findCodexFromPnpmGlobal() {
+  const pnpmBin = spawnSync("pnpm", ["bin", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (pnpmBin.status !== 0 || !pnpmBin.stdout) {
+    return null;
+  }
+  return findCodexInBinDir(pnpmBin.stdout.trim());
+}
+
+function findCodexFromYarnGlobal() {
+  const yarnBin = spawnSync("yarn", ["global", "bin"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env
+  });
+  if (yarnBin.status !== 0 || !yarnBin.stdout) {
+    return null;
+  }
+  return findCodexInBinDir(yarnBin.stdout.trim());
+}
+
+function findCodexFromKnownPaths() {
+  const bins = [];
+  if (process.env.npm_config_prefix) {
+    bins.push(process.env.npm_config_prefix);
+    bins.push(path.join(process.env.npm_config_prefix, "bin"));
+  }
+  if (process.env.npm_prefix) {
+    bins.push(process.env.npm_prefix);
+    bins.push(path.join(process.env.npm_prefix, "bin"));
+  }
+  if (process.env.npm_config_global_prefix) {
+    bins.push(process.env.npm_config_global_prefix);
+    bins.push(path.join(process.env.npm_config_global_prefix, "bin"));
+  }
+  if (process.env.APPDATA) {
+    bins.push(path.join(process.env.APPDATA, "npm"));
+    bins.push(path.join(process.env.APPDATA, "Yarn", "bin"));
+  }
+  if (process.env.LOCALAPPDATA) {
+    bins.push(path.join(process.env.LOCALAPPDATA, "Yarn", "bin"));
+    bins.push(path.join(process.env.LOCALAPPDATA, "npm"));
+  }
+  if (process.env.PNPM_HOME) {
+    bins.push(process.env.PNPM_HOME);
+  }
+  if (process.env.YARN_GLOBAL_FOLDER) {
+    bins.push(process.env.YARN_GLOBAL_FOLDER);
+    bins.push(path.join(process.env.YARN_GLOBAL_FOLDER, "bin"));
+  }
+
+  for (const binDir of bins) {
+    const found = findCodexInBinDir(binDir);
+    if (found) return found;
+  }
+  return null;
+}
+
+function checkCodexAvailable() {
+  const candidates = [
+    findCodexFromShell(),
+    findCodexFromLocalNodeModules(),
+    findCodexFromNpmGlobal(),
+    findCodexFromNpmPrefix(),
+    findCodexFromPnpmGlobal(),
+    findCodexFromYarnGlobal(),
+    findCodexFromWhere(),
+    findCodexFromWhich(),
+    findCodexFromKnownPaths()
+  ];
+  for (const candidate of candidates) {
+    const resolved = ensureWindowsExecutable(candidate);
+    if (canRunCodex(resolved)) return resolved;
+  }
+
+  const result = spawnSync("codex", ["--version"], {
+    stdio: "ignore",
+    env: process.env,
+    shell: process.platform === "win32"
+  });
+  if (!result.error && result.status === 0) {
+    return "codex";
+  }
+  if (result.error && result.error.code !== "ENOENT") {
+    return null;
+  }
+
+  log("");
+  log("No se encontro el comando 'codex' en PATH ni en npm/pnpm/yarn global.");
+  log("Instalacion recomendada:");
+  log("- Instala el CLI de Codex con el metodo oficial segun tu entorno.");
+  log("- Verifica que el comando `codex` quede disponible en PATH.");
+  log("- Luego vuelve a ejecutar `npx pigmalion-setup`.");
+  return null;
+}
+
+async function main() {
+  log("Pigmalion Setup- Init");
+  await copyTemplates(INITIAL_FILES);
+  const codexCmd = checkCodexAvailable();
+  if (!codexCmd) {
+    return;
+  }
+  await runCodex(codexCmd);
+  await copyTemplates(POST_FILES, { allowOverwrite: true });
+  log("");
+  log("Listo. Puedes revisar SETUP.md y los docs generados por Codex.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "pigmalion-setup",
+  "version": "0.1.0",
+  "description": "NPX utility to initialize projects with Pigmalion Manager setup flow.",
+  "type": "module",
+  "bin": {
+    "pigmalion-setup": "bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "license": "MIT"
+}

package/templates/AGENTS.md

@@ -0,0 +1,299 @@
+# 🤖 AGENTS.md - Workflow Automatizado IA
+
+## 🎯 PRINCIPIO FUNDAMENTAL
+**Actúa primero, pregunta después solo si es crítico**  
+Objetivo: Maximizar velocidad sin sacrificar calidad
+
+---
+
+## 🚀 AUTONOMÍA MÁXIMA
+
+### Reglas de Decisión
+```
+SI duda <5s → Implementa mejor práctica estándar
+SI impacto >1h trabajo → 1 pregunta concreta máximo
+SI breaking change → Avisa + propón migración
+```
+
+### Comunicación Prohibida
+❌ "¿Quieres que...?"  
+❌ "¿Prefieres A o B?"  
+❌ "¿Dónde pongo...?"  
+
+### Comunicación Correcta
+✅ "Implementado X. Tests 92%. Review: /diff"  
+✅ "Breaking: API v2. Migración: /docs/MIGRATION.md"  
+✅ "Hotfix deployed. Rollback: `git revert abc123`"
+
+---
+
+## ESTRUCTURA
+(Según proyecto)
+backend/ (3001) | frontend/ (3002) | .github/
+
+
+# 🧠 STACK INTELIGENTE (AUTO-SELECCIÓN)
+
+## HEURÍSTICAS DECISIÓN STACK (Evalúa + elige mejor)
+
+PROYECTO GRANDE (>10 modelos/usuarios/cruzado): Laravel 11 + Inertia + Vue 3 + MySQL (puerto 3000)
+SIMPLE (<1 semana/MVP): Node Express + React Vite (3001/3002)
+REALTIME (chat/socket): Node Socket.io + React (3001/3002)
+ML/DATA (análisis): Python + FastAPI + Streamlit (8000/3002)
+MÓVIL/PWA: Laravel API + React Native
+
+---
+
+## 📁 EJEMPLO DE ESTRUCTURA PROYECTO 
+
+Por defecto, se sigue una estructura modular por capas o pipelines, evitando mezclar responsabilidades.
+
+```
+proyecto/
+├── backend/          # API + lógica negocio
+├── frontend/         # UI + cliente
+├── shared/           # types, utils, schemas compartidos
+├── tests/            # tests unitarios e integración
+├── docs/             # Documentación técnica
+│   ├── API.md
+│   ├── ARCHITECTURE.md
+│   └── DECISIONS.md  # ADRs importantes
+├── .github/
+│   ├── workflows/    # CI/CD
+├── docker-compose.yml
+├── AGENTS.md         # ← ESTE archivo
+├── ROADMAP.md        # Plan de trabajo
+├── README.md         # Documentación general
+└── package.json      # Scripts raíz
+```
+
+### Scripts NPM Raíz (Requeridos)
+```json
+{
+  "scripts": {
+    "dev": "concurrently 'npm:dev:*'",
+    "dev:backend": "cd backend && npm run dev",
+    "dev:frontend": "cd frontend && npm run dev",
+    "install:all": "npm i && cd backend && npm i && cd ../frontend && npm i",
+    "lint": "prettier --check . && eslint .",
+    "format": "prettier --write .",
+    "test": "npm run test --workspaces",
+    "test:ci": "npm run test:ci --workspaces",
+    "build": "npm run build --workspaces"
+  }
+}
+```
+
+---
+
+## 🔄 WORKFLOW GIT
+
+### Branching Strategy
+```bash
+# Nomenclatura obligatoria
+codex-{tipo}-{descripción-corta}-{timestamp}
+
+# Ejemplos
+codex-feat-auth-api-20260215-1430
+codex-fix-login-bug-20260215-1445
+codex-docs-api-spec-20260215-1500
+```
+
+### Tipos Válidos
+- `feat`: Nueva funcionalidad
+- `fix`: Corrección bug
+- `refactor`: Refactorización sin cambio comportamiento
+- `docs`: Solo documentación
+- `test`: Añadir/mejorar tests
+- `chore`: Tareas mantenimiento (deps, config)
+
+### Flujo Automático
+
+```bash
+1. /diff     # Muestra cambios + impacto
+2. /test     # Ejecuta tests + coverage
+3. /merge    # Merge si tests >85% + CI pass
+```
+
+### Commits
+```bash
+# Formato: tipo(scope): descripción
+feat(auth): add JWT refresh token endpoint
+fix(ui): resolve mobile menu overflow
+docs(api): update rate limit documentation
+```
+
+---
+
+# 🔄 ISSUE WORKFLOW (GitHub Issues nativo - OBLIGATORIO)
+
+## PROCESO AUTOMÁTICO
+
+GitHub Issues → Label: 🔴 bug 🤖 codex | 🟢 feature 🤖 codex
+codex /issues → Lista disponibles kanban
+codex /next-bug → codex-bug-#12 (auto-branch)
+Implementa → /test → coverage >85% → /pr → /close #12
+
+
+## COMANDOS AGENTES
+codex /issues # Lista + kanban status
+codex /next-bug # Toma siguiente 🔴 bug
+codex /next-feature # Toma siguiente 🟢 feature
+codex /assign #15 # Asigna agent a issue
+codex /close #12 # Merge + close auto
+codex /kanban # Status visual ToDo/InProgress/Done
+
+## BRANCH CONVENCIÓN
+🔴 bug → codex-bug-#12-login-crash
+🟢 feature → codex-feature-#15-google-oauth
+🔵 docs → codex-docs-#18-api-readme
+
+## PRIORIDADES
+bug > feature > refactor > docs
+GitHub Project: "Codex Kanban" (4 columnas)
+Labels auto: 'crash→bug', 'añade→feature', 'docs→docs'
+
+---
+
+## 📚 DOCUMENTACIÓN OBLIGATORIA
+
+Mantener ROADMAP.md siempre activo y actualizado: referencia principal para agentes y consulta humana.
+
+### README.md (Raíz)
+```markdown
+# Proyecto XYZ
+
+## Quick Start
+npm run install:all
+npm run dev  # → backend:3001 + frontend:3002
+
+## Architecture
+Ver [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
+## Roadmap  (Fases y entregables)
+Ver [ROADMAP.md](ROADMAP.md)
+```
+
+### backend/README.md
+```markdown
+# Backend API
+
+## Endpoints
+GET  /api/users       # Lista usuarios
+POST /api/users       # Crear usuario
+...
+
+## Examples
+curl -X POST http://localhost:3001/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"John"}'
+```
+
+### frontend/README.md
+```markdown
+# Frontend
+
+## Development
+npm run dev  # → http://localhost:3002
+
+## Build
+npm run build  # → dist/
+```
+
+### Inline Code
+- JSDoc en funciones públicas
+- Comentarios en bloques >15 líneas o lógica compleja
+- TODOs con issue: `// TODO(#42): Refactor to use async/await`
+
+---
+
+## ✅ DECISIONES AUTOMÁTICAS
+
+- Al añadir nuevas funciones o testar diferentes parámetros de configuración, siempre crear test particulares para cada escenario. 
+- Siempre mantener los tests actualizados de cualquier capa, módulo o servicio del proyecto. 
+
+### Coverage & Quality
+```yaml
+Tests pass: ✅ Auto-approve
+Coverage ≥85%: ✅ Auto-approve
+Lint errors: ❌ Block merge
+Breaking changes: ⚠️ Require explicit approval
+```
+
+### Comandos
+```bash
+/apply  # Si tests pass → commit
+/merge  # Si CI pass + coverage OK → merge to main
+/docs   # Genera/actualiza docs antes de merge
+```
+
+---
+
+## 🔧 HERRAMIENTAS OPCIONALES
+
+### Browser Automation (si aplica)
+- Puppeteer para E2E tests
+- Playwright para cross-browser
+
+### MCP Servers (si aplica)
+- GitHub MCP: Gestión issues/PRs
+- Filesystem MCP: Operaciones archivo
+- Database MCP: Queries directo
+
+### Monitoring (producción)
+- Sentry (errores)
+- Plausible/Umami (analytics ligero)
+- Uptime robot (disponibilidad)
+
+---
+
+## 🎓 DECISIONES ARQUITECTÓNICAS
+
+### Cuándo Cambiar Stack
+```
+JSON DB → PostgreSQL: >1000 registros o queries complejas
+Context API → Zustand: >5 contexts o prop drilling
+REST → GraphQL: Frontend necesita datos muy específicos
+Monolito → Microservicios: >3 dominios independientes
+```
+
+### Logging
+```javascript
+// Desarrollo: console.log OK
+// Producción: winston/pino con niveles
+logger.info('User created', { userId: 123 });
+logger.error('DB connection failed', { error });
+```
+
+---
+
+## 🚨 EXCEPCIONES AL WORKFLOW
+
+### Requiere Aprobación Humana
+- Cambios en AGENTS.md
+- Eliminación datos producción
+- Cambios permisos/seguridad
+- Refactorización >500 líneas
+
+### Hotfix Critical
+```bash
+# Branch directo desde main
+hotfix-{descripción}-{timestamp}
+
+# Deploy inmediato después de tests
+# Notificar en #incidents canal
+```
+
+---
+
+## 📖 RECURSOS
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Semantic Versioning](https://semver.org/)
+- [GitHub Actions Docs](https://docs.github.com/en/actions)
+
+---
+
+**Última actualización:** 2026-02-15  
+**Versión:** 1.0  
+**Mantenedor:** Equipo + AI Agents

package/templates/CODEX.md

@@ -0,0 +1,29 @@
+# CODING NORMS
+
+## Stack base
+
+- Backend: Express puerto 3001, db.json
+- Frontend: React + Vite puerto 3002
+- Tests: Jest y Vitest, cobertura objetivo >= 85%
+- Git: ramas prefijo codex-*
+
+## Normas de desarrollo
+
+- Crear carpeta `test/` en backend y frontend.
+- Toda funcion nueva debe tener al menos un test asociado.
+- Todo endpoint debe tener tests de integracion.
+- No hacer cambios sin actualizar tests y documentacion si aplica.
+- Validar entradas y manejar errores de forma consistente.
+- Mantener estilos y dependencias simples.
+
+## CI
+
+- CI debe correr en cada push y PR.
+- Pasos minimos: install, test backend, test frontend, coverage.
+- El pipeline debe ejecutar `npm run test:ci` en la raiz.
+- Rechazar merges si coverage < 85% o tests fallan.
+
+## Documentacion
+
+- README.md describe setup, arquitectura y endpoints.
+- ROADMAP.md mantiene el plan de trabajo.

package/templates/SETUP.md

@@ -0,0 +1,48 @@
+# Setup Project
+
+Este documento define el flujo guiado para alinear el objetivo del proyecto, el alcance y las restricciones antes de tocar documentación o arquitectura.
+
+## Resultado acordado
+
+Aplicación sencilla de lista de tareas con:
+
+- CRUD básico (crear, listar, completar, eliminar)
+- Web app con backend local
+- Persistencia en SQLite
+- UI cuidada aunque sea simple
+- Sin usuarios ni autenticación
+- Reaprovechar el código existente
+
+## Flujo Base (Iterativo)
+
+1. El usuario manifiesta objetivos o plan inicial.
+2. Si hubiera documentación previa y archivos de código, el agente la analiza todo y extrae puntos clave para la visión general.
+3. Si *NO* hubiera archivos previos (ignorar SETUP.md), el agente hace una primera pregunta abierta para entender el objetivo general del proyecto.
+4. A partir de ahí, el agente propone **tres escenarios posibles** basados en esa información.
+5. El usuario elige uno de los tres.
+6. El agente plantea otro cuestionario de **tres opciones** sobre un tema específico que necesite ser clarificado o ampliado.
+7. Repetir por **3 o 4 rondas** hasta lograr una visión general clara del proyecto y objetivos del usuario.
+8. El agente propone un **resumen breve** del proyecto.
+9. Si el usuario corrige, se abre una nueva ronda para aclarar y luego se actualiza el resumen.
+10. Si el usuario acepta, el agente redacta o corrige:
+   - `README.md`
+   - `ROADMAP.md`
+   - `docs/ARCHITECTURE.md`
+   - otros documentos relevantes
+11. El agente NO MODIFICA NI CREA CÓDIGO AUN, solo se enfoca en documentación, roadmap y arquitectura. El código se tocará en rondas posteriores.
+
+## Reglas del agente
+
+- Preguntas cortas y enfocadas.
+- Siempre ofrecer **tres opciones**, siendo la primera la recomendada. 
+- Si hubiera código o documentación previa, las opciones deben basarse en esa información, siendo la primera opción la que mejor se alinea con lo ya existente.
+- No avanzar a documentación hasta tener una visión general aceptada.
+- Reaprovechar el código existente siempre que sea posible.
+
+---
+
+Estas instrucciones se usan al iniciar o retomar el proyecto, o para corregir dirección.
+
+*NUNCA* se modifica el código previo en esta etapa, solo se propone la visión general, el roadmap y la arquitectura.
+
+