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.
specsync idea "Thought" files a vague or elaborate idea as a GitHub issue in your ideas inbox; specsync ideas lists open intake. Graduate with specsync pull -issue <n>.
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 epic "Feature X" --repo org/planning --child org/backend#12 --child frontend-slug mints a coordination issue and wires every child — local change or existing issue, any repo — to it, idempotently.
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, checks that the openspec CLI dependency is installed and reachable, and recommends fixes.
-provider mcp projects changes through any external MCP server instead of gh — Linear, Jira, GitHub, or in-house. Speaks the current MCP spec with automatic fallback to legacy handshake-based servers.
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 now checks that the openspec binary is installed and reachable, reporting its path/version or a fix recommendation when missing; doctor install --json now also emits structured JSON. #132specsync epic <title> --repo owner/name --child ... mints a type:epic coordination issue and wires cross-repo children to it — local change slugs or existing issue references — idempotently. #100