| name | issue-sync |
| description | Mirror issues and status across issue trackers with stable external-ID mapping to avoid duplicates. Load when syncing GitHub and Linear issues, mirroring ticket status, or keeping two trackers in sync. Also triggers on "issue sync", "sync issues", "mirror issues to", "keep Linear and GitHub in sync", or bidirectional issue tracker updates. Requires API access on both sides — stops if credentials missing.
|
| license | MIT |
| metadata | {"author":"dvy1987","version":"1.0","category":"project-specific","sources":"ci-orchestrator Notifier pattern","resources":{"references":["SYNC-SCHEMA.md","examples.md"]}} |
Issue Sync
You mirror create/update/close events between source and target trackers using a stable external-ID map — no duplicate issues.
Hard Rules
Maintain mapping at .agent-loom/issue-sync-map.json — {source_id, target_id, status, last_synced_at}.
Never create a target issue without recording the mapping.
On update: look up mapping first; create only if absent.
Never store API tokens in repo — env vars only.
If either side credentials missing, list required env names and stop.
Workflow
Step 1 — Identify source and target
Example: GitHub → Linear, or Linear → GitHub. Confirm direction with user if ambiguous.
Step 2 — Load or init map
Read .agent-loom/issue-sync-map.json. Create {"mirrors":[]} if missing.
Step 3 — Fetch source changes
List open/recently updated issues since last_synced_at (or user-provided window).
Step 4 — Apply to target
| Source event | Target action |
|---|
| create | Create issue + append mapping |
| update status | Update mapped target status |
| close | Close mapped target |
Step 5 — Write map + summary
Persist updated mirrors. Emit sync report.
Gotchas
- Title-only matching causes duplicates — always use mapping file.
- Bidirectional sync needs conflict policy — default: source wins unless user says otherwise.
- Body HTML vs markdown may truncate — sync title + status + link back.
Output Format
## Issue sync — [source] → [target]
Created: N | Updated: N | Closed: N | Skipped (mapped): N
Map: `.agent-loom/issue-sync-map.json`
Errors: [none | list]
Examples
Teaser: 3 new GitHub issues → 3 Linear issues created with github:#42 in description.
Full pairs: references/examples.md
Common Rationalizations
| Excuse | Reality |
|---|
| "Match by title" | Titles change; duplicates multiply. |
| "Skip map file" | Next sync creates duplicates. |
| "Embed PAT in script" | Tokens leak from repo history. |
| "Sync everything ever" | Window by last_synced_at — incremental. |
| "Bidirectional without policy" | Conflicts will corrupt state. |
Verification
Red Flags
- New target issue without map entry
- API token in committed file
- Full resync without user request
Prune Log
Last pruned: 2026-07-05
- Initial release from high-leverage skill spec (Skill 3 family)
Impact Report
Issue sync: [src]→[tgt] | +N ~N -N | Map entries: N
