Skip to content

Home

Jump to bottom
Lex edited this page Aug 21, 2026 · 7 revisions

SpecGit Wiki

SpecGit is a delivery binding and acceptance harness: bind a branch or worktree to forge issues and one pull request, then derive the verdict from real git, PR, and CI evidence. A delivery is done if and only if specgit finish exits 0. If the evidence cannot be gathered, the answer is unknown, never accepted — SpecGit fails closed.

The model in one line

execution context (branch or worktree) + issues[] + one PR (or MR) + required CI checks

One delivery, one PR, N issues. Evidence flows through your authenticated forge CLI — gh for GitHub, glab for declared self-managed GitLab. No tokens read, no telemetry.

Three core ideas

1. A delivery harness for AI agents

SpecGit is a delivery harness for AI coding agents: it does not write code for the agent — it bounds the agent's behavior through binding, evidence, and exit codes. The agent works freely inside the harness, but may only claim "done" when the evidence bar is met. That is what makes large-model development smoother: this is not a restriction, it is giving the agent a deterministic definition of done.

2. One issue = one independently verifiable WHY

A delivery that cannot prove its value with its own evidence should be split. SpecGit binds N issues to one PR, but every issue must stand alone as an independently verifiable WHY. This is the core principle of decomposition granularity: small enough to verify, never smaller.

3. A strictly linear flow

specgit issue → implement → specgit finish — a strict linear pipeline in which finish is the only "done" verdict: exit 0 means the delivery is complete; every other exit code is fail-closed. This removes all ambiguity for the agent: there is no "I think it's done", only "the evidence says it's done".

Contents

Page Content
Getting Started Install, specgit init, first delivery
CLI Reference Ten commands, exit-code contract (0/1/2/3/130), --json envelope
Concepts Three file tiers, delivery binding, fail-closed acceptance, one issue = one WHY
Provider Architecture ForgeProvider port, gh/glab adapters, routing
GitLab Support Version window, differences from GitHub
Team Workflow Delivery loop, policy as team contract, review

Quick facts

  • Repository: https://github.com/LeXwDeX/SpecGit
  • Install: npm install -g specgit
  • Requirements: Node.js ≥ 20.19.0, git, and gh (GitHub) or glab ≥ 1.113.0 (declared GitLab) authenticated
  • Commands: init, setup, issue, pr, finish, bind, unbind, status, accept, doctor — ten, exactly
  • Exit codes: 0 accepted/success · 1 rejected · 2 usage error · 3 fail-closed unknown · 130 interrupted
  • License: MIT

Chinese version: Home-zh

SpecGit Wiki

中文

Repository documentation

Clone this wiki locally