sync-backlog

name	sync-backlog
description	Sync sprint backlog from architecture blueprint to project management tools (Linear, Jira, GitHub Issues, Asana, ClickUp). Creates issues/tasks with user stories, acceptance criteria, priorities, and sprint assignments.

Backlog Sync Tool

Push your architecture blueprint's sprint backlog to project management tools for immediate sprint planning and development.

Perfect for: Sprint planning, team collaboration, task tracking, agile workflows

---

When to Use This Skill

Use this skill when you need to:

• Start sprint planning immediately after blueprinting
• Share tasks with development team in their preferred tool
• Track progress against architecture plan
• Sync blueprint updates with existing project board
• Export backlog for clients or stakeholders
• Integrate architecture planning with agile workflow

Input: Architecture blueprint (Section 15: Sprint Backlog) Output: Issues/tasks created in Linear, Jira, GitHub, Asana, or ClickUp

---

Supported Platforms

1. Linear (Recommended for Startups/Agencies)

Why Linear:

• Best developer experience (keyboard shortcuts, fast UI)
• Excellent GitHub integration
• Built-in roadmaps and cycles
• Free for small teams (<10 members)

What's Created:

• Projects: One per sprint (Sprint 0, Sprint 1, etc.)
• Issues: Each user story becomes an issue
• Labels: Priority (High/Medium/Low), Type (Feature/Bug/Tech Debt)
• Estimates: Story points from blueprint
• Assignees: Can auto-assign or leave unassigned
• Cycles: Map sprints to Linear cycles (2-week sprints)

API Requirements:

• Linear API key (get from: https://linear.app/settings/api)
• Team ID
• Workspace ID (auto-detected)

2. GitHub Issues (Recommended for Open Source)

Why GitHub Issues:

• Free and unlimited
• Integrated with code repository
• Familiar to all developers
• Works with GitHub Projects for boards

What's Created:

• Milestones: One per sprint
• Issues: Each user story becomes an issue
• Labels: Priority, Sprint, Type
• Projects: Optional - create GitHub Project board
• Assignees: Can auto-assign to repo collaborators

API Requirements:

• GitHub personal access token (classic or fine-grained)
• Repository name (e.g., owner/repo)

3. Jira (Recommended for Enterprise)

Why Jira:

• Industry standard for enterprise
• Advanced workflow customization
• Comprehensive reporting
• Integrates with Confluence, Bitbucket

What's Created:

• Epics: One per major feature area
• Stories: Each user story becomes a Jira story
• Sprints: Map blueprint sprints to Jira sprints
• Story Points: From blueprint estimates
• Labels: Priority, Component, Type

API Requirements:

• Jira Cloud instance URL (e.g., yourcompany.atlassian.net)
• Email address
• API token (get from: https://id.atlassian.com/manage-profile/security/api-tokens)
• Project key (e.g., PROJ)

4. Asana (Recommended for Non-Technical Teams)

Why Asana:

• Simple, visual interface
• Great for cross-functional teams
• Timeline view for planning
• Free for basic features

What's Created:

• Projects: One per sprint
• Tasks: Each user story becomes a task
• Sections: Group by feature area
• Tags: Priority, Sprint, Type
• Custom Fields: Story points, status

API Requirements:

• Asana personal access token
• Workspace ID
• Project ID (or create new project)

5. ClickUp (Recommended for Agencies)

Why ClickUp:

• All-in-one (tasks, docs, chat, goals)
• Highly customizable
• Great for client projects
• Free tier is generous

What's Created:

• Lists: One per sprint
• Tasks: Each user story
• Custom Fields: Story points, priority, sprint
• Tags: Feature area, type
• Assignees: Team members

API Requirements:

• ClickUp API token
• Space ID
• List ID (or create new list)

---

How It Works

Step 1: Parse Sprint Backlog from Blueprint

Extract from Section 15: Sprint Backlog:

## Sprint 0: Project Setup & Infrastructure (Week 1)

**Goal**: Production-ready foundation

### User Stories

#### US-0.1: Developer can deploy to production
**Priority**: High
**Story Points**: 5

**Description**: Set up CI/CD pipeline so any developer can deploy code to production with a single command.

**Acceptance Criteria**:
- [ ] GitHub Actions workflow configured
- [ ] Deploys on push to `main` branch
- [ ] Automated tests run before deploy
- [ ] Deploy to Vercel (frontend) and Railway (backend)
- [ ] Environment variables configured
- [ ] Can rollback to previous version

**Technical Notes**:
- Use GitHub Actions for CI/CD
- Vercel for frontend (auto-deploy)
- Railway for backend workers
- Store secrets in GitHub Secrets

---

#### US-0.2: Database is provisioned and migrations run
**Priority**: High
**Story Points**: 3

**Description**: Set up PostgreSQL database with Prisma ORM and run initial migration.

**Acceptance Criteria**:
- [ ] Supabase project created
- [ ] Database connection string in .env
- [ ] Prisma schema matches blueprint
- [ ] Initial migration applied
- [ ] Seed data loaded
- [ ] Can query database from app

**Technical Notes**:
- Use Supabase free tier
- Prisma for ORM
- RLS policies for multi-tenancy

[... more user stories ...]

Step 2: Structure Data for Target Platform

Linear Format:

{
  "title": "US-0.1: Developer can deploy to production",
  "description": "Set up CI/CD pipeline so any developer can deploy code to production with a single command.\n\n**Acceptance Criteria**:\n- [ ] GitHub Actions workflow configured\n- [ ] Deploys on push to `main` branch\n- [ ] Automated tests run before deploy\n- [ ] Deploy to Vercel (frontend) and Railway (backend)\n- [ ] Environment variables configured\n- [ ] Can rollback to previous version\n\n**Technical Notes**:\n- Use GitHub Actions for CI/CD\n- Vercel for frontend (auto-deploy)\n- Railway for backend workers\n- Store secrets in GitHub Secrets",
  "priority": 1,
  "estimate": 5,
  "labelIds": ["<high-priority-label-id>", "<infrastructure-label-id>"],
  "projectId": "<sprint-0-project-id>",
  "teamId": "<team-id>"
}

GitHub Issues Format:

{
  "title": "US-0.1: Developer can deploy to production",
  "body": "**Priority**: High\n**Story Points**: 5\n\n**Description**: Set up CI/CD pipeline so any developer can deploy code to production with a single command.\n\n**Acceptance Criteria**:\n- [ ] GitHub Actions workflow configured\n- [ ] Deploys on push to `main` branch\n- [ ] Automated tests run before deploy\n- [ ] Deploy to Vercel (frontend) and Railway (backend)\n- [ ] Environment variables configured\n- [ ] Can rollback to previous version\n\n**Technical Notes**:\n- Use GitHub Actions for CI/CD\n- Vercel for frontend (auto-deploy)\n- Railway for backend workers\n- Store secrets in GitHub Secrets",
  "labels": ["Sprint 0", "Priority: High", "Type: Infrastructure"],
  "milestone": "Sprint 0",
  "assignees": []
}

Jira Format:

{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "US-0.1: Developer can deploy to production",
    "description": "Set up CI/CD pipeline so any developer can deploy code to production with a single command.\n\nh3. Acceptance Criteria\n* GitHub Actions workflow configured\n* Deploys on push to main branch\n* Automated tests run before deploy\n* Deploy to Vercel (frontend) and Railway (backend)\n* Environment variables configured\n* Can rollback to previous version\n\nh3. Technical Notes\n* Use GitHub Actions for CI/CD\n* Vercel for frontend (auto-deploy)\n* Railway for backend workers\n* Store secrets in GitHub Secrets",
    "issuetype": { "name": "Story" },
    "priority": { "name": "High" },
    "customfield_10016": 5,
    "labels": ["sprint-0", "infrastructure"],
    "sprint": "<sprint-id>"
  }
}

Step 3: Create Projects/Milestones/Sprints

Before creating issues, set up organizational structure:

Linear:

// Create projects for each sprint
const sprint0 = await linear.createProject({
  name: "Sprint 0: Project Setup & Infrastructure",
  description: "Production-ready foundation",
  startDate: "2026-02-07",
  targetDate: "2026-02-14",
  teamId: teamId,
});

const sprint1 = await linear.createProject({
  name: "Sprint 1: Authentication & User Management",
  description: "User signup, login, workspace creation",
  startDate: "2026-02-14",
  targetDate: "2026-02-28",
  teamId: teamId,
});

GitHub:

# Create milestones
gh api repos/{owner}/{repo}/milestones \
  -f title="Sprint 0: Project Setup & Infrastructure" \
  -f description="Production-ready foundation" \
  -f due_on="2026-02-14T00:00:00Z"

gh api repos/{owner}/{repo}/milestones \
  -f title="Sprint 1: Authentication & User Management" \
  -f description="User signup, login, workspace creation" \
  -f due_on="2026-02-28T00:00:00Z"

Jira:

# Create sprints
curl -X POST https://yourcompany.atlassian.net/rest/agile/1.0/sprint \
  -H "Authorization: Basic $(echo -n email:token | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 0",
    "startDate": "2026-02-07T08:00:00.000Z",
    "endDate": "2026-02-14T17:00:00.000Z",
    "originBoardId": <board-id>
  }'

Step 4: Create Issues/Tasks

For each user story:

Linear:

const issue = await linear.createIssue({
  teamId: teamId,
  projectId: sprint0.id,
  title: "US-0.1: Developer can deploy to production",
  description: descriptionMarkdown,
  priority: 1, // 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low
  estimate: 5, // Story points
  labelIds: [highPriorityLabelId, infrastructureLabelId],
});

GitHub:

gh issue create \
  --repo owner/repo \
  --title "US-0.1: Developer can deploy to production" \
  --body "$DESCRIPTION" \
  --label "Sprint 0,Priority: High,Type: Infrastructure" \
  --milestone "Sprint 0"

Jira:

curl -X POST https://yourcompany.atlassian.net/rest/api/3/issue \
  -H "Authorization: Basic $(echo -n email:token | base64)" \
  -H "Content-Type: application/json" \
  -d @issue-payload.json

Step 5: Link Related Issues

If blueprint specifies dependencies:

Linear (blocking relationships):

await linear.createIssueRelation({
  issueId: issue1.id,
  relatedIssueId: issue2.id,
  type: "blocks", // issue1 blocks issue2
});

GitHub (task lists in description):

## Dependencies
- Blocked by #12 (Database setup)
- Blocks #15 (User authentication)

Jira (issue links):

{
  "type": { "name": "Blocks" },
  "inwardIssue": { "key": "PROJ-1" },
  "outwardIssue": { "key": "PROJ-2" }
}

Step 6: Set Labels/Tags

Create and apply labels:

Priority Labels:

• 🔴 Priority: High (Urgent)
• 🟠 Priority: Medium
• 🟢 Priority: Low

Type Labels:

• Feature (new functionality)
• Bug (defects)
• Tech Debt (refactoring, infrastructure)
• Documentation

Sprint Labels:

• Sprint 0
• Sprint 1
• Sprint 2
• ...

Component Labels (from feature areas):

• Authentication
• Database
• Frontend
• Backend
• DevOps
• Security

---

Output Format

When invoked, generate:

🔄 Syncing sprint backlog to Linear...

✅ Detected 8 sprints in blueprint (56 user stories total)
✅ Connected to Linear workspace: Acme Corp
✅ Team: Engineering (team_abc123)

📋 Creating organizational structure...
✅ Created project: Sprint 0 (Feb 7 - Feb 14)
✅ Created project: Sprint 1 (Feb 14 - Feb 28)
✅ Created project: Sprint 2 (Feb 28 - Mar 14)
[... more sprints ...]

🏷️  Creating labels...
✅ Priority: High
✅ Priority: Medium
✅ Priority: Low
✅ Type: Feature
✅ Type: Bug
✅ Type: Tech Debt
✅ Component: Authentication
✅ Component: Database
[... more labels ...]

📝 Creating issues...
✅ US-0.1: Developer can deploy to production (5 pts, High)
✅ US-0.2: Database is provisioned and migrations run (3 pts, High)
✅ US-0.3: Environment variables configured (2 pts, Medium)
[... 53 more issues ...]

🔗 Linking dependencies...
✅ Linked 12 blocking relationships

📊 Summary:
- Sprints: 8
- Total issues: 56
- Story points: 134
- High priority: 18
- Medium priority: 28
- Low priority: 10

🎯 View in Linear:
https://linear.app/acme-corp/project/sprint-0

Next steps:
1. Review issues in Linear
2. Assign team members to issues
3. Start Sprint 0 and begin development
4. Update issue status as work progresses

---

Sync Modes

1. One-Time Push (Default)

Create all issues once, no ongoing sync.

Use when: Initial project setup, blueprint is final.

/architect:sync-backlog --platform=linear

2. Two-Way Sync

Keep blueprint and Linear in sync.

Use when: Blueprint evolves, need to track changes.

Features:

• Detect new user stories in blueprint → Create issues
• Detect completed issues in Linear → Mark in blueprint
• Detect priority changes → Update both sides

/architect:sync-backlog --platform=linear --mode=two-way

3. Export Only (No API)

Generate CSV/JSON for manual import.

Use when: No API access, need manual review before import.

/architect:sync-backlog --platform=csv
# Output: backlog-export.csv

---

Customization Options

Optional parameters:

1. Platform: linear, github, jira, asana, clickup, csv
2. Team ID: Specific team within workspace
3. Assignees: Auto-assign to specific users
4. Start date: Sprint 0 start date (defaults to today)
5. Sprint duration: 1-week, 2-week (default), 3-week, 4-week
6. Include completed: Yes/No (sync already-completed sprints)
7. Dry run: Preview changes without creating issues

Examples:

# Sync to Linear with 1-week sprints
/architect:sync-backlog --platform=linear --sprint-duration=1-week

# Sync to GitHub with auto-assignment
/architect:sync-backlog --platform=github --repo=owner/repo --assign=@me

# Dry run (preview only)
/architect:sync-backlog --platform=jira --dry-run

# Export to CSV
/architect:sync-backlog --platform=csv --output=backlog.csv

---

Platform-Specific Features

Linear

Keyboard Shortcuts Support: Add keyboard shortcut hints in issue descriptions:

**Quick Actions**:
- `c` - Complete this issue
- `a` - Assign to me
- `l` - Add label
- `p` - Change priority

Cycles Integration: Map sprints to Linear cycles automatically:

/architect:sync-backlog --platform=linear --use-cycles
# Creates or updates cycles for each sprint

GitHub

GitHub Projects Integration: Create a GitHub Project board automatically:

/architect:sync-backlog --platform=github --create-project
# Creates: "Architecture Implementation" project
# Columns: Backlog, Sprint 0, Sprint 1, ..., In Progress, Done

Issue Templates: Generate .github/ISSUE_TEMPLATE/user-story.md:

---
name: User Story
about: User story from architecture blueprint
labels: user-story
---

**Priority**:

**Story Points**:

**Description**:

**Acceptance Criteria**:
- [ ]
- [ ]

**Technical Notes**:

Jira

Epics Mapping: Create epics for major feature areas:

Epic: Authentication System
  ├─ US-1.1: User signup
  ├─ US-1.2: Email verification
  └─ US-1.3: Password reset

Epic: Ticket Management
  ├─ US-2.1: Create ticket
  ├─ US-2.2: Update ticket
  └─ US-2.3: Close ticket

Confluence Integration: Generate Confluence page with:

• Architecture overview
• Sprint plan
• Link to blueprint

/architect:sync-backlog --platform=jira --create-confluence-doc

---

Error Handling

If API credentials invalid:

• Action: Error with link to get credentials
• Example: "❌ Linear API key invalid. Get one at https://linear.app/settings/api"

If sprint already exists:

• Action: Prompt user
• Options: "1) Skip existing sprints, 2) Update existing issues, 3) Duplicate with new prefix"

If rate limit hit:

• Action: Pause and retry with exponential backoff
• Notify: "⏸️ Rate limit hit, pausing 60 seconds..."

If blueprint section missing:

• Action: Error with guidance
• Example: "❌ No sprint backlog found. Run /architect:blueprint first."

---

CSV Export Format

For manual import or tools without API:

Sprint,ID,Title,Description,Priority,Story Points,Acceptance Criteria,Technical Notes,Labels
Sprint 0,US-0.1,Developer can deploy to production,"Set up CI/CD pipeline...",High,5,"- [ ] GitHub Actions workflow configured
- [ ] Deploys on push to main branch","Use GitHub Actions for CI/CD
Vercel for frontend","infrastructure,devops"
Sprint 0,US-0.2,Database is provisioned and migrations run,"Set up PostgreSQL...",High,3,"- [ ] Supabase project created
- [ ] Database connection string in .env","Use Supabase free tier
Prisma for ORM","database,setup"
[...]

Import instructions included in output:

📄 CSV exported to: backlog-export.csv

To import:
- Linear: Import via CSV at linear.app/settings/import
- Jira: Tools → Import → CSV
- GitHub: Use gh-issues-import script
- Asana: Import via CSV at app.asana.com/import

---

Success Criteria

A successful backlog sync should:

• ✅ Create all sprints/milestones/projects
• ✅ Create all user stories as issues/tasks
• ✅ Preserve story points and priorities
• ✅ Include acceptance criteria as checklists
• ✅ Add appropriate labels/tags
• ✅ Link dependencies (blocking relationships)
• ✅ Be immediately actionable (team can start work)
• ✅ Match blueprint structure exactly
• ✅ Provide links to view in target platform
• ✅ Handle errors gracefully (partial sync)

---

Examples

Example 1: Linear (Startup)

/architect:sync-backlog --platform=linear

# Interactive prompts:
# - Linear API key: [paste from linear.app/settings/api]
# - Team: Engineering (auto-detected)
# - Start date: 2026-02-07 (today)
# - Sprint duration: 2 weeks

# Output: 56 issues created across 8 sprints

Example 2: GitHub Issues (Open Source)

/architect:sync-backlog --platform=github --repo=acme/backend

# Requires: gh CLI authenticated
# Creates: Milestones + Issues + Labels
# Output: Link to project board

Example 3: Jira (Enterprise)

/architect:sync-backlog --platform=jira

# Interactive prompts:
# - Jira URL: acme.atlassian.net
# - Email: [e-mail]
# - API token: [from id.atlassian.com]
# - Project key: PROJ

# Output: 56 stories created in PROJ project

Example 4: CSV Export

/architect:sync-backlog --platform=csv --output=backlog.csv

# Output: backlog.csv (ready for manual import)