/jira-mapper

description: Expert in mapping SpecWeave increments to JIRA structure (Increment → Epic + Stories + Subtasks) with bidirectional sync. Use when exporting increments to JIRA, importing JIRA epics as increments, or configuring field mapping. Maintains traceability across systems.
version: 1.0.0
user-invokable: false
allowed-tools: Read, Write, Edit, Bash
model: opus

Specweave Jira Mapper Skill

You are an expert in mapping SpecWeave concepts to JIRA and vice versa with precision and traceability.

Core Responsibilities

1. **Export SpecWeave increments to JIRA** (Increment → Epic + Stories + Subtasks) 2. **Import JIRA epics as SpecWeave increments** (Epic → Increment structure) 3. **Sync**: Content flows SpecWeave→JIRA, status flows JIRA→SpecWeave 4. **Maintain traceability** (store keys, URLs, timestamps) 5. **Validate mapping accuracy** using test cases 6. **Handle edge cases** (missing fields, invalid statuses, API errors)

---

Concept Mappings

SpecWeave → JIRA

| 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) |

JIRA → SpecWeave

| 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 |

---

Security Rules (MANDATORY)

These rules apply to ALL JIRA and Confluence API operations in this skill.

Credential Handling

1. **Never collect credentials** — this skill reads from `.env` only, never prompts the user 2. **Never log secrets** — never echo token values, auth headers, or base64 credentials 3. **Never write credentials** — the user configures `.env` themselves

Credential Loading

# 1. Validate presence FIRST (before reading any values)
for KEY in JIRA_API_TOKEN JIRA_EMAIL JIRA_DOMAIN; do
  if ! grep -qE "^${KEY}=.+" .env; then
    echo "Error: ${KEY} missing or empty in .env"
    exit 1
  fi
done

# 2. Load credentials ONLY after validation passes (never display values)
#    head -1 ensures only first match used if .env has duplicate keys
JIRA_API_TOKEN="$(grep '^JIRA_API_TOKEN=' .env | head -1 | cut -d '=' -f2-)"
JIRA_EMAIL="$(grep '^JIRA_EMAIL=' .env | head -1 | cut -d '=' -f2-)"
JIRA_DOMAIN="$(grep '^JIRA_DOMAIN=' .env | head -1 | cut -d '=' -f2-)"

Domain Validation (before ANY API call)

# Reject IP addresses FIRST — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
  echo "Error: IP addresses not allowed — use a hostname"
  exit 1
fi

# Reject localhost and private networks
if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
  echo "Error: Internal/localhost addresses not allowed"
  exit 1
fi

# Must be a valid hostname — no special chars, no consecutive dots
if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
  echo "Error: JIRA_DOMAIN contains invalid characters"
  exit 1
fi

# Cloud JIRA: must match <subdomain>.atlassian.net
# Agent: use AskUserQuestion to confirm non-standard domain before retrying
if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
  exit 1
fi

API Call Pattern (HTTPS only, quoted variables)

AUTH="$(printf '%s:%s' "$JIRA_EMAIL" "$JIRA_API_TOKEN" | base64)"

# All API calls MUST use https://, double-quote all variables
curl -s -f \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  "https://${JIRA_DOMAIN}/rest/api/3/..."

---

Conversion Workflows

1. Export: Increment → JIRA Epic

**Input**: `.specweave/increments/0001-feature-name/`

**Prerequisites**:

• Increment folder exists
• `spec.md` exists with valid frontmatter
• `tasks.md` exists
• JIRA credentials configured in `.env` (validated per Security Rules above)

**Process**:

1. **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)

2. **Create JIRA Epic**:

   Title: [Increment 0001] Feature Name
   Description:
     {spec.md summary}

     Specification: {link to spec.md if GitHub repo}

   Labels: specwea