Skip to content
SpecForge

GitHub Copilot

SpecForge’s Copilot support is a committed bundle — dist/agents/copilot/ — that ports the same spec-driven lifecycle to GitHub Copilot Chat: the /specforge.* commands, repo-wide instructions, 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
.github/prompts/specforge.<n>.prompt.md 15 command prompts, invoked as /specforge.<n> in Copilot Chat
.github/hooks/specforge.json A preToolUse hook registering the gate shim
.github/copilot-instructions.md Repo-wide instructions telling Copilot the gate exists and not to route around it
.specforge/gate/{copilot-gate.sh,decide.sh,common.sh} The gate: a Copilot-specific shim over the same transport-agnostic decision logic Claude Code uses
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 .github/ and .specforge/gate/ 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/copilot/install.sh

This is safe to re-run. If .github/copilot-instructions.md 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. How hard that enforcement bites depends on the agent and, for Copilot, on where you’re running it:

Tier Mechanism Status
Claude Code Real-time PreToolUse hook — blocks the edit at the moment it’s attempted Full (the flagship)
Copilot CLI / coding agent preToolUse hook (.github/hooks/specforge.json → copilot-gate.sh) Expected full (pending verification against Copilot’s live hook API)
Copilot Chat, VS Code inline Same preToolUse hook Preview — requires the chat.useCustomAgentHooks VS Code setting; partial until Copilot promotes it out of preview
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 disabled, in preview, or simply 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 Copilot 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 currently ship a CI workflow; 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: GitHub Copilot’s exact preToolUse hook JSON schema is not publicly pinned as of this writing. .github/hooks/specforge.json and copilot-gate.sh follow the documented preToolUse contract (matcher + command, permissionDecision: "deny" on block), and the shim is deliberately tolerant of field-naming variance (tool_input.filePath, .path, .file_path, .notebook_path) — but it may need a small tweak as Copilot’s hook support matures. It fails open on anything it can’t parse, so a schema drift degrades to “not enforced by this hook,” never to “blocks incorrectly.”

See also

Section titled “See also”