@ronaldjdevfs/forge 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +36 -21
  2. package/package.json +7 -2
  3. package/skills/forge/SKILL.md +56 -122
  4. package/skills/forge/command/forge.md +59 -14
  5. package/skills/forge/reference/adr.md +242 -0
  6. package/skills/forge/reference/anti-corruption-layer.md +340 -0
  7. package/skills/forge/reference/api-design.md +7 -0
  8. package/skills/forge/reference/api-versioning.md +354 -0
  9. package/skills/forge/reference/architectural-depth-checklist.md +311 -0
  10. package/skills/forge/reference/architecture-template.md +41 -0
  11. package/skills/forge/reference/assay.md +6 -0
  12. package/skills/forge/reference/bounded-contexts.md +311 -0
  13. package/skills/forge/reference/chain.md +6 -0
  14. package/skills/forge/reference/cohesion-checklist.md +256 -0
  15. package/skills/forge/reference/cqrs.md +286 -0
  16. package/skills/forge/reference/data-patterns.md +6 -0
  17. package/skills/forge/reference/di-strategies.md +6 -0
  18. package/skills/forge/reference/errors.md +5 -0
  19. package/skills/forge/reference/events.md +8 -0
  20. package/skills/forge/reference/evolutionary-architecture.md +300 -0
  21. package/skills/forge/reference/forge.md +7 -0
  22. package/skills/forge/reference/hooks.md +6 -0
  23. package/skills/forge/reference/idempotency.md +283 -0
  24. package/skills/forge/reference/inscribe.md +5 -0
  25. package/skills/forge/reference/inspect.md +6 -0
  26. package/skills/forge/reference/modular-monolith.md +252 -0
  27. package/skills/forge/reference/observability.md +5 -0
  28. package/skills/forge/reference/quench.md +5 -0
  29. package/skills/forge/reference/relocate.md +6 -0
  30. package/skills/forge/reference/sagas.md +359 -0
  31. package/skills/forge/reference/security-patterns.md +6 -0
  32. package/skills/forge/reference/smelt.md +6 -0
  33. package/skills/forge/reference/temper.md +6 -0
  34. package/skills/forge/reference/testing-patterns.md +6 -0
  35. package/skills/forge/reference/transactional-outbox.md +311 -0
  36. package/skills/forge/scripts/architecture.mjs +10 -5
  37. package/skills/forge/scripts/assay.mjs +2 -2
  38. package/skills/forge/scripts/chain.mjs +31 -5
  39. package/skills/forge/scripts/context.mjs +24 -4
  40. package/skills/forge/scripts/detect.mjs +39 -30
  41. package/skills/forge/scripts/forge-boot.mjs +108 -0
  42. package/skills/forge/scripts/forge-config.mjs +182 -3
  43. package/skills/forge/scripts/forge-state.mjs +1 -1
  44. package/skills/forge/scripts/forgeSentinel-lib.mjs +86 -0
  45. package/skills/forge/scripts/forgeSentinel.mjs +184 -0
  46. package/skills/forge/scripts/forgeSmith-admin.mjs +104 -0
  47. package/skills/forge/scripts/forgeSmith.mjs +164 -0
  48. package/skills/forge/scripts/graph.mjs +65 -9
  49. package/skills/forge/scripts/hook.mjs +2 -2
  50. package/skills/forge/scripts/inspect.mjs +56 -48
  51. package/skills/forge/scripts/parse-imports.mjs +0 -2
  52. package/skills/forge/scripts/pin.mjs +10 -3
  53. package/skills/forge/scripts/posttool.mjs +2 -2
  54. package/skills/forge/scripts/recommendation-engine.mjs +125 -0
  55. package/skills/forge/scripts/rollback.mjs +5 -3
  56. package/skills/forge/templates/agents/SKILL.md.template +283 -0
  57. package/skills/forge/templates/agents/agents/hooks.json +18 -0
  58. package/skills/forge/templates/agents/claude/CLAUDE.md +17 -16
  59. package/skills/forge/templates/agents/claude/settings.local.json +18 -0
  60. package/skills/forge/templates/agents/codex/hooks.json +18 -0
  61. package/skills/forge/templates/agents/cursor/.cursorrules +22 -5
  62. package/skills/forge/templates/agents/cursor/hooks.json +11 -0
  63. package/skills/forge/templates/agents/gemini/SKILL.md +13 -0
  64. package/skills/forge/templates/feature/acl-gateway.ts.md +52 -0
  65. package/skills/forge/templates/feature/acl-repository.ts.md +36 -0
  66. package/skills/forge/templates/feature/acl-translator.ts.md +24 -0
  67. package/skills/forge/templates/feature/cqrs-query.ts.md +40 -0
  68. package/skills/forge/templates/feature/outbox-repository.ts.md +36 -0
  69. package/skills/forge/templates/feature/saga-orchestrator.ts.md +72 -0
  70. package/skills/forge/templates/platform/outbox-relayer.ts.md +80 -0
  71. package/skills/forge/tests/core.test.mjs +284 -0
  72. package/src/agents.mjs +35 -2
  73. package/src/cli.js +112 -39
  74. package/src/wizard.mjs +142 -90
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  <img src="favicon.svg" alt="Forge Logo" width="100" height="100">
2
2
 
3
+ > **v1.3.1** — Bugfixes, New Templates & Interactive Flags
4
+
3
5
  ## Forge — Backend Architecture Operating System
4
6
 
5
7
  **Forge** es un **sistema operativo arquitectónico** para backend. Modela, construye, audita, protege y evoluciona sistemas completos en cuatro dominios arquitectónicos: **Platform**, **Features**, **Shared** e **Infrastructure**.
@@ -356,7 +358,11 @@ Donde vive toda la inteligencia arquitectónica:
356
358
  | `scripts/formatter.mjs` | Output unificado: colores, JSON, scoreBar, formatCheck |
357
359
  | `scripts/registry/rules.mjs` | Registry de reglas R1-R9 + custom rules desacoplado |
358
360
  | `scripts/assay.mjs` | Ensayo multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta) |
359
- | `scripts/posttool.mjs` | PostToolUse hook con `--reminder` y `--strict` |
361
+ | `scripts/forgeSentinel.mjs` | PostToolUse hook adapter para Claude/Codex/agents |
362
+ | `scripts/forgeSentinel-lib.mjs` | Lógica compartida del hook PostToolUse |
363
+ | `scripts/forgeSmith.mjs` | preToolUse gate para Cursor (deniega escrituras con violaciones CRITICAL/ERROR) |
364
+ | `scripts/forgeSmith-admin.mjs` | Gestión de hooks (on/off/status) para Cursor |
365
+ | `scripts/posttool.mjs` | PostToolUse hook (deprecated — usar forgeSentinel) |
360
366
  | `scripts/forge-config.mjs` | Persistencia de config, estado e histórico |
361
367
  | `scripts/forge-state.mjs` | CLI wrapper de estado post-auditoría |
362
368
  | `scripts/forge-signals.mjs` | Manejo de señales (SIGINT, SIGTERM) |
@@ -381,29 +387,22 @@ Donde vive toda la inteligencia arquitectónica:
381
387
 
382
388
  ## Instalación
383
389
 
384
- ### En un proyecto
385
-
386
390
  ```bash
387
- npx @ronaldjdev/forge install
391
+ npx @ronaldjdevfs/forge install # Wizard interactivo
392
+ npx @ronaldjdevfs/forge install --all # Todos los agentes detectados
393
+ npx @ronaldjdevfs/forge install --cursor # Solo Cursor
394
+ npx @ronaldjdevfs/forge install --claude # Solo Claude Code
388
395
  ```
389
396
 
390
- Esto copia la skill en `.opencode/skills/forge/` del proyecto actual.
391
-
392
- ### Global (disponible en todos los proyectos)
393
-
394
- ```bash
395
- npx @ronaldjdev/forge install --global
396
- ```
397
-
398
- Esto copia la skill en `~/.config/opencode/skills/forge/`.
399
-
400
- ### Con instalación global del CLI
401
-
402
- ```bash
403
- npm install -g @ronaldjdev/forge
404
- forge install # proyecto actual
405
- forge install -g # global
406
- ```
397
+ | Flag | Agente | Hook activo |
398
+ |------|--------|-------------|
399
+ | `--opencode` | OpenCode | forgeSentinel (vía SKILL.md) |
400
+ | `--cursor` | Cursor | forgeSmith (preToolUse) |
401
+ | `--claude` | Claude Code | forgeSentinel (PostToolUse) |
402
+ | `--codex` | Codex CLI | forgeSentinel (PostToolUse) |
403
+ | `--gemini` | Gemini Code Assist | — |
404
+ | `--all` | Todos los anteriores | — |
405
+ | `--global` | `~/.config/opencode/` | forgeSentinel |
407
406
 
408
407
  **Requisitos**: Node.js ≥ 18
409
408
 
@@ -436,6 +435,22 @@ Una vez instalada, OpenCode carga automáticamente la skill `forge` al trabajar
436
435
 
437
436
  ---
438
437
 
438
+ ### Sistema de Hooks Multi-Agent
439
+
440
+ Forge se despliega como **skill** en múltiples agentes de IA simultáneamente, con hooks adaptados a cada plataforma:
441
+
442
+ | Agente | Hook | Cuándo se ejecuta | Efecto |
443
+ |--------|------|-------------------|--------|
444
+ | **OpenCode** | forgeSentinel | PostToolUse tras Edit/Write | Reporta violaciones como reminder |
445
+ | **Claude Code** | forgeSentinel | PostToolUse tras Edit/Write/MultiEdit | Reporta violaciones como reminder |
446
+ | **Cursor** | forgeSmith | preToolUse antes de cada escritura | Puede DENEGAR la escritura |
447
+ | **Codex CLI** | forgeSentinel | PostToolUse tras Edit/Write/apply_patch | Reporta violaciones como reminder |
448
+ | **Gemini** | SKILL.md | Al cargar el agente | Instrucciones arquitectónicas |
449
+
450
+ Todos los hooks comparten la misma lógica de detección de violaciones R1-R9 a través de `forgeSentinel-lib.mjs`.
451
+
452
+ ---
453
+
439
454
  ## Desarrollo
440
455
 
441
456
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ronaldjdevfs/forge",
3
- "version": "1.2.0",
3
+ "version": "1.3.1",
4
4
  "description": "Forge — Architecture Operating System for backend systems. Arquitectura Hexagonal, DDD pragmático y vertical slices.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -13,7 +13,12 @@
13
13
  "NOTICE"
14
14
  ],
15
15
  "scripts": {
16
- "install:local": "node ./src/cli.js install"
16
+ "install:local": "node ./src/cli.js install",
17
+ "prepublishOnly": "node -e \"const p=require('./package.json'); if(p.dependencies && p.dependencies[p.name]) { console.error('ERROR: self-referencing dependency detected. Remove before publish.'); process.exit(1); }\"",
18
+ "test:forgeSentinel": "node .opencode/skills/forge/scripts/forgeSentinel.mjs --reminder",
19
+ "test:forgeSmith": "echo '{\"toolName\":\"Write\",\"args\":{\"filePath\":\"src/test.ts\"}}' | node .opencode/skills/forge/scripts/forgeSmith.mjs",
20
+ "test:pin": "node .opencode/skills/forge/scripts/pin.mjs nail cast",
21
+ "test:all": "pnpm install:local && pnpm test:forgeSentinel && pnpm test:forgeSmith"
17
22
  },
18
23
  "keywords": [
19
24
  "opencode",
@@ -70,56 +70,55 @@ En esencia:
70
70
 
71
71
  ---
72
72
 
73
- ## Boot Sequence (OBLIGATORIO — ejecutar siempre antes de responder)
73
+ ## Boot Sequence
74
74
 
75
- ANTES de cualquier acción, Forge DEBE ejecutar esta secuencia. Si no lo haces, puedes dar respuestas incorrectas:
76
-
77
- 1. **context.mjs** — Detectar stack, platform, features, shared, infra, grafo, estado
78
- 2. **armorer.mjs** — Detectar ownership, huérfanos, duplicados, mal ubicados
79
- 3. **profile.mjs** — Determinar perfil tecnológico
80
- 4. **graph.mjs** — Construir grafo arquitectónico global (4 capas + 9 reglas)
81
- 5. **chain.mjs** — Analizar dependencias multi-capa
82
- 6. **inspect.mjs** — Auditoría completa con ownership + platform
83
- 7. **architecture.mjs** — Generar/actualizar ARCHITECTURE.md
84
- 8. **Ejecutar comando solicitado** — cast, quench, temper, etc.
85
- 9. **Actualizar ARCHITECTURE.md** — Reflejar nuevo estado
75
+ ANTES de cualquier acción, Forge DEBE ejecutar `forge-boot.mjs` con la profundidad adecuada al comando:
86
76
 
87
77
  ```bash
88
- # Template de setup que debes ejecutar:
89
- ctx=$(node .opencode/skills/forge/scripts/context.mjs --json 2>/dev/null)
90
- armorer=$(node .opencode/skills/forge/scripts/armorer.mjs --json 2>/dev/null)
91
- profile=$(node .opencode/skills/forge/scripts/profile.mjs --extended 2>/dev/null)
92
- graph=$(node .opencode/skills/forge/scripts/graph.mjs --json 2>/dev/null)
93
- deps=$(node .opencode/skills/forge/scripts/chain.mjs --json 2>/dev/null)
94
- inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
78
+ boot=$(node .opencode/skills/forge/scripts/forge-boot.mjs --depth <depth> --json 2>/dev/null)
95
79
  ```
96
80
 
81
+ La profundidad (`--depth`) depende del comando (ver Execution Flow):
82
+ - **minimal** → context + profile (cast, temper, smelt, relocate, reforge, inscribe)
83
+ - **standard** → minimal + graph + chain (chain, graph, forge hook)
84
+ - **full** → standard + ownership + inspect (inspect, quench, default)
85
+
86
+ Si `$boot` contiene datos cacheados en `.forge/cache/` se reusan automáticamente. Pasa `--force` para regenerar.
87
+
97
88
  ---
98
89
 
99
90
  ## Command Routing
100
91
 
101
- | Lenguaje natural | Comando | Archivo |
92
+ | Intención | Comando | Referencia |
102
93
  |---|---|---|
103
- | "ayuda", "help", "comandos", "lista", "--help" | `forge --help` | `reference/help.md` |
104
- | "inicializar", "setup", "empezar" | `forge` | `reference/forge.md` |
105
- | "crear feature", "nuevo dominio" | `cast` | `reference/cast.md` |
106
- | "inspeccionar", "diagnóstico", "evaluar" | `inspect` | `reference/inspect.md` |
107
- | "trasladar", "mover", "reestructurar feature" | `relocate` | `reference/relocate.md` |
108
- | "refactorizar", "rediseñar", "cambiar estructura" | `reforge` | `reference/reforge.md` |
109
- | "verificar", "quench", "checklist" | `quench` | `reference/quench.md` |
110
- | "templar", "endurecer", "mejorar" | `temper` | `reference/temper.md` |
111
- | "cadena", "grafo", "acoplamiento" | `chain` | `scripts/chain.mjs` |
112
- | "inscribir", "grabar", "ARCHITECTURE.md" | `inscribe` | `reference/inscribe.md` |
113
- | "grafo", "graph", "nodo", "violaciones", "risk score" | `graph` | `scripts/graph.mjs` |
114
- | "fundir", "compartir", "mover a shared" | `smelt` | `reference/smelt.md` |
115
- | "ownership", "huérfanos", "armorer" | `inspect` | (incluido en auditoría) |
116
- | "fijar", "pinar", "atajo", "shortcut" | `nail` | `scripts/pin.mjs` |
117
- | "desfijar", "despinar", "remover atajo" | `unnail` | `scripts/pin.mjs` |
118
- | "hook", "pre-commit", "githook", "validar commit" | `forge hook` | `reference/hooks.md` |
119
- | "api", "contrato", "openapi", "swagger", "graphql" | `forge api` | `scripts/forge-api.mjs` |
120
- | "rollback", "restaurar", "deshacer", "backup" | `forge rollback` | `scripts/rollback.mjs` |
121
- | "estado", "state", "último audit" | `forge state --show` | `scripts/forge-state.mjs` |
122
- | "examinar","calidad", "assay", "opinión", "personas", "critique", "evaluación cualitativa" | `assay` | `reference/assay.md` |
94
+ | Ayuda | `forge --help` | `reference/help.md` |
95
+ | Setup inicial | `forge` | `reference/forge.md` |
96
+ | Crear feature | `cast` | `reference/cast.md` |
97
+ | Auditar | `inspect` | `reference/inspect.md` |
98
+ | Relocalizar feature | `relocate` | `reference/relocate.md` |
99
+ | Refactorizar | `reforge` | `reference/reforge.md` |
100
+ | Verificar violaciones | `quench` | `reference/quench.md` |
101
+ | Endurecer | `temper` | `reference/temper.md` |
102
+ | Dependencias | `chain` | `scripts/chain.mjs` |
103
+ | Inscribir ARCHITECTURE.md | `inscribe` | `reference/inscribe.md` |
104
+ | Grafo arquitectónico | `graph` | `scripts/graph.mjs` |
105
+ | Fundir a shared | `smelt` | `reference/smelt.md` |
106
+ | Atajo / pin | `nail` / `unnail` | `scripts/pin.mjs` |
107
+ | Git hook | `forge hook` | `reference/hooks.md` |
108
+ | API design | `forge api` | `scripts/forge-api.mjs` |
109
+ | Rollback | `forge rollback` | `scripts/rollback.mjs` |
110
+ | Estado | `forge state` | `scripts/forge-state.mjs` |
111
+ | Ensayo cualitativo | `assay` | `reference/assay.md` |
112
+ | Bounded context | `forge` | `reference/bounded-contexts.md` |
113
+ | Modular monolith | `forge` | `reference/modular-monolith.md` |
114
+ | ADR | `inscribe` | `reference/adr.md` |
115
+ | Anti-corruption layer | `relocate` | `reference/anti-corruption-layer.md` |
116
+ | Evolutionary arch | `reforge` | `reference/evolutionary-architecture.md` |
117
+ | CQRS | `cast` | `reference/cqrs.md` |
118
+ | Sagas | `cast` | `reference/sagas.md` |
119
+ | Outbox | `cast` | `reference/transactional-outbox.md` |
120
+ | Idempotencia | `forge` | `reference/idempotency.md` |
121
+ | API versioning | `forge api` | `reference/api-versioning.md` |
123
122
 
124
123
  ---
125
124
 
@@ -127,14 +126,17 @@ inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
127
126
 
128
127
  Para cada comando, Forge sigue este flujo:
129
128
 
130
- 1. **Contexto**: Ejecutar `context.mjs` + `armorer.mjs` + `profile.mjs`
131
- 2. **Grafo**: Ejecutar `graph.mjs` + `chain.mjs`
132
- 3. **Auditoría**: Ejecutar `inspect.mjs`
133
- 4. **Referencia**: Cargar `reference/<command>.md`
134
- 5. **Ejecutar**: Aplicar el flujo definido en la referencia, usando los scripts según corresponda
135
- 6. **Verificar**: Ejecutar `scripts/detect.mjs` para verificar que no se introdujeron violaciones
136
- 7. **Actualizar ARCHITECTURE.md**: Reflejar el nuevo estado (`architecture.mjs`)
137
- 8. **Reportar**: Mostrar resultado al usuario con severidades
129
+ 1. **Boot condicional**: Ejecutar `forge-boot.mjs --depth <depth>` donde depth es:
130
+ - `minimal` para cast, temper, smelt, relocate, reforge, inscribe
131
+ - `standard` para chain, graph, forge hook
132
+ - `full` para inspect, quench, o cualquier otro comando
133
+ 2. **Referencia**: Cargar `reference/<command>.md`
134
+ 3. **Ejecutar**: Aplicar el flujo definido en la referencia
135
+ 4. **Verificar**: Ejecutar `detect.mjs --summary` (resumen compacto)
136
+ 5. **Actualizar ARCHITECTURE.md**: `architecture.mjs` (solo en full)
137
+ 6. **Reportar**: Mostrar resultado al usuario con severidades
138
+
139
+ El boot usa caché de `.forge/cache/`. Si los archivos `src/` no cambiaron, los datos se reusan. Usa `forge-boot.mjs --force` para regenerar todo.
138
140
 
139
141
  ---
140
142
 
@@ -167,84 +169,13 @@ import { crossFeature } from "../other-feature/domain/Entity"; // ← R1 y R8 ig
167
169
 
168
170
  ## ARCHITECTURE.md
169
171
 
170
- Forge mantiene un archivo `ARCHITECTURE.md` en la raíz del proyecto con el contexto persistente. Contiene:
171
-
172
- ```md
173
- # Architecture State
174
-
175
- - Project Name: <name>
176
- - Framework: <detectado>
177
- - Runtime: <detectado>
178
- - Database: <detectado>
179
- - ORM: <detectado>
180
- - DI Strategy: <detectado>
181
- - Profile: <detectado>
182
- - Architecture: hexagonal-feature (Platform + Features + Shared + Infra)
183
- - Last Audit: <fecha> (score: <puntaje>)
184
-
185
- ## Platform
186
- - platform/config/
187
- - platform/server/
188
- ...
189
-
190
- ## Features
191
- - features/users/
192
- ...
193
-
194
- ## Shared
195
- - shared/errors/
196
- ...
197
-
198
- ## Infrastructure
199
- - infra/prisma/
200
- ...
201
-
202
- ## Ownership
203
- - Health: healthy | degraded | critical
204
- - Score: 0-100
205
- - Orphans: 0
206
- - Duplicates: 0
207
- - Misplaced: 0
208
-
209
- ## Architecture Graph
210
- ...
211
-
212
- ## Dependency Health
213
- ...
214
- ```
172
+ Forge mantiene `ARCHITECTURE.md` en la raíz con el estado persistente del proyecto (framework, DB, features, ownership, graph). Se genera y actualiza con `architecture.mjs`.
215
173
 
216
- El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo al finalizar cada comando.
174
+ El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo al finalizar cada comando. Ver `scripts/architecture.mjs` para el formato completo.
217
175
 
218
176
  ---
219
177
 
220
- ## Module Index
221
-
222
- | Módulo | Propósito |
223
- |---|---|
224
- | `reference/principles.md` | Manifiesto y 12 principios inquebrantables |
225
- | `reference/patterns.md` | Convenciones de nomenclatura globales (PascalCase.artifact, kebab dirs, etc.) |
226
- | `reference/errors.md` | Manejo de errores tipados en dominio y aplicación |
227
- | `reference/di-strategies.md` | Estrategias de inyección de dependencias según tamaño |
228
- | `reference/testing-patterns.md` | Pirámide de tests, unit mocks, integration tests |
229
- | `reference/api-design.md` | REST / GraphQL, paginación, validación, contratos |
230
- | `reference/observability.md` | Logging, tracing, métricas, health checks |
231
- | `reference/data-patterns.md` | Repository, Unit of Work, CQRS, Event Sourcing |
232
- | `reference/security-patterns.md` | AuthN, AuthZ, RBAC, rate limiting, validación |
233
- | `reference/events.md` | Eventos de dominio, outbox pattern, sagas |
234
- | `reference/hooks.md` | Git pre-commit hook para validación arquitectónica |
235
- | `reference/help.md` | Lista completa de comandos y flags de Forge |
236
- | `reference/assay.md` | Ensayo arquitectónico multi-persona — interpretación cualitativa del audit |
237
- | `profiles/` | Perfiles tecnológicos detallados (Express, Fastify, NestJS, etc.) |
238
- | `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, posttool, formatter, assay, registry/rules |
239
- | `scripts/registry/rules.mjs` | Anti-pattern rule registry (R1-R9 + custom rules desacopladas de detect.mjs) |
240
- | `scripts/formatter.mjs` | Output formatter unificado (JSON, tabla, severidad coloreada, scoreBar, formatCheck, formatViolation) |
241
- | `scripts/posttool.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
242
- | `scripts/assay.mjs` | Motor de ensayo arquitectónico multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta Senior) |
243
- | `templates/feature/` | Templates de feature (entity, repository, uc, controller, routes, schema, mapper) |
244
- | `templates/platform/` | Templates de platform (config, server, database, logger, http, di) |
245
- | `templates/shared/` | Templates de shared (errors, contracts, types, utils) |
246
- | `templates/infra/` | Templates de infra (prisma, mongodb, redis, mail) |
247
- | `command/forge.md` | Definición del comando `/forge` para opencode |
178
+ > 📚 Todas las referencias están en `reference/`. La tabla de routing arriba mapea cada comando a su referencia. Ver `reference/help.md` para la lista completa de flags.
248
179
 
249
180
  ### Tests
250
181
 
@@ -266,6 +197,9 @@ node --test .opencode/skills/forge/tests/core.test.mjs
266
197
  | `detect.mjs` (inline ignores) | 5 | parseInlineIgnores, isIgnored |
267
198
  | `posttool.mjs` | 1 | PostToolUse hook |
268
199
  | `assay.mjs` | 4 | Personas, generateAssay, opiniones |
200
+ | transactional-outbox | 5 | Entry lifecycle, retry, DLQ, required fields, pending |
201
+ | idempotency | 5 | UUID validation, cached response, different keys, TTL, method filter |
202
+ | anti-corruption-layer | 5 | DTO mapping (2 dirs), null handling, 404, delegation order |
269
203
 
270
204
  ### Flags adicionales
271
205
 
@@ -1,29 +1,51 @@
1
1
  ---
2
- description: Forge — Backend Architecture OS. Subcomandos: forge, cast, inspect, relocate, reforge, quench, temper, chain, inscribe, smelt.
2
+ description: Forge — Backend Architecture OS. Comandos: forge, cast, inspect, assay, quench, chain, graph, armorer, inscribe, smelt, relocate, reforge, temper.
3
3
  agent: build
4
4
  ---
5
5
 
6
6
  Ejecuta herramientas de Forge según el subcomando especificado en $ARGUMENTS.
7
7
 
8
+ Si el subcomando NO tiene flags en $ARGUMENTS y tiene flags disponibles (ver tabla abajo), pregunta al usuario cuáles quiere usar con la `question` tool (tipo checkboxes múltiples). Si el usuario no selecciona ninguna, ejecuta sin flags.
9
+
10
+ | Comando | Flags disponibles |
11
+ |---------|------------------|
12
+ | `forge` | Sin flags |
13
+ | `cast` | Sin flags (pide nombre del feature interactivamente) |
14
+ | `inspect` | `--json`, `--diff`, `--full`, `--summary`, `--severity=<nivel>`, `--force` |
15
+ | `assay` | `--persona=<id>`, `--json`, `--save`, `history` |
16
+ | `quench` | `--fix`, `--show-ignores`, `--severity=<nivel>`, `--json` |
17
+ | `chain` | `--json` |
18
+ | `graph` | `--json` |
19
+ | `armorer` | Sin flags |
20
+ | `inscribe` | `--output=<path>` |
21
+ | `smelt` | Sin flags (pide qué extraer interactivamente) |
22
+ | `relocate` | Sin flags (pide feature y destino) |
23
+ | `reforge` | `--cycles` |
24
+ | `temper` | Sin flags |
25
+
8
26
  ## Build
9
27
 
10
28
  ### forge
11
29
 
12
- Inicializa el proyecto arquitectónicamente (incluye platform, shared, infra).
30
+ Inicializa el proyecto arquitectónicamente. Ejecuta context + bootstrap + profile + armorer + graph + chain + inscribe.
13
31
 
14
32
  ```
15
33
  node .opencode/skills/forge/scripts/context.mjs
16
34
  node .opencode/skills/forge/scripts/bootstrap.mjs
35
+ node .opencode/skills/forge/scripts/profile.mjs
17
36
  node .opencode/skills/forge/scripts/armorer.mjs
37
+ node .opencode/skills/forge/scripts/graph.mjs
38
+ node .opencode/skills/forge/scripts/chain.mjs
39
+ node .opencode/skills/forge/scripts/architecture.mjs
18
40
  ```
19
41
 
20
42
  ### cast
21
43
 
22
- Crea un nuevo feature (verifica platform/shared/infra primero).
44
+ Crea un nuevo feature. Primero verifica que platform/shared/infra existan; si falta, llama a bootstrap.
23
45
 
24
46
  ### relocate
25
47
 
26
- Migra un feature existente.
48
+ Migra un feature existente. Puede targetizar platform/, shared/, infra/ o features/.
27
49
 
28
50
  ### inscribe
29
51
 
@@ -33,9 +55,9 @@ Genera ARCHITECTURE.md con grafo arquitectónico, ownership y platform.
33
55
  node .opencode/skills/forge/scripts/architecture.mjs
34
56
  ```
35
57
 
36
- ### architecture
58
+ ### graph
37
59
 
38
- Construye el grafo arquitectónico del proyecto (4 capas: platform, feature, shared, infra).
60
+ Construye el grafo arquitectónico del proyecto (4 capas: platform, feature, shared, infra) con reglas R1-R9.
39
61
 
40
62
  ```
41
63
  node .opencode/skills/forge/scripts/graph.mjs
@@ -49,11 +71,11 @@ node .opencode/skills/forge/scripts/graph.mjs --json
49
71
 
50
72
  ### smelt
51
73
 
52
- Extrae código reutilizable a shared/.
74
+ Extrae código reutilizable a shared/ (solo código puro, sin dependencias infra/feature).
53
75
 
54
76
  ### bootstrap
55
77
 
56
- Inicializa platform, shared e infra layers (interno, se ejecuta automáticamente).
78
+ Inicializa platform, shared e infra layers (uso interno, se ejecuta automáticamente).
57
79
 
58
80
  ```
59
81
  node .opencode/skills/forge/scripts/bootstrap.mjs
@@ -63,7 +85,7 @@ node .opencode/skills/forge/scripts/bootstrap.mjs
63
85
 
64
86
  ### inspect
65
87
 
66
- Inspecciona la conformidad arquitectónica (incluye ownership y platform).
88
+ Audita la conformidad arquitectónica completa. 6 categorías: structure(20), layers(20), ownership(20), platform(15), dependencies(15), graph(20).
67
89
 
68
90
  ```
69
91
  node .opencode/skills/forge/scripts/inspect.mjs
@@ -75,9 +97,26 @@ Para salida JSON:
75
97
  node .opencode/skills/forge/scripts/inspect.mjs --json
76
98
  ```
77
99
 
100
+ ### assay
101
+
102
+ Ensayo arquitectónico multi-persona. Interpretación cualitativa del audit desde 5 perspectivas (Bezos, Fowler, Hacker, PM, Arquitecta Senior).
103
+
104
+ ```
105
+ node .opencode/skills/forge/scripts/assay.mjs
106
+ ```
107
+
108
+ Filtros:
109
+
110
+ ```
111
+ node .opencode/skills/forge/scripts/assay.mjs --persona=bezos
112
+ node .opencode/skills/forge/scripts/assay.mjs --json
113
+ node .opencode/skills/forge/scripts/assay.mjs --save
114
+ node .opencode/skills/forge/scripts/assay.mjs history
115
+ ```
116
+
78
117
  ### quench
79
118
 
80
- Verifica reglas arquitectónicas.
119
+ Valida reglas arquitectónicas R1-R9.
81
120
 
82
121
  ```
83
122
  node .opencode/skills/forge/scripts/detect.mjs
@@ -85,15 +124,21 @@ node .opencode/skills/forge/scripts/detect.mjs
85
124
 
86
125
  ### chain
87
126
 
88
- Analiza dependencias multi-capa (platform, features, shared, infra).
127
+ Orden topológico de dependencias multi-capa (platform, features, shared, infra).
89
128
 
90
129
  ```
91
130
  node .opencode/skills/forge/scripts/chain.mjs
92
131
  ```
93
132
 
133
+ Para salida JSON:
134
+
135
+ ```
136
+ node .opencode/skills/forge/scripts/chain.mjs --json
137
+ ```
138
+
94
139
  ### armorer
95
140
 
96
- Detecta ownership, huérfanos, duplicados y mal ubicados.
141
+ Reporte de ownership: huérfanos, duplicados, componentes mal ubicados.
97
142
 
98
143
  ```
99
144
  node .opencode/skills/forge/scripts/armorer.mjs
@@ -103,8 +148,8 @@ node .opencode/skills/forge/scripts/armorer.mjs
103
148
 
104
149
  ### reforge
105
150
 
106
- Refactoriza la arquitectura de un feature.
151
+ Refactoriza la arquitectura de un feature considerando las 4 capas.
107
152
 
108
153
  ### temper
109
154
 
110
- Fortalece la arquitectura (DI, seguridad, consistencia).
155
+ Fortalece la arquitectura: constructor injection, sin service locators.