Getting Started

Getting Started

From zero to your first accepted delivery.

Prerequisites

• Node.js ≥ 20.19.0 (node --version)
• git — SpecGit only runs inside a git repository, at its root
• GitHub CLI gh authenticated for GitHub repos: gh auth login then gh auth status
• GitLab CLI glab ≥ 1.113.0, per-host authenticated, only for a declared self-managed GitLab origin: glab auth login --hostname <host>

Install

npm install -g specgit
specgit --version

(pnpm users: pnpm add -g specgit installs the same package globally.)

Verify the environment:

specgit doctor --json

doctor probes in order: git available → inside a repository → origin parses to a forge repository (or declared GitLab host) → the matching forge CLI present and authenticated → spec_git/policy.yaml exists. Exit 0 = all green; exit 3 names the failing probe and its fix.

Initialize (once per repository)

On the default branch:

specgit init
specgit setup        # install agent entry points (commands/skills)
specgit doctor       # all probes green?

specgit init creates the policy spec_git/policy.yaml — the required CI check names, auto-detected from your CI files — and generates the harness: the SpecGit Acceptance workflow (.github/workflows/specgit-accept.yml) and the managed agent block in AGENTS.md. For a self-managed GitLab origin add --gitlab-host <hostname>; the declaration persists to spec_git/providers.yaml. For Chinese generated text add --language zh. Commit the harness on a branch and open a PR.

# spec_git/policy.yaml
version: 1
required_checks:
  - "Build"

Your first delivery

# 1. One command bootstraps everything: issues, branch, draft PR, record
specgit issue "feat: add login flow"

# 2. Work on the created branch, push; CI runs on the PR,
#    including the SpecGit Acceptance job

# 3. When checks are green, gate the merge on evidence
specgit finish
# exit 0 → accepted (merge) · exit 1 → rejected (fix what it names) · exit 3 → cannot determine

Key facts:

• Each argument of specgit issue 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. Titles must match <type>: <english title> where <type> is one of feat, fix, refactor, perf, docs, test, chore, style, build, ci, revert, security, deprecate, dogfood.
• The branch is named <type>/<first-issue#>-<slug>; the draft PR body starts with Closes #n for every bound issue. Keep those closing references intact.
• Re-running specgit issue resumes idempotently after any mid-step failure.
• The record .specgit.yaml is committed on the delivery branch; context is always resolved from live git — never hand-edit it.
• If the PR binding is lost, specgit pr repairs it.
• specgit finish exit 0 is the only definition of done. A draft PR always fails (pr_draft) — mark it ready first.

---

快速开始

从零到第一次 accepted（验收通过） 的交付。

前置条件

• Node.js ≥ 20.19.0（node --version）
• git —— SpecGit 只在 git 仓库根目录内运行
• GitHub 仓库需要已认证的 GitHub CLI gh：先 gh auth login，再 gh auth status
• 仅当 origin 是声明过的自建 GitLab 时，需要 GitLab CLI glab ≥ 1.113.0 并按主机认证：glab auth login --hostname <host>

安装

npm install -g specgit
specgit --version

（pnpm 用户：pnpm add -g specgit 全局安装的是同一个包。）

验证环境：

specgit doctor --json

doctor 按顺序探测：git 可用 → 位于仓库内 → origin 能解析为 forge 仓库（或声明的 GitLab 主机）→ 对应的 forge CLI 已安装且已认证 → spec_git/policy.yaml 存在。退出码 0 = 全部通过；3 会指出失败的探测项及修复方法。

初始化（每个仓库一次）

在默认分支上：

specgit init
specgit setup        # 安装 agent 入口（commands/skills）
specgit doctor       # 探测全绿？

specgit init 创建策略文件 spec_git/policy.yaml（必需的 CI 检查名，从 CI 文件自动检测），并生成验收护栏：SpecGit Acceptance 工作流（.github/workflows/specgit-accept.yml）和 AGENTS.md 中的受管 agent 区块。自建 GitLab origin 请加 --gitlab-host <hostname>，声明会持久化到 spec_git/providers.yaml；需要中文生成文本请加 --language zh。把生成的文件提交到分支并开一个 PR。

第一次交付

# 1. 一条命令完成引导：创建 issue、分支、draft PR、记录文件
specgit issue "feat: add login flow"

# 2. 在创建的分支上工作并 push；CI 会在 PR 上运行，包括 SpecGit Acceptance 任务

# 3. 检查全绿后，用证据门禁验收
specgit finish
# 退出码 0 → accepted（可合并）· 1 → rejected（按提示修复）· 3 → 无法判定

要点：

• specgit issue 的每个参数都是一个可独立验证的 WHY：带引号的标题创建新 issue，纯数字复用已有 issue；N 个参数绑定 N 个 issue 到同一次交付。标题必须符合 <type>: <english title>，<type> 取 feat、fix、refactor、perf、docs、test、chore、style、build、ci、revert、security、deprecate、dogfood 之一。
• 分支命名为 <type>/<first-issue#>-<slug>；draft PR 正文以每个绑定 issue 的 Closes #n 开头，务必保留这些关闭引用。
• 中途失败后重新运行 specgit issue 会幂等地续跑。
• 记录文件 .specgit.yaml 提交在交付分支上；执行上下文始终从实际 git 状态解析，不要手工编辑。
• PR 绑定丢失时用 specgit pr 修复。
• specgit finish 退出码 0 是"完成"的唯一标准。Draft PR 必然失败（pr_draft），先标记为 ready。