https://github.com/mzd-hseokkim/jira-claude-code-integration
Automate your entire dev workflow — from Jira issue to merged PR — inside Claude Code. Jira 이슈부터 PR 완료까지 전 단계 자동화 플러그인.
https://github.com/mzd-hseokkim/jira-claude-code-integration
agile atlassian automation claude-code developer-workflow jira mcp
Last synced: 2 months ago
JSON representation
Automate your entire dev workflow — from Jira issue to merged PR — inside Claude Code. Jira 이슈부터 PR 완료까지 전 단계 자동화 플러그인.
- Host: GitHub
- URL: https://github.com/mzd-hseokkim/jira-claude-code-integration
- Owner: mzd-hseokkim
- Created: 2026-02-15T01:50:07.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T17:49:25.000Z (3 months ago)
- Last Synced: 2026-05-03T19:06:07.471Z (3 months ago)
- Topics: agile, atlassian, automation, claude-code, developer-workflow, jira, mcp
- Language: JavaScript
- Size: 1.25 MB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# jira-integration · Claude Code Plugin
**[English]** | [한국어](#korean)
[](#)
[](LICENSE)
[](https://docs.anthropic.com/en/docs/claude-code)
[](https://github.com/sooperset/mcp-atlassian)
> **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
```mermaid
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 ""` turns a free-form topic into a structured `docs/requirements/.requirements.md`, which `/jira-task create --from-requirements ` can then consume to bulk-register Epic/Story/Sub-tasks.
> **Shortcut**: `/jira-task auto ` 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](https://docs.anthropic.com/en/docs/claude-code) | Yes | CLI environment |
| Python 3.10+ + [uv](https://docs.astral.sh/uv/) | Yes | Run MCP server (`uvx mcp-atlassian`) |
| [Git](https://git-scm.com/) | Yes | Branch / worktree management |
| Jira Cloud account + API Token | Yes | Jira integration |
| [GitHub CLI (`gh`)](https://cli.github.com/) | PR step only | Create GitHub PRs |
---
## Quick Start
```bash
# 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
```bash
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
```bash
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
```bash
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/.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 ` | 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/.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 \|--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//refs/.md is loaded
│ │ # on demand by Read, not into the system
│ │ # prompt. See SKILL bodies for explicit
│ │ # `Read skills//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` 객체에 다음 항목을 추가하세요:
```json
"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`로 끌 수 있습니다.
**테스트 실행**
```bash
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:
```bash
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"**
```bash
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"**
```bash
# macOS
brew install gh && gh auth login
# Windows
winget install GitHub.cli && gh auth login
```
**Worktree creation failed**
```bash
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)
슬래시 커맨드 없이 직접 실행해야 하는 경우:
```bash
# 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.
```bash
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: `/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
- [x] Interactive setup wizard: `/jira setup` *(v0.6.0)*
- [x] Auto mode: `/jira-task auto` *(v0.6.0)*
- [x] Init argument expansion: count, issue key, natural language *(v0.7.0)*
- [x] Iterative review: auto-fix + test + review retry loop *(v0.8.0)*
- [x] Sub-agent isolation: each auto step in independent context *(v0.9.0)*
- [x] Interactive issue creation: `/jira-task create` *(v0.12.0)*
- [x] Requirements discovery: `/jira-task discover` → `docs/requirements/.requirements.md` *(v1.1.x)*
- [x] Reviewer calibration log: review history analyzer (`scripts/analyze-review-log.py`) *(v0.22.x)*
- [x] SKILL bloat refactor: 4 heavy SKILLs (create/discover/init/review) compressed from 1,989 → 921 lines (-54%) via `skills//refs/` split + script extraction *(v0.24.0)*
- [x] 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)*
- [x] Dashboard worktree cleanup button: in-card `🗑 정리` floating action for stale worktrees, with safety guards on the backend `POST /cleanup` *(v0.30.x)*
- [x] Plan + Design → unified `/jira-task approach` (level-aware L1/L2/L3 sizing) *(v0.33.0 — MAE-350)*
- [x] L3 Epic empty-child sequencing guard for `/jira-task auto` (early exit + guidance) *(v0.34.0 — MAE-364)*
- [x] 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. 서버 로그는 `/logs/dashboard-server.log`(JSON Lines, 민감 필드 자동 redact).
### 핵심 특징
- **`/jira-task discover [주제]`** — 자연어 주제를 **요구사항 문서(`docs/requirements/.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`으로 **세션 간 진행 상황 자동 복원**
### 설치
```bash
claude plugin marketplace add mzd-hseokkim/jira-claude-code-integration
claude plugin install jira-integration@jira-claude-code-integration
```
플러그인 설치 후 `/jira setup`을 실행하면 대화형으로 MCP 서버를 설정할 수 있습니다. 또는 직접 등록:
```bash
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
```
자세한 설정은 [상세 설정 섹션](#setup-·-상세-설정)을 참고하세요.
### 기타
- 커맨드 목록, Worktree 전략, 트러블슈팅 등 상세 내용은 영문 섹션에 동일하게 기술되어 있습니다.
- 이슈·제안은 [GitHub Issues](https://github.com/mzd-hseokkim/jira-claude-code-integration/issues)에 남겨주세요.