Spec-first
Plan locally, project outward
Start in openspec/changes/, define proposal and tasks, then sync to the tracker when the plan is ready.
OpenSpec × GitHub Issues
Plan in OpenSpec, sync to issues and boards, and ship from one source of truth. Start spec-first or pull an existing board issue and plan implementation tasks locally.
Dogfooded here: every shipped change traces from OpenSpec plan to issue to release notes.
How it works
specsync supports both entry points: spec-first and issue-first (from your issue tracker). Start from either side, keep OpenSpec as the source of truth, and synchronize issue tracker issues/boards as work evolves.
Spec-first
Start in openspec/changes/, define proposal and tasks, then sync to the tracker when the plan is ready.
Issue-first
Start from an existing issue tracker issue via specsync pull, refine locally, and keep issue plus board state aligned.
Features
specsync is a small CLI binary: no daemon, no SDK lock-in, and no mandatory central config file. In GitHub mode it uses gh, with flags and env vars controlling behavior.
Start from local proposal.md/tasks.md or pull an existing issue tracker issue with specsync pull.
specsync scan shows what already exists for an area — in-flight changes, loose issues, recent commits — before you plan.
Run specsync -slug my-change as often as needed. If the issue tracker issue already exists, specsync updates it (same identity marker) instead of creating a duplicate.
Set stage explicitly with specsync set-stage my-change [active|blocked|in-review|complete] so progress is visible and committed in metadata.
Set priorities (1-100) with specsync set-priority my-change 85. Agents respect priority when deciding what to work on next — humans direct focus.
Project and sync with specsync -slug my-change -project my-org/6. Add -status-map "active=In Progress,complete=Done" to align board columns with change stages.
specsync release-plan highlights shipped changes, loose/unlinked work, archive candidates, and advisory release impact from spec-level deltas.
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.
In practice
Project a local plan outward, or pull an existing issue inward — either way you end up in the same loop.
Repository Evidence
Not a staged demo — follow one real change, the v0.8.0 board projection, through every form it takes:
Changelog
-project owner/number (or $SPECSYNC_PROJECT) syncs an issue onto a GitHub Projects v2 board, maps the change's stage to the board's Status field, and assigns the acting viewer — unconfigured stays a complete no-op, zero board calls. #37pull — the ref-cache key is now repo-stable, and a legacy pre-fix cache entry can no longer be mistaken for a different repo's issue and edited by accident. #35