ForgeCraft

⚠️ Obsoleto (septiembre de 2026), y esa es la buena noticia

El trabajo de ForgeCraft era configurar un proyecto para Generative Specification y codificar sus propiedades de calidad. Ese trabajo ahora pertenece al propio modelo. Apunta un asistente de codificación capaz al white paper y guía de campo de GS y pídele que configure el proyecto como GS: él mismo creará el árbol de navegación centinela y conectará las compuertas por ti, ajustadas a tu código, sin necesidad de una herramienta separada. Esa es la propia tesis de la disciplina haciéndose realidad, la fricción de adopción absorbida por el ejecutor.

• Configuración ahora es un prompt: dale a tu asistente el white paper / guía de campo (DOI https://doi.org/10.5281/zenodo.21726017, y pragmaworks.dev) y pídele que configure el proyecto como GS.
• Las compuertas son hooks estándar de CI (tsc, eslint, jscpd, coverage, dependency-cruiser, commit-msg) que el modelo conecta a partir de la especificación. El conjunto de compuertas ganado con esfuerzo que detecta el catálogo de patologías se conserva en el src/analyzers/ de este repositorio como referencia, y una plantilla de compuertas curada vivirá en pragmaworks.dev.
• Lo que aún aporta valor son los servidores MCP componibles de GS que hacen lo que un modelo no puede hacer barato por sí mismo: Chronicle (memoria entre sesiones) y Chronos (grafo del historial de git). ForgeCraft no es uno de ellos.

Este paquete no recibe más actualizaciones. La última versión permanece instalable como referencia.

ForgeCraft

El contrato de calidad dentro del cual trabaja tu asistente de codificación con IA.

Contrataste a un ingeniero de IA. Es brillante. También instaló las mismas 14 extensiones de VS Code dos veces hoy, levantó 6 contenedores Docker que nunca limpiará, y tu disco pasó de 12 GB libres a 0 KB en una sola sesión.

Un disco lleno no falla con elegancia. Mata VS Code, la terminal, Docker y la base de datos simultáneamente.

ForgeCraft es el contrato de calidad dentro del cual trabaja tu asistente de codificación con IA — para que construya rápido y no queme la casa.

npx forgecraft-mcp setup .

Soporta: Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)

Un marco de calidad para el desarrollo de software asistido por IA

Cada sesión, cada proyecto, cada asistente de IA — medido contra el mismo modelo de Generative Specification de 7 propiedades. No vibraciones. No una puntuación de linter. Una puntuación sobre 14 que te dice exactamente dónde está la brecha y por qué.

$ npx forgecraft-mcp verify .

| Property        | Score | Evidence                                        |
|-----------------|-------|-------------------------------------------------|
| Self-Describing | ✅ 2/2 | CLAUDE.md — 352 non-empty lines                |
| Bounded         | ✅ 2/2 | No direct DB calls in route files              |
| Verifiable      | ✅ 2/2 | 64 test files — 87% coverage                   |
| Defended        | ✅ 2/2 | Pre-commit hook + lint config present           |
| Auditable       | ✅ 2/2 | 11 ADRs in docs/adrs/ + Status.md              |
| Composable      | ✅ 2/2 | Service layer + repository layer detected       |
| Executable      | ✅ 2/2 | Tests passed + CI pipeline configured           |

Total: 14/14 ✅ PASS · Threshold 11/14

Higiene del entorno de desarrollo — impuesta por convención

ForgeCraft inyecta reglas aplicables en las instrucciones de IA de cada proyecto que convierten la contaminación del entorno en una violación de convención, no en un incidente.

Extensiones de VS Code Antes de instalar: code --list-extensions | grep -i <name>. Solo instala si no hay ya una versión en el rango mayor requerido. La misma extensión no se descarga dos veces el mismo día.

Contenedores Docker Comprueba antes de crear: docker ps -a --filter name=<service>. Si existe, inícialo — no lo crees. Prefiere docker compose up (reutilizar) sobre docker run desnudo (siempre crea uno nuevo). Logs limitados a 500 MB. docker system prune -f está documentado como un paso de mantenimiento periódico, no como una emergencia.

Excepción: Se permiten múltiples contenedores del mismo servicio cuando difieren significativamente en el conjunto de plugins o la versión mayor — por ejemplo, un contenedor postgres-pgvector junto a un contenedor estándar postgres. Nombra los contenedores para reflejar la variante (p. ej., db-pgvector, db-timescale); de lo contrario, se aplica la regla de deduplicación.

Entornos virtuales de Python Un .venv por raíz de proyecto. Reutiliza si la versión mayor.menor de Python coincide. Nunca crees un venv en un subdirectorio a menos que sea un paquete instalable independiente. Dependencias no utilizadas marcadas por pip list --not-required.

Datos sintéticos y de series temporales Antes de escribir más de 100 MB de datos generados, la IA pregunta: ¿conservar en bruto, condensar estadísticamente o eliminar tras la ejecución? Conjuntos de datos sintéticos de más de 7 días sin referencia de código: preguntar si eliminar.

General Si el espacio de trabajo crece más allá de 2 GB fuera de artefactos de compilación conocidos (node_modules/, .venv/, dist/), muestra una advertencia y detente. Nunca hagas crecer el espacio de trabajo en silencio.

Configuración del proyecto en una frase

Read the spec in docs/specs/, set up this project with ForgeCraft,
scaffold it with the right tags, recommend the tech stack, start building.

Ese es todo el prompt de incorporación. ForgeCraft lee la especificación, la IA asigna las etiquetas, y ForgeCraft escribe el archivo de instrucciones, emite Status.md, docs/adrs/, docs/PRD.md, docs/TechSpec.md, hooks y skills. La IA tiene contexto completo. Tú empiezas a construir.

ForgeCraft escanea tu proyecto, detecta automáticamente tu stack y genera archivos de instrucciones a medida a partir de 116 bloques curados — SOLID, arquitectura hexagonal, pirámides de pruebas, CI/CD y 24 conjuntos de reglas específicas de dominio — en segundos.

Compuertas de calidad

Las compuertas de calidad son comprobaciones estructuradas de aprobado/fallo que tu asistente de IA ejecuta en momentos definidos — antes de un commit, antes de un release, después de un despliegue. No son reglas de linter. Cada compuerta tiene una condición, un requisito de evidencia y un indicador de si la revisión humana es obligatoria.

Las compuertas se organizan por fase de release para que no ejecutes pruebas de caos previas al release el primer día de un proyecto greenfield:

Las compuertas etiquetadas requires_human_review: true no pueden aprobarse automáticamente — algunas comprobaciones requieren un humano.

La biblioteca completa de compuertas, la guía de contribución y el esquema están en el repositorio de compuertas de calidad →

ADRs, secuenciados automáticamente

Cada decisión arquitectónica no obvia queda registrada. ForgeCraft auto-secuencian docs/adrs/NNNN-slug.md en formato MADR — contexto, decisión, alternativas, consecuencias. Tu asistente de IA razona sobre decisiones pasadas. Tu equipo deja de re-litigarlas.

npx forgecraft-mcp generate_adr . --title "Use event sourcing for order history" \
  --status Accepted \
  --context "Order mutations need full audit trail for compliance" \
  --decision "Append-only event log, project current state on read"
# → docs/adrs/0004-use-event-sourcing-for-order-history.md

Configuración del asistente de IA vs ForgeCraft

claude init, las reglas de espacio de trabajo de Cursor o el archivo de instrucciones de Copilot te ponen en marcha. ForgeCraft te lleva a estándares de producción — en cada asistente de IA, cada sesión, cada ingeniero del equipo.

Playbook de flujo de trabajo

Después de la configuración, tu IA tiene el contexto. Estos prompts dirigen el trabajo. Copia, pega, ejecuta.

→ Playbook completo de flujo de trabajo · Versión en línea

Cómo funciona

# First-time setup — auto-detects your stack
npx forgecraft-mcp setup .

flowchart TD
    A["<b>setup .</b><br/>npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze<br/>Reads spec · infers tags"]
    B --> C{AI assistant\nin the loop?}
    C -->|"Yes (MCP)"| D["Phase 2 — Calibrate<br/>LLM corrects tags from spec<br/>Writes forgecraft.yaml · CLAUDE.md<br/>PRD.md · hooks · ADR-000"]
    C -->|"No (CLI only)"| E["⚠️ CLI-only mode<br/>Directory heuristics only<br/>→ configure an AI assistant"]
    D --> F["<b>check_cascade</b><br/>5-step readiness gate<br/>1 · Functional spec<br/>2 · Architecture + C4<br/>3 · Constitution<br/>4 · ADRs<br/>5 · Use cases"]
    F --> G{All 5 passing?}
    G -->|"Stubs / missing"| H["Fill artifacts<br/>docs/PRD.md · docs/adrs/<br/>docs/use-cases.md"]
    H --> F
    G -->|"✅ All pass"| I["<b>generate_session_prompt</b><br/>Bound context for next task"]
    I --> J["Implement with TDD<br/>RED → GREEN → REFACTOR<br/>+ Documentation Cascade"]
    J --> K["<b>audit_project</b><br/>Score 0 – 100"]
    K --> L{Score ≥ 90?}
    L -->|"Violations found"| M["WORKFLOWS.md remediation<br/>file_length · layer_violation<br/>hardcoded_url · missing_prd"]
    M --> J
    L -->|"✅ Score ≥ 90"| N["<b>close_cycle</b><br/>Re-check cascade · assess gates<br/>promote to registry · bump version"]
    N --> O{Roadmap\ncomplete?}
    O -->|"More features"| I
    O -->|"All done"| P["<b>start_hardening</b><br/>Mutation tests · OWASP · load test"]
    P --> Q["🚢 Ship"]

    style A fill:#1a2e1a,color:#90ee90,stroke:#3a6e3a
    style Q fill:#1a2a3e,color:#87ceeb,stroke:#3a5a8e
    style E fill:#2e1a1a,color:#ffaa88,stroke:#6e3a3a
    style M fill:#2e2a00,color:#ffd700,stroke:#6e6000

ForgeCraft es una herramienta CLI de tiempo de configuración. Ejecútala una vez para configurar tu proyecto y luego elimínala — no tiene huella en tiempo de ejecución.

Opcionalmente, añade el centinela MCP para permitir que tu asistente de IA diagnostique y recomiende comandos:

claude mcp add forgecraft -- npx -y forgecraft-mcp

El centinela es una única herramienta (~200 tokens). Lee tres artefactos — forgecraft.yaml, CLAUDE.md, .claude/hooks — deriva el siguiente comando CLI correcto y lo devuelve. Nada más. Este es el principio central de la metodología expresado como diseño de herramienta: un lector sin estado, un conjunto finito de artefactos, una acción derivada. Elimínalo después de la configuración inicial para recuperar presupuesto de tokens.

Qué obtienes

Después de npx forgecraft-mcp setup, tu proyecto tiene:

your-project/
├── forgecraft.yaml        ← Your config (tags, tier, customizations)
├── CLAUDE.md              ← Engineering standards (Claude)
├── .cursor/rules/         ← Engineering standards (Cursor)
├── .github/copilot-instructions.md  ← Engineering standards (Copilot)
├── Status.md              ← Session continuity tracker
├── .claude/hooks/         ← Pre-commit quality gates
├── docs/
│   ├── PRD.md             ← Requirements skeleton
│   └── TechSpec.md        ← Architecture + NFR sections
└── src/shared/            ← Config, errors, logger starters

Los archivos de instrucciones

Este es el valor central. Ensamblados a partir de bloques curados que cubren:

• Principios SOLID — reglas concretas, no lugares comunes
• Arquitectura hexagonal — puertos, adaptadores, DTOs, límites de capas
• Pirámide de pruebas — objetivos de unit/integración/E2E, taxonomía de test doubles
• Código limpio — CQS, cláusulas de guarda, inmutabilidad, funciones puras
• CI/CD y despliegue — etapas de pipeline, entornos, despliegues de vista previa
• Patrones de dominio — DDD, CQRS, event sourcing (cuando tu proyecto lo necesita)
• Operaciones 12-Factor — configuración, ausencia de estado, desechabilidad, registro

Cada bloque proviene de literatura de ingeniería establecida (Martin, Evans, Wiggins) y está adaptado para el desarrollo asistido por IA.

24 etiquetas — detectadas por IA, ajustables por el usuario

Las etiquetas le dicen a ForgeCraft qué es tu proyecto. En la primera configuración, la IA analiza tu especificación y código y las asigna. Puedes revisarlas y anularlas en forgecraft.yaml. Los bloques se fusionan sin conflictos — añade o elimina etiquetas a medida que el proyecto evoluciona.

La lista completa de etiquetas y la guía de contribución viven en el repositorio de compuertas de calidad →

Niveles de profundidad de contenido

No todos los proyectos necesitan DDD desde el primer día.

Configurar en forgecraft.yaml:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

Comandos CLI

npx forgecraft-mcp <command> [dir] [flags]

Banderas comunes

--tags UNIVERSAL API     Project classification tags (or read from forgecraft.yaml)
--tier core|recommended  Content depth (default: recommended)
--targets claude cursor  AI assistant targets (default: claude)
--dry-run                Preview without writing files
--compact                Strip explanatory bullet tails and deduplicate lines (~20-40% smaller output)
--apply                  Apply changes (for refresh)
--language typescript    typescript | python (default: typescript)
--scope focused          comprehensive | focused (for review)

Centinela MCP

Opcionalmente, añade el centinela MCP de ForgeCraft para que tu asistente de IA diagnostique tu proyecto y sugiera el comando CLI correcto:

El centinela es una herramienta mínima única (~200 tokens por solicitud, frente a ~1,500 para un conjunto completo de herramientas). Comprueba si forgecraft.yaml, tu archivo de instrucciones de IA y tus hooks existen, y luego devuelve el comando CLI específico para el estado actual del proyecto.

El diseño es intencional. La superficie completa de comandos de ForgeCraft — 21 acciones — vive en la CLI, no en el servidor MCP. El servidor MCP expone exactamente una herramienta que lee tres artefactos y devuelve una recomendación. Este es el principio de Especificación Generativa en la propia arquitectura de la herramienta: un lector sin estado, un conjunto acotado de artefactos, una acción derivada. La herramienta practica lo que escribe en tus archivos de instrucciones.

Un efecto secundario: cada herramienta MCP declarada es leída por el modelo en cada turno, se invoque o no. Una herramienta cuesta 200 tokens. Veintiuna herramientas cuestan 1,500. El centinela mantiene el presupuesto MCP recomendado por la metodología (≤3 servidores activos) por diseño.

Flujo de trabajo recomendado:

1. Añade el centinela a tu asistente de IA (ver ejemplos de configuración abajo)
2. Deja que tu asistente de IA ejecute npx forgecraft-mcp setup .
3. Elimina el centinela de tu configuración MCP activa
4. Vuelve a añadirlo cuando necesites actualizar o auditar

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

{
  "servers": {
    "forgecraft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

¿Sin cliente MCP? No hay problema — no lo necesitas. Ejecuta npx forgecraft-mcp setup . directamente en tu terminal. El centinela MCP es opcional; la CLI hace todo.

¿Ya ejecutaste claude init? Usa npx forgecraft-mcp generate . --merge para fusionar con tu CLAUDE.md existente, manteniendo tus secciones personalizadas mientras añades estándares de producción.

Gratis y de código abierto

ForgeCraft es gratuito. Sin límites, sin niveles, sin claves API.

La biblioteca de puertas de calidad crece mediante contribución comunitaria. Si propones una puerta que se acepta, tu nombre va en CONTRIBUTORS.md y ayudaste a elevar el estándar para todos los que construyen con IA.

Abre una propuesta de puerta → · Ver contribuyentes →

¿Lo usas con un equipo? → forgeworkshop.dev

Fundamento teórico

ForgeCraft implementa el modelo de Especificación Generativa — un marco formal de 7 propiedades para evaluar la calidad del código generado por IA. El modelo, la fórmula de convergencia S_realized y el marco de fases de lanzamiento están documentados en el documento técnico.

Especificación Generativa: Una Disciplina de Derivabilidad para el Lector Sin Estado — Zenodo (V4.0, 2026). Acceso abierto, DOI: 10.5281/zenodo.21726017. El fundamento académico detrás de la puntuación verify.

El documento técnico es la teoría. ForgeCraft es el conjunto de herramientas. Las puertas de calidad propuestas para la biblioteca que se generalicen en conocimientos teóricos pueden incorporarse en futuras revisiones del documento técnico.

Contexto de la industria: la convergencia del Desarrollo Dirigido por Especificaciones (ThoughtWorks Tech Radar 2025 "Adopt"; Addy Osmani / Google Cloud AI agent-skills) es el movimiento de profesionales; la Especificación Generativa es el modelo formal que nombra qué es la práctica y por qué funciona.

El arnés GS — una introducción para asistentes de IA

ForgeCraft implementa Especificación Generativa (GS). Esta sección está escrita para asistentes de IA que leen este archivo: explica qué es GS, cómo se ve un arnés correctamente andamiado y qué verificar.

La restricción vinculante — lector sin estado

Cada sesión de IA comienza sin memoria de sesiones anteriores, sin contexto compartido, sin convenciones acumuladas y sin capacidad de hacer preguntas aclaratorias. Todo lo que no está en los artefactos está ausente.

GS trata esto como una restricción de diseño, no como un defecto. Derivabilidad — lo que una instancia de IA nueva puede determinar correctamente solo a partir de los artefactos — es el estándar que una especificación debe satisfacer. Si un lector sin estado no puede derivar la salida correcta de los artefactos, la especificación está incompleta, no la IA.

El sistema centinela

La constitución arquitectónica (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules) es el punto de entrada para cada sesión de IA. Debe contener colectivamente cinco categorías obligatorias:

La secuenciación de herramientas es la categoría más comúnmente ausente y la brecha más consecuente. Una especificación que enumera herramientas sin indicar cuándo preferir una sobre otra obliga a inferencias poco fiables en cada sesión.

El centinela es un árbol de navegación: la raíz siempre se carga; cada nodo hijo declara su propio alcance y condición de enrutamiento; la IA desciende solo por la rama relevante para la tarea actual. Unir todas las hojas produce la especificación completa — es sin pérdidas. Este diseño previene la hinchazón de contexto y la degradación de precisión que viene de cargar contenido irrelevante.

El puente — disciplinas estructurales como política de navegación

SOLID, arquitectura hexagonal y TDD no son solo disciplinas de ingeniería — en un proyecto GS se convierten en políticas de navegación activas:

• Lee interfaces antes que implementaciones. Cuando un límite puerto/adaptador es limpio, la interfaz es el contrato. La implementación se omite a menos que el contrato sea insuficiente.
• Confía en pruebas verdes. Cuando TDD está aplicado, un conjunto de pruebas que pasa es evidencia de comportamiento correcto. No se necesita leer la implementación para verificarlo.
• Los ADR son el porqué. Cuando cada decisión no obvia está registrada, la IA lee el registro en lugar de inferir la intención del código.

Este puente convierte los beneficios estructurales pasivos de disciplinas anteriores en una reducción medible del uso de tokens y consumo de contexto.

Saneamiento de tokens

El tamaño de la ventana de contexto y la colocación posicional degradan la precisión de la IA (Liu et al., 2023). GS minimiza el consumo innecesario de tokens por diseño:

• El árbol centinela es perezoso. Solo se carga la rama relevante por tarea — nunca la especificación completa de una vez.
• Contratos sobre implementaciones. Interfaces, definiciones de esquemas y aserciones de pruebas se leen primero. Los archivos de implementación se leen solo cuando los contratos son insuficientes para derivar la respuesta.
• La constitución lidera cada sesión. El contenido más importante ocupa la posición inicial en el contexto — donde la precisión posicional es más alta.
• La superficie de herramientas MCP está acotada. Cada herramienta MCP declarada es leída por el modelo en cada turno, se invoque o no. El centinela de ForgeCraft expone una herramienta (~200 tokens) en lugar de una superficie completa de comandos (~1,500 tokens). La herramienta practica la metodología que escribe en tu proyecto.

Taxonomía de documentos — qué contiene un proyecto GS completo

Un proyecto andamiado contiene estos tipos de artefactos. Si falta alguno, el arnés está incompleto:

La cascada de inicialización: las especificaciones se producen en secuencia — cada una es una salida de la anterior y una regla de producción para la siguiente. Especificación funcional → arquitectura → constitución → ADR → casos de uso. La cascada está completa cuando un agente sin estado, al recibir los cinco conjuntos de artefactos, puede derivar cualquier estado de implementación válido sin más dirección humana.

Los 7 atributos — qué verificar

Un proyecto GS correctamente estructurado satisface los siete. Estas son las propiedades que el comando verify evalúa:

Configuración

Ajusta lo que ve tu asistente de IA

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants
compact: true                             # Slim output (~20-40% fewer tokens)

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

Paquetes de plantillas de la comunidad

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

Mantener los estándares actualizados

Auditoría (ejecutar en cualquier momento, o en CI)

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

Actualización (¿cambió el alcance del proyecto?)

npx forgecraft-mcp refresh . --apply

O primero en modo de vista previa (por defecto):

npx forgecraft-mcp refresh .   # shows before/after diff without writing

Contribuciones

Las plantillas son YAML, no código. Puedes añadir patrones sin escribir TypeScript.

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
├── review.yaml         # Code review checklists
└── mcp-servers.yaml    # Recommended MCP servers for this tag

Se aceptan PRs. Consulta templates/universal/ para el formato.

Descubrimiento de servidores MCP

npx forgecraft-mcp configure-mcp descubre dinámicamente servidores MCP recomendados que coinciden con las etiquetas de tu proyecto. Los servidores están curados en mcp-servers.yaml por etiqueta — contribuibles por la comunidad mediante PRs.

Las recomendaciones integradas incluyen Context7 (documentación), Playwright (pruebas), Chrome DevTools (depuración), Stripe (fintech), Docker/K8s (infraestructura), y más en las 24 etiquetas.

Opcionalmente, se puede obtener desde un registro remoto en el momento de la configuración:

# In forgecraft.yaml or via tool parameter
include_remote: true
remote_registry_url: https://your-org.com/mcp-registry.json

Desarrollo

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 610 tests, 42 suites

Licencia

MIT

Parte de Generative Specification

Una herramienta gratuita detrás de Generative Specification (GS) — la disciplina para construir software con IA que no se desvía: redactas una especificación lo suficientemente precisa para que una IA sin estado derive código correcto a partir de ella, y un arnés la verifica contra un sistema en vivo.

• 📄 Documento técnico (acceso abierto): https://doi.org/10.5281/zenodo.21726017
• 🧭 Empieza aquí — método, herramientas, testimonios: https://pragmaworks.dev
• 🔨 The Forge — taller práctico de GS de 2 días para tu equipo: https://forgeworkshop.dev