Project Sync

Bidirectional sync between Dev Flow conversations and project management tools. Supports Linear and GitHub Issues.

When to Use

•Pull tasks from Linear/GitHub into conversation
•Create issues from conversation context
•Update issue status when work is shipped
•Link commits to issues automatically
•View assigned tasks
•Triage and prioritize work

Supported Platforms

Platform	API	Features
Linear	GraphQL	Full CRUD, labels, cycles, projects
GitHub Issues	REST/GraphQL	Issues, PRs, labels, milestones
GitHub Projects	GraphQL	Project boards, custom fields

Input Handling

For Pull:

•platform: linear, github, or auto-detect
•filter: assigned, mentioned, team, project
•status: todo, in_progress, done, all

For Create:

•title: Issue title (auto-generated if not provided)
•description: Issue body (from conversation context)
•labels: Array of labels to apply
•assignee: Who to assign (defaults to current user)

For Update:

•issue_id: Issue identifier
•status: New status
•comment: Optional comment to add

Instructions

Configuration

Store credentials in ~/.claude/integrations/:

json

// ~/.claude/integrations/linear.json
{
  "api_key": "lin_api_xxx",
  "team_id": "TEAM_ID",
  "default_project": "PROJECT_ID"
}

// ~/.claude/integrations/github.json
{
  "token": "ghp_xxx",
  "owner": "username",
  "repo": "repo-name",
  "default_labels": ["dev-flow"]
}

Pull Tasks

From Linear

graphql

query AssignedIssues($userId: String!) {
  issues(filter: { assignee: { id: { eq: $userId } }, state: { type: { in: ["triage", "backlog", "unstarted", "started"] } } }) {
    nodes {
      id
      identifier
      title
      description
      state { name }
      priority
      labels { nodes { name } }
      project { name }
      cycle { name number }
    }
  }
}

From GitHub

bash

gh issue list --assignee @me --state open --json number,title,body,labels,milestone

Output Format (Pull)

markdown

## Your Tasks

### Linear (5 tasks)

| ID | Title | Status | Priority | Project |
|----|-------|--------|----------|---------|
| ENG-123 | Add dark mode toggle | In Progress | High | Capsule |
| ENG-124 | Fix checkout bug | Todo | Urgent | Capsule |
| ENG-125 | Update API docs | Backlog | Medium | Platform |

### GitHub (3 issues)

| # | Title | Labels | Milestone |
|---|-------|--------|-----------|
| #45 | Improve error messages | enhancement | v2.0 |
| #42 | Add retry logic | bug | v1.5 |
| #38 | Document webhooks | docs | - |

### Quick Actions

- `/sync start ENG-123` - Start working on task
- `/sync done ENG-123` - Mark as complete
- `/sync create` - Create issue from conversation

Create Issue

Auto-Generate from Conversation

When user says "create issue" or "track this":

•
Extract context:
- •Current thread goal
- •Key decisions made
- •Acceptance criteria discussed
- •Any code files mentioned
•
Generate issue:

markdown

## Title
[Extracted from thread goal]

## Description
**Context:** [Summary of conversation]

**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]

**Technical Notes:**
- [Any technical details discussed]

**Related Files:**
- `path/to/file.ts`

---
*Created via Dev Flow*
*Thread: [thread_id]*

•Create via API:

Linear:

graphql

mutation CreateIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    issue {
      id
      identifier
      url
    }
  }
}

GitHub:

bash

gh issue create --title "Title" --body "Body" --label "dev-flow"

Update Status

On Thread Completion

When a thread ships successfully:

•Check if linked to an issue
•Update status to "Done" / "Closed"
•Add completion comment with summary

Linear:

graphql

mutation UpdateIssue($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    issue { id state { name } }
  }
}

GitHub:

bash

gh issue close 45 --comment "Shipped via Dev Flow. Thread: abc123"

Link Commits

Auto-Link on Commit

When committing with issue reference:

•Parse commit message for issue IDs (ENG-123, #45)
•Add comment to issue with commit link
•Update issue status if keywords present (fixes, closes)

Commit Message Format:

code

feat: Add dark mode toggle

Implements ENG-123

- Added ThemeProvider
- Created toggle component
- Updated all color variables

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Auto-Comment on Issue:

markdown

🔗 Linked commit: abc1234

**Changes:**
- Added ThemeProvider
- Created toggle component
- Updated all color variables

*Committed via Dev Flow*

Required Output Sections

Task List

markdown

## Your Tasks

**Platform:** {{platform}}
**Filter:** {{filter}}
**Last Synced:** {{sync_time}}

### Active ({{active_count}})

{{#each active_tasks}}
#### {{identifier}} - {{title}}
- **Status:** {{status}}
- **Priority:** {{priority}}
- **Labels:** {{labels}}
- **Updated:** {{updated_at}}

{{/each}}

### Quick Actions
- Type `start {{first_task_id}}` to begin working
- Type `create issue` to track current work

Issue Created

markdown

## Issue Created

**Platform:** {{platform}}
**ID:** {{identifier}}
**URL:** {{url}}

### Details
- **Title:** {{title}}
- **Status:** {{status}}
- **Labels:** {{labels}}
- **Assignee:** {{assignee}}

The issue has been linked to this conversation.
When you ship, the issue will be automatically updated.

Status Updated

markdown

## Issue Updated

**{{identifier}}** → **{{new_status}}**

{{#if comment}}
**Comment Added:**
> {{comment}}
{{/if}}

{{#if linked_commit}}
**Linked Commit:** {{commit_sha}}
{{/if}}

Guardrails

•Never store API keys in conversation
•Verify issue exists before updating
•Don't auto-close issues without user confirmation
•Respect rate limits (Linear: 1500/hr, GitHub: 5000/hr)
•Handle API errors gracefully

Commands

/sync

code

/sync                     # Pull all assigned tasks
/sync linear              # Pull from Linear only
/sync github              # Pull from GitHub only
/sync start ENG-123       # Start working on task
/sync done ENG-123        # Mark task complete
/sync create              # Create issue from context
/sync link ENG-123        # Link current thread to issue
/sync status              # Show sync status

/issue

code

/issue create "Title"     # Quick create
/issue close 45           # Close issue
/issue comment 45 "msg"   # Add comment

Trigger Patterns

javascript

if (/(sync linear|sync github|pull tasks|create issue|link commit|update issue|what's assigned|\\/sync|my tasks|assigned to me)/i.test(objective)) {
  // Run project-sync
}

Integration

Dependencies:

•Linear API key (optional)
•GitHub CLI authenticated (optional)

Triggers:

•Auto-runs on thread completion (if issue linked)
•Auto-runs on commit (for linking)

Pairs With:

•launch-planner - Create issues from plans
•changelog-generator - Reference issues in changelog

Setup Guide

Linear Setup

•Generate API key at linear.app/settings/api
•Save to ~/.claude/integrations/linear.json
•Run /sync linear to test

GitHub Setup

•Run gh auth login
•Save config to ~/.claude/integrations/github.json
•Run /sync github to test

Version History

•v1.0.0: Initial release with Linear and GitHub support