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:

| Input starts with | Sub-command | Purpose | Read/Write | |---|---|---|---| | setup | Setup | Guide installation + auth configuration | Config write | | board | Board | Show board columns with issue counts | Read-only | | create | Create | Create a Jira issue | Jira write + optional vault note | | status | Status | Show details for a specific issue | Read-only | | move | Move | Transition an issue to a new status | Jira write + vault note update | | edit | Edit | Update issue fields | Jira write | | assign | Assign | Assign an issue to someone | Jira write | | backlog | Backlog | Show backlog items | Read-only | | search | Search | Find issues via JQL or natural language | Read-only | | sprint | Sprint | Show active sprint details | Read-only | | sync | Sync | Pull Jira state into vault notes | Vault write (additive only) | | (empty) | Help | Show help + quick status summary | Read-only |

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

1. 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}

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

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

1. Confirm with user before creating:

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

Proceed? (y/n)

1. Create the issue:

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

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

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

```markdown

• KEY-123 — Jira issue

```

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

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

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

1. Fetch available transitions:

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

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

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

Proceed? (y/n)

1. Execute transition:

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

1. 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"

1. Confirm before executing:

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

Proceed? (y/n)

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

1. If me, resolve current user from config
2. Confirm before executing:

Assigning TEAM-42 to john.doe

Proceed? (y/n)

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

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

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

1. Execute search:

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

1. Present results:

## Jira Search: "{query}"

Found {count} issues:

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

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

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

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

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

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

1. 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:

| Jira Status | PM-Kit Category | |-------------|-----------------| | To Do | wip | | In Progress | wip | | Done | shipped | | Blocked | blocked |

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

| Error | Response | |-------|----------| | acli not installed | Show install instructions, suggest /jira setup | | Not authenticated | Show auth steps, link to API token page | | Invalid project key | Show available projects from config mapping | | Issue not found | Suggest search, check key format | | Transition not available | Show available transitions for the issue | | No project mapping | Ask user to configure in _core/config.yaml or run /jira setup |

Additional Resources

Reference Files

• **`references/jq

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kv0906
• Source: kv0906/pm-kit
• License: MIT
• Homepage: https://willtran.xyz

Install and usage instructions live in the source repository linked above.