@cristiancorreau/forge 2.1.0

package/assets/core/schemas/project.schema.json

@@ -0,0 +1,503 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Forge project.yaml v2",
+  "description": "Schema de validación para project.yaml v2 del framework Forge",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [],
+  "properties": {
+    "project": {
+      "description": "Metadatos principales del proyecto",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "mode"],
+      "properties": {
+        "name": {
+          "description": "Nombre legible del proyecto",
+          "type": "string",
+          "minLength": 1
+        },
+        "slug": {
+          "description": "Identificador único en lowercase sin espacios, usado en rutas y nombres de recursos",
+          "type": ["string", "null"],
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "description": {
+          "description": "Descripción breve del propósito del proyecto",
+          "type": ["string", "null"]
+        },
+        "language": {
+          "description": "Lenguaje principal del proyecto",
+          "type": ["string", "null"],
+          "enum": ["typescript", "python", "ruby", "go", "php", "mixed", null]
+        },
+        "mode": {
+          "description": "Modo operativo del proyecto: startup (velocidad), standard (balance), enterprise (compliance)",
+          "type": "string",
+          "enum": ["startup", "standard", "enterprise"]
+        },
+        "status": {
+          "description": "Estado actual del proyecto",
+          "type": ["string", "null"],
+          "enum": ["active", "paused", "maintenance", "archived", null]
+        }
+      }
+    },
+    "team": {
+      "description": "Equipo del proyecto",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "Nombre del equipo",
+          "type": ["string", "null"]
+        },
+        "members": {
+          "description": "Lista de miembros del equipo",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "role": {
+                "type": "string",
+                "enum": ["lead", "backend", "frontend", "fullstack", "qa", "design"]
+              },
+              "email": { "type": ["string", "null"], "format": "email" }
+            }
+          }
+        }
+      }
+    },
+    "stack": {
+      "description": "Stack tecnológico del proyecto",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "backend": {
+          "description": "Framework o runtime del backend",
+          "type": ["string", "null"],
+          "enum": ["hono", "fastapi", "rails", "express", "laravel", "nestjs", "django", "go-gin", null]
+        },
+        "frontend": {
+          "description": "Framework del frontend",
+          "type": ["string", "null"],
+          "enum": ["nextjs", "nuxt", "remix", "rails-views", "astro", "sveltekit", null]
+        },
+        "database": {
+          "description": "Motor de base de datos principal",
+          "type": ["string", "null"],
+          "enum": ["postgresql", "mysql", "sqlite", null]
+        },
+        "orm": {
+          "description": "ORM o query builder utilizado (nuevo en v2)",
+          "type": ["string", "null"],
+          "enum": ["drizzle", "prisma", "sequelize", "typeorm", "sqlalchemy", "active-record", null]
+        },
+        "cache": {
+          "description": "Sistema de caché",
+          "type": ["string", "null"],
+          "enum": ["redis", "memcached", null]
+        },
+        "package_manager": {
+          "description": "Gestor de paquetes del proyecto (nuevo en v2)",
+          "type": ["string", "null"],
+          "enum": ["npm", "pnpm", "yarn", "bun", "pip", "poetry", "bundler", null]
+        },
+        "monorepo": {
+          "description": "Herramienta de monorepo si aplica (nuevo en v2)",
+          "type": ["string", "null"],
+          "enum": ["turborepo", "nx", "lerna", null]
+        },
+        "testing": {
+          "description": "Frameworks de testing activos",
+          "type": ["array", "null"],
+          "items": {
+            "type": "string",
+            "enum": ["vitest", "jest", "pytest", "rspec", "phpunit", "playwright", "cypress"]
+          }
+        }
+      }
+    },
+    "runtimes": {
+      "description": "Runtimes de IA habilitados. Si se omite, forge-generate-all.py auto-detecta por archivos presentes.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "active": {
+          "description": "Lista de runtimes a generar. Tiene prioridad sobre la auto-detección.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["claude-code", "opencode", "codex", "kiro"]
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      }
+    },
+    "agents": {
+      "description": "Configuración de agentes activos para este proyecto",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "active": {
+          "description": "Lista de nombres de agentes activos (de core/agents/)",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "by_role": {
+          "description": "Mapeo de rol a modelo específico (nuevo en v2)",
+          "type": ["object", "null"],
+          "additionalProperties": {
+            "type": "string",
+            "description": "Nombre del modelo Claude a usar para este rol (ej: claude-opus-4-7)"
+          }
+        },
+        "compliance": {
+          "description": "Agentes de compliance opcionales",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "profiles": {
+          "description": "Profiles stack-específicos (Tier 2) que reemplazan agentes genéricos",
+          "type": ["array", "null"],
+          "items": {
+            "type": "string",
+            "enum": [
+              "hono-drizzle", "nextjs-admin", "astro", "expo", "playwright-crawler",
+              "fastapi", "express", "rails", "nestjs", "django", "vuenuxt",
+              "go-gin", "sveltekit"
+            ]
+          }
+        }
+      }
+    },
+    "sprint": {
+      "description": "Configuración del sprint actual",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "current": {
+          "description": "Número del sprint actual",
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "length_days": {
+          "description": "Duración del sprint en días",
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "phases": {
+          "description": "Fases del sprint con sus specs",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "specs": {
+                "type": ["array", "null"],
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "skills": {
+      "description": "Skills de Forge activos para el proyecto",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "active": {
+          "description": "Lista de skills activos (de core/skills/)",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "integrations": {
+          "description": "Integraciones opcionales que requieren herramienta externa",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "wiki": {
+      "description": "Configuración del wiki del proyecto (solo si wiki-ingest/wiki-query están activos)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "description": "Ruta al wiki del proyecto, relativa a la raíz del repo",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "deploy": {
+      "description": "Configuración de deploy y smoke tests (nuevo en v2)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": {
+          "description": "Plataforma de deploy",
+          "type": ["string", "null"],
+          "enum": ["vercel", "railway", "fly", "aws", "github-actions", "custom", null]
+        },
+        "branch": {
+          "description": "Branch que trigerea el deploy automático",
+          "type": ["string", "null"]
+        },
+        "project_id": {
+          "description": "ID del proyecto en la plataforma de deploy (ej: prj_xxx en Vercel)",
+          "type": ["string", "null"]
+        },
+        "production_url": {
+          "description": "URL de producción del proyecto",
+          "type": ["string", "null"],
+          "format": "uri"
+        },
+        "team_id": {
+          "description": "ID del equipo en Vercel (ej: team_xxx)",
+          "type": ["string", "null"]
+        },
+        "app_name": {
+          "description": "Nombre de la app en Fly.io",
+          "type": ["string", "null"]
+        },
+        "check_command": {
+          "description": "Comando para verificar el deploy en providers custom",
+          "type": ["string", "null"]
+        },
+        "smoke_tests": {
+          "description": "Tests de humo a ejecutar después del deploy",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["url"],
+            "properties": {
+              "url": {
+                "description": "URL o ruta relativa a verificar (ej: /api/health o https://...)",
+                "type": "string"
+              },
+              "expect_status": {
+                "description": "HTTP status code esperado",
+                "type": ["integer", "null"],
+                "minimum": 100,
+                "maximum": 599
+              },
+              "expect_json": {
+                "description": "Objeto JSON que debe estar contenido en la respuesta",
+                "type": ["object", "null"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "mcp": {
+      "description": "Configuración de servidores MCP (Model Context Protocol) (nuevo en v2)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "servers": {
+          "description": "Lista de servidores MCP configurados para el proyecto",
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "description": "Nombre del servidor MCP",
+                "type": "string"
+              },
+              "auto_approve": {
+                "description": "Lista de nombres de tools que se auto-aprueban sin confirmación",
+                "type": ["array", "null"],
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "github": {
+      "description": "Integración con GitHub Projects para tracking de tareas (nuevo en v2)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "project": {
+          "description": "Configuración del GitHub Project asociado",
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "properties": {
+            "number": {
+              "description": "Número del GitHub Project",
+              "type": ["integer", "null"],
+              "minimum": 1
+            },
+            "owner": {
+              "description": "Owner del repositorio (usuario u organización)",
+              "type": ["string", "null"]
+            },
+            "repo": {
+              "description": "Nombre del repositorio",
+              "type": ["string", "null"]
+            },
+            "status_field_id": {
+              "description": "ID del campo Status en el GitHub Project",
+              "type": ["string", "null"]
+            },
+            "status_in_progress": {
+              "description": "Valor del campo Status para tareas en progreso",
+              "type": ["string", "null"]
+            },
+            "status_done": {
+              "description": "Valor del campo Status para tareas completadas",
+              "type": ["string", "null"]
+            }
+          }
+        }
+      }
+    },
+    "rules": {
+      "description": "Reglas de desarrollo y guardrails del proyecto (nuevo en v2)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "forbidden_in_production": {
+          "description": "Lista de strings o patrones que no deben estar en código de producción",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "required_review_before_ship": {
+          "description": "Requiere revisión humana antes de hacer ship",
+          "type": ["boolean", "null"]
+        },
+        "require_spec_before_implementation": {
+          "description": "Requiere spec aprobada antes de comenzar implementación",
+          "type": ["boolean", "null"]
+        },
+        "conventional_commits": {
+          "description": "Enforza Conventional Commits en todos los commits",
+          "type": ["boolean", "null"]
+        },
+        "forbidden_patterns": {
+          "description": "Lista de patrones regex evaluados por el hook pre-edit-check",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "scripts": {
+      "description": "Comandos de scripts del proyecto (nuevo en v2)",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "check": {
+          "description": "Comando ejecutado por post-turn-check.sh para validar el proyecto",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "compliance": {
+      "description": "Configuración de compliance y regulaciones",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "frameworks": {
+          "description": "Frameworks regulatorios aplicables al proyecto",
+          "type": ["array", "null"],
+          "items": {
+            "type": "string",
+            "enum": ["gdpr", "lgpd", "ley-21719", "ccpa"]
+          }
+        },
+        "pii_handling": {
+          "description": "El proyecto maneja Personally Identifiable Information",
+          "type": ["boolean", "null"]
+        },
+        "audit_logs": {
+          "description": "El proyecto requiere logs inmutables de auditoría",
+          "type": ["boolean", "null"]
+        }
+      }
+    },
+    "paths": {
+      "description": "Paths del proyecto relativos a la raíz del repo",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "specs": {
+          "description": "Directorio de specs del proyecto",
+          "type": ["string", "null"]
+        },
+        "progress": {
+          "description": "Archivo de progreso HTML",
+          "type": ["string", "null"]
+        },
+        "migrations": {
+          "description": "Directorio de migraciones de base de datos",
+          "type": ["string", "null"]
+        },
+        "tests": {
+          "description": "Directorio de tests",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "agent_paths": {
+      "description": "Paths de scope por agente, inyectados en el frontmatter de cada agente durante forge-init",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "api": {
+          "description": "Directorio del agente backend/API",
+          "type": ["string", "null"]
+        },
+        "frontend": {
+          "description": "Directorio del agente frontend",
+          "type": ["string", "null"]
+        },
+        "admin": {
+          "description": "Directorio del agente admin",
+          "type": ["string", "null"]
+        },
+        "mobile": {
+          "description": "Directorio del agente mobile",
+          "type": ["string", "null"]
+        },
+        "scanner": {
+          "description": "Directorio del agente scanner/crawler",
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "integrations": {
+      "description": "Configuración de integraciones externas",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "obsidian": {
+          "description": "Integración con Obsidian via Local REST API",
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "properties": {
+            "vault_path": {
+              "description": "Ruta al vault de Obsidian, relativa a la raíz del repo",
+              "type": ["string", "null"]
+            },
+            "map": {
+              "description": "Mapeo de área de código a nota del vault",
+              "type": ["object", "null"],
+              "additionalProperties": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/assets/core/skills/README.md

@@ -0,0 +1,88 @@
+# Skills del framework forge
+
+## Mapa de skills y dependencias
+
+```
+new-feature ──────────────────────────────────────────────────┐
+│                                                              │
+├── spec              (Fase 1 — verificar/crear spec)          │
+├── phase-kickoff     (Fase 3 — si se crea team de agentes)    │
+├── security-audit    (Fase 4 — checklist antes de API routes) │
+├── db-migrate        (Fase 5 — si hay cambios de schema)      │
+├── browser-test      (Fase 6 — OPCIONAL, screenshot evidencia)│
+├── obsidian-sync     (Fase 6 — OPCIONAL, si está configurado) │
+└── local2prod        (Fase 6 — deploy a producción)           │
+    └── obsidian-sync (Paso 5 — OPCIONAL)               ───────┘
+
+wiki-ingest ← fuente (URL | archivo | texto)
+     ↓ crea/actualiza
+wiki/ (concepts, entities, sources, synthesis)
+     ↑
+wiki-query  ← pregunta → respuesta con citas
+wiki-lint   → health check + auto-reparación
+```
+
+## Catálogo
+
+| Skill | Categoría | Requiere herramienta externa | Invocado por |
+|-------|-----------|------------------------------|--------------|
+| `spec` | Core | No | new-feature, orchestrator |
+| `phase-kickoff` | Core | No | orchestrator, new-feature |
+| `security-audit` | Universal | No | new-feature, security-auditor |
+| `db-migrate` | Universal | No (solo el ORM del proyecto) | new-feature |
+| `browser-test` | Universal | `agent-browser` CLI (npm i -g) | new-feature, usuario directo |
+| `wiki-ingest` | Wiki | No | usuario directo, docs-writer |
+| `wiki-query` | Wiki | No | usuario directo, new-feature |
+| `wiki-lint` | Wiki | No | usuario directo |
+| `local2prod` | Universal | CLI del provider de deploy | new-feature |
+| `new-feature` | Universal | No (orquesta los otros) | Usuario directo |
+| `obsidian-sync` | Integración | Obsidian + Local REST API | new-feature, local2prod |
+
+## Categorías
+
+### Core — siempre presentes
+- **`spec`**: redactar specs siguiendo la plantilla obligatoria
+- **`phase-kickoff`**: protocolo para iniciar un sprint o fase nueva
+
+### Universales — activar según el proyecto
+Configurar en `project.yaml` bajo `skills.active`:
+- **`security-audit`**: checklist de auth, authz, IDOR, input validation
+- **`db-migrate`**: flujo seguro de migraciones (Prisma, Drizzle, Rails, Alembic, Goose)
+- **`browser-test`**: automatización de navegador — screenshots, verificación de UI, testeo visual. Requiere `agent-browser` instalado globalmente (`npm i -g agent-browser && agent-browser install`)
+- **`local2prod`**: commit → push → esperar CI → verificar (Vercel, Railway, Fly, custom)
+- **`new-feature`**: checklist completo de implementación (orquesta los otros)
+
+### Wiki — knowledge base del proyecto
+Configurar en `project.yaml` bajo `skills.active`. Generan slash commands `/wiki-ingest`, `/wiki-query`, `/wiki-lint` en Claude Code. La estructura `docs/wiki/` se inicializa con `forge-init.py`:
+- **`wiki-ingest`**: ingesta fuentes (URL, archivo, texto) → actualiza `raw/` + páginas wiki + index + log
+- **`wiki-query`**: responde preguntas usando el wiki como base, con citas a páginas
+- **`wiki-lint`**: verifica integridad del wiki: links, huérfanos, frontmatter, log
+
+Configuración opcional en `project.yaml`:
+```yaml
+wiki:
+  path: "docs/wiki"   # default
+```
+
+### Integraciones — requieren herramienta externa
+Configurar en `project.yaml` bajo `skills.integrations`:
+- **`obsidian-sync`**: mantiene vault de Obsidian sincronizado con el código
+
+## Cómo conviven
+
+Los skills son componibles: `new-feature` invoca los demás en el orden correcto.
+Las integraciones son opcionales — si no están configuradas en `project.yaml`, los
+skills que las referencian las saltean silenciosamente.
+
+No hay conflicto entre skills porque cada uno tiene un dominio claro:
+- `security-audit` y `db-migrate` son standalone (no se invocan entre sí)
+- `local2prod` solo invoca `obsidian-sync` opcionalmente
+- `new-feature` es el único que orquesta los demás
+
+## Cómo agregar un skill nuevo
+
+1. Crear `core/skills/<nombre>/SKILL.md` con frontmatter `name`, `description`, `triggers`
+2. Definir claramente: cuándo usarlo, qué hace, qué no hace
+3. Declarar relación con otros skills al final ("Relación con otros skills")
+4. Agregar al catálogo en este README
+5. Si requiere configuración en `project.yaml`, actualizar `templates/project.yaml.tpl`

package/assets/core/skills/aitmpl-search/SKILL.md

@@ -0,0 +1,74 @@
+# Skill: aitmpl-search
+
+Busca en el catálogo curado de forge: frameworks de agentes IA, MCP servers instalables,
+profiles de stack y herramientas. La búsqueda es offline (catálogo local); opcionalmente
+puede extenderse a GitHub con `--github`.
+
+Triggers: /aitmpl-search, "buscar templates", "buscar en catálogo", "templates de AI",
+"buscar template", "buscar MCP", "buscar profile".
+
+---
+
+## Cuándo usar este skill
+
+- Cuando el usuario quiere explorar frameworks o herramientas de agentes IA
+- Antes de diseñar un agente Tier 2 nuevo, para ver si ya existe un profile en forge
+- Cuando se necesita instalar un MCP server y se quiere ver qué hay disponible
+- Para explorar patrones de arquitectura de agentes reutilizables
+
+---
+
+## Protocolo
+
+### Paso 1 — Ejecutar la búsqueda
+
+Búsqueda por texto en el catálogo local:
+```bash
+python3 .agentic/scripts/aitmpl-search.py "<query>" --limit 10
+```
+
+Filtrar por categoría (`framework`, `mcp-server`, `profile`, `tool`, `resource`):
+```bash
+python3 .agentic/scripts/aitmpl-search.py "<query>" --category mcp-server
+```
+
+Ver todas las categorías disponibles:
+```bash
+python3 .agentic/scripts/aitmpl-search.py --list-categories
+```
+
+Salida JSON (para integración o análisis):
+```bash
+python3 .agentic/scripts/aitmpl-search.py "<query>" --json
+```
+
+Extender con búsqueda en GitHub (requiere red; límite 60 req/h sin token):
+```bash
+python3 .agentic/scripts/aitmpl-search.py "<query>" --github
+export GITHUB_TOKEN=ghp_...   # aumenta a 5000 req/h
+```
+
+Desde el CLI interactivo:
+```bash
+python3 .agentic/forge.py   # → "Buscar templates" → buscar o filtrar por categoría
+```
+
+### Paso 2 — Analizar resultados
+
+- Revisar los items más relevantes a la necesidad del proyecto
+- Para MCP servers: verificar el campo `install` del resultado JSON para el comando exacto
+- Para profiles: comparar con los profiles activos en `agents.profiles` de `project.yaml`
+- Para frameworks: comparar con el stack del proyecto antes de sugerir adopción
+
+### Paso 3 — Instalar (opcional)
+
+Para MCP servers, el CLI interactivo ofrece instalación directa que escribe en `.claude/settings.json`.
+Para profiles, ofrece agregar el profile a `project.yaml` directamente.
+
+---
+
+## No hagas
+
+- No asumir que un resultado del catálogo está actualizado — verificar el repositorio antes de recomendar
+- No crear agentes Tier 2 sin revisar si el stack ya tiene un profile en `profiles/`
+- No instalar MCP servers sin verificar que el usuario tiene Python 3.9+ y las dependencias requeridas