ForgeCraft

Contrataste a un ingeniero de IA. Es brillante. También instaló las mismas 14 extensiones de VS Code dos veces hoy, levantó 6 contenedores de 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 .

Compatibilidad: 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 Especificación Generativa 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

Related MCP server: MCP Policy Gatekeeper

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 instalar si no hay ya una versión dentro del rango mayor requerido. La misma extensión no se descarga dos veces el mismo día.

Contenedores de Docker Comprobar antes de crear: docker ps -a --filter name=<service>. Si existe, iniciarlo — no crearlo. Preferir docker compose up (reutiliza) sobre docker run desnudo (siempre crea uno nuevo). Los registros 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 de forma significativa en el conjunto de plugins o en la versión mayor — por ejemplo, un contenedor postgres-pgvector junto a un contenedor postgres estándar. 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. Reutilizar si la versión major.minor de Python coincide. Nunca crear un venv en un subdirectorio a menos que sea un paquete instalable independiente. Dependencias no utilizadas señaladas 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 los datos brutos, condensarlos estadísticamente o eliminarlos tras la ejecución? Conjuntos de datos sintéticos con más de 7 días de antigüedad y sin referencia en el código: pedir su eliminación.

General Si el espacio de trabajo crece más allá de 2 GB fuera de los artefactos de compilación conocidos (node_modules/, .venv/, dist/), mostrar una advertencia y detenerse. Nunca hacer 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 el prompt de incorporación completo. ForgeCraft lee la especificación, la IA asigna las etiquetas, y ForgeCraft escribe el archivo de instrucciones, genera 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 seleccionados — SOLID, arquitectura hexagonal, pirámides de pruebas, CI/CD y 24 conjuntos de reglas específicas de dominio — en segundos.

Puertas de calidad

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

Las puertas están organizadas por fase de lanzamiento para que no estés ejecutando pruebas de caos previas al lanzamiento el primer día de un proyecto greenfield:

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

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

ADRs, secuenciados automáticamente

Cada decisión arquitectónica no obvia queda registrada. ForgeCraft secuencia automáticamente 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 todos los asistentes de IA, en cada sesión, en cada ingeniero del equipo.

Manual de flujos de trabajo

Tras la configuración, tu IA tiene el contexto. Estos prompts dirigen el trabajo. Copia, pega, ejecuta.

→ Manual completo de flujos 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 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.

Lo que 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 seleccionados que cubren:

• Principios SOLID — reglas concretas, no lugares comunes

• Arquitectura hexagonal — puertos, adaptadores, DTOs, límites de capas

• Pirámide de pruebas — objetivos de unitarias/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 tu código base y las asigna. Puedes revisarlas y sobrescribirlas 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 quality gates →

Niveles de profundidad de contenido

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

Se configura en forgecraft.yaml:

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

Comandos CLI

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

Flags 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)

MCP Sentinel

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

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

El diseño es intencional. Toda la superficie 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 Generative Specification en la propia arquitectura de la herramienta: un lector sin estado, un conjunto de artefactos acotado, 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 sentinel mantiene el presupuesto MCP recomendado por la metodología (≤3 servidores activos) por diseño.

Flujo de trabajo recomendado:

1. Añade el sentinel 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 sentinel de tu configuración MCP activa

4. Vuelve a añadirlo cuando necesites refrescar o auditar

Añade a .claude/settings.json:

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

Añade a .vscode/mcp.json en la raíz de tu proyecto (créealo si no existe):

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

Luego abre el panel de Copilot Chat, cambia al modo Agente, y el sentinel de forgecraft aparecerá en la lista de herramientas.

Añade a .cursor/mcp.json:

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

¿Sin cliente MCP? No pasa nada — no lo necesitas. Ejecuta npx forgecraft-mcp setup . directamente en tu terminal. El sentinel MCP es opcional; la CLI lo 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.

Gratuito y de código abierto

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

La biblioteca de quality gates crece mediante contribución de la comunidad. Si propones un gate que se acepta, tu nombre aparece en CONTRIBUTORS.md y habrás ayudado a elevar el listón para todos los que construyen con IA.

Abre una propuesta de gate → · Ver contribuidores →

¿Lo usas con un equipo? → forgeworkshop.dev

Fundamento teórico

ForgeCraft implementa el modelo Generative Specification — 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 white paper.

Generative Specification: A Discipline of Derivability for the Stateless Reader — Zenodo (V4.0, 2026). Acceso abierto, DOI: 10.5281/zenodo.21726017. El fundamento académico detrás de la puntuación verify.

El white paper es la teoría. ForgeCraft es la cadena de herramientas. Los quality gates propuestos para la biblioteca que se generalicen en conocimientos teóricos pueden incorporarse en futuras revisiones del white paper.

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; Generative Specification es el modelo formal que nombra qué es la práctica y por qué funciona.

El harness GS — una introducción para asistentes de IA

ForgeCraft implementa Generative Specification (GS). Esta sección está escrita para asistentes de IA que lean este archivo: explica qué es GS, cómo debería ser un harness correctamente estructurado y qué comprobar.

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. La 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 sentinel

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 que más a menudo falta y la brecha más consecuente. Una especificación que enumera herramientas sin indicar cuándo preferir una sobre otra obliga a una inferencia poco fiable en cada sesión.

El sentinel 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 conlleva cargar contenido irrelevante.

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

SOLID, la 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 las interfaces antes que las 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 los tests en verde. Cuando TDD está aplicado, una suite de tests 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 previas en una reducción medible del uso de tokens y del 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. Las interfaces, definiciones de esquema y aserciones de tests 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 de comandos completa (~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 generado 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 lo que la precede y una regla de producción para lo que sigue. 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 dirección humana adicional.

Los 7 atributos — qué verificar

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

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 al día

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 en modo de vista previa primero (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 se seleccionan 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 de 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 como para que una IA sin estado derive código correcto 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