Skip to content

dvy1987/agent-loom / .agents/skills/issue-sync

issue-sync

Verified

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.

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 eventTarget action
createCreate issue + append mapping
update statusUpdate mapped target status
closeClose 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

ExcuseReality
"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
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall