/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

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:

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/jql-cheatsheet.md — Common JQL patterns for PMs

Scripts

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