sync

Tool availability:

• GitHub CLI (gh) for creating projects and issues
• Linear MCP (mcp__claude_ai_Linear__*) for creating Linear documents and issues
• Both support programmatic creation and updates

Sync architecture:

SPEC.md ──────→ Linear Document (PRD / Initiative)
TASKS.md ─────→ GitHub Issues ←──→ Linear Issues (bidirectional)
                     ↕
              GitHub Project Board

Linear has a native GitHub integration that handles bidirectional sync between GitHub Issues and Linear Issues. We don't need to build that — just configure it.

Also: Does a GitHub Project or Linear project already exist for this, or should I create new ones?"

AWAIT: User choice STORE: sync_targets, existing_project_ids

</step>

<step id="2" name="GitHub Projects Setup">

IF sync_targets includes GITHUB:

IF existing GitHub Project: VERIFY: Project exists and is accessible USE: existing project ID ELSE: CREATE project: gh project create --title "{Project Name}" --owner {user/org}

FOR each task in TASKS.md: CREATE GitHub Issue: gh issue create
--title "T{NNN}: {task title}"
--body "{task description with validation criteria}"
--label "{layer}"
--project "{project name}"

MAP dependencies:
  - Add "Depends on #X" in issue body for each dependency
  - Add labels for layer (foundation, core, feature, integration, polish)
  - Add labels for complexity (low, medium, high)

ORGANIZE project board: - Create columns/status fields: Backlog, Ready, In Progress, Review, Done - Place foundation tasks in "Ready" - Place dependent tasks in "Backlog" - Add priority field matching task execution order

REPORT: "Created {count} issues in GitHub Project: {project_url} Board organized by execution order with dependency tracking."

</step>

<step id="3" name="Linear Setup">

IF sync_targets includes LINEAR:

DETERMINE Linear team: Use mcp__claude_ai_Linear__list_teams to find available teams ASK user which team if multiple exist

CREATE Linear document from SPEC.md: Use mcp__claude_ai_Linear__create_document with: - Title: "{Project Name} — Product Specification" - Content: Contents of SPEC.md (converted to Linear-compatible format)

IF sync_targets is LINEAR_ONLY (no GitHub): FOR each task in TASKS.md: CREATE Linear issue: Use mcp__claude_ai_Linear__save_issue with: - Title: "T{NNN}: {task title}" - Description: task description + validation criteria - Priority: based on layer (foundation=urgent, core=high, feature=medium, polish=low) - Labels: layer name, complexity

REPORT: "Created SPEC.md as Linear document: {doc_url} {count} issues created in Linear project."

</step>

<step id="4" name="Bidirectional Sync Setup (GitHub ↔ Linear)">

IF sync_targets includes BOTH GitHub AND Linear:

EXPLAIN to user: "## Setting Up GitHub ↔ Linear Sync

Linear has a native GitHub integration that handles bidirectional sync.
Here's what to do:

**One-time setup (takes ~2 minutes):**

1. Go to Linear → Settings → Integrations → GitHub
2. Connect your GitHub account/organization
3. Select the repository for {project_name}
4. Configure sync settings:
   - ✅ Sync issues bidirectionally
   - ✅ Auto-create Linear issues from GitHub issues
   - ✅ Sync status changes (closing a GitHub issue closes the Linear issue)
   - ✅ Sync comments
   - ✅ Sync labels

**How it works after setup:**
- Issues created in GitHub → automatically appear in Linear
- Status changes in either tool → synced to the other
- Comments on GitHub issues → appear in Linear and vice versa
- Closing an issue in either place → closes it in both

**What this means for your workflow:**
- Claude Code updates GitHub Issues via `gh` CLI as tasks complete
- Those updates automatically flow to Linear
- You or collaborators can manage priorities in Linear's UI
- The senior dev in your accelerator can watch progress in Linear

Would you like me to walk you through the setup now, or do you want
to handle it later?"

IF user wants walkthrough now: Use browser automation tools to guide through Linear settings OR provide step-by-step with screenshots via Linear's docs

AWAIT: User confirms sync is configured

</step>