Linear Sync Skill

Procedural knowledge for synchronizing Linear project data with PM workspace initiatives.

When to Use

• Running /sync-linear command

• Running /sync-dev for unified dev status

• Checking cycle progress for a team

• Mapping Linear issues to initiatives

• Generating dev activity reports

Prerequisites

Requires Linear MCP tools. Two options available:

Option 1: Dedicated Linear MCP

• linear_getTeams

• List teams

• linear_getProjects

• List projects

• linear_getActiveCycle

• Get current cycle

• linear_searchIssues

• Search issues by criteria

• linear_getProjectIssues

• Get issues for a project

Option 2: Composio MCP (composio-config)

Server: composio-config

The unified Composio MCP provides Linear tools with slightly different naming:

• LINEAR_LIST_LINEAR_TEAMS

• List teams

• LINEAR_LIST_LINEAR_PROJECTS

• List projects

• LINEAR_LIST_LINEAR_CYCLES

• List cycles

• LINEAR_SEARCH_ISSUES

• Search issues

• LINEAR_GET_LINEAR_ISSUE

• Get issue details

• LINEAR_CREATE_LINEAR_ISSUE

• Create new issues

• LINEAR_UPDATE_ISSUE

• Update issues

Note: The composio-config server also provides Slack, Notion, HubSpot, and PostHog tools (700+ total).

Data Sources

Linear Data

• Teams: ASK (Development), VAN (Vanguard), CEX (Core Experience), EPD (Product)

• Projects: Linked to initiatives via linear_project_id in _meta.json

• Cycles: Two-week sprints with progress tracking

• Issues: Work items with state, assignee, priority

Local Data

• pm-workspace-docs/initiatives/active/*/_meta.json

• Initiative metadata with Linear links

• pm-workspace-docs/signals/issues/

• Processed issue signals

• pm-workspace-docs/status/dev-status-*.md

• Development status reports

Initiative Mapping

Smart Inference Strategy (No Labels Required)

Reality check from 2026-01-23 audit: Explicit labels and prefixes have 0% adoption. Use what exists:

• Notion "Linear Link" - Projects DB has direct Linear project URLs

• Notion "Linear Epic" - Engineering Specs DB has Linear epic/issue URLs

• Issue titles & descriptions - Parse for initiative keywords

• Existing _meta.json mappings - Use established linear_project_id

• Smart inference - Match project names to initiatives

_meta.json Schema

{ "linear_project_id": "05066db9-89d7-432c-bffd-234ca92af024", "linear_project_url": "https://linear.app/askelephant/project/global-chat-05066db9", "notion_project_id": "abc123-def456", "dev_activity": { "last_synced": "2026-01-23T18:00:00Z", "linear_issues_total": 57, "linear_issues_completed": 23, "linear_issues_in_progress": 10, "github_prs_merged_30d": null } }

Mapping Priority (Smart Inference)

• Existing linear_project_id in _meta.json (100% confidence)

• Already mapped, use directly

• Notion Projects DB "Linear Link" (90% confidence)

• Cross-reference with notion-sync skill

• Extract project ID from URL

• Notion Eng Specs "Linear Epic" (80% confidence)

• Secondary Linear connection

• Look up issue → get project → map to initiative

• Project name → Initiative name match (70% confidence)

• "Global Chat" project → "internal-search" initiative (semantic match)

• Use keyword overlap scoring

• Issue title keywords (50% confidence)

• Parse issue titles for initiative-related terms

• Add to sync-queue.md for confirmation

Confidence Scoring

Signal Confidence

linear_project_id in _meta.json

100% (definite)

Notion "Linear Link" matches 90%

Notion "Linear Epic" resolves to project 80%

Project name ≈ initiative name 70%

Keyword overlap > 60% 50%

No match found 0% → sync-queue

Thresholds:

• ≥80%: Auto-map without confirmation

• 50-79%: Auto-map, note in sync report

• <50%: Add to sync-queue.md for user confirmation

Known Project-Initiative Relationships

These are established mappings (verified in _meta.json ):

PM Initiative Linear Project Notes

internal-search Global Chat Name differs - semantic relationship

crm-exp-ete CRM Agent Upgrades Direct match

call-import-engine Call & Data Imports Direct match

universal-signal-tables Universal Signals Direct match

hubspot-agent-config-ui HubSpot Integration Direct match

Unmapped Work Handling

When Linear issues/projects can't be mapped:

• Check if Notion project exists - May need /sync-notion first

• Suggest new initiative - If active Linear project has no PM tracking

• Add to sync-queue.md - For user decision

Unmapped Linear Project Detected

Project: "Mobile App v2" (ID: xyz789) Active Issues: 15 Last Activity: 2 days ago

No matching PM initiative found.

Options:

• [Create "mobile-app-v2" initiative]
• [Map to existing initiative: ___]
• [Skip - not PM-tracked work]

Sync Procedures

Step 1: Load Initiative Metadata

1. Glob all initiatives: pm-workspace-docs/initiatives/active/*/_meta.json
2. Extract linear_project_id from each
3. Build mapping: { project_id: initiative_slug }
4. Identify unmapped initiatives for suggestions

Step 2: Fetch Linear Data

For Cycle Sync (--cycle flag):

1. Call linear_getActiveCycle(teamId: "2b25052e-675d-4530-90c6-f2b6085d15e2")
2. Extract: cycle name, progress %, issue counts
3. Search issues in cycle with states: "In Progress", "In Review"

For Project Sync (--project [name] flag):

1. Find project by name or ID
2. Call linear_getProjectIssues(projectId)
3. Group by state: Todo, In Progress, Done

For Team Sync (--team [key] flag):

1. Get team ID from key (ASK, VAN, CEX, EPD)
2. Search all in-progress issues for team
3. Group by project → initiative

Step 3: Update Initiative Metadata

For each mapped initiative:

{ "dev_activity": { "last_synced": "2026-01-23T18:00:00Z", "linear_issues_total": <count>, "linear_issues_completed": <done_count>, "linear_issues_in_progress": <active_count>, "github_prs_merged_30d": null } }

Step 4: Generate Status Output

Cycle Progress Section:

Cycle Progress

Cycle 79 (Jan 13 - Jan 27)

• Progress: 28% (14/50 issues completed)
• In Progress: 10 issues
• In Review: 3 issues

By Initiative Section:

Work by Initiative

Global Chat

Linear Project: Global Chat

• Total Issues: 57
• Completed: 23 (40%)
• In Progress: 8

Active Work:

• ASK-4592: Global Chat first time experience (@Skylar)
• ASK-4477: New condensed chat input (@Skylar)

Unlinked Work Section:

Unlinked Work

Issues without initiative mapping:

• ASK-4583: BBL - Internal CLI POC (@Matt)
• ASK-4575: Engagement card re-design (@Adam)

Issue Signal Generation

When processing issues for signals (/ingest issue ):

Signal Output Format

Issue: [Issue Key] - [Title]

Date: YYYY-MM-DD Source: Linear Project: [Project Name] Assignee: [Name] State: [State]

Summary

[Issue description summary]

Work Type

• Bug fix
• Feature
• Improvement
• Tech debt

Initiative Link

Mapped to: [initiative-slug] (via project)

Labels

[List of labels]

Related Issues

[Parent, blockers, related]

Save Location

pm-workspace-docs/signals/issues/YYYY-MM-DD-[issue-key].md

Team Reference

Team Key ID Focus

Development ASK 2b25052e-675d-4530-90c6-f2b6085d15e2 Core development

Vanguard VAN 51c213c2-9404-4fc8-846a-22c456fc2691 Experimental features

Core Experience CEX ab724e37-e2b5-48a2-91dd-cfb11d648e09 UX/UI polish

Product EPD ff631bc1-8b68-4900-937f-969fe4a3b532 Product direction

Output Formats

Dev Status Report

Save to: pm-workspace-docs/status/dev-status-YYYY-MM-DD.md

Development Status Report

Generated: YYYY-MM-DD HH:MM Cycle: Cycle 79 (28% complete)

Summary

Cycle Progress

[cycle details]

Work by Initiative

[per-initiative breakdown]

Unlinked Work

[issues without mapping]

Team Activity

[per-team breakdown if requested]

JSON Output (--json flag)

{ "generated_at": "ISO8601", "cycle": { "name": "Cycle 79", "progress": 28, "total_issues": 50, "completed": 14 }, "by_initiative": [ { "slug": "global-chat", "linear_project_id": "...", "issues_total": 57, "issues_completed": 23, "issues_in_progress": 8, "active_issues": [...] } ], "unlinked_issues": [...], "team_summary": {...} }

Error Handling

No Linear Access

⚠️ Linear MCP tools not available.

Ensure Linear integration is configured in MCP settings.

No Mapped Initiatives

ℹ️ No initiatives have linear_project_id configured.

Suggest mappings:

• universal-signal-tables → Universal Signals (978cd60b...)
• call-import-engine → Call & Data Imports (f4f924a8...)

Run /sync-linear --map to configure mappings.

Project Not Found

⚠️ Linear project not found for initiative: [name]

The linear_project_id in _meta.json may be invalid. Current ID: [id]

Run /sync-linear --verify to check all mappings.

Integration Points

After Sync

• Update _meta.json dev_activity for each initiative

• Update signals/_index.json if issues were ingested

• Generate dev status report

With Notion Sync

• Primary: Use Notion "Linear Link" from Projects DB for mapping

• Secondary: Use Notion "Linear Epic" from Eng Specs for validation

• Cross-reference: If Linear project found but no Notion link, suggest adding in Notion

• Notion phase → Initiative phase updates

With Portfolio Status

• portfolio-status skill reads dev_activity from _meta.json

• Include dev progress in artifact matrix

• Surface initiatives with high activity but stale docs

With GitHub Sync

• Combined in /sync-dev command

• Correlate Linear issues with PR references (via ASK-XXXX in branch names)

• Build complete work-to-ship pipeline view

With Sync Queue

• Ambiguous mappings → add to sync-queue.md

• User confirms/rejects → update _meta.json

• New Linear projects → suggest initiative creation

Bidirectional Sync (Enhanced)

Sync Commands

Command Direction Description

/sync-linear

Linear → PM Pull Linear data into PM workspace

/sync-linear --push

PM → Linear Push initiative data to Linear (create/update)

/sync-linear --full

Bidirectional Full sync both directions

/sync-linear --labels

PM → Linear Create/update workflow labels

Push to Linear (--push )

Creates or updates Linear projects from PM workspace initiatives:

• Read all _meta.json files with priority P0 or P1

• For each initiative without linear_project_id :

• Create Linear project with same name

• Set description from PRD summary

• Create "Release Criteria" issue from template

• For each initiative with linear_project_id :

• Update project status/priority if changed

• Sync blockers to Linear issues

Workflow Labels

The following labels exist in Linear Development team:

Label ID Purpose

workflow/needs-prd

1bb0f920-3bc3-4f44-97a6-c010fabe7083

PM work required

workflow/needs-design

905ec3cd-e8c4-49e5-9e13-9fcb6c9f3d6a

Design work required

workflow/needs-eng-spec

42efd000-50b9-4e5d-883e-b70193dc9c23

Engineering spec required

workflow/needs-decisions

2f77b3aa-333c-4388-b77b-af18f0737d31

Open questions blocking progress

workflow/ready-to-build

81299a18-f7cd-454c-91f6-e6c2651b56b6

All inputs ready, passes Ivan Test

workflow/in-review

9cb83f70-f260-4451-ae6a-e127d6f7b34d

Stakeholder review needed

workflow/blocked

615742cf-d765-4359-a090-cab7e3dda246

External blocker

MCP Tools for Sync

Tool Purpose

LINEAR_CREATE_LINEAR_PROJECT

Create new project

LINEAR_UPDATE_LINEAR_PROJECT

Update project status/priority

LINEAR_CREATE_LINEAR_ISSUE

Create release criteria issue

LINEAR_UPDATE_ISSUE

Update issue labels/status

With Team Dashboard

• /sync-linear updates data for /team command

• Share mappings and project IDs

• Avoid duplicate MCP calls