X Jira Create Epic

Parameters

Prerequisites

Read the field mapping reference before creating issues:

• .claude/skills/x-jira-create-epic/references/jira-field-mapping.md

Workflow

Step 1 — Input and Parse

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-epic Phase-1-Read-Markdown

1. Accept the epic file path as argument. If not provided, ask:

   question: "Qual o caminho do arquivo do epico? (ex: plans/epic-0012/epic-0012.md)"
   header: "Epic File"
   

2. Read the epic file completely
3. Extract:
   • Title: From # Epico: <titulo> (line 1)
   • Local ID: From the directory name (epic-XXXX)
   • Overview: From Section 1 (Visao Geral) — all text after **Chave Jira:** line until Section 2
   • Status: From the header **Status:** field
   • Existing Jira Key: From **Chave Jira:** field

Step 2 — Pre-checks

1. Verify mcp__atlassian__createJiraIssue is available. If not:

   ERROR: MCP tool mcp__atlassian__createJiraIssue not available.
   Ensure the Atlassian MCP server is configured in .claude/settings.json.
   

   Abort.

2. Check existing Jira key. If **Chave Jira:** has a real value (not <CHAVE-JIRA> and not —):

   question: "Este epico ja tem chave Jira: {KEY}. O que deseja fazer?"
   header: "Epico ja vinculado ao Jira"
   options:
     - label: "Criar novo epico no Jira"
       description: "Ignorar a chave existente e criar um novo issue"
     - label: "Pular — manter a chave existente"
       description: "Nao criar no Jira, manter o vinculo atual"
   

   If "Pular": exit with message "Epico mantido com chave {KEY}."

Step 3 — Project Selection

1. Call mcp__atlassian__getAccessibleAtlassianResources to discover available Atlassian sites

2. Use the first available site's id as cloudId. If no sites returned:

   ERROR: No accessible Atlassian sites found. Check your Atlassian credentials.
   

   Abort.

3. Call mcp__atlassian__getVisibleJiraProjects with the discovered cloudId

4. Present the project list to the user:

   question: "Selecione o projeto Jira para criar o epico:"
   header: "Projeto Jira"
   options:
     - label: "{PROJECT_KEY} — my-java-cli"
       description: "Project key: {PROJECT_KEY}"
     (one option per project)
   

5. Capture the selected projectKey

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-1-Read-Markdown ok

Step 4 — Create Epic in Jira

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-epic Phase-2-MCP-Call

Wrap the Jira MCP call with mcp-start / mcp-end markers (story-0040-0008 §3.2) so the tool.call event carries tool=mcp__atlassian__createJiraIssue and a measured durationMs:

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-start x-jira-create-epic createJiraIssue

Call mcp__atlassian__createJiraIssue with:

• cloudId: discovered cloudId
• projectKey: selected project key
• issueTypeName: "Epic"
• summary: epic title (extracted from # Epico: <titulo>)
• description: Section 1 (Visao Geral) text content
• contentFormat: "markdown"
• additional_fields:

  {
    "labels": [
      { "name": "generated-by-ia-dev-env" },
      { "name": "epic-XXXX" }
    ]
  }
  

Where epic-XXXX is the local epic ID (e.g., epic-0012).

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-end x-jira-create-epic createJiraIssue ok

(On MCP failure, invoke the mcp-end marker with status failed instead of ok so the telemetry record reflects the real outcome — §5.3.)

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-2-MCP-Call ok

Step 5 — Sync Jira Key Back to Local File

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-epic Phase-3-Sync-Back

1. Capture the returned Jira issue key (e.g., PROJ-123)
2. Read the epic markdown file
3. Replace the **Chave Jira:** value:
   • If current value is <CHAVE-JIRA>: replace with the actual key
   • If current value is —: replace with the actual key
   • If creating a new epic (user chose to ignore existing key): replace with the new key
4. Write the updated file

Step 6 — Report

Output:

Epico criado no Jira: {JIRA_KEY}
Projeto: {PROJECT_KEY}
Arquivo local atualizado: {EPIC_FILE_PATH}
Label de sync: epic-XXXX

Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-3-Sync-Back ok

Error Handling

Integration Notes

ID Synchronization Strategy

Bidirectional lookup is enabled by:

• Local to Jira: The local ID (epic-XXXX) is stored as a Jira label
• Jira to Local: The Jira key (e.g., PROJ-123) is stored in the **Chave Jira:** field
• JQL Lookup: labels = "epic-XXXX" AND labels = "generated-by-ia-dev-env"