> **RFC — discuss, do not implement yet.** Goal: explore *how* Workgraph mirrors > or syncs with the systems teams already live in (Notion, GitHub, Linear, …). ## Motivation `workgraph import github` already pulls issues into `triage` (one-way, idempotent by `source_ref`). But people also want the reverse and the ongoing case: reflect Workgraph items into Notion/GitHub, and keep them roughly in step — without Workgraph pretending to be Linear/Jira (an explicit non-goal). ## Questions to answer - **Source of truth.** Workgraph stays authoritative for *its* objects; the external system stays authoritative for *its*. So this is **mirroring with provenance**, not shared ownership. Agreed? - **Which systems first.** GitHub (issues/PRs) and Notion are named. Linear? Each needs an adapter with the same shape. - **Push model.** On `item.*` events, upsert a mirror (Notion page / GitHub issue) keyed by `source_ref`. Store the external id back on the item for idempotency. - **Sync-back.** If the mirror changes (someone edits the Notion page), do we pull status/comments? The V0 spec deferred two-way sync — start export-only? - **Conflict & drift.** Detect when the mirror diverged; surface as attention (`external_drift`) rather than silently overwriting. - **Secrets/rate limits.** Adapters need tokens (never in Git) and backoff. ## Sketch ``` workgraph mirror notion --item ITM-… # create/update a Notion page workgraph mirror github --project PRJ-… # push open items as issues workgraph mirror status # show drift as attention ``` Adapters live behind a small interface (`Upsert(obj) -> externalRef`, `Fetch(externalRef) -> state`) so new systems are additive. ## Cross-cutting Same atomicity problem as memory: "commit item **and** upsert Notion page" must be recoverable if the second half fails. Defer to the atomic cross-system RFC. ## Non-goals - Replacing GitHub Issues for public collaboration or Linear/Jira for teams. - Real-time bidirectional sync in a first cut.