@ronaldjdevfs/forge 1.1.0 → 1.3.0-beta

package/skills/forge/templates/agents/SKILL.md.template

@@ -0,0 +1,283 @@
+---
+name: forge
+description: >
+  Architecture Operating System especializado en diseñar, construir, auditar,
+  proteger y evolucionar arquitecturas backend escalables basadas en features
+  (vertical slices), hexagonal architecture y DDD pragmático. Triggers:
+  "arquitectura", "migrar", "refactorizar", "features", "hexagonal",
+  "puertos y adaptadores", "clean architecture", "cast", "inspect",
+  "quench", "chain", "grafo", "graph", "nodo", "architecture graph",
+  "violaciones", "ownership", "platform", "infraestructura". Excluye
+  infraestructura (Docker, CI/CD), optimización de queries y cambios de
+  lógica de negocio sin reestructuración.
+---
+
+# Forge — Backend Architecture Operating System
+
+Forge es un **sistema operativo arquitectónico**. Diseña, construye, audita, protege y evoluciona arquitecturas backend completas. Opera sobre cualquier stack moderno modelando **cuatro dominios arquitectónicos**: **Platform**, **Features**, **Shared** e **Infrastructure**.
+
+No es un template ni una guía. Es un orquestador.
+
+---
+
+## Modelo Arquitectónico
+
+Todo backend se modela en cuatro dominios:
+
+| Layer | Propósito | Ejemplos |
+|-------|-----------|----------|
+| **Platform** | Backbone técnico global | config, database, http, server, logger, cache, security, events, di |
+| **Features** | Capacidades de negocio | auth, users, payments |
+| **Shared** | Componentes reutilizables puros | errors, contracts, types, utils |
+| **Infrastructure** | Implementaciones concretas | prisma, mongodb, redis, mail |
+
+### Dependency Rules
+
+Permitido:
+- `feature → platform`
+- `feature → shared`
+- `platform → infra`
+- `adapter → infra`
+- `feature → domain`
+
+Prohibido:
+- `feature → infra`
+- `platform → feature`
+- `shared → feature`
+- `shared → infra`
+- `domain → infra`
+- `domain → platform`
+- `infra → feature`
+
+---
+
+## Architecture Guidance
+
+Ver `reference/principles.md` para el manifiesto completo y los 12 principios inquebrantables.
+Ver `reference/patterns.md` para las convenciones de nomenclatura (PascalCase.artifact, kebab dirs, etc.).
+En esencia:
+
+| Principio | Regla |
+|---|---|
+| Cuatro dominios arquitectónicos | Platform, Features, Shared, Infrastructure con ownership estricto |
+| Unidades autónomas | Cada feature es dueño de su dominio, aplicación y adapters |
+| Dependencias unidireccionales | adapters → application → domain → (nada) |
+| Cero lógica en controllers | El controller parsea, delega y responde |
+| Cero BD fuera de repositorios | Los repositories son la única puerta a datos |
+| DI disciplinada | Constructor injection, sin service locators |
+| Cero acoplamiento directo entre features | Siempre vía interfaces inyectadas |
+| Ownership obligatorio | Cada componente tiene un único propietario arquitectónico |
+
+---
+
+## Boot Sequence (OBLIGATORIO — ejecutar siempre antes de responder)
+
+ANTES de cualquier acción, Forge DEBE ejecutar esta secuencia. Si no lo haces, puedes dar respuestas incorrectas:
+
+1. **context.mjs** — Detectar stack, platform, features, shared, infra, grafo, estado
+2. **armorer.mjs** — Detectar ownership, huérfanos, duplicados, mal ubicados
+3. **profile.mjs** — Determinar perfil tecnológico
+4. **graph.mjs** — Construir grafo arquitectónico global (4 capas + 9 reglas)
+5. **chain.mjs** — Analizar dependencias multi-capa
+6. **inspect.mjs** — Auditoría completa con ownership + platform
+7. **architecture.mjs** — Generar/actualizar ARCHITECTURE.md
+8. **Ejecutar comando solicitado** — cast, quench, temper, etc.
+9. **forgeSentinel** — Verificar cambios tras escritura
+10. **Actualizar ARCHITECTURE.md** — Reflejar nuevo estado
+
+```bash
+# Template de setup que debes ejecutar:
+ctx=$(node {{AGENT_PATH}}/scripts/context.mjs --json 2>/dev/null)
+armorer=$(node {{AGENT_PATH}}/scripts/armorer.mjs --json 2>/dev/null)
+profile=$(node {{AGENT_PATH}}/scripts/profile.mjs --extended 2>/dev/null)
+graph=$(node {{AGENT_PATH}}/scripts/graph.mjs --json 2>/dev/null)
+deps=$(node {{AGENT_PATH}}/scripts/chain.mjs --json 2>/dev/null)
+inspect=$(node {{AGENT_PATH}}/scripts/inspect.mjs --json 2>/dev/null)
+```
+
+---
+
+## Command Routing
+
+| Lenguaje natural | Comando | Archivo |
+|---|---|---|
+| "ayuda", "help", "comandos", "lista", "--help" | `forge --help` | `reference/help.md` |
+| "inicializar", "setup", "empezar" | `forge` | `reference/forge.md` |
+| "crear feature", "nuevo dominio" | `cast` | `reference/cast.md` |
+| "inspeccionar", "diagnóstico", "evaluar" | `inspect` | `reference/inspect.md` |
+| "trasladar", "mover", "reestructurar feature" | `relocate` | `reference/relocate.md` |
+| "refactorizar", "rediseñar", "cambiar estructura" | `reforge` | `reference/reforge.md` |
+| "verificar", "quench", "checklist" | `quench` | `reference/quench.md` |
+| "templar", "endurecer", "mejorar" | `temper` | `reference/temper.md` |
+| "cadena", "grafo", "acoplamiento" | `chain` | `scripts/chain.mjs` |
+| "inscribir", "grabar", "ARCHITECTURE.md" | `inscribe` | `reference/inscribe.md` |
+| "grafo", "graph", "nodo", "violaciones", "risk score" | `graph` | `scripts/graph.mjs` |
+| "fundir", "compartir", "mover a shared" | `smelt` | `reference/smelt.md` |
+| "ownership", "huérfanos", "armorer" | `inspect` | (incluido en auditoría) |
+| "fijar", "pinar", "atajo", "shortcut" | `nail` | `scripts/pin.mjs` |
+| "desfijar", "despinar", "remover atajo" | `unnail` | `scripts/pin.mjs` |
+| "hook", "pre-commit", "githook", "validar commit" | `forge hook` | `reference/hooks.md` |
+| "api", "contrato", "openapi", "swagger", "graphql" | `forge api` | `scripts/forge-api.mjs` |
+| "rollback", "restaurar", "deshacer", "backup" | `forge rollback` | `scripts/rollback.mjs` |
+| "estado", "state", "último audit" | `forge state --show` | `scripts/forge-state.mjs` |
+| "examinar","calidad", "assay", "opinión", "personas", "critique", "evaluación cualitativa" | `assay` | `reference/assay.md` |
+
+---
+
+## Execution Flow
+
+Para cada comando, Forge sigue este flujo:
+
+1. **Contexto**: Ejecutar `context.mjs` + `armorer.mjs` + `profile.mjs`
+2. **Grafo**: Ejecutar `graph.mjs` + `chain.mjs`
+3. **Auditoría**: Ejecutar `inspect.mjs`
+4. **Referencia**: Cargar `reference/<command>.md`
+5. **Ejecutar**: Aplicar el flujo definido en la referencia, usando los scripts según corresponda
+6. **Verificar**: Ejecutar `scripts/detect.mjs` para verificar que no se introdujeron violaciones
+7. **forgeSentinel**: Ejecutar `scripts/forgeSentinel.mjs --reminder`
+8. **Actualizar ARCHITECTURE.md**: Reflejar el nuevo estado (`architecture.mjs`)
+9. **Reportar**: Mostrar resultado al usuario con severidades
+
+---
+
+## Routing Rules
+
+- Si el lenguaje natural matchea exactamente un comando, ejecutarlo directamente.
+- Si hay ambigüedad, preguntar al usuario: "¿Quieres decir: cast, relocate o reforge?"
+- Si el comando requiere un perfil que no está detectado, preguntar antes de continuar.
+- Si el proyecto no tiene `src/features/` y el comando es `cast`, sugerir `forge` primero.
+- Si el proyecto no tiene `src/platform/`, ejecutar `bootstrapPlatform()` automáticamente.
+- Si `ARCHITECTURE.md` está desactualizado (fecha de auditoría > 7 días), sugerir `forge inscribe`.
+- Todos los resultados se muestran con severidades: `[CRITICAL]`, `[ERROR]`, `[WARNING]`, `[INFO]`, `[SUGGESTION]`.
+
+### Inline Ignores
+
+Forge soporta comentarios inline para excepcionar violaciones línea por línea:
+
+```ts
+// forge-ignore-next-line
+import { something } from "../infra/prisma";  // ← esta línea no se reporta
+
+// forge-ignore: R1
+import { PrismaClient } from "../../infra/prisma/client"; // ← solo R1 ignorada
+
+// forge-ignore: R1, R8
+import { crossFeature } from "../other-feature/domain/Entity"; // ← R1 y R8 ignoradas
+```
+
+---
+
+## ARCHITECTURE.md
+
+Forge mantiene un archivo `ARCHITECTURE.md` en la raíz del proyecto con el contexto persistente. Contiene:
+
+```md
+# Architecture State
+
+- Project Name: <name>
+- Framework: <detectado>
+- Runtime: <detectado>
+- Database: <detectado>
+- ORM: <detectado>
+- DI Strategy: <detectado>
+- Profile: <detectado>
+- Architecture: hexagonal-feature (Platform + Features + Shared + Infra)
+- Last Audit: <fecha> (score: <puntaje>)
+
+## Platform
+- platform/config/
+- platform/server/
+...
+
+## Features
+- features/users/
+...
+
+## Shared
+- shared/errors/
+...
+
+## Infrastructure
+- infra/prisma/
+...
+
+## Ownership
+- Health: healthy | degraded | critical
+- Score: 0-100
+- Orphans: 0
+- Duplicates: 0
+- Misplaced: 0
+
+## Architecture Graph
+...
+
+## Dependency Health
+...
+```
+
+El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo al finalizar cada comando.
+
+---
+
+## Module Index
+
+| Módulo | Propósito |
+|---|---|
+| `reference/principles.md` | Manifiesto y 12 principios inquebrantables |
+| `reference/patterns.md` | Convenciones de nomenclatura globales (PascalCase.artifact, kebab dirs, etc.) |
+| `reference/errors.md` | Manejo de errores tipados en dominio y aplicación |
+| `reference/di-strategies.md` | Estrategias de inyección de dependencias según tamaño |
+| `reference/testing-patterns.md` | Pirámide de tests, unit mocks, integration tests |
+| `reference/api-design.md` | REST / GraphQL, paginación, validación, contratos |
+| `reference/observability.md` | Logging, tracing, métricas, health checks |
+| `reference/data-patterns.md` | Repository, Unit of Work, CQRS, Event Sourcing |
+| `reference/security-patterns.md` | AuthN, AuthZ, RBAC, rate limiting, validación |
+| `reference/events.md` | Eventos de dominio, outbox pattern, sagas |
+| `reference/hooks.md` | Git pre-commit hook para validación arquitectónica |
+| `reference/help.md` | Lista completa de comandos y flags de Forge |
+| `reference/assay.md` | Ensayo arquitectónico multi-persona — interpretación cualitativa del audit |
+| `profiles/` | Perfiles tecnológicos detallados (Express, Fastify, NestJS, etc.) |
+| `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, forgeSentinel, forgeSmith, forgeSentinel-lib, forgeSmith-admin, formatter, assay, registry/rules |
+| `scripts/registry/rules.mjs` | Anti-pattern rule registry (R1-R9 + custom rules desacopladas de detect.mjs) |
+| `scripts/formatter.mjs` | Output formatter unificado (JSON, tabla, severidad coloreada, scoreBar, formatCheck, formatViolation) |
+| `scripts/forgeSentinel.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
+| `scripts/forgeSentinel-lib.mjs` | Lógica compartida para hooks forgeSentinel y forgeSmith |
+| `scripts/forgeSmith.mjs` | preToolUse gate — previene escrituras con violaciones CRITICAL/ERROR (Cursor) |
+| `scripts/forgeSmith-admin.mjs` | Gestión de hooks (on/off/status) |
+| `scripts/assay.mjs` | Motor de ensayo arquitectónico multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta Senior) |
+| `templates/feature/` | Templates de feature (entity, repository, uc, controller, routes, schema, mapper) |
+| `templates/platform/` | Templates de platform (config, server, database, logger, http, di) |
+| `templates/shared/` | Templates de shared (errors, contracts, types, utils) |
+| `templates/infra/` | Templates de infra (prisma, mongodb, redis, mail) |
+| `command/forge.md` | Definición del comando `/forge` para opencode |
+
+### Tests
+
+Forge incluye tests unitarios con `node:test` (sin dependencias externas).
+
+```bash
+node --test {{AGENT_PATH}}/tests/core.test.mjs
+```
+
+| Módulo | Tests | Descripción |
+|--------|-------|-------------|
+| `profile.mjs` | 8 | Detección de perfiles |
+| `graph.mjs` | 1 | Grafo vacío |
+| `armorer.mjs` | 1 | Ownership vacío |
+| `forge-config.mjs` | 2 | Load/save state |
+| `chain.mjs` | 1 | Grafo de dependencias vacío |
+| `formatter.mjs` | 4 | Output format, colores, JSON |
+| `registry/rules.mjs` | 4 | R1-R9, evaluación, custom rules |
+| `detect.mjs` (inline ignores) | 5 | parseInlineIgnores, isIgnored |
+| `forgeSentinel.mjs` | 1 | PostToolUse hook |
+| `assay.mjs` | 4 | Personas, generateAssay, opiniones |
+
+### Flags adicionales
+
+| Flag | Comando | Descripción |
+|---|---|---|
+| `--fix` | `quench` | Auto-corrige violaciones WARNING/INFO (missing @injectable(), tsconfig, naming, container.resolve) |
+| `--show-ignores` | `quench` | Muestra los inline ignores encontrados en el código |
+| `--persona=<id>` | `assay` | Filtra ensayo por una persona (bezos, fowler, hacker, pm, senior) |
+| `--save` | `assay` | Persiste ensayo en `.forge/assay/` |
+| `--json` | `assay` | Salida JSON |

package/skills/forge/templates/agents/agents/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Forge architecture guard: runs forgeSentinel after Edit/Write/apply_patch and surfaces architectural violations as system reminders.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.agents/skills/forge/scripts/forgeSentinel.mjs\" --hook",
+            "timeout": 10,
+            "statusMessage": "forgeSentinel — checking architecture"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/forge/templates/agents/claude/CLAUDE.md

@@ -0,0 +1,99 @@
+# Forge — Backend Architecture Operating System
+
+Forge es un sistema operativo arquitectónico para backend. Diseña, construye, audita y evoluciona arquitecturas basadas en **Arquitectura Hexagonal**, **DDD pragmático** y **vertical slices**.
+
+## Boot Sequence
+
+Ejecutar en orden antes de cualquier acción. Todos los paths son relativos a `.claude/skills/forge/`:
+
+1. `node .claude/skills/forge/scripts/context.mjs` — stack + layers detection
+2. `node .claude/skills/forge/scripts/armorer.mjs` — ownership, orphans, duplicates
+3. `node .claude/skills/forge/scripts/profile.mjs --extended` — tech profile
+4. `node .claude/skills/forge/scripts/graph.mjs --json` — 4-layer graph
+5. `node .claude/skills/forge/scripts/chain.mjs --json` — dependency analysis
+6. `node .claude/skills/forge/scripts/inspect.mjs --json` — full audit
+7. `node .claude/skills/forge/scripts/architecture.mjs` — update ARCHITECTURE.md
+8. Execute user command (cast, quench, relocate, etc.)
+9. Run `node .claude/skills/forge/scripts/forgeSentinel.mjs --reminder` — check changes
+10. Run `architecture.mjs` again
+
+## Architecture Model
+
+Cuatro capas obligatorias:
+
+| Layer | Propósito |
+|-------|-----------|
+| `src/platform/` | config, database, http, server, logger, cache, security, events, di |
+| `src/features/<name>/` | domain/, application/use-cases/, application/mappers/, adapters/in/http/, adapters/out/persistence/ |
+| `src/shared/` | errors/, contracts/, types/, utils/ (puro, sin lógica de negocio) |
+| `src/infra/` | prisma/, mongodb/, redis/, mail/ (implementaciones, sin reglas de negocio) |
+
+### Dependency Rules
+
+**Permitido:** `feature → platform`, `feature → shared`, `platform → infra`, `adapter → infra`, `feature → domain`
+
+**Prohibido (CRITICAL):**
+- R1: `feature → infra`
+- R2: `platform → feature`
+- R3: `shared → feature`
+- R4: `shared → infra`
+- R5: `domain → infra`
+- R6: `domain → platform`
+- R7: `infra → feature`
+- R8: cross-feature direct imports
+- R9: cycles
+
+## Naming Conventions
+
+| Elemento | Formato |
+|----------|---------|
+| Directorios | `kebab-case/` |
+| Archivos | `<PascalCase>.<artefacto>.ts` |
+| Interfaces | `I<PascalCase>.<artefacto>.ts` |
+| Use cases | `<Action>.uc.ts` |
+| Clases | `PascalCase` |
+| Funciones/variables | `camelCase` |
+| Constantes | `UPPER_SNAKE_CASE` |
+| Barrel files | `index.ts` con named exports, no `export default` |
+| Imports ESM | con extensión `.js`: `import { X } from "./foo.js"` |
+
+## Commands
+
+| Comando | Acción |
+|---------|--------|
+| `forge` | Init project (context + bootstrap + profile + graph) |
+| `cast` | New feature (verifica platform/shared/infra primero) |
+| `inspect` | Full audit (6 categorías, 110pts → 0-100) |
+| `quench` | Validate dependency rules |
+| `chain` | Topological dependency sort |
+| `graph` | Architecture graph con R1-R9 |
+| `armorer` | Ownership report (orphans, duplicates, misplaced) |
+| `smelt` | Extract code to shared/ |
+| `relocate` | Migrate legacy to platform/, shared/, infra/ or features/ |
+| `reforge` | Refactor considering all 4 layers |
+| `temper` | Harden DI (constructor injection) |
+| `inscribe` | Generate ARCHITECTURE.md |
+
+## Architecture Principles
+
+1. **Hexagonal basado en features** — unidad de organización = feature, no capa técnica
+2. **DDD ligero** — sin sobreingeniería, pragmatismo sobre dogma
+3. **Separación dominio e infraestructura** — domain/ no sabe de frameworks ni BD
+4. **Feature autónomo** — todo lo del dominio vive dentro de `features/<name>/`
+5. **Dependencias unidireccionales** — `adapters → application → domain → (nada)`
+6. **Cero lógica en controllers** — parsean, delegan, responden
+7. **Cero BD fuera de repositories** — única puerta a datos
+8. **DI disciplinada** — constructor injection, sin service locators
+9. **Errores tipados** — clases explícitas, no `throw Error()`
+10. **Grafo arquitectónico vivo** — todo componente es un nodo, toda relación un edge validado
+
+## Key Files
+
+- `.claude/skills/forge/SKILL.md` — orchestrator principal
+- `.claude/skills/forge/reference/principles.md` — manifiesto y 15 principios
+- `.claude/skills/forge/reference/patterns.md` — naming conventions
+- `.claude/skills/forge/scripts/` — context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forgeSentinel, forgeSmith
+- `.claude/skills/forge/profiles/` — 10 tech profiles (express, fastify, nestjs × mongodb, postgres, prisma, drizzle)
+- `.claude/skills/forge/templates/` — templates para feature, platform, shared, infra
+- `AGENTS.md` — guía para agentes de IA
+- `ARCHITECTURE.md` — estado actual de la arquitectura

package/skills/forge/templates/agents/claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "description": "Forge architecture guard: runs forgeSentinel after Edit/Write/MultiEdit and surfaces architectural violations as system reminders.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/skills/forge/scripts/forgeSentinel.mjs\" --hook",
+            "timeout": 10,
+            "statusMessage": "forgeSentinel — checking architecture"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/forge/templates/agents/codex/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Forge architecture guard: runs forgeSentinel after Edit/Write/apply_patch and surfaces architectural violations as system reminders.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.agents/skills/forge/scripts/forgeSentinel.mjs\" --hook",
+            "timeout": 10,
+            "statusMessage": "forgeSentinel — checking architecture"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/forge/templates/agents/cursor/.cursorrules

@@ -0,0 +1,97 @@
+You are an AI assistant for a project that uses Forge — a Backend Architecture Operating System. Tu función es ayudar a diseñar, construir, auditar y evolucionar la arquitectura usando Arquitectura Hexagonal, DDD pragmático y vertical slices.
+
+All forge scripts are in `.cursor/skills/forge/scripts/`.
+
+## Architecture Model
+
+The project uses four mandatory layers:
+
+```
+src/
+├── platform/          # Config, database, http, server, logger, cache, security, events, di
+├── features/<name>/   # domain/, application/use-cases/, application/mappers/, adapters/in/http/, adapters/out/persistence/
+├── shared/            # errors/, contracts/, types/, utils/ (pure code, no business logic)
+└── infra/             # prisma/, mongodb/, redis/, mail/ (implementations, no business rules)
+```
+
+## Dependency Rules (CRITICAL — never violate)
+
+**Allowed:** `feature → platform`, `feature → shared`, `platform → infra`, `adapter → infra`, `feature → domain`
+
+**Prohibited:**
+- R1: `feature → infra`
+- R2: `platform → feature`
+- R3: `shared → feature`
+- R4: `shared → infra`
+- R5: `domain → infra`
+- R6: `domain → platform`
+- R7: `infra → feature`
+- R8: cross-feature direct imports
+- R9: cycles
+
+## Boot Sequence
+
+Ejecutar en orden antes de cualquier acción:
+
+1. `node .cursor/skills/forge/scripts/context.mjs` — stack + layers detection
+2. `node .cursor/skills/forge/scripts/armorer.mjs` — ownership, orphans, duplicates
+3. `node .cursor/skills/forge/scripts/profile.mjs --extended` — tech profile
+4. `node .cursor/skills/forge/scripts/graph.mjs --json` — 4-layer graph
+5. `node .cursor/skills/forge/scripts/chain.mjs --json` — dependency analysis
+6. `node .cursor/skills/forge/scripts/inspect.mjs --json` — full audit
+7. `node .cursor/skills/forge/scripts/architecture.mjs` — update ARCHITECTURE.md
+8. Execute user command (cast, quench, relocate, etc.)
+9. Run `node .cursor/skills/forge/scripts/forgeSentinel.mjs --reminder`
+10. Run `architecture.mjs` again
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Directories | `kebab-case/` | `credit-card/` |
+| Files | `<PascalCase>.<artifact>.ts` | `User.entity.ts` |
+| Interfaces | `I<PascalCase>.<artifact>.ts` | `IUser.repository.ts` |
+| Use cases | `<Action>.uc.ts` | `CreateUser.uc.ts` |
+| Classes | `PascalCase` | `UserController` |
+| Functions/vars | `camelCase` | `formatDate` |
+| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
+| Barrels | `index.ts` | named exports only, no `export default` |
+| ESM imports | with `.js` extension | `import { X } from "./foo.js"` |
+
+## Code Principles
+
+1. **Zero business logic in controllers** — parse, delegate, respond
+2. **Zero DB access outside repositories** — only repositories touch the database
+3. **Constructor injection only** — no service locators, no `container.resolve()` in business logic
+4. **Typed domain errors** — explicit error classes, never generic `throw Error()`
+5. **Unidirectional dependencies** — `adapters → application → domain → (nothing)`
+6. **Domain knows nothing about infrastructure** — no framework, database, or external service imports in domain/
+7. **Features are autonomous** — no direct imports between features, only via injected interfaces
+8. **Explicit over magic** — prefer explicit imports and declared types over hidden decorators
+
+## Available Commands
+
+| Command | Action |
+|---------|--------|
+| `forge` | Initialize project |
+| `cast` | Create new feature |
+| `inspect` | Full architecture audit |
+| `quench` | Validate dependency rules |
+| `chain` | Dependency graph (topological) |
+| `graph` | Architecture graph with rules |
+| `armorer` | Ownership report |
+| `smelt` | Extract to shared/ |
+| `relocate` | Migrate legacy code |
+| `reforge` | Refactor architecture |
+| `temper` | Harden dependency injection |
+| `inscribe` | Generate ARCHITECTURE.md |
+
+## Key Files Reference
+
+- `.cursor/skills/forge/SKILL.md` — orchestrator
+- `.cursor/skills/forge/reference/principles.md` — 15 principles
+- `.cursor/skills/forge/reference/patterns.md` — naming conventions
+- `.cursor/skills/forge/scripts/` — all engine scripts
+- `.cursor/skills/forge/profiles/` — tech profiles
+- `AGENTS.md` — agent guide
+- `ARCHITECTURE.md` — current architecture state

package/skills/forge/templates/agents/cursor/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "node \".cursor/skills/forge/scripts/forgeSmith.mjs\"",
+        "timeout": 10
+      }
+    ]
+  }
+}

package/skills/forge/templates/agents/gemini/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: forge
+description: >
+  Architecture Operating System especializado en diseñar, construir, auditar,
+  proteger y evolucionar arquitecturas backend escalables basadas en features
+  (vertical slices), hexagonal architecture y DDD pragmático.
+allowed-tools:
+  - Bash(node .gemini/skills/forge/scripts/*)
+---
+
+# Forge — Backend Architecture Operating System
+
+Ver `.gemini/skills/forge/SKILL.md` para la guía completa.

package/skills/forge/tests/core.test.mjs

@@ -318,10 +318,10 @@ describe("detect.mjs — inline ignores", () => {
   });
 });
 
-describe("posttool.mjs", () => {
-  it("postToolCheck returns empty for no files", async () => {
-    const { postToolCheck } = await import("../scripts/posttool.mjs");
-    const result = await postToolCheck([], {});
+describe("forgeSentinel.mjs", () => {
+  it("runSentinelCheck returns empty for no files", async () => {
+    const { runSentinelCheck } = await import("../scripts/forgeSentinel-lib.mjs");
+    const result = await runSentinelCheck([], {});
     assert.equal(result.total, 0);
     assert.ok(result.summary);
   });

package/src/agents.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const HOME = homedir();
+
+function detect(cwd) {
+  const agents = [];
+
+  agents.push({
+    id: "claude-global",
+    label: "Claude Code",
+    scope: "Global",
+    detected: existsSync(join(HOME, ".claude")) || existsSync(join(HOME, ".config", "claude")),
+  });
+
+  agents.push({
+    id: "claude-project",
+    label: "Claude Code",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".claude")) || existsSync(join(cwd, "CLAUDE.md")),
+  });
+
+  agents.push({
+    id: "opencode-global",
+    label: "OpenCode",
+    scope: "Global",
+    detected: existsSync(join(HOME, ".config", "opencode")),
+  });
+
+  agents.push({
+    id: "opencode-project",
+    label: "OpenCode",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".opencode")),
+  });
+
+  agents.push({
+    id: "cursor-project",
+    label: "Cursor",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".cursor")) || existsSync(join(cwd, ".cursorrules")),
+  });
+
+  agents.push({
+    id: "codex-project",
+    label: "Codex CLI",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".codex")),
+  });
+
+  agents.push({
+    id: "gemini-project",
+    label: "Gemini Code Assist",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".gemini")),
+  });
+
+  agents.push({
+    id: "agents-project",
+    label: "Agentes Genéricos",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".agents")),
+  });
+
+  agents.push({
+    id: "copilot-project",
+    label: "GitHub Copilot",
+    scope: "Proyecto",
+    detected: existsSync(join(cwd, ".github", "copilot-instructions.md")),
+  });
+
+  agents.push({
+    id: "codex-global",
+    label: "Codex CLI",
+    scope: "Global",
+    detected: existsSync(join(HOME, ".codex")),
+  });
+
+  return agents;
+}
+
+function detectAll(cwd) {
+  const all = detect(cwd);
+  return all.filter(a => a.detected).map(a => a.id);
+}
+
+export { detect as detectForWizard, detectAll };