SpecForge: Spec-Driven AI Development With Approval Gates That Actually Block

SpecForge is an open-source, spec-driven development lifecycle for Claude Code that turns human approval from a polite suggestion into a technical barrier. It fuses the executable specs of GitHub spec-kit with the approval governance of AWS AI-DLC, then enforces the gate with a hook that blocks every code edit until a human approves the spec and the plan. I built it, it is MIT licensed, and you can install it today from GitHub or skills.sh.

The gate is the difference between a workflow you supervise and one you review.

Why advisory gates fail

Every spec-driven toolkit tells the model to stop and wait for approval. Almost none of them can make it stop.

I wrote about this pattern in spec-driven development and in AIDLC, and the failure mode is always the same. The instructions say "wait for explicit approval before proceeding." A well-behaved model follows them. A hurried one, deep in a long context with a big goal, blows right through and starts editing files, because instructions are suggestions and the model's job is to make progress. You find out three thousand generated lines later that it built the wrong thing against an unapproved plan.

Agents got fast enough that process discipline became the bottleneck. A vague spec now produces confidently wrong code in minutes, and an ignored checkpoint ships it. The fix is not a sterner prompt. The fix is moving the gate out of the prompt and into the harness, where the model cannot rationalize its way past it.

That is the whole point of SpecForge.

What is SpecForge?

SpecForge combines three layers that existing tools ship separately.

First, the pipeline. From spec-kit it takes executable specs and the clean progression of constitution, specify, clarify, plan, tasks, analyze, implement. Every stage produces a committed markdown artifact that travels with your pull requests.

Second, the governance. From AI-DLC it takes human approval as a first-class blocking step, an append-only audit trail, and a reverse-engineering stage for brownfield codebases.

Third, the enforcement. A Claude Code PreToolUse hook runs a gate-check script before every file edit. Until the active feature's spec and plan are both approved, the hook denies code changes. This is the layer the other kits are missing, and it changes the character of the whole workflow. You stop supervising the model's discipline and start reviewing its artifacts.

The package ships as one installable Claude Code plugin containing 15 lifecycle skills, five role subagents (spec-analyst, architect, implementer, reviewer, reverse-engineer), the hook layer, and canonical artifact templates. The same skills appear on skills.sh for any of the 70+ agents that support the skills format.

How does the SpecForge lifecycle work?

The lifecycle runs as a sequence of commands, each producing an artifact the next one consumes. Two approvals sit in the middle, and the second one opens the gate.

The spec captures the what and the why in language precise enough that an agent cannot misread it. I covered what that takes in how to write a spec an AI agent can actually build. The plan captures the how, including the data model and API contracts. Tasks break the plan into an ordered, traceable checklist, and analyze runs a read-only cross-check for gaps between the three before any code exists.

The full command set:

How does SpecForge enforce the approval gate?

The gate is a real hook, not an instruction. Claude Code calls the PreToolUse hook before every Edit or Write, the hook runs gate-check.sh, and the script decides from committed state whether the edit may proceed.

Three design choices matter here.

The gate is inert by default. On a project without a specforge/ workspace, the hook allows everything, so installing the plugin globally costs you nothing on repos that don't use it.

The gate never blocks spec writing. The hook always allows edits to the artifacts inside specforge/, because the whole point is to push work into the spec phase.

The state is committed and diff-able. Approvals live in specforge/state.md, and every gate transition lands in an append-only specforge/audit.md. Your reviewer can see in the pull request exactly when the plan was approved and what happened after.

In practice a blocked edit looks like this. Claude tries to write a source file, the hook checks state, and the deny message tells it exactly what is missing:

For a typo-sized change, running the full ceremony would be absurd, so /specforge:quick fast-tracks a trivial change through an audited escape hatch. The kit never becomes bureaucracy for a one-line fix, and the audit trail still records that you took the shortcut.

What is the governed Ralph loop?

The Ralph loop is the simplest autonomous coding pattern that works. Point an agent at a goal, let it work the list, repeat until done. Raw Ralph is fast and undisciplined, which is exactly the trade SpecForge refuses.

/specforge:loop runs the loop governed. It only starts once a human has approved the spec and the plan. It works tasks.md one task at a time and invents no new scope. It logs every step to audit.md. When it hits a blocker it stops and asks instead of guessing. The pitch in one line is the Ralph loop's speed with a gate that keeps a human in the loop.

For fully unattended runs, a bundled headless runner re-invokes claude per task as the classic outer loop, gate-checked and iteration-bounded:

How does SpecForge handle an existing codebase?

Most spec-driven tooling assumes a greenfield project, and most real work is not. SpecForge inherits AI-DLC's answer. /specforge:reverse-engineer reads the existing codebase first and produces the documentation a spec needs to stand on, so the specify stage starts from what the system actually does rather than what anyone remembers it doing. From there the lifecycle proceeds normally, and the gate protects the legacy code from unapproved changes just as it would protect a fresh repo.

How does SpecForge compare to spec-kit and AI-DLC?

Both parents deserve credit. Spec-kit proved that specs can be executable artifacts rather than documentation theater. AI-DLC proved that approval workflow and audit trails belong in the lifecycle. SpecForge exists because no kit combined the two and then made the approval step technically binding.

How do I install SpecForge?

As a Claude Code plugin, which is the full experience with commands, skills, subagents, and the enforced gates:

As skills only, for any of the 70+ agents supported by skills.sh:

Skills installed this way still guide the workflow and write the artifacts. They don't ship the enforcement hooks, which are the Claude Code plugin's bonus. The degradation is graceful by design.

Two more agents ship as committed bundles. GitHub Copilot gets the /specforge.* prompts, repo-wide instructions, a preToolUse gate hook, and a git pre-commit backstop, currently in preview. Cursor gets the /specforge-* commands, an always-applied repo rule, and a real preToolUse gate hook on Cursor's generally available Hooks feature, so it denies unapproved code edits at edit time just like Claude Code. Gemini CLI and Codex adapters sit on the roadmap; I built the generator that produces the Claude, Copilot, and Cursor bundles from one neutral step source so new adapters slot in cheaply.

A first run looks like this:

The repository includes a complete worked example of exactly this run in examples/todo-api/.

SpecForge builds itself with itself

The strongest evidence I can offer is the repo's own history. I ran the full SpecForge lifecycle on SpecForge itself to ship the Operations phase, and the committed specforge/ store, with its constitution, audit trail, and specs/001-operations-phase/, is the output. The tool passed through its own gate.

The trust posture is deliberate. MIT licensed, local-first, no telemetry. Specs are committed files that travel with your pull requests, and SpecForge logs every gate transition in specforge/audit.md. Nothing leaves your machine.

SpecForge is the enforcement layer for the method I run on every engagement, the AI Development Life Cycle. If you want the rest of the tooling around it, the Claude Code Toolkit catalogs what I ship, and the docs site has the quickstart, the command reference, and the gate internals.