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.

Processing

1. Parse query from $ARGUMENTS (everything after "search")

2. Determine if it's JQL or natural language:

   • Contains JQL operators (=, in, AND, ORDER BY, field names like assignee, status) → Use as JQL
   • Otherwise → Convert natural language to JQL

3. Natural language → JQL conversion examples:

   • "my open bugs" → assignee = currentUser() AND type = Bug AND status != Done
   • "high priority in TEAM" → project = TEAM AND priority in (Highest, High)
   • "created this week" → created >= startOfWeek()
   • "blocked items" → status = Blocked OR labels = blocked

   When unsure, refer to references/jql-cheatsheet.md for patterns.

4. Execute search:

acli jira --action getIssueList --jql "YOUR_JQL" --outputType json

5. Present results:

## Jira Search: "{query}"

Found {count} issues:

| Key | Summary | Status | Assignee | Priority | Updated |
|-----|---------|--------|----------|----------|---------|
| {key} | {summary} | {status} | {assignee} | {priority} | {date} |

6. Offer follow-up actions: "Want to /jira status KEY for details or /jira move KEY status to transition?"

sprint — Active Sprint

Show the active sprint with progress metrics.

Processing

1. Resolve project
2. Fetch active sprint data:

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

3. Present with metrics:

## Active Sprint — {sprint name}

**Dates**: {start} → {end} ({days remaining} days left)
**Progress**: {done}/{total} issues ({percent}%)

### Done ({count})
- [{KEY}] {summary}

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

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

### Blocked ({count})
- [{KEY}] {summary} — ⚠ {blocker reason}

sync — Pull Jira State Into Vault

Sync Jira issue state with vault notes. Additive only — creates/updates vault notes, never deletes.

Processing

1. Create a session task for progress tracking
2. Resolve project (or sync all mapped projects)
3. Read integrations.jira.status_mapping and integrations.jira.project_mapping from config
4. Fetch recent issues (updated in last 7 days, or --days N):

acli jira --action getIssueList --project "PROJECT" --jql "updated >= -7d" --outputType json

5. For each issue, determine vault action based on status_mapping:

   Blocked issues → Create/update blocker notes:

   • Check if a blocker note with jira_key: KEY already exists
   • If not, create one using _templates/blocker.md:
     • jira_key: KEY-123 in frontmatter
     • tags: [KEY-123]
     • severity mapped from Jira priority
     • ## Links includes [KEY-123](https://site/browse/KEY-123)
   • If exists and still blocked, skip (no-op)
   • If exists but now resolved in Jira, update status: resolved

   Shipped issues → Update daily note:

   • Check today's daily note exists
   • Append shipped items under the relevant project's ### Shipped section
   • Format: - [{KEY}] {summary} ✓

   Resolved blockers → Archive:

   • Find vault blockers with matching jira_key where Jira status maps to "shipped"
   • Update status: resolved (auto-archive rules will handle the rest)

6. Bulk safety: If sync would create 5+ new notes, show summary and confirm:

Sync will create:
  - 3 new blocker notes
  - 7 shipped items added to daily note
  - 2 blockers resolved

Proceed? (y/n)

7. Report what was synced:

## Jira Sync Complete — {date}

Created: 3 blocker notes
Updated: 2 blockers → resolved
Daily: 7 shipped items added
Skipped: 12 issues (no vault action needed)

Flags

• --days N — Look back N days (default: 7)
• --dry-run — Show what would change without writing
• --project {name} — Sync only one project

(empty) — Help & Quick Status

When called with no arguments, show help and a quick status summary.

Processing

1. Check acli connection status
2. Read Jira config from _core/config.yaml
3. Count vault notes linked to Jira issues:

grep -rl "^jira_key:" --include="*.md" | wc -l

4. Present:

## Jira Integration

**Status**: Connected to {site}
**Mapped projects**: {project-a} → TEAM, ...
**Vault links**: {count} notes linked to Jira issues

### Commands

| Command | Example | Purpose |
|---------|---------|---------|
| board | `/jira board TEAM` | View board columns |
| create | `/jira create TEAM --summary "..."` | Create issue |
| status | `/jira status TEAM-42` | Issue details |
| move | `/jira move TEAM-42 Done` | Transition issue |
| edit | `/jira edit TEAM-42 --summary "..."` | Update fields |
| assign | `/jira assign TEAM-42 john` | Assign issue |
| backlog | `/jira backlog TEAM` | View backlog |
| search | `/jira search "my open bugs"` | Search via JQL |
| sprint | `/jira sprint TEAM` | Active sprint |
| sync | `/jira sync` | Pull state into vault |
| setup | `/jira setup` | Configure connection |

Vault Integration Patterns

Frontmatter Tagging

When a vault note is linked to a Jira issue, add to frontmatter:

jira_key: TEAM-42
tags: [TEAM-42]

Cross-Reference Format

In note body and ## Links sections, use:

[TEAM-42](https://your-org.atlassian.net/browse/TEAM-42)

Status Mapping

Map Jira statuses to PM-Kit categories via integrations.jira.status_mapping in config:

Users can customize this mapping for their Jira workflow (e.g., add "In Review" → wip).

Safety Rules

1. Read-only commands execute without confirmation: board, status, search, sprint, backlog
2. Mutating commands require confirmation: create, move, edit, assign
3. Sync is additive only — creates/updates vault notes, never deletes vault content
4. Bulk operations (5+ changes) show summary before proceeding
5. API tokens are handled by acli — never log, display, or store tokens in vault files
6. Never auto-transition Jira issues based on vault changes — Jira writes only happen via explicit commands

Error Handling

Additional Resources

Reference Files

• references/jql-cheatsheet.md — Common JQL patterns for PMs

Scripts

• scripts/check-jira.sh — Verify acli installation and auth status