gh-anton-abyzov-specweave-plugins-specweave-jira/skills/jira-sync

jira-sync Skill

Status: To be developed Priority: Medium

Purpose

Bidirectional sync between SpecWeave increments and JIRA (Atlassian)

Note: This skill handles ONLY JIRA. For Azure DevOps, see ado-sync skill.

Features

Export to JIRA

• Create JIRA issues from SpecWeave increments
• Map spec.md user stories → JIRA Stories
• Map tasks.md tasks → JIRA Sub-tasks
• Create Epics if specified in spec.md
• Set priorities, labels, components

Import from JIRA

• Sync JIRA updates back to SpecWeave
• Import existing JIRA issues as increments
• Update status, assignees, comments

Bidirectional Sync

• Keep status in sync (To Do, In Progress, Done)
• Sync descriptions and acceptance criteria
• Sync comments
• Handle conflicts intelligently

JIRA-Specific Concepts

Mapping: SpecWeave → JIRA

SpecWeave	JIRA
spec.md (with Epic)	Epic
spec.md User Story	Story
tasks.md Task	Sub-task
Acceptance Tests (spec.md)	Acceptance Criteria (Story)
Acceptance Criteria (tasks.md)	Sub-task checklist
Status: planned	To Do
Status: in-progress	In Progress
Status: completed	Done

JIRA Structure Example

spec.md with JIRA structure:

---
increment: 002-payment-processing
status: planned
structure: jira
jira_epic: PROJ-123
---

## Epic: E-commerce Infrastructure
**JIRA**: PROJ-123

### Story: Subscribe to Plan
**JIRA**: PROJ-124
**Priority**: P1
**Labels**: payments, stripe
**Components**: Backend, Frontend

**Description**:
As a user, I want to subscribe to a monthly plan...

**Acceptance Criteria**:
- User can select plan
- Payment processed
- Subscription activated

tasks.md creates Sub-tasks:

## Tasks for PROJ-124 (Subscribe to Plan)

### Task T001: Create StripeService
**JIRA**: PROJ-125 (Sub-task of PROJ-124)
**Agent**: nodejs-backend

**Description**: Create Stripe service class...

**Acceptance Criteria**:
- [ ] StripeService class exists
- [ ] Unit tests passing

Authentication

JIRA Cloud:

JIRA Server/Data Center:

jira_sync:
  type: "server"
  url: "https://jira.your-company.com"
  username: "user"
  password: "${JIRA_PASSWORD}"  # From environment variable
  project_key: "PROJ"

Configuration

Workflow

Export Workflow (SpecWeave → JIRA)

User: Creates increment in SpecWeave
  .specweave/increments/0002-payment/
    spec.md (with structure: jira)
    tasks.md

↓ jira-sync detects new increment

Creates in JIRA:
  Epic: PROJ-123 "E-commerce Infrastructure"
    Story: PROJ-124 "Subscribe to Plan"
      Sub-task: PROJ-125 "Create StripeService"
      Sub-task: PROJ-126 "Create API endpoints"

Links created:
  spec.md → PROJ-124
  tasks.md T001 → PROJ-125
  tasks.md T002 → PROJ-126

Import Workflow (JIRA → SpecWeave)

User: Updates JIRA issue status to "In Progress"

↓ JIRA webhook triggers

jira-sync:
  Detects change to PROJ-124
  Finds linked increment: 002-payment
  Updates: .specweave/increments/0002-payment/spec.md
    status: planned → in-progress

Bidirectional Sync

User: Checks off task in tasks.md
  - [x] T001: Create StripeService

↓ jira-sync detects change

Updates JIRA:
  PROJ-125 status → Done

User: Changes PROJ-124 to "Done" in JIRA

↓ JIRA webhook triggers

jira-sync updates SpecWeave:
  .specweave/increments/0002-payment/spec.md
    status: in-progress → completed

API Integration

JIRA REST API Endpoints Used

// Create Epic
POST /rest/api/3/issue
{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Epic" },
    "summary": "E-commerce Infrastructure",
    "customfield_10011": "epic-name"  // Epic Name field
  }
}

// Create Story (linked to Epic)
POST /rest/api/3/issue
{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Story" },
    "summary": "Subscribe to Plan",
    "parent": { "key": "PROJ-123" }  // Link to Epic
  }
}

// Create Sub-task
POST /rest/api/3/issue
{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Sub-task" },
    "parent": { "key": "PROJ-124" },
    "summary": "Create StripeService"
  }
}

// Update status
POST /rest/api/3/issue/{issueKey}/transitions
{
  "transition": { "id": "31" }  // "In Progress"
}

Webhooks

Setup JIRA Webhook

1. Go to JIRA Settings → System → Webhooks
2. Create webhook:
   • URL: https://your-app.com/api/webhooks/jira
   • Events: Issue created, updated, deleted
   • Secret: Random string (store in JIRA_WEBHOOK_SECRET)

Webhook Handler

// Receives JIRA webhook
POST /api/webhooks/jira

// jira-sync processes:
1. Verify webhook signature
2. Extract issue data
3. Find linked SpecWeave increment
4. Update spec.md or tasks.md
5. Commit changes (optional)

Conflict Resolution

Scenario: Both SpecWeave and JIRA updated simultaneously

Strategy:

1. Timestamp-based: Latest change wins
2. User prompt: Ask user which to keep
3. Merge: Combine changes if possible

Example:

SpecWeave: status → in-progress (10:00 AM)
JIRA: status → done (10:05 AM)

jira-sync:
  Latest is JIRA (10:05 AM)
  Update SpecWeave → done

Error Handling

Common errors:

• JIRA API rate limits → Retry with exponential backoff
• Authentication failed → Notify user, check credentials
• Issue not found → Create if export, skip if import
• Network errors → Queue for retry

Testing

Test scenarios:

1. Create increment → Creates JIRA issues
2. Update JIRA → Updates SpecWeave
3. Update SpecWeave → Updates JIRA
4. Conflict resolution
5. Webhook handling
6. Error recovery

Integration with Other Skills

• task-builder: Reads JIRA structure from spec.md
• increment-planner: Can specify structure: jira

Future Enhancements

• Support for JIRA sprints/iterations
• Sync custom fields
• Attachment sync
• Advanced filtering (which issues to sync)
• Bulk import from JIRA

---

To implement: See task in .specweave/increments/

See also: ado-sync skill for Azure DevOps integration