OpenSpec × GitHub Issues
specsync projects your OpenSpec change specs into your issue tracker — automatically. Plan locally, sync once, collaborate everywhere. And when you ship, the changelog writes itself from the specs — in user language, never a commit dump.
How it works
Start from a local spec or an existing issue — specsync handles both directions and keeps them in sync as work progresses.
Spec-first
Author proposal.md and tasks.md locally. Run specsync once — the GitHub issue appears, body and checklist intact. No branch, no pre-existing issue required.
# Write your spec
mkdir -p openspec/changes/my-feature
# ... edit proposal.md and tasks.md ...
# Preview
specsync -dry-run -slug my-feature
# Create the issue
specsync -slug my-feature
created github.com/org/repo/issues/42Issue-first
When the issue already exists — created manually or via your backlog MCP — pull it. specsync materialises proposal.md and tasks.md from the issue body and caches the ref — the next push updates that same issue, never creates a duplicate.
# Pull issue #4083 into a local spec
specsync pull -issue 4083
specsync: pulled issue 4083 ->
openspec/changes/streamlined-modals/
+ proposal.md
+ tasks.md
# Refine locally, then push back
specsync -slug streamlined-modalsCross-repo
Large features span multiple repos. Use -repo to target any repo, then specsync link to cross-reference both. Each issue gets a ## Related section pointing to the sibling — maintained automatically on every push.
# Create issues in two repos
specsync -slug feature-api -repo org/api
specsync -slug feature-ui
# Cross-link them
specsync link feature-api feature-ui
linked feature-api <-> .../issues/89
linked feature-ui <-> .../issues/42
specsync link: 2 specs cross-linkedFeatures
specsync is a small, focused binary. No config file, no daemon, no SDK dependency — just gh under the hood.
Reads the git remote — no config required. Override with -repo owner/name for any other repo.
Re-run freely. An identity marker in the issue body prevents duplicates even if the ref cache is lost.
Not just GitHub. Project an OpenSpec change onto a Beads task graph with -provider beads — the WorkProvider interface keeps the tracker your choice.
specsync link writes links.md and pushes a Related section to both issues automatically.
Pull any existing issue into a local spec. The ref is cached so subsequent pushes update — never duplicate.
specsync scan shows what already exists for an area — in-flight changes, loose issues, recent commits — before you plan.
specsync release-plan reconstructs what shipped, what's loose, and an advisory bump — using OpenSpec requirement deltas as a release signal no commit-only tool can see.
A bundled skill installs for Claude Code, Codex, OpenCode, Copilot, or any agentskills.io-compatible .agents directory.
sync, pull, and link support -dry-run. Read-only inspection commands need no preview mode.
stage:active while work remains; auto-flips to stage:complete when all tasks are checked. Optional -close-completed keeps the issue open/closed state aligned — completion closes it, new work reopens it.
Checkboxes ticked in the GitHub issue merge back into your local tasks.md on the next sync — progress flows both ways, never lost in either direction.
specsync trace reconstructs how a change, its issue, PRs, and commits connect — every link backed by evidence (markers, branches, commit footers), never guessed.
Point -project owner/number at a GitHub Projects board: synced issues land on the board, Status follows the change lifecycle, and human curation is respected.
specsync changelog writes a Keep a Changelog section from your shipped changes — one entry per change, release notes authored at planning time, never a raw commit dump.
Changelog
Requires Node 16+ for the installer. The binary itself has no runtime dependencies.
Or install with Go: go install github.com/androidand/specsync/cmd/specsync@latest
Full documentation on GitHub →