Spec · Build · Verify · Ship

From issue spec to verified delivery.

SpecGit gives coding agents one shared delivery workflow for GitHub and GitLab. Issues hold the specification, a native PR or MR gathers the work, and SpecGit reads the forge's live state so an agent can repair failures and tell pending work from completed delivery.

Download latest See the pipeline Read the README

verified checkpoint CI green

specgit — delivery

$ specgit issue 906 --branch feat/title-scope ✓ checkpoint selected · Issue #906 $ specgit pr --ready ✓ PR #909 ready · target main $ specgit watch --checks ✓ Required verification · success ✓ SpecGit Acceptance · success ✓ merged · #906 closed · verified

The delivery pipeline

One issue, one traceable path to production.

Every commit binds to a selected Issue through a local checkpoint. SpecGit aggregates the native PR/MR and observes the platform, so delivery is verified against live state — never assumed.

Issue specification spec

The Issue holds Why / Scope / Approach / Acceptance. specgit issue --inspect deduplicates the WHY before anything is created.

Local checkpoint bind

A checkpoint records the selected Issue on the branch. The native Git guard checks it and the Issue: #N trailer on every commit and push.

Native PR / MR build

The agent implements and specgit pr gathers the selected Issues into one native request, preserving closing references and the PR template.

CI & review observe

specgit watch and pr --status read the current head's checks and reviews. Failures are repaired in scope, never by weakening protection.

Merge ship

When required checks pass and the head is clean, the request merges on the platform. SpecGit reads back the merge — exit code 0 alone is never completion.

Verified closure verify

Delivery is confirmed only when the target branch merged and every associated Issue is closed with native evidence — not by a local guess.

Signed release release

A separate, signed GitHub Release publishes three-platform ZIPs with a Cosign-signed SHA256SUMS. Merging is not releasing.

Product principles

Host-neutral by design.

Capability lives in the CLI and the native Git guard first. Hosts only add prompts and context — they never carry business rules.

Zero-host usable

A project works with no host integration at all. The shared CLI and Git guard deliver the full workflow on their own.

Native Git guard

Pre-commit and pre-push checks bind every commit to a selected Issue. No --no-verify, no weakened protection.

Live-state verification

SpecGit reads the forge's current state to distinguish pending work from completed delivery, and to repair failures in scope.

Managed host assets

Host guidance, hooks and read-only allowlists are explicit, owned, refreshable and removable — never global state.

Install

One executable, every repository.

Open your coding agent in the repository and ask it to follow the agent installation guide. It downloads the latest signed GitHub Release, verifies the signature and SHA-256, installs the shared CLI and initializes the project. No Node.js, npm or Rust compiler needed.

specgit init --provider github --remote origin --check --json
specgit init --provider github --remote origin --dry-run --json
specgit init --provider github --remote origin --json
specgit setup --catalog --json

Already installed? Use the project maintenance guide. The specgit CLI is distributed only through GitHub Releases.

Host quick start

Bring your own agent.

Naming a host with --agent adds its guidance and Skill only; hooks and managed read-only permissions are separate explicit choices. Preview with --dry-run, then repeat without it to apply.

Generic

Guidance in AGENTS.md and the canonical .agents/skills/specgit-native/SKILL.md. No host callbacks; the Git guard still applies.

specgit setup --agent generic --dry-run --json
specgit setup --agent generic --json

Fallback: read guidance and Skill directly. Supported Hosts.

Claude Code

Root CLAUDE.md, the canonical .agents Skill plus a .claude/skills copy. Context hooks and the managed read-only allowlist are optional.

specgit setup --agent claude --dry-run --json
specgit setup --agent claude --json
specgit setup --agent claude --readonly-permissions --json

The allowlist reduces prompts; it is not a sandbox. Supported Hosts.

Codex

Canonical .agents Skill and guidance in AGENTS.md or an existing nonempty AGENTS.override.md. Context hooks go to .codex/hooks.json.

specgit setup --agent codex --hook-purpose context --dry-run --json
specgit setup --agent codex --hook-purpose context --json

Trust the .codex/ layer in the host's /hooks review. Supported Hosts.

OpenCode

The official build gets the AGENTS.md entry and .agents Skill; context hooks are declined. A custom fork can opt into Claude-compatible hooks.

specgit setup --agent opencode --dry-run --json
specgit setup --agent opencode --json

Fallback: re-read guidance and use bounded watch/inbox. Supported Hosts.

Support matrix

What each host gets.

The maintained summary lives in Supported coding agents and Supported Hosts; the linked documents are authoritative.

Host	Guidance entry	Skill discovery	Context hooks	Read-only allowlist	Fallback
`generic`	`AGENTS.md`	`.agents/skills/specgit-native/SKILL.md` when the host reads `.agents`	none; declined	declined: no host permission configuration	Read guidance and the Skill directly
Claude Code	`CLAUDE.md`	Canonical `.agents` Skill plus `.claude/skills/specgit-native/SKILL.md`	`.claude/settings.json` SessionStart/PreToolUse	`.claude/settings.json` `permissions.allow` with `--readonly-permissions`	Re-read guidance and Skill
Codex	`AGENTS.md`, or an existing nonempty `AGENTS.override.md`	Canonical `.agents` Skill; scans working directory to repo root and `~/.agents/skills`	`.codex/hooks.json`; requires host `/hooks` trust review	declined: experimental approval and sandbox	Re-read guidance and Skill
OpenCode (official)	`AGENTS.md`	`.agents` Skill; host also reads project `.opencode/` and `.claude/` skills	none; declined	declined: default-allow, no portable allowlist	Re-read guidance and Skill; bounded `watch`/`inbox`
OpenCode custom fork	`AGENTS.md`	Same as official OpenCode	`.opencode/hooks.json` with `inputFormat: claude-code`; requires `--agent opencode --opencode-claude-hooks` plus an explicit hook purpose	declined	Same as official OpenCode

guard is the native Git pre-commit/pre-push check, not a host callback. It applies to every host, including generic, through setup --hook-purpose guard or specgit guard --install. Context hooks only prompt and provide context; they never carry business rules.

Download

Signed, three-platform releases.

The native specgit CLI is distributed only through GitHub Releases. The latest stable release provides:

macOS

specgit-<version>-darwin-arm64.zip

Linux

specgit-<version>-linux-x64-gnu.zip

Windows

specgit-<version>-win32-x64.zip

Verify before installing

Each release ships SHA256SUMS and SHA256SUMS.sigstore.json. The Cosign signature covers SHA256SUMS and therefore the ZIP bytes; cross-check the tag commit and the native build workflow run separately. See the release asset verification reference.

Install as a plugin

The plugin bundles the specgit-native Skill and onboarding only; the native CLI still comes from GitHub Releases. See the plugin installation guide.

# Claude Code
claude plugin marketplace add LeXwDeX/SpecGit
claude plugin install specgit@specgit-marketplace

# Codex: add the marketplace, then browse and install in /plugins
codex plugin marketplace add LeXwDeX/SpecGit

# Pi, OpenCode and other skill-only hosts
specgit init
specgit skill --user

Open the latest release

Documentation

Go deeper.

README: product, installation and workflow→ Agent installation and initialization→ Installed-CLI project maintenance→ Supported coding agents and discovery boundaries→ Release asset verification reference→ Native commands, configuration and JSON contract→ SpecGit Skill workflow→ Migration from v1→ Release procedure and recovery→ Current glossary→ English Wiki→ 中文 Wiki→