issue-sync

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

SKILL.md

GitHub

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

  • Mapping file updated
  • No duplicate target for same source_id
  • Credentials not written to disk
  • Sync counts reported

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