speckit.linear.sync

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

1. Validate prerequisites:

   • Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
   • Parse FEATURE_DIR and verify tasks.md exists
   • Load .specify/linear-mapping.json for task-to-issue mapping

2. Determine sync direction:

   • --to-linear: Push tasks.md status → Linear (default)
   • --from-linear: Pull Linear status → tasks.md
   • --bidirectional: Merge both (Linear wins on conflicts)

3. Fetch current state from both sources:

   From tasks.md:

   • Parse each task's completion status [x] vs [ ]
   • Extract task IDs and descriptions

   From Linear (using mapped issue IDs):

   • Fetch each issue's current status
   • Map Linear status to completion:

     Linear Status	tasks.md
     Done, Completed, Closed	[x]
     In Progress	[ ] (with note)
     Todo, Backlog	[ ]
     Canceled	[-] (skipped)

4. Detect changes and conflicts:

   Sync Analysis:
   
   | Task | tasks.md | Linear | Action |
   |------|----------|--------|--------|
   | T001 | [x] | In Progress | → Update Linear to Done |
   | T002 | [ ] | Done | ← Update tasks.md to [x] |
   | T003 | [x] | Done | ✓ In sync |
   | T004 | [ ] | Todo | ✓ In sync |
   

5. Apply changes based on direction:

   --to-linear (default):

   • For each task marked [x] in tasks.md:
     • Update Linear issue status to "Done"
   • For tasks marked [ ]:
     • If Linear shows "Done", warn about potential regression

   --from-linear:

   • For each Linear issue marked "Done":
     • Update tasks.md to [x]
   • For issues "In Progress":
     • Add comment to task: <!-- In Progress in Linear -->

   --bidirectional:

   • Linear status takes precedence on conflicts
   • Update both systems to match

6. Update tracking metadata:

   • Update .specify/linear-mapping.json with sync timestamp:

     {
       "last_sync": "2025-01-15T14:30:00Z",
       "sync_direction": "bidirectional",
       "changes_applied": 3
     }