OpenSpec × GitHub Issues

The issue is the spec.
The changelog is the spec history.

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.

$ npm install -g @androidand/specsync

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

Specs and issues shouldn't be two jobs.

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

Two flows. One source of truth.

Start from a local spec or an existing issue — specsync handles both directions and keeps them in sync as work progresses.

Spec-first

Write the plan, create the issue

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/42

Issue-first

Pull an existing issue into a spec

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-modals

Cross-repo

Link issues across repositories

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-linked

Everything a spec needs. Nothing it doesn't.

specsync is a small, focused binary. No config file, no daemon, no SDK dependency — just gh under the hood.

Plan

Auto-detect repo

Reads the git remote — no config required. Override with -repo owner/name for any other repo.

Planning scan

specsync scan shows what already exists for an area — in-flight changes, loose issues, recent commits — before you plan.

Issue-first pull

Pull any existing issue into a local spec. The ref is cached so subsequent pushes update — never duplicate.

Agent-friendly

A bundled skill installs for Claude Code, Codex, OpenCode, Copilot, or any agentskills.io-compatible .agents directory.

Collaborate

Idempotent

Re-run freely. An identity marker in the issue body prevents duplicates even if the ref cache is lost.

Tracker-agnostic

Not just GitHub. Project an OpenSpec change onto a Beads task graph with -provider beads — the WorkProvider interface keeps the tracker your choice.

Cross-repo linking

specsync link writes links.md and pushes a Related section to both issues automatically.

Preview writes

sync, pull, and link support -dry-run. Read-only inspection commands need no preview mode.

Two-way reconcile

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.

Projects boards

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.

Ship

Auto-lifecycle

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.

Traceability

specsync trace reconstructs how a change, its issue, PRs, and commits connect — every link backed by evidence (markers, branches, commit footers), never guessed.

Release follow-up

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.

Spec-driven changelog

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

specsync manages its own repository.

Every specsync issue is projected from an OpenSpec change. Here's one real example, end to end:

Generated release note

v0.7.0 changelog entry

Get started

Self-contained binary for macOS and Linux. GitHub synchronization requires the authenticated GitHub CLI.

$ npm install -g @androidand/specsync

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-run

Changelog

Recent releases

v0.7.0 Jul 14, 2026

No spec-derived entries for this release.

View complete release details on GitHub →
v0.6.0 Jul 14, 2026

No spec-derived entries for this release.

View complete release details on GitHub →
v0.5.1 Jul 13, 2026

No spec-derived entries for this release.

View complete release details on GitHub →