Skip to content
SpecForge

Quickstart

Get from zero to an enforced, spec-driven feature in about five minutes. Adapted from the spec-kit quickstart, using SpecForge’s commands and its hook-enforced approval gate.

1. Install

Section titled “1. Install”

Claude Code (full experience — commands + skills + enforced gate):

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

Any skills-compatible agent:

npx skills add pooyagolchian/specforge

GitHub Copilot (preview — commands + repo instructions + a preview gate hook):

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

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 (commands + an always-applied rule + a real preToolUse gate):

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

See the Cursor guide for the full command list and the enforcement-tier breakdown — Cursor’s Hooks are GA (not a preview), so this is real edit-time enforcement, though the exact hook JSON schema isn’t verified against a live Cursor install yet.

Gemini CLI (commands + repo instructions + a BeforeTool gate):

Terminal window
# 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 — the BeforeTool hook’s config, matcher, and deny shape match Gemini’s documented hooks schema, but it hasn’t been tested against a live Gemini CLI install yet.

Codex (skills + repo instructions + an apply_patch-parsing PreToolUse gate):

Terminal window
# 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 — the PreToolUse hook’s matcher and deny shape match Codex’s documented schema, but it hasn’t been tested against a live Codex install yet.

On every shipped agent the workflow and artifacts are identical; only the invocation syntax differs (/specforge:* on Claude and Gemini, /specforge.* on Copilot, /specforge-* on Cursor, $specforge-* on Codex). All five ship a real native pre-tool hook plus the same agent-independent git pre-commit backstop; more agents are generator-ready to follow the same pattern.

2. The lifecycle, one command at a time

Section titled “2. The lifecycle, one command at a time”
/specforge:init                    # scaffold the specforge/ workspace
# fill in specforge/inputs/vision.md and tech-environment.md
/specforge:constitution            # optional: set project principles
/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                    # design the HOW
/specforge:approve  plan           # ← the gate opens here
/specforge:tasks
/specforge:analyze
/specforge:implement               # build it, under the gate

3. What the gate does

Section titled “3. What the gate does”

Until the active feature’s spec and plan are both approved, SpecForge blocks code edits — via a real PreToolUse hook on Claude Code, via a preToolUse hook (expected full in the Copilot CLI/coding agent — pending verification against Copilot’s live hook API — preview in VS Code inline) plus a git pre-commit backstop on GitHub Copilot installs, via a real preToolUse hook (Cursor’s Hooks are GA, not a preview — schema unverified against a live Cursor install) plus the same pre-commit backstop on Cursor installs, and via a BeforeTool hook on Gemini CLI installs / an apply_patch-parsing PreToolUse hook on Codex installs (both match their agent’s documented hook schema but are not yet verified against a live install) plus the same pre-commit backstop on both. See the Copilot guide, the Cursor guide, the Gemini CLI guide, and the Codex guide for the honest, per-surface breakdown. None of the five ships a CI/PR-time gate — the pre-commit backstop is local only. Writing the specs themselves is always allowed; /specforge:quick fast-tracks a trivial change.

Key principles

Section titled “Key principles”
  • AI proposes, a human approves, and approval is enforced — not hoped for.
  • Specs are committed and travel with your pull requests.
  • Stack-agnostic and local-first — no telemetry.

Next steps

Section titled “Next steps”