Getting Started

Getting Started

From zero to your first accepted delivery. For the command details see the CLI Reference; for the underlying model see Concepts.

Prerequisites

• Node.js ≥ 20.19.0 — check with node --version
• git — SpecGit verifies deliveries against a real repository; it will not run outside one
• gh (GitHub) — authenticated: gh auth login, verify with gh auth status
• glab ≥ 1.113.0 (declared self-managed GitLab only) — per-host auth: glab auth login --hostname git.example.com

The forge CLI is the provider seam: SpecGit reads issues, pull requests, and check runs through gh or glab. No tokens are read, echoed, or persisted by SpecGit itself — it relies on your existing authentication.

Install

npm install -g specgit
specgit --version
specgit doctor --json     # probe the environment; exit 0 = ready

The loop in one screen

# one-time, per repository
specgit init            # auto-detects required checks (empty list when no CI exists)

# per delivery: one command bootstraps issues, branch, draft PR, record
specgit issue "feat: add login flow"

# after CI (including the SpecGit Acceptance job) is green on the PR
specgit finish
# exit 0 → accepted · exit 1 → rejected (evidence attached) · exit 3 → cannot determine

That is the entire product surface. Everything else is diagnostics and JSON. (bind / unbind / accept remain as script aliases.)

Step by step

1. Initialize the policy and the harness

On the repository's default branch:

specgit init                                  # auto-detect from CI files
specgit init --required-check "Build"         # or name them explicitly (repeatable)

With no arguments the check names are auto-detected from the repository's CI files (GitHub workflow job names, GitLab CI job keys). A repository with no CI at all gets an empty list — the SpecGit Acceptance job itself is then the gate.

This creates the policy spec_git/policy.yaml and generates the harness: the acceptance workflow .github/workflows/specgit-accept.yml (runs specgit finish --json on every PR) and the managed agent block in AGENTS.md. Re-running init refreshes the harness idempotently and never touches an existing policy; specgit init --force rebuilds both.

2. Bootstrap the delivery with one command

specgit issue "feat: add login flow"

Each argument is one independently verifiable WHY: a quoted title creates a new issue; a pure number reuses an existing one. N arguments bind N issues to one delivery. The command creates the branch feat/<first-issue#>-<slug>, opens a draft PR whose body contains Closes #n for every bound issue, writes .specgit.yaml, commits, and pushes. Re-running the same command resumes after any failure between steps — it is idempotent.

The record (.specgit.yaml, committed on the delivery branch):

version: 1
delivery: add-login-flow
context:
  kind: branch
  branch: feat/123-add-login-flow
issues: [123]
pr: 42

Rules that matter:

• One issue = one independently verifiable WHY; if a deliverable cannot be verified on its own evidence, split it before binding.
• New titles must match <type>: <english title>; <type> comes from a fixed whitelist (feat, fix, refactor, perf, docs, test, chore, style, build, ci, revert, security, deprecate, dogfood).
• context is filled in automatically from live git — never hand-edit it.

3. Work, push, and keep the closing refs

Work on the branch the bootstrap created. The PR body must close every bound issue with a closing reference:

Closes #123

Supported forms: Closes #123, owner/repo#123, and full issue URLs, with any closing keyword (closes, fixes, resolves, and tense variants). Missing references produce closing_refs_incomplete at acceptance. If the PR binding is ever lost, specgit pr auto-discovers the PR by head branch and repairs the record.

4. Pass the required checks

Your CI must produce checks whose names exactly match required_checks, reported on the PR head commit — including the generated SpecGit Acceptance job. A draft PR always fails the verdict (pr_draft): mark it ready for review before finishing — gh pr ready <number> on GitHub, glab mr update <number> --ready on GitLab.

5. Finish

specgit finish

SpecGit re-reads the record and policy, probes live git, and asks the forge (via gh or glab) for issue, PR, and check evidence. Every gate either passes with evidence or fails with a code and a fix. Exit 0 means accepted: the delivery is bound, every issue is closed by the PR, and every required check is green at the PR head.

Where things live

SpecGit's entire footprint is three tiers of files:

Tier	Path	What it is	Committed?
Authoritative	spec_git/policy.yaml	The project's required-checks policy (created by init)	Yes
Authoritative	.specgit.yaml	This delivery's binding record (created by issue)	Yes, on the delivery branch
Authoritative	spec_git/providers.yaml	Optional platform declaration (declared GitLab host)	Yes
Derived harness	.github/workflows/specgit-accept.yml	The generated acceptance gate — regenerate with init --force	Yes
Derived harness	AGENTS.md / CLAUDE.md managed block	The generated agent contract between the specgit markers	Yes
Local integration	Guard hooks, setup entry points	Machine-local wiring, merged non-destructively	Your choice

There are no artifact folders, no stores, no caches. Verdicts are never stored — they are computed on every run.

---

Chinese version: Getting-Started-zh