Issue specifications → code changes → native PR/MR → verified completion.
SpecGit gives coding agents a shared delivery workflow for GitHub and GitLab. Issues hold the specification. A PR or MR gathers the selected Issues and the implementation. SpecGit reads the forge's current state so the agent can repair failures and distinguish pending work from completed delivery.
The runtime architecture describes module ownership, program checks and agent guidance.
Open your coding agent in the repository you want to use with SpecGit, then paste:
Read https://raw.githubusercontent.com/LeXwDeX/SpecGit/main/docs/agent-install.md
and carry out the installation and initialization described there for this machine
and the current repository. Install the latest stable SpecGit ZIP from GitHub
Releases, verify its signature and SHA-256, extract it, initialize the project with specgit init, and configure the
integration for the agent running this task. Use manual observation when required by
detected capabilities and preserve other settings. Installation and enablement delegate
the SpecGit workflow required for this project and task; carry it through without asking
again at each step. Use repository and agent context already available; ask only when
a task decision or real blocker requires user input. Finish the
installation and verification, rather than only giving me commands to run.
If the document is inaccessible, retrieve it through my authenticated gh session
or report the access problem; do not guess its contents.
The agent installation document covers signatures, checksums, PATH, existing installations, project initialization and agent registration. It works with Codex, Claude Code and OpenCode through their supported integrations; other agents can use the CLI and project guidance directly.
SpecGit is distributed only through GitHub Releases as native macOS arm64,
Linux x64 glibc and Windows x64 ZIP packages, accompanied by SHA256SUMS and its
Sigstore signature bundle. End-user installation needs no Node.js,
npm or Rust compiler. Repository work needs Git and an authenticated gh or glab.
For installation without an agent, see the manual guide.
From 2.6 on, specgit update upgrades the shared executable from GitHub Releases
with the same signature and checksum verification and keeps a backup.
Use the project maintenance guide, not the first-install
procedure. Open your Agent in the target repository and copy its
English request or
中文请求. The request asks the Agent to
actually inspect and apply safe local maintenance, with a separate verified stable
CLI update when needed. It preserves project settings and checkpoints. Manual
observation sets native_auto_merge=false; preserve configured preferences unless a
specific change is required by the task. Setup refresh includes all recorded hosts, not only the
--agent selection. Ordinary refresh omits purposes and reviews every host's effects.
Enablement delegates task-related Issue, implementation, verification, commit/push,
PR/MR, review, merge and closure work. Publication is included only when the task
itself includes release work. A declaration or old receipt cannot expand task scope.
| Stage | What happens |
|---|---|
| Specify | Put larger goals in a Milestone; create/select complete Issues for independently verifiable outcomes. |
| Implement | The agent changes code, runs the relevant checks, commits and pushes. |
| Propose | SpecGit creates or adopts a native PR/MR and preserves the Issue references. |
| Observe | SpecGit reports current checks and lifecycle state; the agent repairs failures. |
| Complete | The forge confirms the merge and associated Issue closures. |
One Issue represents one independently verifiable need. Split larger goals by outcome and dependency, not implementation step. TDD and PR Actions/CI follow-up are strongly recommended; project and platform requirements still govern. Work interrupted by a tool or network failure can be resumed by reconciling the exact native objects and saved intent.
After initialization, a typical delivery uses existing Issue numbers:
git switch -c feat/selected-specs
specgit issue 21 22 --dry-run --json
specgit issue 21 22 --json
# Implement, verify, commit and push the actual changes.
specgit pr --title 'feat: implement selected specs' --body-file request.md --dry-run --json
specgit pr --title 'feat: implement selected specs' --body-file request.md --json
specgit pr --status --json
specgit pr --ready --request 42 --dry-run --json
specgit pr --ready --request 42 --json
specgit watch --request 42 --session task-42 --goal lifecycle --json
# After platform review and merge, re-read the native request and Issues:
specgit pr --status --request 42 --jsonReplace the example IDs with real Issues and the resulting request number.
Previews do not authorize later writes by themselves; task enablement delegates the
required workflow within its scope. A branch without pushed changes remains pending;
SpecGit does not create an empty delivery just to attach a PR. Marking ready, review
and merge happen within that delegation on GitHub or GitLab; watch observes current evidence but does not perform
review, merge, or Issue closure. After merge, verify the native request and every
associated Issue with the explicit status read above.
For a read from another checkout, use specgit pr --status --request <id>; it
reports same-repository native state and a separate local-applicability result.
Implicit lookup and watch remain bound to the current worktree.
The agent implements and repairs. GitHub or GitLab owns checks, review rules,
merge and ordinary Issue closure. SpecGit's Rust core, watch and hooks cannot
merge requests, close Issues, delete branches or administer repository settings.
An authorized agent can use the native gh / glab operations for those actions.
A successful read can report failed CI. Exit zero means the requested operation succeeded; it does not mean a delivery is accepted or merged. Missing evidence stays unknown. A merged request with open or uncertain Issues is not complete. Auto-merge preferences do not grant permission to change native protections.
Project integration remains project-only. Run specgit init in every clone
and worktree because the declaration, Skill and private records are local; it
installs the common project Skill and stable guidance entry points. Those entry points direct agents to the Skill and to the official install
guide when the shared CLI is missing; with the CLI installed, use specgit init
to recover local project state. Initialization does not install host hooks. Run
specgit setup only when selecting a host integration; it refreshes the recorded
host assets and hooks for the current project. Setup never copies the executable
into a project or scans other repositories. Hooks invoke the shared user-installed
executable. The 2.3 global integration scope and its --root,
--provider, --api-host, --register-* and per-host root/settings options
are removed; watch, hook and inbox state is always Git-private. A custom
OpenCode fork can opt in to claude-code-format project hooks with the explicit
--opencode-claude-hooks choice (requires --agent opencode); official
OpenCode keeps the skill and guidance only. Refresh migrates recorded, uniquely
owned legacy guidance blocks; unknown ownership or damaged/duplicate markers
remain conflicts. Manual text outside managed blocks is preserved. Registration
is reported separately from actual host discovery or event delivery; a reload,
a host trust review (Codex /hooks), or another turn may be needed to verify the
host. Coordinated removal
of a whole project's SpecGit integration is the separate specgit remove command (preview,
digest-bound apply, offline rollback), introduced in the 2.3 runtime contract;
project-scope --uninstall covers only the recorded agent assets.
The only user-level asset is the explicitly installed Skill file; no global
hooks, state or receipts. To opt in, preview specgit skill --user --dry-run --json,
then run specgit skill --user --json. It owns only
~/.agents/skills/specgit-native/SKILL.md (Windows uses %USERPROFILE%) with a
transaction backup for recovery. --remove keeps user edits and
foreign files; --refresh-only skips missing or foreign files. After a successful
update, the new executable refreshes an already managed user Skill, never
installs one by default. Refresh failure retains the binary and reports the
remedy specgit skill --user. Project Skill refresh remains separate.
Upgrading from 2.3 refreshes existing project receipts in place (the 2.4
receipt omits shared_root) without reading or writing the retired global
root. Existing 2.3 global data is preserved; 2.4 ships no global cleanup
command — back up first and use the 2.3 CLI's exact owned cleanup before
upgrading if that data must go, never a blind delete.
Host integration uses SessionStart for brief rules and the Skill entry, and
PreToolUse for relevant context or recovery. It does not gate ordinary edits.
specgit guard --install adds owned pre-commit and pre-push blocks
to the effective native/custom hook path, including Husky user scripts, and
--uninstall removes only those blocks. The installed pre-push block buffers
and replays Git's standard ref stdin for the existing user hook.
After CLI upgrades, use the project maintenance guide
to verify the executable selected by PATH and refresh the existing project and host
integration. Omit hook purposes to preserve recorded modes; explicit purposes affect
all recorded and newly selected hosts. Review the effects for every affected host.
Only SessionStart and PreToolUse are supported; use bounded watch/inbox where
automatic observation is unavailable. The current runtime is 2.13.0. After project updates, run status and doctor, read back
the generated Skill/guidance, then repeat dry-runs to check convergence.
For a v1 project, follow the v1 → v2 migration guide before
replacing its declaration or lifecycle workflows. finish, accept, bind and
the old acceptance controller are retired in the native v2 CLI. Binary installation
alone does not migrate a repository. Use the migration guide for a v1 project's
repository-specific cutover; retired v1 command workflows are no longer maintained.
- Agent installation and initialization
- Installed-CLI project maintenance — English / 中文 Agent requests
- Supported coding agents and delivery flow
- Manual installation
- Native commands, configuration and JSON contract
- Migration from v1
- Release procedure and recovery
- Runtime development
- Current glossary
- English / 中文 Wiki
- Documentation audit and source inventory
The runtime lives in runtime/; its pinned Rust toolchain builds the executable.
The v1 TypeScript implementation and its test/build workflows are retired.
The private root Node workspace contains only repository verification tooling.
pnpm install --frozen-lockfile --ignore-scripts
pnpm test
node scripts/ci-metadata-check.mjs
cd runtime
cargo fmt --all --check
cargo clippy --locked --all-targets --features test-fixtures -- -D warnings
cargo test --locked --all-targets --features test-fixturesThe Release workflow runs from main after
an explicit dispatch with a stable version. GitHub-hosted standard Linux/Windows x64
and macOS ARM64 runners compile and smoke-test the native binaries. The final job creates ZIPs and signs SHA256SUMS
using the main Release workflow identity. Publication verifies source identity, signature, SHA-256 and
uploaded bytes, and preserves existing immutable releases. Full source and
installed-binary regressions run in ordinary CI.
See CI scope for current checks. The installed CLI help/schema and native command reference define current behavior; dated design records preserve rationale rather than release status.