jira-integration · Claude Code Plugin

[English] | 한국어

Automate your entire dev workflow — from Jira issue to merged PR — inside Claude Code.

---

Why This Plugin?

Most Jira + AI tools stop at CRUD (read/create/update issues). This plugin automates the entire development lifecycle: approach → implementation → testing → review → PR → done, with every step synced back to Jira automatically.

	This Plugin	Atlassian Official AI	netresearch/jira-skill
Jira MCP integration	✅	✅	❌ Python scripts
Full PDCA lifecycle	✅	❌ code gen only	❌ CRUD only
Multi-worktree batch setup	✅	❌	❌
Auto Jira status transitions	✅	✅	manual
Approach / Test docs	✅	❌	❌
Approach-Impl gap analysis	✅	❌	❌
Iterative review (auto-fix + retry)	✅	❌	❌
Progress tracking across sessions	✅	❌	❌

---

Workflow

graph LR
    DSC["/jira-task discover\nTopic → requirements doc"] -.-> N["/jira-task create\nNew issue + sub-tasks"]
    N -.-> A["/jira-task init\nBatch worktree setup"]
    A --> B["/jira-task start\nIn Progress"]
    B --> C["/jira-task approach\nApproach doc (L1/L2/L3)"]
    C --> E["/jira-task impl\nImplement"]
    E --> F["/jira-task test\nE2E + unit tests"]
    F --> G["/jira-task review\nGap analysis + review"]
    G --> H["/jira-task merge\nLocal merge"]
    H --> I["/jira-task pr\nCreate GitHub PR"]
    I --> J["/jira-task done\nDone"]

    AUTO["⚡ /jira-task auto\nstart→review (auto)"]

    style DSC fill:#A0522D,color:#fff
    style N fill:#8B4513,color:#fff
    style A fill:#2B50D4,color:#fff
    style J fill:#156030,color:#fff
    style AUTO fill:#7B2D8B,color:#fff

Discover (optional first step): /jira-task discover "<topic>" turns a free-form topic into a structured docs/requirements/<slug>.requirements.md, which /jira-task create --from-requirements <file> can then consume to bulk-register Epic/Story/Sub-tasks.

Shortcut: /jira-task auto <ID> runs start → approach → impl → test → review automatically. Each step runs as an isolated sub-agent, and already-completed steps are skipped. If review fails, it auto-fixes and retries (up to 2×).

Each step automatically posts a comment and/or attachment to the Jira issue and transitions its status.

---

Key Features

Interactive Issue Creation (v0.12.0) /jira-task create [hint] registers a brand-new Jira issue from conversation context. If context is thin, it asks a few batched questions; if the scope warrants it, it proposes a sub-task breakdown (with Blocks links for dependencies so downstream init can auto-detect ready-to-start sub-tasks). Supports linking to an existing epic.

• No raw jira_create_issue footguns: the skill encodes the exact mcp-atlassian schema (e.g. additional_fields is a JSON string, parent is a bare key, priority is {"name": "..."}, components is a CSV string, assignee must be top-level).
• Auto sub-task decision: the skill judges whether to split based on scope; no flag needed.
• Silent-skip guard: re-fetches created issues to verify priority/labels actually landed (unknown additional_fields keys are otherwise dropped with only a warning).

Auto Mode (v0.9.0) /jira-task auto PROJ-123 runs the full start → approach → impl → test → review pipeline automatically.

• Sub-agent isolation: Each step runs as an independent sub-agent, preventing context pollution between stages.
• Iterative review: When review finds issues (gap analysis or code quality), auto-fix → test → review retries up to 2 times before stopping.
• Smart resume: Already-completed steps are skipped based on .jira-context.json.
• Scope boundary: merge, pr, done are excluded (cross-worktree / externally visible actions require manual confirmation).

Interactive Setup Wizard (v0.6.0) /jira setup guides you through prerequisites (uv, Python 3.10+), credential collection, MCP server registration, and connection validation — no manual CLI commands needed.

Multi-Worktree Parallel Development (v0.7.0) /jira-task init supports three argument modes: count (init 5 — bulk setup), issue key (init PROJ-123 — sub-task analysis), or natural language (init "auth 관련 작업" — filtered search). Creates isolated git worktrees for each task.

Document Auto-generation Generates requirements / approach / test report / review / PR description documents from dedicated templates under templates/, then immediately posts them as Jira attachments and comments via scripts/jira-attach.sh. No copy-paste required.

Reviewer Calibration Log (v0.22.x) Each /jira-task review run appends a structured entry to docs/review-log/ (redacted per the project's policy). scripts/analyze-review-log.py aggregates pass/fail rates and recurring findings over time so reviewer behavior doesn't silently drift toward self-praise.

Status Transition Automation start → In Progress, merge → In Review, done → Done. Jira stays up to date without opening a browser.

Approach-Impl Gap Analysis /jira-task review compares your approach document against actual code changes and flags discrepancies alongside code quality issues.

Session Continuity Progress is tracked in .jira-context.json. Reopen Claude Code anytime and see exactly where you left off:

Progress: init ✓ → start ✓ → approach ✓ → impl → test → review → merge → pr → done

---

Prerequisites

Requirement	Required	Purpose
Claude Code	Yes	CLI environment
Python 3.10+ + uv	Yes	Run MCP server (uvx mcp-atlassian)
Git	Yes	Branch / worktree management
Jira Cloud account + API Token	Yes	Jira integration
GitHub CLI (gh)	PR step only	Create GitHub PRs

---

Quick Start

# 1. Install the plugin
claude plugin marketplace add mzd-hseokkim/jira-claude-code-integration
claude plugin install jira-integration@jira-claude-code-integration

# 2. Register the Atlassian MCP server
claude mcp add atlassian \
  -e JIRA_URL=https://your-domain.atlassian.net \
  -e JIRA_USERNAME=your-email@company.com \
  -e JIRA_API_TOKEN=your-api-token \
  -e JIRA_PROJECTS_FILTER=PROJ \
  -- uvx mcp-atlassian

# 3. Verify connection
claude
> /jira

# 4a. (Optional) Create a brand-new issue interactively
> /jira-task create auth 모듈에 OTP 2차 인증 추가    # → parent + sub-tasks + Blocks links

# 4b. Fetch your top tasks and set up worktrees
> /jira-task init 5

# 5a. Auto mode — run the full pipeline in one command
> cd ../your-project_worktree/PROJ-123
> /jira-task auto       # start → approach → impl → test → review

# 5b. Or step-by-step (TASK-ID is auto-detected from branch/directory)
> /jira-task start      # Transition to In Progress
> /jira-task approach   # Generate approach doc (L1/L2/L3)
> /jira-task impl       # Implement based on approach
> /jira-task test       # Run tests + post report to Jira
> /jira-task review     # Gap analysis + code review
> /jira-task merge      # Merge locally (choose strategy)

# 6. Back in the main repo
> cd ../your-project
> /jira-task pr         # Push branch + create GitHub PR
> /jira-task done       # Transition to Done + post summary

---

Setup

Step 1: Install the Plugin

claude plugin marketplace add mzd-hseokkim/jira-claude-code-integration
claude plugin install jira-integration@jira-claude-code-integration

# For local dev / testing:
claude --plugin-dir /path/to/jira-claude-code-integration

Tip: Instead of running claude mcp add manually, you can use the interactive wizard after installing the plugin:

> /jira setup

The wizard checks prerequisites, collects your credentials, registers the MCP server, and validates the connection.

Step 2: Create a Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Enter a label (e.g. claude-code) → Create
4. Copy the token (shown only once)

Step 3: Register the MCP Server

claude mcp add atlassian \
  -e JIRA_URL=https://your-domain.atlassian.net \
  -e JIRA_USERNAME=your-email@company.com \
  -e JIRA_API_TOKEN=your-api-token \
  -e JIRA_PROJECTS_FILTER=PROJ \
  -- uvx mcp-atlassian

This saves credentials to .claude/settings.local.json. Add it to .gitignore:

.claude/settings.local.json

Variable	Required	Description
JIRA_URL	Yes	Jira Cloud URL (no trailing /)
JIRA_USERNAME	Yes	Atlassian account email
JIRA_API_TOKEN	Yes	API token from Step 2
JIRA_PROJECTS_FILTER	No	Comma-separated project keys (e.g. PROJ,DEV)

Step 4: Verify Connection

claude
> /jira

---

Commands

Command	Run from	Description
/jira	anywhere	Connection status + help
/jira setup	anywhere	Interactive setup wizard (prerequisites → credentials → MCP registration → validation)
/jira-task discover [topic]	anywhere	Turn a free-form topic into a requirements doc (docs/requirements/<slug>.requirements.md) for /jira-task create --from-requirements
/jira-task create [hint]	anywhere	Interactively create a new Jira issue with optional sub-tasks, dependency links, and epic linking
/jira-task init [N|KEY|desc]	main repo	Fetch tasks + create worktrees (count, issue key, or natural language)
/jira-task auto <ID>	worktree	Auto-run full pipeline with sub-agent isolation + iterative review
/jira-task start [ID]	worktree	Start task (branch, In Progress)
/jira-task approach [ID]	worktree	Generate docs/approach/<ID>.approach.md (L1/L2/L3 level-aware; replaces plan+design)
/jira-task impl [ID]	worktree	Implement based on approach doc
/jira-task test [ID]	worktree	Run tests + post report to Jira
/jira-task review [ID]	worktree	Gap analysis + code review → Jira
/jira-task merge [ID]	worktree	Merge locally (strategy: ff/squash/rebase)
/jira-task pr [ID]	main repo	Push branch + create GitHub PR
/jira-task done [ID]	main repo	Transition Done + post summary
/jira-task clean <ID...>|--all|--list	main repo	Remove worktree, delete branch, clean MCP config + context
/jira-task report	anywhere	My assigned issues status report
/jira-task status	anywhere	Current active task status

TASK-ID Auto-detection

When working inside a worktree, [ID] can be omitted. It is resolved in this order:

1. Git branch name: feature/PROJ-123 → PROJ-123
2. Current directory name matching [A-Z]+-\d+
3. .jira-context.json active task ID

---

Project Structure

jira-claude-code-integration/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest
│   └── marketplace.json
├── CLAUDE.md                    # Claude behavior instructions
│
├── commands/
│   ├── jira.md                  # /jira
│   ├── jira-task.md             # /jira-task (router)
│   └── dashboard.md             # /dashboard (alias of /jira dashboard)
│
├── skills/                      # One SKILL.md per workflow step
│   │                            # Heavy SKILLs use refs/ for split details:
│   │                            #   skills/<name>/refs/<topic>.md is loaded
│   │                            #   on demand by Read, not into the system
│   │                            #   prompt. See SKILL bodies for explicit
│   │                            #   `Read skills/<name>/refs/...` calls.
│   ├── _shared/                 # script-lookup.md 등 공용 스니펫
│   ├── jira-setup/              # interactive setup wizard
│   ├── jira-dashboard/          # /jira dashboard 라우팅 SKILL
│   ├── jira-task-discover/      # topic → requirements doc
│   │   └── refs/                # conflict-detection / synthesis-confirm / trace-markers
│   ├── jira-task-create/        # interactive issue creation
│   │   └── refs/                # mcp-schema / from-requirements-mode
│   ├── jira-task-init/
│   │   └── refs/                # issue-key-mode / worktree-creation
│   ├── jira-task-auto/          # auto-run full pipeline
│   ├── jira-task-start/
│   ├── jira-task-approach/      # level-aware approach doc (replaces plan+design)
│   ├── jira-task-impl/
│   ├── jira-task-test/
│   ├── jira-task-review/        # heavy logic extracted to scripts/append-review-log.py
│   ├── jira-local-merge/
│   ├── jira-task-pr/
│   ├── jira-task-done/
│   ├── jira-task-clean/
│   └── jira-task-report/
│
├── agents/                      # Subagent definitions
│   └── jira-reviewer.md         # Gap analysis + code quality (forced delegation, opus)
│
├── hooks/                       # Session event hooks
│   ├── hooks.json
│   └── scripts/
│       ├── session-start.js         # Show active task on startup
│       ├── stop-sync.js             # Remind to sync Jira on exit
│       ├── dashboard-ingest.sh      # Forward UserPromptSubmit/PreToolUse/PostToolUse/SubagentStop/Notification → POST /ingest
│       ├── dashboard-ingest.test.sh # Unit test for dashboard-ingest.sh
│       ├── stop-ingest.sh           # Forward Stop event (extracts last assistant text from transcript)
│       ├── phase-gate.js            # Phase dependency hook (disabled by default)
│       ├── phase-gate.config.json
│       ├── phase-gate.test.js
│       └── phase-gate.scenarios.test.js
│
├── scripts/                     # Helper scripts invoked by skills
│   ├── jira-attach.sh             # Upload attachments via Jira REST API
│   ├── jira-context-update.py     # merge/done: completedSteps/status 동기화
│   ├── clean-worktree.py          # Worktree/branch cleanup helper
│   ├── cleanup-worktree-mcp.py    # done: worktree 단위 MCP config 정리
│   ├── analyze-review-log.py      # Reviewer calibration log analyzer
│   ├── append-review-log.py       # /jira-task review: append entry to review-log
│   ├── append-review-log-wrapper.sh # review SKILL → append-review-log.py wrapper
│   ├── propagate-mcp-config.sh    # /jira-task init: propagate MCP config to worktree
│   ├── dashboard-control.sh       # /jira dashboard start/stop/status/setup 제어
│   ├── dashboard/                 # Dashboard 서버 + React SPA 소스
│   └── review_log/                # Stored reviewer calibration entries
│
├── templates/                   # Document templates per workflow step
│   ├── requirements.template.md
│   ├── approach.template.md
│   ├── test-report.template.md
│   ├── review.template.md
│   ├── pr-description.template.md
│   └── report.template.md
│
├── docs/                        # Plugin reference docs
│   ├── mcp-atlassian-tools.md   # Tool reference for the Atlassian MCP server
│   └── review-log/              # Review log schema + sample entries
│                                # (PDCA outputs approach/test/review/
│                                #  requirements are gitignored as
│                                #  per-task artifacts)
│
└── tests/                       # Python tests for analyze-review-log
    ├── test_analyze_review_log.py
    └── fixtures/

Phase Gate (실험적 — 현재 비활성화)

/jira-task 단계 호출 순서를 강제하는 PreToolUse hook이 코드베이스에 포함되어 있지만, 기본적으로 비활성화 상태입니다. 활성화하려면 명시적으로 hook을 등록해야 합니다.

구현된 것 (Phase 1.2.1 ~ 1.2.4)

• hooks/scripts/phase-gate.config.json — 12 phase 의존 그래프 + artifact 패턴
• hooks/scripts/phase-gate.js — Node hook 스크립트 (의존성 미충족 시 차단, fail-open 설계)
• hooks/scripts/phase-gate.test.js, phase-gate.scenarios.test.js — 단위 20 + 시나리오 5 테스트
• bypass 메커니즘: JIRA_PHASE_GATE_BYPASS=1 (1회성), .jira-context.json의 bypassGate: true (영속)

왜 비활성화 상태인가

이 플러그인은 본래 "원하는 단계만 골라 쓰는 도구함"으로 설계되었습니다 (작은 fix는 approach 생략, 문서 작업은 impl 생략 등). phase-gate를 켜면 모든 인접 단계가 강제 선행 조건이 되어 이 유연성을 깨뜨립니다. 따라서 강제 선형 워크플로를 원하는 팀만 명시적으로 켤 수 있도록 비활성화 상태로 둡니다.

활성화 방법

hooks/hooks.json의 hooks 객체에 다음 항목을 추가하세요:

"PreToolUse": [
  {
    "matcher": "Skill",
    "hooks": [
      {
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.js",
        "timeout": 5
      }
    ]
  }
]

커스터마이즈

phase-gate.config.json을 편집해 의존성을 완화하거나(requires 비우기), 필수 artifact를 바꾸거나, 특정 단계를 enforced: false로 끌 수 있습니다.

테스트 실행

npm test   # unit 20 + scenarios 5

Worktree Layout

workspace/
├── your-project/                  ← main repo (base branch)
└── your-project_worktree/         ← created by /jira-task init
    ├── PROJ-101/                  ← feature/PROJ-101 branch
    ├── PROJ-102/
    └── PROJ-103/

---

Multi-Worktree Merge Strategy

When multiple tasks touch the same files, merging in the wrong order causes conflicts.

Check for file overlap at design time
├─ No overlap            → PR in any order
├─ Overlap (independent releases) → Sequential rebase-and-merge
└─ Overlap (release together)     → Integration branch strategy

Check before starting implementation:

git diff --name-only main feature/PROJ-101
git diff --name-only main feature/PROJ-102

Available merge strategies when running /jira-task merge:

Strategy	Description	Equivalent GitHub option
--no-ff (default)	Merge commit, preserves branch history	Create a merge commit
--squash	Squash all commits into one	Squash and merge
rebase	Linear history, no merge commit	Rebase and merge

---

Troubleshooting

"Atlassian MCP server not connected"

claude mcp list                  # Check registered servers
claude mcp get atlassian         # Verify env vars
uvx mcp-atlassian                # Test server directly (Ctrl+C to stop)
pip install uv                   # Install uv if missing

"Transition failed"

"Show available transitions for PROJ-123"

Transition names vary by Jira workflow. Common names: To Do, In Progress, In Review, Done.

"Authentication failed"

• Verify JIRA_USERNAME matches your Atlassian account email exactly
• Confirm JIRA_URL has no trailing /
• Check if the API token has expired

"gh CLI not found"

# macOS
brew install gh && gh auth login

# Windows
winget install GitHub.cli && gh auth login

Worktree creation failed

git rev-parse --git-dir          # Confirm you're in a git repo
git branch -a | grep feature/    # Check for existing branches
git worktree prune               # Clean stale worktree refs

---

Dashboard

A real-time activity monitor for every Claude Code worktree in your workspace. Hook events from each session (user prompts, tool calls, sub-agent lifecycle, final responses) stream into a browser UI via SSE so you can see at a glance which session is busy, which is waiting on you, and what each one just answered.

Quick Start (원클릭)

Claude Code 안에서 슬래시 커맨드 한 줄로 Dashboard를 시작할 수 있습니다:

/jira dashboard

첫 실행 시 npm 의존성 설치와 UI 빌드를 자동으로 수행한 뒤 서버를 기동합니다. 두 번째 이후 실행부터는 캐시 감지로 setup을 건너뛰고 바로 시작합니다.

커맨드	동작
/jira dashboard	상태 확인 → stopped이면 자동 setup+start
/jira dashboard start	Dashboard 시작
/jira dashboard stop	Dashboard 중지
/jira dashboard status	현재 상태 조회 (URL/PID/시작 시각)
/jira dashboard setup	npm 의존성 설치 및 UI 빌드만 수행

서버는 http://127.0.0.1:8765에 바인딩됩니다.

수동 실행 (Troubleshooting)

슬래시 커맨드 없이 직접 실행해야 하는 경우:

# 1) Install root deps (express, chokidar)
npm install

# 2) Install web deps and build the SPA bundle into scripts/dashboard/public/
npm --prefix scripts/dashboard/web install
npm --prefix scripts/dashboard/web run build

# 3) Start the dashboard server
npm run dashboard
# or: node scripts/dashboard/server.js

After the first build, daily use is just npm run dashboard. Re-run the build step whenever the React source changes.

The server binds to http://127.0.0.1:8765 and opens your default browser automatically.

DASHBOARD_NO_OPEN=1 npm run dashboard   # suppress auto-open (CI / headless)
PORT=9000 npm run dashboard              # override default port

What you see on each card

• Header — Jira task id (or directory name when no Jira context), issue type, outlined status badge with leading dot (Jira workflow status, distinct from agent activity), ⚙ N cumulative tool calls in this session, X분 전 last activity, and badges for ⏵ 응답 대기 / stale / ⛔ blocked × N.
• SDLC stepper — One chip per /jira-task step (init/start/approach/impl/test/review/merge/pr/done) coloured by completedSteps in .jira-context.json. Skipped intermediate steps after done are shown with strikethrough.
• Activity panel — Last prompt, Last response (final concluding line of Claude's reply), current tool-in-flight, sub-agent indicator, and a blocked flag. Prompt/response signals are persisted on the server independent of the activity ring buffer so they survive long tool-call bursts.
• Issue links — Below the meta row, blocks / blocked by chips show related issue keys. Open blockers are highlighted; resolved ones are struck through.
• Card border state:
  • Blue glow + pulse = busy. Defined as "a UserPromptSubmit event without a matching Stop yet" — i.e. Claude is generating right now. Time-independent.
  • Amber glow + pulse + 응답 대기 badge = busy and most recent Notification mentions permission/input/waiting.
  • Red left stripe + ⛔ blocked badge = at least one un-resolved is blocked by link.
  • Dim + stale badge = Jira status is 완료 but the worktree still exists (cleanup candidate).
• Header bar (KITT) — Top of viewport scans left-right while connected (SSE live). The connection chip in the top-right fills bottom-up to indicate countdown to the next jira-collector poll.
• Sort & filter — Header has chips for sort key (activity / taskId / summary) and a search field that matches taskId / summary / branch / path.
• View toggle: Cards ↔ Graph (v0.30.x) — Header has a Cards / Graph toggle. Graph mode renders worktrees as a force-directed graph (react-flow + d3-force) showing blocks / parent / epic relationships with color-coded edges, marching-ants flow direction, and arrow markers. Parent/epic edges anchor the hierarchy (parent on top, children below); blocks edges connect siblings. Click a node → side panel with the full WorktreeCard. Drag a node → it pins in place (simulation won't drag it back). Status/assignee chip filters dim non-matches; isolated nodes get a dashed border; cycle members get heavier red dashes.
• Cleanup button (v0.30.x) — Cards in stale state (Jira 완료 but worktree alive) get a 🗑 정리 floating button on hover at the bottom-right. Click → confirm → server runs git worktree remove + git branch -d. Backend safety: only registered worktrees, only when status is done, dirty trees rejected, branch name read from store (no body injection).
• Cards without Jira context (e.g. main repo while running /jira dashboard) show only directory + path + activity, with stepper and Jira-only fields hidden.

Hooks

Hook events are wired in hooks/hooks.json, forwarded by two small scripts in hooks/scripts/ to POST /ingest, then broadcast via SSE:

Hook	Forwarder	Used for
UserPromptSubmit	dashboard-ingest.sh	Last prompt + busy detection
PreToolUse	dashboard-ingest.sh	Current tool, tool-call counter
PostToolUse	dashboard-ingest.sh	Closes a tool-in-flight marker
SubagentStop	dashboard-ingest.sh	Sub-agent active indicator
Notification	dashboard-ingest.sh	Awaiting / blocked detection
Stop	stop-ingest.sh	Last response preview (reads transcript_path)

Each ingest is mapped to a worktree path and Jira task id via .jira-context.json. SessionStart and Stop also drive non-dashboard side-effects (Jira context injection, end-of-session reminder) — those forwarders are independent.

Logs

Log file: <workspaceRoot>/logs/dashboard-server.log

• Append-only JSON Lines format; no rotation in this release.
• Sensitive fields (apiToken, Authorization) are automatically redacted to [REDACTED] before writing.
• The server prints the absolute log path to stdout on startup.

Out of Scope

• Log rotation / size capping
• Authentication / remote access (currently localhost-only by design)
• Browser env var (BROWSER) support on Linux
• Windows PowerShell fallback (current: cmd /c start)
• Fallback stdout URL prompt on browser-open failure

---

Roadmap

• Interactive setup wizard: /jira setup (v0.6.0)
• Auto mode: /jira-task auto (v0.6.0)
• Init argument expansion: count, issue key, natural language (v0.7.0)
• Iterative review: auto-fix + test + review retry loop (v0.8.0)
• Sub-agent isolation: each auto step in independent context (v0.9.0)
• Interactive issue creation: /jira-task create (v0.12.0)
• Requirements discovery: /jira-task discover → docs/requirements/<slug>.requirements.md (v1.1.x)
• Reviewer calibration log: review history analyzer (scripts/analyze-review-log.py) (v0.22.x)
• SKILL bloat refactor: 4 heavy SKILLs (create/discover/init/review) compressed from 1,989 → 921 lines (-54%) via skills/<name>/refs/ split + script extraction (v0.24.0)
• Dashboard graph view: react-flow + d3-force visualization of blocks / parent / epic relationships with hierarchical force layout, drag-to-pin, status/assignee filters, isolated/cycle highlighting (v0.30.x — Epic MAE-249)
• Dashboard worktree cleanup button: in-card 🗑 정리 floating action for stale worktrees, with safety guards on the backend POST /cleanup (v0.30.x)
• Plan + Design → unified /jira-task approach (level-aware L1/L2/L3 sizing) (v0.33.0 — MAE-350)
• L3 Epic empty-child sequencing guard for /jira-task auto (early exit + guidance) (v0.34.0 — MAE-364)
• Auto SKILL.md hygiene: Scope Shortfall 출처 trail + PDCA 자동 분기 안내 (v0.34.0 — MAE-366)
• Bitbucket Cloud + GitLab MR support for /jira-task pr
• Jira Server / Data Center (Personal Access Token)
• Sub-task auto-creation from approach doc task breakdown
• Time tracking: auto-log work sessions to Jira
• CI/CD result posting (GitHub Actions, Bitbucket Pipelines)
• Slack / Teams notifications on PR creation and task completion
• English documentation for all templates

---

License

MIT

---

한국어 요약

이 플러그인은 Jira + Claude Code를 연결하는 개발 워크플로우 자동화 도구입니다.

대시보드

Claude Code 안에서 /jira dashboard 한 줄로 셋업·기동을 자동 수행합니다. 첫 실행 시 npm 의존성 설치와 UI 빌드를 자동으로 처리하고, 두 번째부터는 캐시 감지로 즉시 시작합니다.

커맨드	동작
/jira dashboard	상태 확인 → stopped이면 자동 setup+start
/jira dashboard start/stop/status/setup	개별 액션

서버는 http://127.0.0.1:8765에 바인딩되며 기본 브라우저가 자동으로 열립니다. 수동 실행은 npm run dashboard로도 가능 (CI/헤드리스: DASHBOARD_NO_OPEN=1, 포트 변경: PORT=9000).

각 worktree 카드는 다음을 보여줍니다:

• 상단 배지: Jira 워크플로 상태(outlined + 좌측 dot), 누적 도구 호출 수(⚙ N), 마지막 활동 상대시간, 상태별 배지(⏵ 응답 대기 / stale / ⛔ blocked × N)
• SDLC stepper: .jira-context.json의 completedSteps 기반 단계 진행. done 후 건너뛴 중간 단계는 취소선 표시
• 활동 패널: 마지막 prompt, 마지막 응답의 결론 줄, 진행 중 도구, sub-agent / blocked 상태. prompt/response 신호는 ring buffer와 별도로 서버에 보존되어 도구 호출 폭주에도 사라지지 않음
• 이슈 링크: blocks / blocked by 칩 표시. 미해결 blocker는 강조, 완료된 것은 취소선
• 카드 보더 상태:
  • 파란 펄스 = busy — UserPromptSubmit 이후 Stop이 아직 안 옴(시간 임계값 없음, "지금 응답 생성 중")
  • 앰버 펄스 + 응답 대기 배지 — busy + 최근 Notification이 permission/input/waiting을 포함
  • 빨간 좌측 stripe + ⛔ blocked 배지 — 미해결 is blocked by 링크 존재
  • dim + stale 배지 — Jira 상태가 완료인데 worktree가 아직 살아있음(정리 대상)
• 상단 KITT 바: SSE 연결 시 좌→우 스캔. LIVE 칩은 다음 jira-collector polling까지의 진행률을 아래→위로 fill
• 정렬/필터: 헤더에 정렬 칩(최근활동 / 이슈키 / summary) + 제목 검색 필드(taskId/summary/branch/path 매치)
• 카드/그래프 뷰 토글 (v0.30.x): 헤더에서 두 모드 전환. 그래프 모드는 worktree를 force-directed 그래프(react-flow + d3-force)로 렌더링하여 blocks / parent / epic 관계를 색상 분리된 엣지(흐르는 점선 + 화살표)로 표시. parent/epic edge가 계층(부모 위, 자식 아래)을 형성하고 blocks edge는 형제 노드를 연결. 노드 클릭 → 우측 사이드 패널에 풀 카드, 노드 드래그 → 그 자리 고정(simulation이 끌어당기지 않음). status/assignee 필터·고립 노드(dashed border)·순환 엣지(굵은 빨간 점선) 강조 지원
• 정리 버튼 (v0.30.x): stale 상태(Jira 완료 + worktree 생존) 카드 우하단에 hover 시 🗑 정리 floating 버튼 노출. 클릭 → confirm → 서버가 git worktree remove + git branch -d 실행. 백엔드 안전장치(등록된 worktree만, 완료 상태만, dirty 거부, branch 이름은 store에서만 조회)
• Jira context 없는 카드(예: 메인 레포): 디렉토리명·path·활동만 표시, stepper와 Jira 전용 필드는 숨김

Hook 흐름: hooks/hooks.json → hooks/scripts/dashboard-ingest.sh(UserPromptSubmit·PreToolUse·PostToolUse·SubagentStop·Notification) / hooks/scripts/stop-ingest.sh(Stop, transcript에서 마지막 assistant 텍스트 추출) → POST /ingest → SSE. 서버 로그는 <workspaceRoot>/logs/dashboard-server.log(JSON Lines, 민감 필드 자동 redact).

핵심 특징

• /jira-task discover [주제] — 자연어 주제를 요구사항 문서(docs/requirements/<slug>.requirements.md)로 변환. /jira-task create --from-requirements <파일>과 자연 연동되어 Epic/Story/Sub-task 일괄 등록의 입력으로 사용됨 (v1.1.x)
• /jira-task create [힌트] — 대화 컨텍스트 기반으로 신규 Jira 이슈를 대화형 생성. 범위가 크면 서브태스크 분해를 스킬이 직접 제안하고, 의존성은 Blocks 링크로 등록되어 이후 init의 "착수 가능 분석"과 자연 연동. 기존 에픽 연결 지원. mcp-atlassian의 jira_create_issue 필드 규약(JSON string additional_fields, bare-key parent, CSV components 등)을 스킬에 박아 반복 실패 방지 (v0.12.0)
• /jira-task init — 숫자(init 5), 이슈 키(init PROJ-123), 자연어(init "인증 관련") 세 가지 모드로 worktree 일괄 생성 (v0.7.0)
• Auto 모드 (/jira-task auto PROJ-123): 각 단계를 독립 sub-agent로 실행하여 컨텍스트 오염 방지. review 미통과 시 자동 수정 → 재테스트 → 재리뷰 최대 2회 반복 (v0.9.0)
• 설정 위자드 (/jira setup): 사전 요건 확인 → 자격증명 입력 → MCP 등록 → 연결 검증 대화형 안내 (v0.6.0)
• 접근 설계(approach) → 구현 → 테스트 → 리뷰 → PR → 완료까지 전 단계 커맨드화 (plan/design 두 단계는 v0.33.0에서 approach로 통합)
• 각 단계 완료 시 Jira 코멘트·첨부파일·상태 전이 자동 처리
• approach 문서와 실제 구현 코드 간 Gap 자동 분석
• Reviewer Calibration Log — 매 review 결과를 docs/review-log/에 누적하고 scripts/analyze-review-log.py로 통과율·반복 지적 패턴을 분석해 리뷰어 self-praise drift 방지 (v0.22.x)
• .jira-context.json으로 세션 간 진행 상황 자동 복원

설치

claude plugin marketplace add mzd-hseokkim/jira-claude-code-integration
claude plugin install jira-integration@jira-claude-code-integration

플러그인 설치 후 /jira setup을 실행하면 대화형으로 MCP 서버를 설정할 수 있습니다. 또는 직접 등록:

claude mcp add atlassian \
  -e JIRA_URL=https://your-domain.atlassian.net \
  -e JIRA_USERNAME=your-email@company.com \
  -e JIRA_API_TOKEN=your-api-token \
  -- uvx mcp-atlassian

자세한 설정은 상세 설정 섹션을 참고하세요.

기타

• 커맨드 목록, Worktree 전략, 트러블슈팅 등 상세 내용은 영문 섹션에 동일하게 기술되어 있습니다.
• 이슈·제안은 GitHub Issues에 남겨주세요.