SpecGit connects a branch or worktree, one or more issues, one PR/MR, and the project's required checks. It derives acceptance from Git and your authenticated GitHub or GitLab session. Teams and coding agents get a shared, verifiable meaning of acceptance and completion.

Design principles

• Evidence determines acceptance. The record declares the delivery; Git, issue, request, and current-head check facts substantiate it on every run.
• Missing evidence stays unknown. Unavailable or incomplete evidence cannot produce an accepted verdict.
• Completion closes the delivery. Acceptance precedes merge; completion requires a confirmed merge and every bound issue closed.
• Verification follows the change. A README introduction needs content and link checks. Product behavior needs applicable product tests. Publication requires explicit release intent.

One issue describes one independently verifiable WHY. One PR/MR may close several such issues. See Concepts for the full model.

Quick start

Requirements: Node.js >=20.19, Git, and an authenticated gh or glab. Run repository commands inside the project you intend to use with SpecGit.

npm install -g specgit@latest
specgit --version

gh auth status                       # GitHub; use glab for GitLab
specgit init                         # review detected required checks
specgit setup                        # install agent entry points

specgit issue "feat: add login flow"
# Implement, run the checks appropriate to the change, commit, and push.
# Keep Closes #n for every bound issue in the PR/MR body.

gh pr ready <number>                 # GitLab: glab mr update <number> --ready
specgit finish

issue creates or reuses the issues, creates the branch and draft PR/MR, records the binding, and pushes it. Repeating the same command resumes an interrupted bootstrap. Fill in the actual Why, Scope, Approach, and Acceptance; selected body rules may require --body-file and --pr-body-file at creation.

finish reads evidence and never merges or closes issues itself:

| Result | Meaning | Next step | | --- | --- | --- | | accepted, exit 0 | The observed request head satisfies acceptance | Complete the authorized merge and issue closure | | rejected, exit 1 | Evidence proves a condition is not satisfied | Fix the named condition; pending CI may simply need time | | unknown, exit 3 | Necessary evidence is unavailable | Follow errors[].fix and collect fresh evidence | | closure_pending | Merge is confirmed, but bound issues remain open | Complete their closure and run finish again | | completed | Merge and all bound issue closures are confirmed | Start the next delivery when ready |

A changed head, request body, or check result needs a fresh verdict. See Getting Started for the detailed walkthrough.

Keep small changes small

For changes to SpecGit's own README, Wiki, or manual project guidance, use the documentation short path: review the affected content once, run the existing metadata check, and finish local verification when it passes. These changes do not need product compilation, typechecks, the full test suite, mutation testing, or repeated agent reviews.

node scripts/ci-metadata-check.mjs

This repository still uses lightweight remote metadata validation and acceptance before a delivery merges. Product build/test jobs are skipped for a complete metadata-only diff; a documentation edit does not request an npm release. A PR that also contains source changes still requires product verification. Keep unrelated work out of a small documentation delivery.

Shipped templates, generators, executable workflows, schemas, and distributed skills are product inputs, even when they produce Markdown. Their changes need the applicable product checks. The binding classification is CI scope. An adopting project chooses its own checks and their scope; SpecGit's private source-repository CI map does not replace the adopter's business CI.

Platforms

| Platform | Setup | Evidence | | --- | --- | --- | | GitHub.com | Authenticate gh, then run specgit init | GitHub issues, PRs, and current-head checks | | Self-managed GitLab | Authenticate glab for the host and declare it with --gitlab-host | GitLab issues, MRs, and pipeline jobs | | GitLab.com | Declare --gitlab-host gitlab.com and authenticate glab | Capability-probed GitLab evidence |

glab auth status --hostname gitlab.example.com
specgit init --gitlab-host gitlab.example.com

The verified self-managed window is GitLab CE/Free >=19.2.4 <19.4.0, with glab >=1.113.0. Outside that window, live evidence remains authoritative; consult GitLab support for the qualification policy. GitHub Enterprise has no v1 provider route. One delivery belongs to one repository on one platform.

GitHub gets a generated acceptance workflow. GitLab's business acceptance job remains project-owned; its reviewed pipeline must run specgit finish --json. See the platform guide before enabling completion automation.

Configuration and automation

| File | Purpose | | --- | --- | | spec_git/policy.yaml | Required checks and optional language, title/label/body rules, templates, and automation | | spec_git/providers.yaml | Explicit GitLab host declaration, when used | | .specgit.yaml | This delivery's issue, execution-context, and PR/MR binding |

init creates shared integration assets and local hooks; setup installs local agent entry points. Review generated changes before committing shared assets. Neither a local refresh nor an ordinary merge authorizes package publication. Acceptance state is derived on each invocation, never stored in a checklist. The three tiers are authoritative delivery files, the derived committed harness, and local integration assets.

Automatic merge and issue closure are off by default. Only the user's explicit yes enables them; an agent cannot supply that decision. For an existing policy:

specgit init --force --automation yes --merge-target <branch>

Once enabled, the trusted completion workflow continues after CI. specgit pr --merge --json recovers interrupted completion: it checks the approved target and current head, verifies acceptance and CI, confirms merge, then closes bound issues. See Team Workflow and Actions.

To keep merging manual and close issues after a merge into a chosen branch:

specgit init --force --automation no --close-issues yes --close-target preview

The target accepts any valid branch name, such as dev, preview, or release/stable. It is the PR/MR destination, not its source branch. The generated workflow signals a confirmed merge and the trusted runtime closes bound issues through gh or glab. specgit pr --close-issues --json is the recovery command. The trusted completion workflow still lives on the remote default branch; deploy its approved integration there and the acceptance/notification integration on the configured target before relying on automatic closure.

Historical authorization uses the original target parent for a two-parent merge. Squash, rebase, and fast-forward recovery uses a platform-provided target revision only when Git proves it is an ancestor of the merged result and policy remained unchanged throughout that history. Missing or ambiguous history returns policy_history_unavailable; the runtime never substitutes the newly merged policy for prior approval. A policy-changing delivery should use a merge commit when it needs automatic closure recovery.

Upgrade an existing installation

Updating the package and refreshing a repository are separate steps: Refresh generated assets after CLI upgrades with this explicit sequence:

npm install -g specgit@latest
specgit --version
specgit init --force --no-protect
specgit setup --tool all
specgit status --json

Review the resulting diff. Follow Installation for ownership conflicts and projects that intentionally track authoritative files without the managed ignore block. Use doctor for a reported environment or provider problem; status checks local state and generated-asset drift. A refresh does not grant permission to change automation or release a package.

Commands and agent integration

| Command | Purpose | | --- | --- | | specgit init | Initialize policy and integration assets; refresh explicitly with --force | | specgit setup | Install or refresh OpenCode commands or portable agent skills | | specgit issue | Start or resume the bound delivery | | specgit pr | Repair the request binding; recover enabled completion with --merge | | specgit finish | Read live acceptance and completion evidence | | specgit status | Inspect local binding and generated-asset state | | specgit doctor | Probe Git, repository, origin, forge CLI/authentication, and policy | | specgit bind, specgit unbind, specgit accept | Script-level binding operations and the acceptance alias |

Humans may omit --json. Agents and scripts use its single stdout JSON envelope and stable exit codes: 0 success/accepted, 1 rejected, 2 usage error, 3 unknown, 130 interrupted. Diagnostics include a code and a repair direction. See CLI Reference for flags and exact result shapes. For specgit status, a missing record is normal before binding: exit 0 with state unbound. That local snapshot is not a remote acceptance verdict.

setup --tool generic installs .agents/skills/ entry points; setup --tool opencode installs .opencode/command/ entries; --tool all refreshes both. Init-managed guards protect merge operations such as gh pr merge and glab mr merge. SPECGIT_GUARD_BUDGET_S controls the hook's verdict budget; it is not a general CLI setting. The forge overrides are SPECGIT_GH, SPECGIT_GH_TIMEOUT_MS, SPECGIT_GLAB, and SPECGIT_GLAB_TIMEOUT_MS. See the Agent Contract for authorization and completion.

Documentation and contributing

• Project Wiki · 中文 Wiki
• Getting Started · Installation · Existing Projects
• Concepts · CLI Reference · Schemas and gates
• Team Workflow · CI scope · Agent Contract
• GitLab support · Troubleshooting · FAQ
• Contributing · Release gates · Changelog

The Wiki provides English and Chinese introductions; detailed contracts live in docs/. Repository copies of Wiki pages live in docs/wiki/. Publishing the Wiki is a separate update, so editing those files alone does not update the live site.

SpecGit uses your authenticated gh/glab session without storing tokens or sending telemetry. Report vulnerabilities through the repository's private security advisory channel. Workflow permissions and supply-chain guidance are in Actions security.

MIT — see LICENSE.