navraj007in/sync-backlog

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: [email protected]
# - 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)