Plugin de Claude Code · código abiertoClaude Code plugin · open source

forge-methodology

"A la par con Stripe" deja de significar "hicimos las partes que se nos ocurrieron": cada capacidad de la referencia es una fila, y el PR no se abre hasta que cada una tiene evidencia firmada por alguien que no la construyó. "Parity with Stripe" stops meaning "we built the parts we thought of": every capability of the reference becomes a row, and the PR won't open until each one carries evidence signed by someone who didn't build it.

9pasossteps
8domain packsdomain packs
8ejemplos end-to-endend-to-end examples
2checkpoints del ownerowner checkpoints

Qué haceWhat it does

El trabajo asistido por IA falla de dos formas repetibles: se mide contra el propio checklist del ejecutor en vez de contra el objetivo real ("a la par con X" pero solo la mitad de X), y el mismo agente que construye algo se declara a sí mismo verificado. forge-methodology convierte ambos fallos en código: la referencia externa se enumera en un Acceptance Matrix —un req-id por capacidad— y un hook bloquea gh pr create mientras cualquier fila en scope no tenga evidencia real ni un verificador independiente.AI-assisted work fails in two repeatable ways: it gets measured against the executor's own checklist instead of the real goal ("parity with X" but only half of X), and the same agent that built something declares itself verified. forge-methodology turns both failures into code: the external reference is enumerated into an Acceptance Matrix — one req-id per capability — and a hook blocks gh pr create while any in-scope row lacks real evidence or an independent verifier.

Es un guardarraíl del propio agente sobre su gh pr create, no protección del lado del servidor — y, honestamente, es fail-open por defecto: si no encuentra ninguna Acceptance Matrix, avisa pero no bloquea (el repo puede no estar usando Forge ahí). FORGE_REQUIRE_MATRIX=1 lo hace estricto también en ese caso.It's a guardrail on the agent's own gh pr create, not server-side protection — and, honestly, it's fail-open by default: if it finds no Acceptance Matrix at all, it warns but doesn't block (the repo may not be using Forge there). FORGE_REQUIRE_MATRIX=1 makes it strict in that case too.

Ejemplo realReal example

"Fórjalo: añade webhooks de pago idempotentes, a la par con la spec de webhooks de Stripe." Declaras done demasiado pronto y el hook corta gh pr create: FORGE BLOCK — R2 -> no-evidence no-verified-by / R3 -> built≠yes. Corres /forge-verify-matrix, construyes R3, y el mismo comando devuelve Acceptance Matrix COMPLETE."Forge this: add idempotent payment webhooks, parity with Stripe's webhook spec." Declare done too early and the hook cuts gh pr create: FORGE BLOCK — R2 -> no-evidence no-verified-by / R3 -> built≠yes. Run /forge-verify-matrix, build R3, and the same command returns Acceptance Matrix COMPLETE.

Cómo funciona, en diagramasHow it works, in diagrams

Diagramas interactivos hechos con Archify, sacados del propio repo: recorre los caminos, haz zoom o ábrelos a pantalla completa.Interactive diagrams built with Archify, taken from the repo itself: trace the paths, zoom in, or open them full screen.

Diagrama de los 9 pasos de la Forja: alinear intención, descomponer la referencia, borrador y grill, checkpoint 1, spec versionado, re-grill, checkpoint 2, plan global y ejecución con verificación independiente.Diagram of the 9 Forge steps: align intent, decompose the reference, draft and grill, checkpoint 1, versioned spec, re-grill, checkpoint 2, global plan, and execution with independent verification.
fig. 1El loop de la Forja, 9 pasosThe Forge loop, 9 stepsAbrir interactivo ↗ (pestaña nueva)Open interactive ↗ (new tab)
Diagrama del hook PreToolUse que intercepta gh pr create y bloquea mientras alguna fila en scope de la Acceptance Matrix no tenga evidencia ni verificador independiente.Diagram of the PreToolUse hook that intercepts gh pr create and blocks while any in-scope Acceptance Matrix row lacks evidence or an independent verifier.
fig. 2El hook de la Acceptance MatrixThe Acceptance Matrix hookAbrir interactivo ↗ (pestaña nueva)Open interactive ↗ (new tab)

Por qué importaWhy it matters

Cómo se usaHow it's used

Dices "fórjalo: <tarea>, a la par con <referencia>" (o "forge this" en inglés) dentro de Claude Code. El loop de 9 pasos corre solo, interrumpiéndote exactamente dos veces —cada una un multi-select con la recomendación ya marcada— hasta cerrar con el spec, la Acceptance Matrix y el plan versionados en el repo.You say "forge this: <task>, parity with <reference>" inside Claude Code. The 9-step loop runs on its own, interrupting you exactly twice — each one a multi-select with the recommendation already marked — until it closes with the spec, Acceptance Matrix and plan versioned in the repo.

Compone conComposes with

working-methods es su capa de enforcement dentro de Claude Code —aplica esta metodología con /forge-run, fases codificadas y un hook fail-closed de verdad (más estricto que el de este propio plugin).working-methods is its enforcement layer inside Claude Code — it applies this methodology via /forge-run, coded phases, and a genuinely fail-closed hook (stricter than this plugin's own).

working-methodscapa de enforcement, /forge-runenforcement layer, /forge-run
design-reviewfase de ejecución visualvisual execution phase
swarmmismo problema, para el ciclo completosame problem, for the whole cycle
grill-meentrevista al humano, no al documentointerviews the human, not the document

Preguntas frecuentesFrequently asked questions

¿Qué hace forge-methodology?What does forge-methodology do?

Enumera una referencia externa en capacidades con req-id, las convierte en una Acceptance Matrix, y un hook bloquea gh pr create mientras falte evidencia real y un verificador independiente.It enumerates an external reference into req-id capabilities, turns them into an Acceptance Matrix, and a hook blocks gh pr create while real evidence and an independent verifier are missing.

¿El hook siempre bloquea el PR?Does the hook always block the PR?

No por defecto: sin ninguna Acceptance Matrix, avisa pero no bloquea (fail-open). FORGE_REQUIRE_MATRIX=1 lo hace estricto también entonces.Not by default: with no Acceptance Matrix at all, it warns but doesn't block (fail-open). FORGE_REQUIRE_MATRIX=1 makes it strict then too.

¿Cómo se usa?How is it used?

Diciendo "fórjalo: <tarea>, a la par con <referencia>" dentro de Claude Code. El loop de 9 pasos interrumpe al owner exactamente dos veces.By saying "forge this: <task>, parity with <reference>" inside Claude Code. The 9-step loop interrupts the owner exactly twice.

¿Es gratis y de código abierto?Is it free and open source?

Sí — licencia MIT, publicado en GitHub.Yes — MIT license, published on GitHub.

InstalaciónInstall

Un plugin, una frase para arrancar.One plugin, one sentence to start.

$ /plugin marketplace add davidgarciagordo/claude-plugins
$ /plugin install forge-methodology@davidgarciagordo-plugins