292 lines
6.0 KiB
Markdown
292 lines
6.0 KiB
Markdown
# 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**:
|
|
```markdown
|
|
---
|
|
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**:
|
|
```markdown
|
|
## 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**:
|
|
```yaml
|
|
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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|