/jira-promote Command

WHAT: Promote local exploration issue to Jira for team collaboration.

WHY: Convert validated prototypes to production-tracked work.

HOW: Migrate TASK-###/BUG-### to Jira, preserve all artifacts, update branch.

Usage

/jira-promote TASK-001    # Promote local task to Jira
/jira-promote BUG-003     # Promote local bug to Jira

Execution Flow

Before you start: Read jira-integration.md for Jira integration patterns, field discovery, and promotion workflow.

High-Level Steps

1. Validate Prerequisites

   • Check Jira enabled in CLAUDE.md
   • Verify Atlassian MCP accessible
   • Confirm local issue exists (TASK.md or BUG.md)

2. Load Local Artifacts

   • Read TASK.md/BUG.md, PLAN.md, WORKLOG.md, RESEARCH.md
   • Extract summary, description, acceptance criteria

3. Field Discovery & Collection

   • Load field cache (.ai-toolkit/jira-field-cache.json)
   • Map local → Jira (summary, description, issue type)
   • Prompt for custom fields conversationally

4. Create Jira Issue

   • Use Atlassian MCP to create issue
   • Get PROJ-### issue key and URL
   • Display Jira link

5. Migrate Artifacts

   • Create pm/issues/PROJ-###-{name}/
   • Copy PLAN.md, WORKLOG.md, RESEARCH.md, resources/
   • Add promotion note to WORKLOG

6. Cleanup & Branch Update

   • Ask: Delete original directory?
   • If yes: Remove pm/issues/TASK-###-*/
   • Rename branch: feature/TASK-### → feature/PROJ-###

See jira-integration.md "Promotion Workflow" for complete artifact migration and field mapping details.

When to Promote

Promote when: Prototype validated, ready for production, needs team collaboration Don't promote when: Still exploring, throwaway spike, personal learning, already complete

Error Handling

Jira not enabled: Enable in CLAUDE.md with jira.enabled: true Issue not found: Verify local issue exists in pm/issues/ Field discovery fails: Field cache will auto-refresh on failure MCP unavailable: Install and configure Atlassian MCP server

See jira-integration.md for complete error scenarios and solutions.