SpecForge

A spec-driven AI development lifecycle — where AI proposes, a human approves, and approval is enforced, not hoped for. Claude Code (flagship), GitHub Copilot (preview), Cursor, Gemini CLI, and Codex all ship today.

SpecForge fuses GitHub spec-kit's executable specs with AWS AI-DLC's human-approval governance, and makes the gates real using Claude Code hooks — delivered as one installable plugin (and listable on skills.sh).

Install as a Claude Code plugin — full experience (commands + skills + enforced gates):

/plugin marketplace add pooyagolchian/specforge
/plugin install specforge@specforge

Or add the skills to any agent via skills.sh:

npx skills add pooyagolchian/specforge

Then run /specforge:init in any project to start.

---

Why SpecForge

Most AI coding tools jump straight to code. Spec-driven tools add discipline but the "stop and let a human approve" step is advisory — a well-behaved model follows it; a hurried one blows right through. SpecForge closes that gap:

• 📐 Spec-kit's executable specs — a clean constitution → specify → clarify → plan → tasks → analyze → implement pipeline that produces committed, PR-traveling artifacts.
• 🛡️ AI-DLC's governance — human approval as a first-class, blocking step, with an append-only audit trail and brownfield reverse-engineering.
• ⚙️ Enforced by hooks — a PreToolUse hook blocks code edits until the active feature's spec and plan are approved. Governance you can't accidentally skip.
• 🏃 An escape hatch — /specforge:quick fast-tracks a trivial change so the kit never becomes ceremony for a typo.

No existing kit combines all four. That's what makes this a portfolio-grade FDE showcase — and a genuinely useful starting kit for teams.

The gate (the whole point)

flowchart LR
    A[Claude tries to Edit/Write code] --> B{specforge/ workspace?}
    B -- no --> P[allow · inert]
    B -- yes --> C{editing specforge/ docs?}
    C -- yes --> P2[allow · writing specs]
    C -- no --> D{fast-track on?}
    D -- yes --> P3[allow · logged]
    D -- no --> E{active feature's spec + plan approved?}
    E -- yes --> P4[allow · gate OPEN]
    E -- no --> X[DENY · finish + approve the plan]

Loading

The gate is a real hook (scripts/gate-check.sh), inert on projects that don't use SpecForge, and it always lets you write the specs themselves. State lives in a committed, diff-able specforge/state.md.

The lifecycle

flowchart TD
    init[/specforge:init/] --> con[/specforge:constitution/]
    con --> spec[/specforge:specify → spec.md/]
    spec --> cl[/specforge:clarify/]
    cl --> as([approve specify])
    as --> plan[/specforge:plan → plan.md + design/]
    plan --> ap([approve plan → gate OPEN])
    ap --> tasks[/specforge:tasks → tasks.md/]
    tasks --> an[/specforge:analyze/]
    an --> impl[/specforge:implement/]
    impl --> op[/specforge:operate → operations.md/]
    subgraph brownfield [adopting existing code]
      re[/specforge:reverse-engineer/] --> spec
    end

Loading

Commands

Command	Phase	What it does
/specforge:init	setup	Scaffold the specforge/ workspace + input templates
/specforge:constitution	inception	Set project principles (soft gates)
/specforge:reverse-engineer	inception	Seed specs from an existing codebase (brownfield)
/specforge:specify	inception	Write the spec (WHAT/WHY) → spec.md
/specforge:clarify	inception	Resolve unknowns via a questions-in-a-file flow
/specforge:plan	construction	Design the HOW → plan.md + data-model, contracts/
/specforge:tasks	construction	Break the plan into an ordered, traceable checklist
/specforge:analyze	construction	Cross-check spec ↔ plan ↔ tasks for gaps (read-only)
/specforge:approve <stage>	gate	Record human approval — specify + plan opens the gate
/specforge:implement	construction	Build it, under the gate
/specforge:loop	construction	Autonomously work the approved task list — gated Ralph loop
/specforge:operate	operations	Ship & own it — deploy plan, runbook, observability, rollback, handoff
/specforge:quick	escape hatch	Audited fast-track for a trivial change
/specforge:status	any	Show progress + gate state
/specforge:resume	any	Continue after a context reset

Five subagents (spec-analyst, architect, implementer, reviewer, reverse-engineer) do the heavy lifting for each phase.

Autonomous loop (Ralph, governed)

Want it to just finish the feature? /specforge:loop runs the Ralph loop — work the task list one task at a time until it's done — but gated: it can only run once a human approved the spec + plan, it follows tasks.md (no invented scope), it logs every step to audit.md, and it stops instead of guessing when it hits a blocker.

/specforge:loop                                   # in-session, one task at a time

For a fully unattended run, the bundled headless runner is the classic outer loop, gate-checked and iteration-bounded:

"${CLAUDE_PLUGIN_ROOT}/scripts/ralph-loop.sh" 25   # re-invokes `claude` per task until done

The pitch in one line: the Ralph loop's speed, with a gate that keeps a human in the loop. See docs/loop.md.

Install

As a Claude Code plugin (full experience — commands + skills + gates)

/plugin marketplace add pooyagolchian/specforge
/plugin install specforge@specforge
/reload-plugins

Try it live without installing:

claude --plugin-dir ./plugins/specforge

As skills only (any of 70+ agents, via skills.sh)

npx skills add pooyagolchian/specforge

Skills installed this way still guide the workflow and write the artifacts — they just don't ship the enforcement hooks (those are the Claude Code plugin's bonus). Graceful degradation by design.

Other agents

GitHub Copilot ships as a committed bundle (dist/agents/copilot/) — the /specforge.* prompts, repo-wide instructions, and a preToolUse gate hook, plus a git pre-commit backstop. install.sh needs the rest of the bundle beside it, so it can't be piped through curl | sh; run it from inside your project instead:

# From inside your project repo:
git clone --depth 1 https://github.com/pooyagolchian/specforge /tmp/specforge
/tmp/specforge/dist/agents/copilot/install.sh
# then in Copilot Chat: /specforge.init

See the Copilot guide for the full command list and the honest enforcement-tier breakdown (expected full in the CLI/coding agent — pending verification against Copilot's live hook API — preview in VS Code inline).

Cursor ships as a committed bundle (dist/agents/cursor/) — the /specforge-* commands, an always-applied .cursor/rules/specforge.mdc rule, and a real preToolUse gate hook (.cursor/hooks.json), plus the same git pre-commit backstop. Cursor's Hooks feature is GA (not a preview), so this is genuine edit-time enforcement. The hook config (matcher Write|Delete), the deny response shape, and the project-dir field match Cursor's documented hooks schema; the exact tool_input file-path field for a Write is handled across candidate names. Verify against your Cursor version — and it fails open the same way every other tier does. install.sh needs the rest of the bundle beside it, so run it from inside your project:

# From inside your project repo:
git clone --depth 1 https://github.com/pooyagolchian/specforge /tmp/specforge
/tmp/specforge/dist/agents/cursor/install.sh
# then in Cursor's Agent chat: /specforge-init

See the Cursor guide for the full command list and the enforcement-tier breakdown.

Gemini CLI ships as a committed bundle (dist/agents/gemini/) — the /specforge:* TOML commands, GEMINI.md repo instructions, and a BeforeTool gate hook (.gemini/settings.json), plus the same git pre-commit backstop. The hook's config, matcher, and deny shape match Gemini's documented hooks schema, but it hasn't been exercised against a live Gemini CLI install. install.sh needs the rest of the bundle beside it, so run it from inside your project:

# From inside your project repo:
git clone --depth 1 https://github.com/pooyagolchian/specforge /tmp/specforge
/tmp/specforge/dist/agents/gemini/install.sh
# then in Gemini CLI: /specforge:init

See the Gemini CLI guide for the full command list and the enforcement-tier breakdown.

Codex ships as a committed bundle (dist/agents/codex/) — the $specforge-* skills, AGENTS.md repo instructions, and a PreToolUse gate hook (.codex/hooks.json) that parses Codex's apply_patch text for the files it touches, plus the same git pre-commit backstop. The hook's matcher and deny shape match Codex's documented schema, but it hasn't been exercised against a live Codex install. install.sh needs the rest of the bundle beside it, so run it from inside your project:

# From inside your project repo:
git clone --depth 1 https://github.com/pooyagolchian/specforge /tmp/specforge
/tmp/specforge/dist/agents/codex/install.sh
# then in Codex: $specforge-init

See the Codex guide for the full command list and the enforcement-tier breakdown.

All five shipped agents — Claude Code (the flagship), GitHub Copilot (preview), Cursor, Gemini CLI, and Codex — get a real native pre-tool hook plus the same agent-independent git pre-commit backstop; none ships a CI/PR-time gate. The generator architecture (neutral step source + per-agent adapter, tools/gen_agents.py) that produces all five bundles is built to extend to more agents; those are generator-ready but not yet shipped as committed bundles.

Quickstart

/specforge:init
# fill in specforge/inputs/vision.md and tech-environment.md
/specforge:specify   "Todo CRUD API with list, create, complete, delete"
/specforge:clarify   # answer the questions file, then say "answers ready"
/specforge:approve specify
/specforge:plan
/specforge:approve plan          # ← the gate opens here
/specforge:tasks
/specforge:analyze
/specforge:implement

See a complete, real run in examples/todo-api/.

SpecForge builds itself with itself. The committed specforge/ store — constitution, audit trail, and specs/001-operations-phase/ — was produced by running the full SpecForge lifecycle on this repo to ship the Operations phase.

Repo layout

.claude-plugin/marketplace.json     # the marketplace catalog
plugins/specforge/                  # the plugin
  ├─ .claude-plugin/plugin.json
  ├─ skills/        # 13 lifecycle skills (each is also a /command)
  ├─ agents/        # 5 role subagents
  ├─ hooks/hooks.json + scripts/    # the enforcement layer
  └─ skills/_shared/                # canonical artifact templates
examples/todo-api/                  # a full worked example
docs/                               # lifecycle guide, command reference, gate + brownfield guides

How it compares

	spec-kit	AI-DLC	opinionated SDD plugins	SpecForge
Executable specs	✅	partial	✅	✅
Full lifecycle + brownfield	partial	✅	partial	✅
Enforced approval gates	❌ advisory	❌ advisory	mostly advisory	✅ hook-enforced
Native Claude Code (skills+agents+hooks)	❌ CLI	❌ rules	✅	✅
Stack-agnostic	✅	✅	often opinionated	✅

Trust & design

MIT licensed · local-first · no telemetry · specs are committed and travel with your PRs · every gate transition is logged in specforge/audit.md.

Docs

• Quickstart
• Installation guide
• Lifecycle guide
• Command reference
• How the gates work
• Autonomous loop (Ralph, governed)
• Brownfield adoption
• Contributing

License

MIT © Pooya Golchian