One-Way Sync Implementation (Local Docs → Linear)

[mateicanavra]

One-Way Sync Implementation

Implement the core sync engine that pushes local Markdown issue docs to Linear.

Goal

Enable AI agents and developers to edit issue docs locally (using familiar file operations) and have those changes automatically reflected in Linear.

Scope

In scope:

• Parse local issue docs with frontmatter
• Resolve field lookups (state/label/project names → UUIDs)
• Create new issues in Linear for LOCAL-TBD docs
• Update existing issues when content changes
• Write back sync metadata to local files

Out of scope (for now):

• Linear → Local sync (bidirectional)
• Real-time file watching
• Conflict resolution
• Project/document sync (issues only)

Architecture

docs/projects/<slug>/issues/*.md
        ↓
   [Parser Module]
   - gray-matter frontmatter
   - [SYNC] body extraction
   - Change detection (hash)
        ↓
   [Lookup Resolver]
   - Cache state/label/project UUIDs
   - One-time API calls per sync run
        ↓
   [Sync Engine]
   - Create vs Update decision
   - Linear SDK calls
   - Write-back to local files
        ↓
   [CLI Entrypoint]
   - bun run linear:sync
   - --project filter
   - --dry-run mode

Tech Stack

• Runtime: Bun
• API: @linear/sdk (TypeScript SDK)
• Parsing: gray-matter for frontmatter
• Hashing: Node crypto (built-in)

API Constraints

• Rate limit: 1,500 requests/hour (per user)
• Complexity: 250,000 points/hour
• Endpoint: https://api.linear.app/graphql
• Auth: Personal API key via LINEAR_API_KEY env var

Sub-Issues

This parent tracks the overall implementation. See child issues for specific deliverables:

1. Parser module (frontmatter + body extraction)
2. Lookup resolver (name → UUID caching)
3. Sync engine (create/update logic)
4. CLI entrypoint (bun command)
5. Post-tool hook trigger (deferred)

Success Criteria

• bun run linear:sync --project <slug> syncs all issues in that project
• New issues created in Linear for LOCAL-TBD docs
• Existing issues updated when content changes
• Local files updated with linear_id, synced_at, linear_url
• Dry-run mode shows what would sync without making changes