# Sync

> sw:sync — external tracker sync

- Skill: `anton-abyzov/sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add anton-abyzov/sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anton-abyzov/sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: anton-abyzov (https://skillmd.com/u/anton-abyzov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/anton-abyzov/sync

---


# sw:sync — external tracker sync

Everything goes through the CLI. Never call `gh`, `curl`, or a provider REST API
directly: the CLI owns token resolution, the rate budget, duplicate detection and
the bidirectional links.

## Commands

| Intent | Command |
|---|---|
| Push local progress to issues | `specweave sync push [increment-id]` |
| Preview a push | `specweave sync push <id> --dry-run` |
| Push to one provider | `specweave sync push <id> --provider github` |
| Fix stale/duplicate milestones first | `specweave sync push <id> --reconcile` |
| Report external changes | `specweave sync pull [--since 7]` |
| Import issues as increments | `specweave sync pull --create-increments` |
| Tokens, health, retry queue, gaps | `specweave sync status [--json]` |
| Connect a provider | `specweave sync setup [--provider github]` |
| Validate an existing config | `specweave sync setup --validate` |

`sync push` runs tasks.md → spec.md ACs → living docs → provider write, then
drains the retry queue through the same entry point. Exit code of
`sync status` is 1 when anything needs attention; `--json` prints one parsable
report (`providers`, `github`, `health`, `resilience`, `gaps`, `hasIssues`).

Not sync: `specweave doctor --fix-status` repairs metadata.json ↔ spec.md status
desyncs, and `specweave sync-living-docs` regenerates internal living docs.

## Providers

Read the provider from `.specweave/config.json` (`sync.github` / `sync.profiles`);
never guess. GitHub is the first-class path. **Jira and Azure DevOps are
community-maintained**: push and close work, nothing else is guaranteed — say so
before promising Jira/ADO behaviour.

Tokens resolve in one documented order: `.specweave/config.json` → `process.env`
(`GITHUB_TOKEN`, then `GH_TOKEN`) → project `.env` → `gh auth token`.
`sync status` prints which layer and which account won. A 404 on write means the
token's account has no write access to `owner/repo` — fix the token, do not retry.

Concept mapping tables: `plugins/specweave/reference/{github,jira,ado}/*-specweave-mapping.md`.

## Bidirectional links (required both ways)

- Local → external: the issue key lives in `metadata.json` under `externalLinks`.
- External → local: the issue body carries the increment id and the commit sha.

If either side is missing after a push, the link is broken — re-run
`specweave sync push <id> --force` rather than editing the issue by hand.

## Rules

1. Push after tasks change, not on every edit.
2. Never edit `externalLinks` by hand.
3. `--dry-run` first when the increment has never synced.
4. Report `sync status` output verbatim when it reports issues; do not paraphrase
   token or permission errors.