规格 · 实现 · 验证 · 交付

从 Issue 规格到验证交付。

SpecGit 为编码 agent 提供 GitHub 与 GitLab 共享的交付工作流。规格写在 Issue，原生 PR/MR 汇聚所选 Issue 与实现，SpecGit 读取平台实时状态，让 agent 能修复失败、区分待办与已完成的交付。

下载最新版查看交付管道阅读 README

已验证 checkpoint CI 通过

specgit — 交付

$ specgit issue 906 --branch feat/title-scope ✓ 已选 checkpoint · Issue #906 $ specgit pr --ready ✓ PR #909 ready · 目标 main $ specgit watch --checks ✓ Required verification · success ✓ SpecGit Acceptance · success ✓ 已合并 · #906 已关闭 · 已验证

交付管道

一个 Issue，一条可追溯的上线路径。

每个提交通过本地 checkpoint 绑定所选 Issue。SpecGit 汇聚原生 PR/MR 并观察平台，交付以实时状态验证——绝不靠假设。

Issue 规格 spec

Issue 承载原因 / 范围 / 方案 / 验收。specgit issue --inspect 在创建前对 WHY 查重。

本地 checkpoint bind

checkpoint 在分支上记录所选 Issue。原生 Git guard 在每次 commit/push 检查它与 Issue: #N trailer。

原生 PR / MR build

agent 实施后由 specgit pr 把所选 Issue 汇聚为一个原生请求，保留关闭引用与 PR 模板。

CI 与评审 observe

specgit watch 与 pr --status 读取当前 head 的检查与评审。失败在范围内修复，绝不弱化保护。

合并 ship

必需检查通过且 head 干净时在平台合并。SpecGit 回读合并结果——退出码 0 本身从不等于完成。

验证关闭 verify

仅当目标分支已合并、每个关联 Issue 以原生证据关闭时才确认交付——不靠本地猜测。

签名发布 release

独立的签名 GitHub Release 发布三平台 ZIP 与 Cosign 签名的 SHA256SUMS。合并不等于发布。

产品原则

生而宿主中立。

能力首先在 CLI 与原生 Git guard 中实现。宿主只增加提示与上下文——绝不承载业务规则。

零宿主可用

项目无需任何宿主集成即可工作。共享 CLI 与 Git guard 独立交付完整工作流。

原生 Git guard

pre-commit/pre-push 检查把每个提交绑定到所选 Issue。不用 --no-verify，不弱化保护。

实时状态验证

SpecGit 读取平台当前状态，区分待办与已完成交付，并在范围内修复失败。

受管宿主资产

宿主指导、hooks 与只读白名单都是显式、受管、可刷新、可移除的——绝不写全局状态。

安装

一个可执行文件，服务所有仓库。

在仓库中打开你的编码 agent，让它遵循 agent 安装指南：下载最新签名 GitHub Release，校验签名与 SHA-256，安装共享 CLI 并初始化项目。无需 Node.js、npm 或 Rust 编译器。

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

已安装？请使用项目维护指南。原生 specgit CLI 仅通过 GitHub Releases 分发。

宿主快速上手

带上你自己的 agent。

用 --agent 指定宿主只增加其指导与 Skill；hooks 与受管只读权限是独立的显式选择。先用 --dry-run 预览，再去掉它重复执行以应用。

Generic

指导写在 AGENTS.md 与规范的 .agents/skills/specgit-native/SKILL.md。无宿主回调；Git guard 仍生效。

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

回退：直接阅读指导与 Skill。Supported Hosts。

Claude Code

根 CLAUDE.md、规范 .agents Skill 加 .claude/skills 副本。上下文 hooks 与受管只读白名单可选。

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

白名单减少提示，不是沙箱。Supported Hosts。

Codex

规范 .agents Skill，指导写在 AGENTS.md 或已存在的非空 AGENTS.override.md。上下文 hooks 写入 .codex/hooks.json。

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

在宿主 /hooks 复核中信任 .codex/ 层。Supported Hosts。

OpenCode

官方构建获得 AGENTS.md 入口与 .agents Skill；上下文 hooks 被拒绝。自定义 fork 可显式选用 Claude 兼容 hooks。

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

回退：重读指导并用有界 watch/inbox。Supported Hosts。

支持矩阵

每个宿主获得什么。

维护中的摘要见 Supported coding agents 与 Supported Hosts；以链接文档为准。

宿主	指导入口	Skill 发现	上下文 hooks	只读白名单	回退
`generic`	`AGENTS.md`	宿主读取 `.agents` 时用 `.agents/skills/specgit-native/SKILL.md`	无；declined	declined：无宿主权限配置	直接阅读指导与 Skill
Claude Code	`CLAUDE.md`	规范 `.agents` Skill 加 `.claude/skills/specgit-native/SKILL.md`	`.claude/settings.json` SessionStart/PreToolUse	`.claude/settings.json` `permissions.allow` 配 `--readonly-permissions`	重读指导与 Skill
Codex	`AGENTS.md`，或已存在的非空 `AGENTS.override.md`	规范 `.agents` Skill；从工作目录扫描到仓库根并读 `~/.agents/skills`	`.codex/hooks.json`；需宿主 `/hooks` 信任复核	declined：实验性审批与沙箱	重读指导与 Skill
OpenCode（官方）	`AGENTS.md`	`.agents` Skill；宿主还读项目 `.opencode/` 与 `.claude/` skills	无；declined	declined：默认放行，无可移植白名单	重读指导与 Skill；有界 `watch`/`inbox`
OpenCode 自定义 fork	`AGENTS.md`	同官方 OpenCode	`.opencode/hooks.json` 配 `inputFormat: claude-code`；需 `--agent opencode --opencode-claude-hooks` 加显式 hook 用途	declined	同官方 OpenCode

guard 是原生 Git pre-commit/pre-push 检查，不是宿主回调。它对每个宿主（含 generic）生效，通过 setup --hook-purpose guard 或 specgit guard --install 安装。上下文 hooks 只提示与提供上下文，绝不承载业务规则。

下载

签名的三平台发布。

原生 specgit CLI 仅通过 GitHub Releases 分发。最新稳定版提供：

macOS

specgit-<version>-darwin-arm64.zip

Linux

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

Windows

specgit-<version>-win32-x64.zip

安装前先校验

每个发布附带 SHA256SUMS 与 SHA256SUMS.sigstore.json。Cosign 签名覆盖 SHA256SUMS 从而覆盖 ZIP 字节；请另行交叉核对 tag 提交与原生构建工作流运行。见发布资产校验参考。

作为插件安装

插件只包含 specgit-native Skill 与引导；原生 CLI 仍来自 GitHub Releases。见插件安装指南。

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

# Codex：先添加市场，再在 /plugins 中浏览安装
codex plugin marketplace add LeXwDeX/SpecGit

# Pi、OpenCode 等仅支持 Skill 的宿主
specgit init
specgit skill --user

打开最新 release

文档

深入了解。

README：产品、安装与工作流→ Agent 安装与初始化→ 已安装 CLI 的项目维护→ 支持的编码 agent 与发现边界→ 发布资产校验参考→ 原生命令、配置与 JSON 契约→ SpecGit Skill 工作流→ 从 v1 迁移→ 发布流程与恢复→ 当前术语表→ 英文 Wiki→ 中文 Wiki→