Skip to content
SpecForge

Cursor

SpecForge’s Cursor support is a committed bundle — dist/agents/cursor/ — that ports the same spec-driven lifecycle to Cursor’s Agent chat: the /specforge-* commands, an always-applied repo rule, and a real pre-edit gate. It’s generated from the same neutral step source as the Claude Code plugin, so the workflow and artifacts (specforge/spec.md, plan.md, tasks.md, state.md, …) are identical; only the command prefix and hook transport differ.

What’s in the bundle

Section titled “What’s in the bundle”
Path Purpose
.cursor/commands/specforge-<n>.md 15 command files, invoked as /specforge-<n> in Cursor’s Agent chat
.cursor/rules/specforge.mdc An alwaysApply rule telling Cursor the gate exists and not to route around it
.cursor/hooks.json A preToolUse hook registering the gate shim
.specforge/gate/{cursor-gate.sh,decide.sh,common.sh} The gate: a Cursor-specific shim over the same transport-agnostic decision logic Claude Code and Copilot use
.specforge/scripts/{new-feature.sh,ralph-loop.sh} Helper scripts the /specforge-* commands reference
pre-commit An agent-independent git hook — the backstop described below
install.sh Copies the above into your repo (see Install)

Install

Section titled “Install”

install.sh needs the rest of the bundle sitting beside it — it copies .cursor/ and .specforge/ from its own directory, and it detects your repo root by running git rev-parse --show-toplevel from wherever you invoke it. That means it can’t be safely piped through curl | sh: it has to be run from inside your target repo, pointed at a real copy of the bundle. Get the bundle, then run its installer from inside your project:

/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

This is safe to re-run. If .cursor/rules/specforge.mdc or a git pre-commit hook already exists and differs from SpecForge’s version, install.sh backs up the existing file (.bak) before installing rather than silently overwriting it.

Commands

Section titled “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 + companions
/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 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

Enforcement tiers

Section titled “Enforcement tiers”

SpecForge’s differentiator is that approval is enforced, not advisory. Cursor is the strongest non-Claude tier shipped so far, because Cursor’s Hooks feature itself is no longer a preview:

Tier Mechanism Status
Claude Code Real-time PreToolUse hook — blocks the edit at the moment it’s attempted Full (the flagship)
Cursor Agent preToolUse hook (.cursor/hooks.json → cursor-gate.sh) Real edit-time enforcement — Cursor’s Hooks are GA (generally available), stronger than Copilot’s preview-stage hook — matches Cursor’s documented hooks schema; the exact tool_input file-path field is handled defensively
Any agent, or a human editing directly git pre-commit hook (installed by install.sh) Agent-independent backstop — fires at commit time regardless of which AI (or no AI) made the edit

The pre-commit hook is the honest floor: even where a coding agent’s own hook is misconfigured, disabled, or not wired up, an unapproved code change staged for commit is still caught locally, before it’s committed. It reuses the same decide.sh decision logic as the Cursor and Claude hooks, so its verdict is always consistent with theirs. Note this is a local git hook, not a CI/PR check — the bundle doesn’t ship a CI workflow for your repo; if you want enforcement at PR time too, you can wire decide.sh into your own CI job the same way pre-commit does.

Caveat: Cursor’s Hooks feature is real and GA (not a preview or beta gate), so .cursor/hooks.json registering a preToolUse hook is genuine edit-time enforcement, not an advisory. The hook config (matcher Write|Delete — Cursor’s documented, case-sensitive tool-type names for file creates/edits and deletions), the deny response shape ({"permission":"deny",...}), and the project-dir field (cwd) match Cursor’s documented hooks schema (cursor.com/docs/agent/hooks). The one thing not pinned in Cursor’s docs is the exact tool_input field that carries the file path for a Write, so the shim is deliberately tolerant of field-naming variance there (tool_input.path, .file_path, .target_file, .filePath, .notebook_path). .cursor/hooks.json does not set failClosed, so it defaults to fail-open — the same principle SpecForge applies everywhere else. That means if a Cursor version ever sends the file path under a field name outside that candidate list, the failure mode is “this hook silently stops blocking” (caught by the pre-commit backstop at commit time regardless), never “this hook incorrectly blocks a legitimate edit.” Verify against your Cursor version — this is matched against Cursor’s documented schema, not tested against a live Cursor install.

See also

Section titled “See also”