Jira

/jira — Jira Integration

Bridge your PM-Kit vault with Jira issue tracking via the acli (Atlassian CLI) command-line tool. View boards, create/edit/transition issues, search via JQL, and sync Jira state with vault notes.

Prerequisites

• acli (Atlassian CLI): brew install acli or download from https://bobswift.atlassian.net/wiki/spaces/ACLI
• Jira Cloud or Server instance with API access
• Authentication configured via acli jira auth login

Context

Today's date: !date +%Y-%m-%d Config: @_core/config.yaml Processing rules: @_core/PROCESSING.md Active projects: !ls 01-index/*.md 2>/dev/null | sed 's|01-index/||;s|\.md||'

Input

User input: $ARGUMENTS

Sub-commands

Parse the first word of $ARGUMENTS to determine the sub-command:

Step 0: Connection Check

Before any sub-command (except setup), verify acli is installed and authenticated:

# 1. Check acli is installed
command -v acli &>/dev/null

# 2. Check auth works with a simple query
acli jira --action getServerInfo 2>/dev/null

If either fails:

Jira CLI (acli) is not connected yet.

Run `/jira setup` to install and configure — it takes about 2 minutes.

Then stop. Don't attempt other operations without a working connection.

Project Resolution

Many sub-commands accept an optional [PROJECT] argument. Resolve it:

1. If user provides a Jira project key directly (e.g., TEAM), use it
2. If user provides a vault project ID (e.g., project-a), look up integrations.jira.project_mapping in _core/config.yaml
3. If no project specified, check for a single active project or use integrations.jira.default_board
4. If ambiguous, ask the user

setup — Install & Configure

Guide the user through installing acli and connecting to their Jira instance.

Steps to present:

## Jira CLI Setup

### Step 1: Install acli
  brew install acli

Or download from: https://bobswift.atlassian.net/wiki/spaces/ACLI

### Step 2: Authenticate
  acli jira --server https://YOUR-ORG.atlassian.net --user your@email.com --token YOUR_API_TOKEN --action getServerInfo

Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens

### Step 3: Save credentials
Create ~/.acli/credentials with:

  jira.server = https://YOUR-ORG.atlassian.net
  jira.user = your@email.com
  jira.token = YOUR_API_TOKEN

### Step 4: Verify
  /jira

You should see your Jira instance info and recent activity.

After presenting, ask the user for their Jira site URL and email to help configure.

Then update _core/config.yaml integrations block:

integrations:
  jira:
    enabled: true
    site: "your-org.atlassian.net"
    email: "your@email.com"
    project_mapping:
      project-a: TEAM        # vault project ID: JIRA PROJECT KEY
    default_board: ""
    status_mapping:
      "To Do": wip
      "In Progress": wip
      "Done": shipped
      "Blocked": blocked

Confirm each value with the user before writing.

board — View Board

Show the current board state with issues grouped by column.

Processing

1. Resolve project (see Project Resolution above)
2. Fetch board data:

acli jira --action getIssueList --project "PROJECT" --outputType json

3. Group issues by status and present:

## Jira Board — {PROJECT}

### To Do ({count})
- [{KEY}] {summary} — {assignee} ({priority})

### In Progress ({count})
- [{KEY}] {summary} — {assignee} ({priority})

### Done ({count} recent)
- [{KEY}] {summary} — completed {date}

4. Highlight any issues matching vault blockers (cross-reference by jira_key in frontmatter)

create — Create Issue

Create a Jira issue, optionally from vault note context.

Processing

1. Determine source — Check if user provided:

   • A vault file path or wikilink → Read that note for context
   • --type, --summary, --description flags → Use directly
   • Freeform text → Parse into fields
   • Nothing → Ask what to create

2. Extract issue fields:

   • Project: From vault project mapping or ask
   • Type: Task (default), Bug, Story, Epic — from --type or inferred from note type (blocker→Bug)
   • Summary: From --summary, note H1, or frontmatter title
   • Description: From note body or --description (convert wikilinks to plain text)
   • Priority: Map from blocker severity (high→Highest, medium→High, low→Medium) or ask
   • Assignee: From --assignee or ask (optional)

3. Confirm with user before creating:

Creating Jira issue:
  Project: {PROJECT}
  Type: {type}
  Summary: {summary}
  Priority: {priority}
  Assignee: {assignee}

Proceed? (y/n)

4. Create the issue:

acli jira --action createIssue --project "PROJECT" --type "Task" --summary "summary" --description "description" --priority "Medium"

5. Link back — If created from a vault note, update the note:

   • Add jira_key: KEY-123 to frontmatter
   • Add to ## Links > ### Related:

   - [KEY-123](https://site.atlassian.net/browse/KEY-123) — Jira issue

6. Report the created issue key and URL.

status — Issue Details

Show detailed information for a specific issue.

Processing

1. Parse issue key from $ARGUMENTS (e.g., TEAM-42)
2. Fetch issue details:

acli jira --action getIssue --issue "KEY-123" --outputType json

3. Present formatted output:

## TEAM-42: {summary}

**Status**: {status} | **Priority**: {priority} | **Type**: {type}
**Assignee**: {assignee} | **Reporter**: {reporter}
**Sprint**: {sprint} | **Created**: {date}

### Description
{description}

### Comments ({count})
- {author} ({date}): {comment snippet}...

### Vault Links
- [[blockers/project-a/2026-03-01-api-rate-limit|API Rate Limit]] (jira_key: TEAM-42)

4. Check vault for any notes with jira_key: KEY-123 in frontmatter and show cross-references.

move — Transition Issue

Move an issue to a new status (e.g., "In Progress" → "Done").

Processing

1. Parse issue key and target status from $ARGUMENTS
   • e.g., /jira move TEAM-42 "Done" or /jira move TEAM-42 done
2. Fetch available transitions:

acli jira --action getTransitionList --issue "KEY-123"

3. Match target status (case-insensitive, fuzzy match)
4. Confirm before executing:

Moving TEAM-42: "API Rate Limit Fix"
  From: In Progress
  To: Done

Proceed? (y/n)

5. Execute transition:

acli jira --action transitionIssue --issue "KEY-123" --transition "Done"

6. Update vault — If a vault note has jira_key: KEY-123:
   • If moved to a "shipped" status (per status_mapping): Update note status: resolved or status: shipped
   • If moved to a "blocked" status: Flag in daily note
   • Check if archive_on_status_change applies

edit — Update Issue Fields

Update fields on an existing Jira issue.

Processing

1. Parse issue key and fields from $ARGUMENTS
   • --summary "new title", --description "new desc", --priority High, --labels "label1,label2"
2. Confirm before executing:

Updating TEAM-42:
  summary: "New Title"
  priority: High

Proceed? (y/n)

3. Execute update:

acli jira --action updateIssue --issue "KEY-123" --summary "New Title" --priority "High"

assign — Assign Issue

Assign an issue to a team member.

Processing

1. Parse issue key and assignee from $ARGUMENTS
   • /jira assign TEAM-42 "john.doe" or /jira assign TEAM-42 me
2. If me, resolve current user from config
3. Confirm before executing:

Assigning TEAM-42 to john.doe

Proceed? (y/n)

4. Execute:

acli jira --action updateIssue --issue "KEY-123" --assignee "john.doe"

backlog — View Backlog

Show backlog items not in the active sprint.

Processing

1. Resolve project
2. Fetch backlog issues:

acli jira --action getIssueList --project "PROJECT" --filter "sprint not in openSprints()" --outputType json

3. Present sorted by priority:

## Backlog — {PROJECT} ({count} items)

### High Priority
- [{KEY}] {summary} — {type} ({assignee})

### Medium Priority
- [{KEY}] {summary} — {type} ({assignee})

### Low / Unset
- [{KEY}] {summary} — {type}

search — Search Issues

Find issues using JQL or natural language queries.