@cristiancorreau/forge 2.1.0

package/assets/adapters/codex/commands/work.md

@@ -0,0 +1,53 @@
+---
+name: work
+description: Template para implementar una feature con Codex CLI siguiendo SDD
+usage: Copia el contenido de Prompt en tu sesión de Codex
+---
+
+## Prompt para Codex
+
+Implementa la siguiente feature: [NOMBRE O RUTA A LA SPEC]
+
+Sigue estos pasos en orden estricto:
+
+1. **Verificar spec aprobada**
+   - Lee `docs/specs/[ID]-[nombre].md`.
+   - Verifica que el estado sea `APPROVED`. Si dice `DRAFT`, detente: la spec necesita aprobación antes de implementar.
+
+2. **Leer contexto existente**
+   - Lee `project.yaml` para entender el stack y los paths configurados.
+   - Lee los archivos que la spec indica que serán afectados.
+   - Si el proyecto tiene `CLAUDE.md` o `AGENTS.md`, léelo para entender las convenciones del proyecto.
+
+3. **Implementar en este orden**
+   ```
+   a. Schema de base de datos (si hay modelos nuevos o modificados)
+   b. Types / interfaces compartidos
+   c. Backend — lógica de negocio, servicios, API routes
+   d. Frontend — componentes, páginas (si aplica)
+   e. Tests junto con cada capa, no al final
+   ```
+
+4. **Checklist de seguridad** (aplicar a cada endpoint o función que crees):
+   - [ ] ¿Verifica autenticación?
+   - [ ] ¿Verifica autorización por rol/ownership?
+   - [ ] ¿El input está validado con schema explícito?
+   - [ ] ¿Las queries usan parámetros preparados (no interpolación de strings)?
+   - [ ] ¿No hay secrets hardcodeados?
+
+5. **Al terminar cada archivo**
+   - Verifica que el código compila / no tiene errores de sintaxis.
+   - Si es TypeScript: asegúrate que los tipos son correctos.
+   - Si es Python: sin errores de sintaxis.
+
+6. **Al terminar la implementación completa**
+   - Actualiza `docs/specs/[ID]-[nombre].md`: agrega decisiones tomadas en la sección "Notas de implementación".
+   - Cambia el estado de la spec de `APPROVED` a `IMPLEMENTED`.
+   - Lista todos los archivos creados o modificados.
+
+Restricciones absolutas:
+- Sin hardcodear tokens, passwords ni secrets — usar variables de entorno.
+- Sin force push a main/master.
+- Sin eliminar archivos sin confirmación explícita.
+- Correr los tests antes de declarar la tarea completa.
+- Nunca commitear directamente a main/master.

package/assets/adapters/codex/generate-codex-config.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+# Copyright 2026 Cristian Correa — Apache License 2.0
+# https://github.com/cristiancorreau/forge
+"""
+generate-codex-config.py — Genera AGENTS.md para Codex CLI (OpenAI).
+
+Usage:
+  python3 .agentic/adapters/codex/generate-codex-config.py
+
+Lee project.yaml en la raíz y genera AGENTS.md enriquecido para Codex CLI.
+
+Diferencias respecto al adapter OpenCode:
+  - Incluye sección "Workflow SDD" con pasos explícitos (Codex opera autónomamente)
+  - Incluye "Security rules" y "Autonomy limits" inline (crítico para ejecución sin supervisión)
+  - Header identifica el archivo como generado para Codex CLI
+
+Codex CLI lee AGENTS.md desde la raíz del repositorio como contexto del agente.
+Referencia: https://github.com/openai/codex
+
+Requiere: pyyaml
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("ERROR: pyyaml requerido. pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+
+def find_project_root() -> Path:
+    here = Path.cwd()
+    for p in [here] + list(here.parents):
+        if (p / "project.yaml").exists():
+            return p
+    raise FileNotFoundError("No se encontró project.yaml")
+
+
+def find_forge_dir() -> Path:
+    root = find_project_root()
+    for candidate in [root / ".agentic", root / "forge", Path(__file__).parent.parent.parent]:
+        if (candidate / "core").exists():
+            return candidate
+    raise FileNotFoundError("No se encontró el directorio forge con core/")
+
+
+def read_agent_description(forge: Path, name: str, profiles: list[str]) -> str:
+    """Lee el frontmatter description del agente desde forge (profiles > core)."""
+    for profile in profiles:
+        p = forge / "profiles" / profile / "agents" / f"{name}.md"
+        if p.exists():
+            content = p.read_text()
+            for line in content.splitlines():
+                if line.startswith("description:"):
+                    return line.split(":", 1)[1].strip().strip('"')
+    p = forge / "core" / "agents" / f"{name}.md"
+    if p.exists():
+        content = p.read_text()
+        for line in content.splitlines():
+            if line.startswith("description:"):
+                return line.split(":", 1)[1].strip().strip('"')
+    return "Agente de implementación"
+
+
+def generate_agents_md(config: dict, forge: Path) -> str:
+    """
+    Genera AGENTS.md enriquecido para Codex CLI.
+
+    Codex CLI opera autónomamente en terminal: las reglas de seguridad y los
+    límites de autonomía deben estar inline en AGENTS.md, no en un archivo
+    separado, para que el agente las reciba como contexto en cada sesión.
+    """
+    proj = config.get("project", {})
+    agents_cfg = config.get("agents", {})
+    compliance_cfg = config.get("compliance", {})
+    stack = config.get("stack", {})
+    paths = config.get("paths", {})
+
+    name = proj.get("name", "Mi Proyecto")
+    description = proj.get("description", "")
+    language = proj.get("language", "typescript")
+    active = agents_cfg.get("active", [])
+    compliance = agents_cfg.get("compliance", [])
+    specialized = agents_cfg.get("specialized", [])
+    profiles = agents_cfg.get("profiles", [])
+    frameworks = compliance_cfg.get("frameworks", [])
+    specs_path = paths.get("specs", "docs/specs")
+
+    if frameworks and "compliance-reviewer" not in active + compliance:
+        compliance = list(set(compliance + ["compliance-reviewer"]))
+
+    lines = [
+        f"# AGENTS.md — {name}",
+        "",
+        f"> Generado por forge (adapter Codex CLI).",
+        f"> Fuente de verdad: `project.yaml`. Re-ejecutar `generate-codex-config.py` al cambiar agentes.",
+        "",
+    ]
+
+    if description:
+        lines += [description, ""]
+
+    lines += [
+        "## Stack",
+        "",
+        f"- **Lenguaje:** {language}",
+        f"- **Backend:** {stack.get('backend') or 'N/A'}",
+        f"- **Frontend:** {stack.get('frontend') or 'N/A'}",
+        f"- **Base de datos:** {stack.get('database') or 'N/A'}",
+        f"- **Testing:** {', '.join(stack.get('testing', []))}",
+        "",
+        "## Workflow: Spec-Driven Development",
+        "",
+        "Antes de implementar cualquier feature:",
+        "",
+        f"1. Verificar que existe una spec en `{specs_path}/`.",
+        "2. Si no existe, crearla y esperar aprobación antes de codificar.",
+        "3. Implementar con tests junto al código, no al final.",
+        "4. Actualizar la spec con decisiones tomadas durante la implementación.",
+        "",
+        "## Reglas de seguridad (no negociables)",
+        "",
+        "- Sin hardcodear tokens, passwords ni secrets — usar variables de entorno.",
+        "- Parámetros preparados en todas las queries SQL — nunca concatenar input del usuario.",
+        "- PII nunca en logs de stdout.",
+        "- Verificar autenticación Y autorización en cada endpoint de API.",
+        "- Sin force push a main/master.",
+        "",
+        "## Límites de autonomía",
+        "",
+        "- Modificar solo archivos dentro del scope declarado del agente.",
+        "- Preguntar antes de eliminar archivos o ejecutar comandos destructivos.",
+        "- Nunca hacer commit directo a main/master.",
+        "- Correr los tests antes de marcar una tarea como completa.",
+        "- Si una tarea requiere acceso a credenciales no disponibles, detenerse y reportar.",
+        "",
+        "## Roster de agentes",
+        "",
+    ]
+
+    if active:
+        lines += ["### Activos", ""]
+        for agent in active:
+            desc = read_agent_description(forge, agent, profiles)
+            lines.append(f"#### `{agent}`")
+            lines.append(desc)
+            lines.append("")
+
+    if compliance:
+        lines += ["### Compliance y revisión", ""]
+        for agent in compliance:
+            desc = read_agent_description(forge, agent, profiles)
+            lines.append(f"#### `{agent}`")
+            lines.append(desc)
+            lines.append("")
+
+    if specialized:
+        lines += ["### Especializados del proyecto", ""]
+        for agent in specialized:
+            desc = read_agent_description(forge, agent, profiles)
+            lines.append(f"#### `{agent}`")
+            lines.append(desc)
+            lines.append("")
+
+    if frameworks:
+        lines += [
+            "## Compliance activo",
+            "",
+            f"Marcos regulatorios: {', '.join(f.upper() for f in frameworks)}",
+            "",
+            "Incluir `compliance-reviewer` en toda tarea que toque:",
+            "- Datos de usuarios o consentimientos",
+            "- Logs de auditoría",
+            "- Endpoints de derechos del titular (DSAR)",
+            "",
+        ]
+
+    lines += [
+        "## Forge v2 Commands",
+        "",
+        "Codex CLI no soporta slash commands. Usa las plantillas de prompt de",
+        "`adapters/codex/commands/` copiando su contenido directamente en tu sesión.",
+        "",
+        "| Comando | Archivo | Cuándo usarlo |",
+        "|---------|---------|---------------|",
+        "| plan | `adapters/codex/commands/plan.md` | Antes de implementar — verifica o crea la spec |",
+        "| work | `adapters/codex/commands/work.md` | Implementar una feature con spec APPROVED |",
+        "| review | `adapters/codex/commands/review.md` | Revisar código o cambios antes del merge |",
+        "| ship | `adapters/codex/commands/ship.md` | Verificar que el proyecto está listo para deploy |",
+        "| session-start | `adapters/codex/commands/session-start.md` | Al iniciar cada sesión de trabajo |",
+        "| session-close | `adapters/codex/commands/session-close.md` | Al cerrar cada sesión de trabajo |",
+        "",
+        "### Flujo SDD recomendado",
+        "",
+        "```",
+        "1. session-start   → verificar ambiente y branch",
+        "2. plan            → spec antes que código (DRAFT → APPROVED)",
+        "3. work            → implementar con tests (spec APPROVED → IMPLEMENTED)",
+        "4. review          → checklist de seguridad y calidad",
+        "5. ship            → verificar build, tests y variables antes del deploy",
+        "6. session-close   → registrar progreso y limpiar",
+        "```",
+        "",
+        "## Reglas de producción (pre-bash-check)",
+        "",
+        "Los siguientes comandos están bloqueados en contexto de producción.",
+        "Si necesitás ejecutarlos, hacelo manualmente en la terminal con plena consciencia:",
+        "",
+        "- `--force-reset` — puede destruir datos de base de datos",
+        "- `prisma migrate reset` — borra y re-crea la base de datos",
+        "- `DROP TABLE` / `DROP DATABASE` — destruye tablas o bases de datos",
+        "- `TRUNCATE` — elimina todos los registros de una tabla",
+        "- `DELETE FROM <tabla>;` — sin cláusula WHERE, elimina todo",
+        "- `dropdb` — elimina una base de datos completa",
+        "- `rm -rf /` — elimina recursivamente desde la raíz",
+        "- `git push --force` sin `--with-lease` — sobreescribe historial remoto",
+        "",
+        "Contexto de producción = la URL de producción o el project_id aparecen",
+        "en el comando, o hay variables de entorno `PROD_*` / `PRODUCTION_*` activas.",
+        "",
+        "Lección del 2026-04-28: --force-reset borró 225 usuarios y 35 formularios",
+        "en producción. Estas reglas existen por eso.",
+        "",
+        "## Branch guard (pre-edit-check)",
+        "",
+        "No editar archivos de código fuente directamente en `main` o `master`.",
+        "",
+        "Archivos de código = `.py`, `.ts`, `.js`, `.tsx`, `.jsx`, `.php`, `.rb`,",
+        "`.go`, `.rs`, `.java`, `.cs`, `.cpp`, `.c`, `.sh`",
+        "",
+        "Excenciones permitidas en rama protegida:",
+        "- Archivos de documentación (`docs/`, `.md`)",
+        "- Archivos de configuración en raíz (`.yaml`, `.yml`, `.json`)",
+        "- `CLAUDE.md`, `AGENTS.md`, `README.md`, `CHANGELOG.md`",
+        "",
+        "Si estás en `main` o `master`, crea una feature branch primero:",
+        "```bash",
+        "git checkout -b feature/<tema>-$(date +%Y-%m-%d)",
+        "```",
+        "",
+    ]
+
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        root = find_project_root()
+        forge = find_forge_dir()
+    except FileNotFoundError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(root / "project.yaml") as f:
+        config = yaml.safe_load(f)
+
+    content = generate_agents_md(config, forge)
+    output_path = root / "AGENTS.md"
+    with open(output_path, "w") as f:
+        f.write(content)
+    print(f"  [OK]   AGENTS.md generado en {output_path}")
+    print("         (adapter Codex: incluye SDD workflow + security rules + autonomy limits)")
+
+
+if __name__ == "__main__":
+    main()

package/assets/adapters/codex/hooks/codex.yaml.tpl

@@ -0,0 +1,43 @@
+# .codex/codex.yaml — Forge v2 hooks para Codex CLI
+#
+# Generar con: cp adapters/codex/hooks/codex.yaml.tpl .codex/codex.yaml
+# O usar: bash scripts/setup-codex.sh
+#
+# SOPORTE DE HOOKS EN CODEX CLI (estado a 2025):
+#   onStart  — se ejecuta al inicio de cada sesión de Codex. Equivalente
+#              al hook SessionStart / UserPromptSubmit de Claude Code.
+#   onFinish — se ejecuta al finalizar cada sesión de Codex. Equivalente
+#              al hook Stop de Claude Code.
+#   onDiff   — se ejecuta cuando Codex aplica cambios al filesystem.
+#              No tiene equivalente directo en Claude Code.
+#
+# NO SOPORTADO en Codex CLI (a diferencia de Claude Code):
+#   - PreToolUse: Codex no puede interceptar herramientas individuales
+#     antes de ejecutarlas. Las reglas de pre-bash-check.py y
+#     pre-edit-check.py NO tienen equivalente automático en Codex.
+#     Esas reglas están embebidas en AGENTS.md como instrucciones de texto
+#     para que el agente las respete voluntariamente.
+#   - PostToolUse: tampoco soportado.
+#
+# IMPLICACIÓN: La capa de seguridad de Codex es instruccional (AGENTS.md),
+# no mecánica (hooks que bloquean). Para proyectos de alto riesgo, preferir
+# Claude Code que sí puede bloquear comandos destructivos antes de ejecutarlos.
+
+model: o4-mini  # Cambiar según preferencia: o4-mini | o3 | gpt-4o
+
+hooks:
+  # Ejecutado al inicio de cada sesión.
+  # Equivalent: Claude Code SessionStart / UserPromptSubmit hook.
+  # Verifica herramientas disponibles, branch, cambios sin commitear,
+  # project.yaml y variables de entorno de producción activas.
+  onStart: bash .codex/forge-codex-start.sh
+
+  # Ejecutado al finalizar cada sesión.
+  # Equivalent: Claude Code Stop hook (post-turn-check.sh).
+  # Detecta archivos modificados y corre type-check / syntax-check.
+  onFinish: bash .codex/forge-codex-finish.sh
+
+  # onDiff: no configurado por defecto.
+  # Se puede usar para correr linters en los archivos cambiados.
+  # Ejemplo: onDiff: bash -c 'echo "$CODEX_DIFF_FILES" | xargs eslint --fix'
+  # onDiff: ""

package/assets/adapters/codex/hooks/forge-codex-finish.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Forge v2 — Codex onFinish hook: forge-codex-finish.sh
+#
+# Se ejecuta al finalizar cada sesión de Codex CLI.
+# Equivalente al hook post-turn-check.sh de Claude Code (Stop event).
+#
+# DIFERENCIAS vs Claude Code:
+#   - Claude Code: post-turn-check.sh corre después de CADA turno del agente.
+#   - Codex CLI: forge-codex-finish.sh corre al FINALIZAR la sesión completa,
+#     no después de cada mensaje individual. Codex no tiene un equivalente
+#     granular de "Stop por turno".
+#   - Claude Code Stop hook: puede imprimir al contexto del agente (el output
+#     se muestra como resultado del hook).
+#   - Codex CLI onFinish: el output se muestra en la terminal del usuario,
+#     pero puede no ser visible en el contexto del agente dependiendo de la
+#     versión de Codex.
+#
+# LIMITACIONES de Codex vs Claude Code:
+#   - No hay PreToolUse/PostToolUse hooks para interceptar herramientas individuales.
+#   - Los checks de este script son post-sesión, no post-turno.
+#
+# Instalación: este script debe copiarse o enlazarse en .codex/forge-codex-finish.sh
+# El setup-codex.sh lo hace automáticamente.
+
+set -uo pipefail
+
+# ---------------------------------------------------------------------------
+# Step 1 — Find modified files
+# ---------------------------------------------------------------------------
+MODIFIED=$(git diff --name-only HEAD 2>/dev/null || echo "")
+STAGED=$(git diff --name-only --cached 2>/dev/null || echo "")
+ALL_CHANGED="$MODIFIED $STAGED"
+
+if [ -z "$(echo "$ALL_CHANGED" | tr -d '[:space:]')" ]; then
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2 — Read project config
+# ---------------------------------------------------------------------------
+PKG_MGR=""
+CUSTOM_CHECK=""
+
+if [ -f "project.yaml" ]; then
+  PKG_MGR=$(python3 -c "
+import yaml, sys
+try:
+    d = yaml.safe_load(open('project.yaml'))
+    print(d.get('stack', {}).get('package_manager', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+  CUSTOM_CHECK=$(python3 -c "
+import yaml, sys
+try:
+    d = yaml.safe_load(open('project.yaml'))
+    print(d.get('scripts', {}).get('check', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+fi
+
+CHECK_OUTPUT=""
+
+# ---------------------------------------------------------------------------
+# Step 3 — Run checks
+# ---------------------------------------------------------------------------
+
+# Helper: check if any changed file matches a glob pattern
+files_matching() {
+  local pattern="$1"
+  echo "$ALL_CHANGED" | tr ' ' '\n' | grep -E "$pattern" 2>/dev/null || true
+}
+
+if [ -n "$CUSTOM_CHECK" ]; then
+  # Run user-defined check command
+  CHECK_OUTPUT=$(eval "$CUSTOM_CHECK" 2>&1 | head -20 || true)
+
+else
+  # Auto-detect by file type
+
+  # TypeScript / JavaScript
+  TS_FILES=$(files_matching '\.(ts|tsx)$')
+  if [ -n "$TS_FILES" ]; then
+    if [ -f "turbo.json" ] && command -v pnpm &>/dev/null; then
+      TSC_OUTPUT=$(pnpm turbo typecheck 2>&1 | head -20 || pnpm tsc --noEmit 2>&1 | head -20 || true)
+    elif command -v pnpm &>/dev/null; then
+      TSC_OUTPUT=$(pnpm tsc --noEmit 2>&1 | head -20 || true)
+    elif command -v npx &>/dev/null; then
+      TSC_OUTPUT=$(npx tsc --noEmit 2>&1 | head -20 || true)
+    else
+      TSC_OUTPUT=""
+    fi
+    if [ -n "${TSC_OUTPUT:-}" ]; then
+      CHECK_OUTPUT="${CHECK_OUTPUT:+$CHECK_OUTPUT$'\n'}[tsc] $TSC_OUTPUT"
+    fi
+  fi
+
+  # PHP
+  PHP_FILES=$(files_matching '\.php$')
+  if [ -n "$PHP_FILES" ] && [ -f "composer.json" ]; then
+    if command -v composer &>/dev/null; then
+      PHP_OUTPUT=$(composer validate --no-check-publish 2>&1 | head -10 || true)
+      if [ -n "$PHP_OUTPUT" ]; then
+        CHECK_OUTPUT="${CHECK_OUTPUT:+$CHECK_OUTPUT$'\n'}[composer] $PHP_OUTPUT"
+      fi
+    fi
+  fi
+
+  # Python
+  PY_FILES=$(files_matching '\.py$')
+  if [ -n "$PY_FILES" ]; then
+    PY_OUTPUT=""
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      [ -f "$f" ] || continue
+      RESULT=$(python3 -m py_compile "$f" 2>&1 || true)
+      if [ -n "$RESULT" ]; then
+        PY_OUTPUT="${PY_OUTPUT:+$PY_OUTPUT$'\n'}$f: $RESULT"
+      fi
+    done <<< "$PY_FILES"
+    if [ -n "$PY_OUTPUT" ]; then
+      CHECK_OUTPUT="${CHECK_OUTPUT:+$CHECK_OUTPUT$'\n'}[python] $PY_OUTPUT"
+    fi
+  fi
+
+  # Ruby
+  RB_FILES=$(files_matching '\.rb$')
+  if [ -n "$RB_FILES" ] && [ -f "Gemfile" ]; then
+    RB_OUTPUT=""
+    if command -v bundle &>/dev/null; then
+      while IFS= read -r f; do
+        [ -z "$f" ] && continue
+        [ -f "$f" ] || continue
+        RESULT=$(bundle exec ruby -c "$f" 2>&1 | head -10 || true)
+        if [ -n "$RESULT" ]; then
+          RB_OUTPUT="${RB_OUTPUT:+$RB_OUTPUT$'\n'}$f: $RESULT"
+        fi
+      done <<< "$RB_FILES"
+    fi
+    if [ -n "$RB_OUTPUT" ]; then
+      CHECK_OUTPUT="${CHECK_OUTPUT:+$CHECK_OUTPUT$'\n'}[ruby] $RB_OUTPUT"
+    fi
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4 — Report
+# ---------------------------------------------------------------------------
+if [ -n "$CHECK_OUTPUT" ]; then
+  echo "── Forge Codex post-session check ───────────"
+  echo "$CHECK_OUTPUT"
+  echo "─────────────────────────────────────────────"
+fi
+
+# Siempre exit 0 — este hook nunca bloquea.
+exit 0