jira-task-epic

name	jira-task-epic
description	Set, show, or clear the project-local Epic scope that jira-task create attaches new issues to. Triggers: jira-task epic, set epic, epic scope; 이번 작업은 epic, 이번 작업 에픽, 에픽 설정, 에픽 지정, 에픽 스코프, 에픽 해제, 현재 에픽 뭐야.
user-invocable	false
argument-hint	[set <에픽 키|에픽 이름> | show | clear]
allowed-tools	["Read","Write","Bash","AskUserQuestion"]

jira-task-epic: Project Epic Scope

Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력). 이슈 키·필드명·JSON 키는 영어 유지.

Overview

"이번 작업은 epic v1.0이야" 한 마디를 .jira-epic.json에 고정해 두고, 이후 /jira-task create가 그 Epic 아래에 이슈를 만들도록 한다. 스코프가 없으면 create는 지금과 동일하게 Epic 없이 생성한다.

필수: Read skills/_shared/epic-scope.md — 파일 위치 결정, 스키마, .gitignore 등록 블록의 단일 출처.

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회 해석 — set(과 show의 상태 확인)에서만 필요. clear는 파일만 다루므로 연결 없이 동작한다.
• git 레포 안에서 실행. 아니면 "git 레포 안에서 실행해 주세요" 안내 후 종료.

Workflow

Step 0: Parse Argument

$ARGUMENTS에서 서브액션을 결정한다.

입력	서브액션
show, status, 빈 인자	show
clear, unset, 해제, 없음	clear
set <값> 또는 그 외 자연어(v1.0, MAE-100, 이번 작업은 epic v1.0이야)	set (값 = 서브액션 토큰을 제외한 나머지)

자연어에서 값을 뽑을 때 epic/에픽/이번 작업은/이야/으로 같은 조사·군더더기는 떼어낸다. 남은 것이 없으면 AskUserQuestion으로 Epic 키나 이름을 묻는다.

Step 1: Resolve File Path

skills/_shared/epic-scope.md의 경로 결정 블록을 실행해 EPIC_FILE을 얻는다. NOT_A_GIT_REPO면 종료.

Step 2: show

파일이 없으면:

📌 Epic 스코프: 설정되지 않음
   `/jira-task epic set <에픽 키 또는 이름>`으로 지정하면 이후 create가 그 Epic 아래에 이슈를 만듭니다.

있으면 키/요약/설정 시각을 출력한다. 이때 python3 "<scripts>/jira-cli.py" get <epicKey>로 현재 상태를 1회 확인해 출력의 status가 Done이면 아래 줄을 덧붙인다:

⚠️ 이 Epic은 이미 Done 상태입니다. 새 작업은 다른 Epic이 맞는지 확인하세요.

Step 3: clear

파일이 없으면 "설정된 Epic 스코프가 없습니다" 출력 후 종료. 있으면 삭제하고 어떤 Epic이 해제됐는지 알린다.

rm -f "$EPIC_FILE"

Step 4: set — Epic 해석

입력값이 이슈 키 형태([A-Z][A-Z0-9]+-\d+)인지 먼저 본다.

4-A. 키인 경우: python3 "<scripts>/jira-cli.py" get <KEY> --fields project로 조회 (summary/issuetype/status는 기본 출력, 프로젝트 키는 --fields project).

4-B. 이름인 경우: JQL로 검색한다.

python3 "<scripts>/jira-cli.py" search "project = <PROJECT_KEY> AND issuetype = Epic AND summary ~ \"<입력값>\" ORDER BY created DESC" --limit 20

<PROJECT_KEY>는 JIRA_DEFAULT_PROJECT 환경변수. JIRA_DEFAULT_PROJECT가 있으면 project 조건은 CLI가 자동 삽입한다 (CLAUDE.md의 스코핑 규칙). 없으면 사용자에게 프로젝트 키를 묻고 JQL에 직접 넣는다.

• 0건 → Step 5의 N0 처리
• 1건 → 확정
• 2건 이상 → 키/요약/상태 테이블을 보여주고 AskUserQuestion으로 선택

Step 5: set — 검증

#	조건	처리
N0	이름 검색 0건	후보 없음 알림 + AskUserQuestion(다른 이름으로 재검색 / 취소). Epic을 자동 생성하지 않는다
N1	issuetype != Epic	거부 + 종료. jira-cli.py epic-link가 Epic이 아닌 대상에 실패한다
N2	status == Done	경고 후 AskUserQuestion으로 계속 여부 확인
N3	JIRA_DEFAULT_PROJECT와 프로젝트가 다름	경고 후 계속 여부 확인

N1 예외: 대상이 epic-substitute 라벨을 가진 Task면 Epic 타입이 비활성화된 프로젝트의 대체 Epic이다. 이 경우 허용하되, 저장 시 사용자에게 "Epic 타입 대체 이슈로 등록합니다"라고 1줄 알린다.

Step 6: set — 저장

skills/_shared/epic-scope.md의 .gitignore 블록을 먼저 실행한 뒤(메인 레포 루트 기준), Write 도구로 EPIC_FILE을 쓴다.

{
  "epicKey": "<확정 키>",
  "epicSummary": "<Jira summary>",
  "projectKey": "<프로젝트 키>",
  "setAt": "<date -Iseconds 결과>"
}

기존 파일이 있으면 덮어쓰되, 이전 값이 무엇이었는지 완료 출력에 표시한다.

Step 7: Completion Summary

─────────────────────────────────────────
📌 Epic 스코프 설정 완료

**Epic**: <JIRA_URL>/browse/MAE-100 — v1.0 릴리스
**저장 위치**: <repo-root>/.jira-epic.json (gitignored)
# 덮어쓴 경우: **이전 값**: MAE-90 — v0.9 릴리스

이후 `/jira-task create`로 만드는 이슈는 이 Epic 아래에 생성됩니다.
해제하려면 `/jira-task epic clear`.
─────────────────────────────────────────

Non-goals

• Epic 신규 생성 (검색 결과가 없어도 만들지 않는다)
• 기존 이슈의 Epic 링크 변경 (이미 만들어진 이슈는 건드리지 않는다)
• .jira-context.json 수정, worktree/branch 조작
• init/report의 JQL 스코핑 — 본 스코프는 create에만 영향을 준다