OpenSpec × GitHub Issues
specsync projects your OpenSpec change specs into your issue tracker — automatically. Plan locally, sync with one command, collaborate everywhere. And when you ship, the changelog writes itself from the specs — in user language, never a commit dump.
Example: running "specsync -slug my-feature" creates a GitHub label and issue for the my-feature OpenSpec change, then prints the new issue's URL and a one-line summary — "specsync: 1 created, 0 updated".
Why specsync
OpenSpec keeps plans and requirements in the repository. Teams still collaborate through GitHub issues and project boards. Maintaining both manually means duplicating intent and watching them drift apart. specsync makes them two views of the same work.
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.
specsync scan shows what already exists for an area — in-flight changes, loose issues, recent commits — before you plan.
Pull any existing issue into a local spec. The ref is cached so subsequent pushes update — never duplicate.
A bundled skill installs for Claude Code, Codex, OpenCode, Copilot, or any agentskills.io-compatible .agents directory.
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.
sync, pull, and link support -dry-run. Read-only inspection commands need no preview mode.
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.
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.
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.
specsync trace reconstructs how a change, its issue, PRs, and commits connect — every link backed by evidence (markers, branches, commit footers), never guessed.
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.
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.
Dogfooding proof
Every specsync issue is projected from an OpenSpec change. Here's one real example, end to end:
OpenSpec change
openspec/changes/archive/fix-completion-lifecycleProjected issue
specsync#29 — Fix completion lifecycleGenerated release note
v0.7.0 changelog entrySelf-contained binary for macOS and Linux. GitHub synchronization requires the authenticated GitHub CLI.
Or install with Go: go install github.com/androidand/specsync/cmd/specsync@latest
Full documentation on GitHub →
# Check prerequisites, install, then preview safely
gh auth status
npm install -g @androidand/specsync
specsync -dry-runChangelog
No spec-derived entries for this release.
No spec-derived entries for this release.
No spec-derived entries for this release.