jira-task-init

name	jira-task-init
description	Fetch assigned high-priority Jira tasks and set up git worktrees for each (count, issue key, or natural language). Triggers: jira-task init, init sprint, setup tasks; 작업 환경 세팅, 스프린트 초기화, 할당된 작업 가져와.
user-invocable	false
argument-hint	[count | ISSUE-KEY | 자연어설명]
allowed-tools	["Read","Write","Edit","Bash","Glob"]

jira-task-init: Bulk Sprint/Task Initialization

Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력, Jira 코멘트 제목은 영어).

나에게 할당된 Jira 태스크를 우선순위 순으로 가져와서 각각 git worktree를 생성하고 작업 컨텍스트를 세팅하는 일괄 처리 워크플로우.

Prerequisites

• Jira 호출은 scripts/jira-cli.py (규약: Read skills/_shared/jira-cli.md). 호출 prompt가 <scripts>/ 절대 경로를 줬으면 그대로, 없으면 skills/_shared/script-lookup.md로 SCRIPT_NAME="jira-cli.py" 1회 해석.
• 현재 디렉토리가 git repository 내부
• 자격증명: 메인 레포 .jira-context.json의 jira 블록 (없으면 환경변수 JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN)

Workflow

Step 0: Argument Parsing

인자를 분석하여 3가지 모드 중 하나로 분류한다:

1. 숫자 (Count 모드): 인자가 없거나 숫자만 있으면 → 기존 동작. Step 1로 진행.
   • 예: "", "3", "5"
2. 이슈 키 (Issue Key 모드): 인자에 Jira 이슈 키 패턴([A-Z]+-\d+, 예: MAE-2, PROJ-123)이 포함되면 → Step 1-B로 진행.
   • 예: "MAE-2", "MAE-2 하위작업 분석해서 착수 가능한 것만"
   • 자연어 속에 이슈 키가 포함된 경우에도 이슈 키를 추출하여 Issue Key 모드로 처리
3. 자연어 (이슈 키 미포함): 이슈 키 패턴이 없는 자연어만 있으면 → 사용자에게 이슈 키를 확인 요청. 이슈 키를 받으면 Step 1-B, 숫자를 받으면 Step 1로 진행.

Step 1: Fetch My Assigned Tasks (Count 모드)

사용자에게 몇 개의 태스크를 가져올지 확인 (기본값: 5).

JQL 쿼리로 나에게 할당된 고우선순위 태스크 조회. JIRA_DEFAULT_PROJECT가 설정되어 있으면 project = <JIRA_DEFAULT_PROJECT> 조건은 CLI가 자동 삽입한다.

python3 "<scripts>/jira-cli.py" search "assignee = currentUser() AND status NOT IN (Done, Closed) ORDER BY priority DESC, created ASC" --limit 20

또는 활성 스프린트가 있으면 스프린트 기반으로 조회:

1. python3 "<scripts>/jira-cli.py" boards [PROJECT]로 보드 목록 확인
2. python3 "<scripts>/jira-cli.py" sprints <BOARD-ID> active로 활성 스프린트 확인
3. python3 "<scripts>/jira-cli.py" search "sprint = <active-sprint-id> AND assignee = currentUser() AND status NOT IN (Done, Closed) ORDER BY priority DESC" --limit 20

결과에서 상위 N개(기본 5개)만 선택. → Step 2로 진행.

Step 1-B: Fetch Sub-tasks by Issue Key (Issue Key 모드)

Step 0에서 추출한 이슈 키로 해당 이슈와 하위작업을 조회하고 의존성을 분석한다.

상세 절차: Read skills/jira-task-init/refs/issue-key-mode.md

요약:

1. 부모 이슈 조회 (jira-cli.py get <ISSUE-KEY>)
2. JQL로 미완료 하위작업 조회 (jira-cli.py search "parent = <ISSUE-KEY> AND status NOT IN (Done, Closed)")
3. 각 하위작업의 issuelinks 분석 (get <KEY> --fields issuelinks) → is blocked by 미완료 블로커 있으면 blocked 처리
4. 착수 가능 작업만 선별하여 의존성 표 출력 → Step 2로 전달

Step 2: Display Task List

가져온 태스크 목록을 테이블로 표시:

Found <N> tasks assigned to you:

| # | Key | Summary | Priority | Status | Type |
|---|-----|---------|----------|--------|------|
| 1 | PROJ-101 | 로그인 기능 구현 | Highest | To Do | Story |
| 2 | PROJ-102 | API 에러 핸들링 | High | To Do | Task |
| 3 | PROJ-103 | 대시보드 UI | High | In Progress | Story |
| 4 | PROJ-104 | 테스트 커버리지 | Medium | To Do | Task |
| 5 | PROJ-105 | 문서 업데이트 | Medium | To Do | Task |

사용자에게 확인: "이 태스크들에 대해 worktree를 생성할까요? (전체 또는 번호 선택)"

Step 3: Detect Git Context

REPO_ROOT=$(git rev-parse --show-toplevel)
PROJECT_NAME=$(basename "$REPO_ROOT")
PARENT_DIR=$(dirname "$REPO_ROOT")
WORKTREE_BASE="$PARENT_DIR/${PROJECT_NAME}_worktree"

Base branch 감지 (순서대로 시도):

git rev-parse --verify develop 2>/dev/null  # 1st: develop
git rev-parse --verify main 2>/dev/null     # 2nd: main
git rev-parse --verify master 2>/dev/null   # 3rd: master

Step 4: Ensure .gitignore

프로젝트의 .gitignore에 아래 항목이 없으면 bash로 추가:

REPO_GITIGNORE="$REPO_ROOT/.gitignore"
if ! grep -qF ".jira-context.json" "$REPO_GITIGNORE" 2>/dev/null; then
  printf '\n# Jira integration (local dev context)\n.jira-context.json\nTASK-README.md\n' >> "$REPO_GITIGNORE"
fi
if ! grep -qF ".jira-epic.json" "$REPO_GITIGNORE" 2>/dev/null; then
  printf '\n# Jira integration (local epic scope)\n.jira-epic.json\n' >> "$REPO_GITIGNORE"
fi

이미 존재하면 스킵.

Step 5: Create Worktrees

선택된 각 태스크에 대해 브랜치/worktree 존재 여부를 확인한 뒤 생성하고, .gitignore를 동기화한다.

상세 절차: Read skills/jira-task-init/refs/worktree-creation.md

요약:

• 브랜치+worktree 모두 있으면 → "Already exists — skipped"
• 브랜치만 있으면 → git worktree add "$WORKTREE_BASE/<TASK-ID>" "feature/<TASK-ID>"
• 둘 다 없으면 → git worktree add -b "feature/<TASK-ID>" "$WORKTREE_BASE/<TASK-ID>" <base-branch>
• 생성 후 worktree .gitignore에 .jira-context.json / TASK-README.md 항목 추가 (없으면)
• 중요: worktree는 반드시 원본 레포 상위 디렉토리 안에 생성 (<parent>/<project>_worktree/<TASK-ID>)

Step 5.5: Propagate MCP Config to Worktree (선택 — MCP 서버를 쓰는 경우에만)

atlassian MCP 서버를 계속 쓰는 경우에만 수행한다. jira-cli.py는 메인 레포 .jira-context.json의 jira 블록을 worktree에서도 찾아 읽으므로 CLI만 쓰면 이 전파는 필요 없다 — 그 경우 Step 6으로 넘어간다.

워크트리는 별도의 프로젝트 루트로 인식되어 MCP 설정이 자동 상속되지 않는다. scripts/propagate-mcp-config.sh를 호출하여 메인 레포의 atlassian 서버 설정을 워크트리로 전파한다.

스크립트 경로 결정은 Read skills/_shared/script-lookup.md 후 lookup 블록 실행:

REPO_ROOT_ABS="<REPO_ROOT 절대경로>"
WORKTREE_ABS="<워크트리 절대경로>"

SCRIPT_NAME="propagate-mcp-config.sh" OUT_VAR="PROPAGATE_SH"
# Read skills/_shared/script-lookup.md and execute its lookup block here

if [ -n "$PROPAGATE_SH" ]; then
  bash "$PROPAGATE_SH" "$REPO_ROOT_ABS" "$WORKTREE_ABS"
else
  echo "propagate-mcp-config.sh not found — skipping MCP propagation. Run /jira setup in the worktree if needed." >&2
fi

• 출처 우선순위: project .mcp.json > ~/.claude.json projects > ~/.claude.json top-level
• atlassian 서버가 빠져 있으면 경고만 출력하고 진행
• 워크트리에서 .mcp.json을 처음 로드하면 신뢰 승인 프롬프트가 한 번 뜰 수 있다

Step 6: Generate README for Each Worktree

각 worktree 디렉토리에 TASK-README.md 생성. 포함 항목:

• Issue Details (Key, Summary, Type, Priority, Status, Branch, Worktree, Initialized)
• Description (Jira 이슈 설명)
• Acceptance Criteria (설명에서 추출)
• Workflow (start → test → review → done 명령 안내)

Step 7: Post Comments to Jira

각 태스크에 코멘트 게시:

python3 "<scripts>/jira-cli.py" comment <TASK-ID> "브랜치 \`feature/<TASK-ID>\`의 worktree가 \`<worktree-path>\`에 초기화되었습니다."

Step 8: Save Context

각 worktree에 .jira-context.json 생성 (세션 시작 시 hook이 읽을 수 있도록):

{
  "taskId": "PROJ-101",
  "branch": "feature/PROJ-101",
  "worktreePath": "<path>",
  "repoRoot": "<REPO_ROOT 절대경로>",
  "baseBranch": "<detected base branch>",
  "summary": "로그인 기능 구현",
  "priority": "Highest",
  "status": "To Do",
  "completedSteps": ["init"],
  "initializedAt": "<ISO timestamp>"
}

원본 레포에도 .jira-context.json 저장 (전체 태스크 목록용). 기존 aggregate가 있으면 통째로 덮어쓰지 말고 병합한다: 기존 tasks[]에 같은 taskId 항목이 있으면 그 항목의 completedSteps·deferred·deferredKind·deferredReason·타임스탬프를 보존하고(없는 신규 태스크만 추가), 최상위 필드는 갱신 — 진행 중 큐를 리셋하면 loop/resume이 깨진다.

{
  "initialized": "<ISO timestamp>",
  "repoRoot": "<REPO_ROOT 절대경로>",
  "baseBranch": "<detected base branch>",
  "worktreeBase": "<worktree base path>",
  "tasks": [
    {
      "taskId": "PROJ-101",
      "branch": "feature/PROJ-101",
      "worktreePath": "<path>",
      "repoRoot": "<REPO_ROOT 절대경로>",
      "summary": "로그인 기능 구현",
      "priority": "Highest",
      "status": "To Do"
    }
  ]
}

Step 8.5: Dashboard Workspace Registration

생성된 worktree들이 dashboard에 즉시 보이도록, 부모 레포($REPO_ROOT)를 dashboard workspace registry에 등록한다. (idempotent — 이미 등록돼 있으면 lastSeenAt만 갱신.)

node "$CLAUDE_PLUGIN_ROOT/scripts/register-workspace.js" "$REPO_ROOT"

실패해도 워크플로는 진행 (등록은 dashboard 가시성에만 영향).

Step 9: Completion Summary

.jira-context.json의 completedSteps에 "init" 추가. 결과를 테이블로 표시한 뒤, 아래 형식으로 완료 요약 출력:

| # | Task | Branch | Worktree Path | Status |
|---|------|--------|---------------|--------|
| 1 | PROJ-101 | feature/PROJ-101 | ../project_worktree/PROJ-101 | Created |
| 2 | PROJ-102 | feature/PROJ-102 | ../project_worktree/PROJ-102 | Created |

---
✅ **Init Complete**

- <N>개 worktree 생성됨
- Jira 코멘트 게시됨
- 컨텍스트 `.jira-context.json`에 저장됨

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

**Next**: `cd <worktree-path>` → `/jira-task start <TASK-ID>`
---