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.
specsync spinoff spawns a new linked change from a discovery, keeping the parent scoped and marking the source task as moved.
Run specsync -change 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 -change my-change -project my-org/6. Add -status-map "active=In Progress,complete=Done" to align board columns with change stages.
specsync resolves the target repository deterministically: -repo flag → gh repo set-default → origin. Fork-parent writes are refused by default; use -repo to override.
Board resolution per-repository: -project flag → openspec/specsync.yml → no board. No global default; each repo syncs only to its own declared board.
specsync resolves a change's issue from branch name (feat/42-my-change), issue marker, or ref cache — so pull without -issue and idempotent sync update the right issue instead of creating duplicates.
specsync agent-help provides command guidance without manuals. Use --json for machine-readable schema suitable for agents and automation.
specsync doctor detects and diagnoses AI agent skill installations (Claude Code, OpenCode, Copilot, etc.), analyzes token usage, and recommends optimizations.
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.
specsync audit cross-references archived changes against GitHub PRs to find archived-but-unmerged work. Add -mark-shipped to record the final lifecycle step.
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
specsync doctor command for diagnosing and optimizing Claude Code token usage. Run specsync doctor to see installation status, detect duplicate skills, and get personalized recommendations. Use specsync doctor --json for automation and scripting. #114specsync validate CI gate #64--repo to every gh invocation. Resolution order: -repo flag → gh repo set-default → origin. Fork-parent writes are refused by default; use -repo to override. Board resolution also gained a repository-local declaration: openspec/specsync.yml with board: owner/number. The -project flag and this config file are the only ways to set a board; the SPECSYNC_PROJECT env var is no longer used. #76specsync audit — a read-only command that cross-references archived OpenSpec changes against GitHub PRs to find archived changes whose PR was never merged. Also add a new shipped stage that represents the final step in the lifecycle: the PR has landed. #59