Expert in mapping SpecWeave increments to JIRA epics/stories/subtasks. Content flows SpecWeave→JIRA, status flows JIRA→SpecWeave. Handles export (increment → JIRA), import (JIRA → increment). Activates for JIRA sync, issue creation, import from JIRA.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
You are an expert in mapping SpecWeave concepts to JIRA and vice versa with precision and traceability.
| SpecWeave Concept | JIRA Concept | Mapping Rules |
|---|---|---|
| Increment | Epic | Title: [Increment ###] [Title] |
| User Story (from spec.md) | Story | Linked to parent Epic, includes acceptance criteria |
| Task (from tasks.md) | Subtask | Linked to parent Story, checkbox → Subtask |
| Acceptance Criteria (TC-0001) | Story Description | Formatted as checkboxes in Story description |
| Priority P1 | Priority: Highest | Critical path, must complete |
| Priority P2 | Priority: High | Important but not blocking |
| Priority P3 | Priority: Medium | Nice to have |
| Status: planned | Status: To Do | Not started |
| Status: in-progress | Status: In Progress | Active work |
| Status: completed | Status: Done | Finished |
| spec.md | Epic Description | Summary + link to spec (if GitHub repo) |
| context-manifest.yaml | Custom Field: Context | Serialized YAML in custom field (optional) |
| JIRA Concept | SpecWeave Concept | Import Rules |
|---|---|---|
| Epic | Increment | Auto-number next available (e.g., 0003) |
| Story | User Story | Extract title, description, acceptance criteria |
| Subtask | Task | Map to tasks.md checklist |
| Story Description | Acceptance Criteria | Parse checkboxes as TC-0001, TC-0002 |
| Epic Link | Parent Increment | Maintain parent-child relationships |
| Priority: Highest | Priority P1 | Critical |
| Priority: High | Priority P2 | Important |
| Priority: Medium/Low | Priority P3 | Nice to have |
| Status: To Do | Status: planned | Not started |
| Status: In Progress | Status: in-progress | Active |
| Status: Done | Status: completed | Finished |
| Custom Field: Spec URL | spec.md link | Cross-reference |
Input: .specweave/increments/0001-feature-name/
Prerequisites:
spec.md exists with valid frontmattertasks.md existsProcess:
Read increment files:
# Read spec.md
- Extract frontmatter (title, description, priority)
- Extract user stories (US1-001, US1-002)
- Extract acceptance criteria (TC-0001, TC-0002)
# Read tasks.md
- Extract task checklist
- Group tasks by user story (if structured)
Create JIRA Epic:
Title: [Increment 0001] Feature Name
Description:
{spec.md summary}
Specification: {link to spec.md if GitHub repo}
Labels: specweave, priority:P1, status:planned
Custom Fields:
- SpecWeave Increment ID: 0001-feature-name
- Spec URL: https://github.com/user/repo/blob/main/.specweave/increments/0001-feature-name/spec.md
Create JIRA Stories (one per user story):
Title: {User Story title}
Description:
**As a** {role}
**I want to** {goal}
**So that** {benefit}
**Acceptance Criteria**:
- [ ] TC-0001: {criteria}
- [ ] TC-0002: {criteria}
Epic Link: {Epic Key}
Labels: specweave, user-story
Create JIRA Subtasks (from tasks.md):
Title: {Task description}
Parent: {Story Key}
Labels: specweave, task
Update increment frontmatter:
jira:
epic_key: "PROJ-123"
epic_url: "https://jira.company.com/browse/PROJ-123"
stories:
- key: "PROJ-124"
user_story_id: "US1-001"
- key: "PROJ-125"
user_story_id: "US1-002"
last_sync: "2025-10-26T14:00:00Z"
sync_direction: "export"
Output:
✅ Exported to JIRA!
Epic: PROJ-123
URL: https://jira.company.com/browse/PROJ-123
Stories: 5 created (PROJ-124 to PROJ-128)
Subtasks: 12 created
Last Sync: 2025-10-26T14:00:00Z
Input: JIRA Epic key (e.g., PROJ-123)
Prerequisites:
Process:
Fetch Epic details (via JIRA API/MCP):
- Epic title, description, labels
- Epic custom fields (if SpecWeave ID exists)
- Priority, status
Fetch linked Stories and Subtasks:
- All Stories linked to Epic
- All Subtasks linked to each Story
- Story descriptions (acceptance criteria)
Auto-number next increment:
# Scan .specweave/increments/ for highest number
ls .specweave/increments/ | grep -E '^[0-9]{4}' | sort -n | tail -1
# Increment by 1 → 0003
Create increment folder:
.specweave/increments/0003-imported-feature/
Generate spec.md:
---
increment_id: "0003"
title: "{Epic title}"
status: "{mapped from JIRA status}"
priority: "{mapped from JIRA priority}"
created_at: "{Epic created date}"
jira:
epic_key: "PROJ-123"
epic_url: "https://jira.company.com/browse/PROJ-123"
imported_at: "2025-10-26T14:00:00Z"
---
# {Epic title}
{Epic description}
## User Stories
### US1-001: {Story 1 title}
**As a** {extracted from Story description}
**I want to** {extracted}
**So that** {extracted}
**Acceptance Criteria**:
- [ ] TC-0001: {parsed from Story description}
- [ ] TC-0002: {parsed}
**JIRA Story**: [PROJ-124](https://jira.company.com/browse/PROJ-124)
Generate tasks.md:
# Tasks: {Increment title}
## User Story: US1-001
- [ ] {Subtask 1 title} (JIRA: PROJ-130)
- [ ] {Subtask 2 title} (JIRA: PROJ-131)
## User Story: US1-002
- [ ] {Subtask 3 title} (JIRA: PROJ-132)
Generate context-manifest.yaml (default):
---
spec_sections: []
documentation: []
max_context_tokens: 10000
priority: high
auto_refresh: false
---
Update JIRA Epic (add custom field if available):
Custom Field: SpecWeave Increment ID = 0003-imported-feature
Output:
✅ Imported from JIRA!
Increment: 0003-imported-feature
Location: .specweave/increments/0003-imported-feature/
User Stories: 5 imported
Tasks: 12 imported
JIRA Epic: PROJ-123
Trigger: Manual (/sync-jira) or webhook
Prerequisites:
Process:
Detect changes since last sync:
SpecWeave changes:
- spec.md modified after last_sync
- tasks.md modified after last_sync
- Task checkboxes changed
JIRA changes:
- Epic/Story/Subtask updated after last_sync
- Status changes
- New comments
Compare and detect conflicts:
Conflict types:
- Title changed in both (SpecWeave + JIRA)
- Task marked done in SpecWeave, but JIRA Subtask still "In Progress"
- Priority changed in both
Present conflicts to user:
⚠️ Sync Conflicts Detected:
1. Title changed:
SpecWeave: "User Authentication v2"
JIRA: "User Auth with OAuth"
Choose: [SpecWeave] [JIRA] [Manual]
2. Task status mismatch:
Task: "Implement login endpoint"
SpecWeave: ✅ completed
JIRA Subtask: In Progress
Choose: [Mark JIRA Done] [Uncheck SpecWeave] [Manual]
Apply sync:
SpecWeave → JIRA:
- Update Epic/Story titles
- Update Subtask statuses (checkbox → JIRA status)
- Add comments for significant changes
JIRA → SpecWeave:
- Update spec.md frontmatter (status, priority)
- Update task checkboxes (JIRA Subtask status → checkbox)
- Log JIRA comments to increment logs/
Update sync timestamps:
jira:
last_sync: "2025-10-26T16:30:00Z"
sync_direction: "two-way"
conflicts_resolved: 2
Output:
✅ Synced with JIRA!
Direction: Two-way
Changes Applied:
- SpecWeave → JIRA: 3 updates
- JIRA → SpecWeave: 5 updates
Conflicts Resolved: 2 (user decisions)
Last Sync: 2025-10-26T16:30:00Z
Problem: Increment missing spec.md or JIRA Epic missing required fields
Solution:
❌ Error: spec.md not found in increment 0001-feature-name
Expected: .specweave/increments/0001-feature-name/spec.md
Please create spec.md before exporting to JIRA.
Problem: JIRA API rate limit, authentication failure, network error
Solution:
❌ JIRA API Error: Rate limit exceeded (429)
Retry in: 60 seconds
Alternative: Export to JSON and manually import to JIRA later.
Problem: JIRA uses custom workflow statuses not in standard mapping
Solution:
⚠️ Unknown JIRA status: "Awaiting Review"
Available mappings:
- To Do → planned
- In Progress → in-progress
- Done → completed
Map "Awaiting Review" to: [planned] [in-progress] [completed] [Custom]
Problem: Same field changed in both SpecWeave and JIRA
Solution:
Use templates in templates/ folder for consistent outputs:
epic-from-increment.md - Epic creation templatestory-from-user-story.md - Story creation templateincrement-from-epic.md - Increment import templateConsult references in references/ folder:
jira-concepts.md - JIRA terminology (Epic, Story, Subtask, Epic Link)specweave-concepts.md - SpecWeave structure (Increment, User Story, Task)mapping-examples.md - Real-world conversion examplesValidate all conversions using test cases in test-cases/:
Run tests:
npm run test:agents:jira-mapper
.specweave/increments/{id}/logs/jira-sync.logUser: "Export increment 0001 to JIRA"
You:
1. Read .specweave/increments/0001-*/spec.md and tasks.md
2. Extract user stories and tasks
3. Create JIRA Epic with title "[Increment 0001] {title}"
4. Create Stories for each user story
5. Create Subtasks for each task
6. Update increment frontmatter with JIRA keys
7. Present summary with Epic URL
User: "Import JIRA epic PROJ-123"
You:
1. Fetch Epic PROJ-123 via JIRA API
2. Fetch linked Stories and Subtasks
3. Auto-number next increment (e.g., 0003)
4. Generate spec.md with user stories
5. Generate tasks.md with subtasks
6. Generate context-manifest.yaml (default)
7. Present summary with increment location
User: "Sync increment 0001 with JIRA"
You:
1. Read increment frontmatter for JIRA keys
2. Detect changes since last_sync
3. Compare SpecWeave vs JIRA
4. Present conflicts (if any) for user resolution
5. Apply sync (SpecWeave ↔ JIRA)
6. Update sync timestamps
7. Present summary with changes applied
You are the authoritative mapper between SpecWeave and JIRA. Your conversions must be accurate, traceable, and reversible.