/zenhub:epic {feature_name} {entity_name} [--options]

// 1. Repository ID + Pipeline ID
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.githubRepositories.find(r = >   /* GitHub 레포 선택 */).id;

// 2. Issue Type ID (includes hierarchy level: lower = higher level)
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId: repoId });
const initiativeType = issueTypes.find(t = >   t.name ===  " Initiative " );  // may be absent
const projectType = issueTypes.find(t = >   t.name ===  " Project " );  // may be absent
const epicTypeId = issueTypes.find(t = >   t.name ===  " Epic " ).id;
const featureTypeId = issueTypes.find(t = >   t.name ===  " Feature " ).id;
const subtaskTypeId = issueTypes.find(t = >   t.name ===  " Sub-task " ).id;

// Initiative type fallback: if --initiative given but type absent,
// warn the user and create the Project (or Epic, if no --project) as top level instead
if (useInitiativeLevel  & &   !initiativeType) {
  // ⚠️  " 이 워크스페이스에는 Initiative Issue Type이 없습니다. Project(또는 Epic)를 최상위로 생성합니다. " 
 }

// Project type fallback: if --project given but type absent,
// warn the user and create Epic(s) as top level instead
if (useProjectLevel  & &   !projectType) {
  // ⚠️  " 이 워크스페이스에는 Project Issue Type이 없습니다. Epic을 최상위로 생성합니다. " 
 }

# Specify individual files
--images  " list.png,detail.png,form.png " 

 # Specify directory (auto-filter supported formats)
--images-dir ./screenshots/

entity:
  name: {EntityName}
  fields:
    - name: title
      type: String
      required: true
      ui_component: TextField
      validation:
        max_length: 100
      source_screen: form.png

    - name: content
      type: String
      required: true
      ui_component: TextArea
      validation:
        max_length: 5000
      source_screen: form.png

    - name: category
      type:  " {EntityName}Category " 
       required: true
      ui_component: Dropdown
      options: [general, notice, event]
      source_screen: form.png

    - name: imageUrls
      type:  " List < String > ? " 
       required: false
      ui_component: ImagePicker
      validation:
        max_count: 5
      source_screen: form.png

# {Feature} Requirements Specification

 >   Auto-generated from image analysis

## Entity Definition

### {Entity}
| Field | Type | Required | Description |
|------|------|------|------|
| title | String | ✅ | Title |
| content | String | ✅ | Content |
...

## Screen Definition

### 1. List Screen (list.png)
- Components: AppBar, ListView, FAB
- Actions: Card tap → navigate to detail, FAB tap → create
...

🖼️ 이미지를 repo에 commit하시겠습니까?

- 대상 파일: list.png, detail.png, form.png
- 저장 경로: .claude/docs/{feature}/screenshots/
- 현재 브랜치: {current_branch}

**계속하시겠습니까? (y/N)**

# 1. Copy images to .claude/docs
cp {input_images} .claude/docs/{feature}/screenshots/

# 2. Add to Git (current branch)
git add .claude/docs/{feature}/screenshots/
git commit -m  " docs: 📸 {feature} 스크린샷 추가 " 
 git push origin HEAD

# 3. Generate GitHub raw URLs
# https://raw.githubusercontent.com/{owner}/{repo}/{branch}/.claude/docs/{feature}/screenshots/{image}

## 📸 이미지 분석 결과

### 식별된 화면
| # | 이미지 | 화면 타입 | 컴포넌트 수 |
|---|--------|----------|-----------|
| 1 | list.png | List | 5 |
| 2 | detail.png | Detail | 4 |
| 3 | form.png | Form | 6 |

### 추출된 Entity 필드
| 필드 | 타입 | 필수 | 출처 |
|------|------|------|------|
| title | String | ✅ | form.png |
| content | String | ✅ | form.png |
| category | Enum | ✅ | form.png |

### 생성할 BDD 시나리오
- 목록: 8개
- 상세: 6개
- 폼: 7개

**분석 결과가 정확합니까? (Y/n)**

## 요구사항 로드

1. .claude/docs/{feature}/requirements.md 읽기
2. BDD 시나리오 파일들 읽기 (있는 경우)
3. Entity 필드 정의 추출
4. 화면 정의 추출

## 🔢 우선순위 검토 결과

| 순위 | 이슈 | 티어 | impact | 근거 |
|------|------|------|--------|------|
| 1 | {feature} 목록 화면 | P0 | high | 상세/폼 화면이 목록 Entity에 의존(value+dependency 높음) |
| 2 | {feature} 상세 화면 | P1 | med | 핵심 경로, 의존 이슈 없음 |
| 3 | {feature} 폼 화면 | P1 | low | 핵심 경로 |

**이 우선순위로 진행하시겠습니까? (Y/n)**

const initiative = await mcp__zenhub__createGitHubIssue({
  title:  " {initiative_title} " ,
  body:  " {initiative_body_template} " ,   // strategic goal, wrapped Project/Epic list
  repositoryId: repoId,
  issueTypeId: initiativeType.id,
  labels: [ " initiative " ,  " p{priority} " ]
});

const project = await mcp__zenhub__createGitHubIssue({
  title:  " {project_title} " ,
  body:  " {project_body_template} " ,   // goals, Epic list, priority table
  repositoryId: repoId,
  issueTypeId: projectType.id,
  parentIssueId: initiative?.id, // when --initiative/--parent-initiative is used
  labels: [ " project " ,  " p{priority} " ]
});

mcp__zenhub__createGitHubIssue({
  title:  " {feature} 기능 구현 " ,
  body:  " {epic_body_template} " ,
  repositoryId: repoId,      // getWorkspacePipelinesAndRepositories()에서 조회
  issueTypeId: epicTypeId,   // getIssueTypes()에서 조회
  parentIssueId: project?.id ?? initiative?.id, // --project/--parent-project 우선, 없으면 --initiative/--parent-initiative 직접 연결
  labels: [ " epic " ,  " feature " ,  " {feature_name} " ,  " p{priority} " ]
})

// 1) Organization ID (required by setDatesForIssue)
const orgId = workspace.zenhubOrganization.id;

// 2) Compute the timeline window
//    시작: 명시 플래그  >   --sprint 셀렉터 스프린트 시작  >   오늘
//    ⚠️ getUpcomingSprint 는  ' 다음 '   스프린트다. 기본값으로 쓰면 Epic 바가 한 스프린트 밀린다.
//       기본(current)은 getSprint()(id 없음=활성)를 쓴다.
const kickoffSprint = options.sprint ===  " next " 
   ? await mcp__zenhub__getUpcomingSprint()
  : await mcp__zenhub__getSprint();                        // 기본 current = 활성 스프린트
const startDate =
  options.startDate ??
  kickoffSprint?.startAt?.slice(0, 10) ??
  todayISO();                                              //  " YYYY-MM-DD " 

 // Default duration auto-derived from total Story Points when --duration/--end-date omitted.
// Heuristic: ~5 points ≈ one 2-week sprint (min 2 weeks, rounded up to whole weeks).
const totalPoints = stories.reduce((s, x) = >   s + x.point, 0);
const weeks = options.duration ?? Math.max(2, Math.ceil(totalPoints / 5) * 2);
const endDate = options.endDate ?? addWeeksISO(startDate, weeks);

// 3) Set the Epic timeline (THIS is what was missing) — unless --no-dates
if (!options.noDates) {
  await mcp__zenhub__setDatesForIssue({
    issueId: epic.id,
    startDate,                 //  " YYYY-MM-DD " 
     endDate,                   //  " YYYY-MM-DD " 
     zenhubOrganizationId: orgId,
  });
}

// 4) Set the Epic estimate (roll-up of child Story Points)
await mcp__zenhub__setIssueEstimate({
  issueId: epic.id,
  estimate: totalPoints,
});

## Epic 생성 확인

**제목**: {feature} 기능 구현

**내용 미리보기**:
---
# Epic: {Feature} 기능 구현

## 📋 개요
{feature_description}

## 💼 비즈니스 가치
**사용자로서**, {capability}을(를) 원합니다.
**그래서** {value}을(를) 얻을 수 있습니다.

## 📊 범위
- ✅ 목록 화면
- ✅ 상세 화면
- ✅ 폼 화면

## 🛠️ 기술 노트
| 항목 | 값 |
|------|-----|
| Entity | `{EntityName}` |
| Backend | Serverpod endpoint |
| Caching | SWR |
---

**라벨**: epic, feature, {feature_name}, kobic

**📅 타임라인**: {start_date} ~ {end_date} ({weeks}주)  ← Goals  &   Planning 로드맵에 표시됨
**📐 Story Point (롤업)**: {total_points}

**생성하시겠습니까? (Y/n)**

mcp__zenhub__createGitHubIssue({
  title:  " {feature} {screen} 화면 " ,
  body:  " {story_body_template} " ,
  repositoryId: repoId,         // getWorkspacePipelinesAndRepositories()에서 조회
  issueTypeId: featureTypeId,   // getIssueTypes()에서 조회
  parentIssueId:  " {epic_id} " ,                                    // Epic과 연결
  labels: [ " story " ,  " {feature_name} " ,  " {screen_type}-view " ,  " p{priority} " ,  " impact-{impact} " ]  // impact: high|med|low (Matrix Y축, C6)
})

// effort 축: Story Point 설정 (Matrix X축)
await mcp__zenhub__setIssueEstimate({ issueId: story.id, estimate: story.point });

// ⚠️ Story 타임라인: setDatesForIssue 는 상위 타입(Epic/Project) 전용이므로 Story 에는 쓰지 않는다(off-spec).
//   Roadmap Visibility Contract(rules/zenhub-conventions.md)대로 Story 는 **스프린트 멤버십**으로 노출한다 —
//   --sprint 가 주어지면 Step 5 에서 addIssuesToSprints 로 해당 스프린트 레인에 올린다.
//   즉 Story 의 로드맵 가시성 = 부모 Epic 의 기간 바 + 자신의 스프린트 레인.

## Story 생성

| # | Screen | Title | Point | Timeline | Acceptance Criteria Count |
|---|------|------|-------|----------|-------|
| 1 | List | {feature} 목록 화면 | 3 | {s1_start}~{s1_end} | 8 |
| 2 | Detail | {feature} 상세 화면 | 3 | {s2_start}~{s2_end} | 9 |
| 3 | Form | {feature} 폼 화면 | 5 | {s3_start}~{s3_end} | 10 |

**Total Stories**: 3
**Total Points**: 11
**Epic Timeline**: {epic_start} ~ {epic_end}

mcp__zenhub__createGitHubIssue({
  title:  " [{PREFIX}-00X-0Y] {task_description} " ,
  body:  " {subtask_body} " ,
  repositoryId: repoId,         // getWorkspacePipelinesAndRepositories()에서 조회
  issueTypeId: subtaskTypeId,   // getIssueTypes()에서 조회
  parentIssueId:  " {story_id} " ,                                   // Story와 연결
  labels: [ " subtask " ,  " {feature_name} " ,  " p{priority} " ]
})

## 연결 완료

✅ Project #{project_number} 생성 완료 (--project 사용 시)
✅ Epic #{epic_number} 생성 완료 (Project에 연결됨)
✅ Story #{story_1} 연결됨
✅ Story #{story_2} 연결됨
✅ Story #{story_3} 연결됨

### 생성된 이슈 링크
- Project: https://github.com/cocode/kobic/issues/{project_number}
- Epic: https://github.com/cocode/kobic/issues/{epic_number}
- 목록: https://github.com/cocode/kobic/issues/{story_1}
- 상세: https://github.com/cocode/kobic/issues/{story_2}
- 폼: https://github.com/cocode/kobic/issues/{story_3}

// fail-closed 해석: 이름이 라이브 파이프라인과 다르면 throw (부분 배치 후 무음 중단 방지)
const pipelineByName = (name) = >   {
  const p = workspace.pipelines.find(p = >   p.name === name);
  if (!p) throw new Error(`파이프라인  ' ${name} '   없음. 라이브: ${workspace.pipelines.map(p = >   p.name).join( " ,  " )}`);
  return p;
};
const backlog = pipelineByName( " Product Backlog " );
const sprintBacklog = pipelineByName( " Sprint Backlog " );
const icebox = pipelineByName( " Icebox " );

// ⚠️ moveIssueToPipeline has no position param —
// move in DESCENDING priority order (P0 first) to approximate top-to-bottom ordering
for (const issue of issuesSortedByPriority) {
  await mcp__zenhub__moveIssueToPipeline({
    issueId: issue.id,
    pipelineId: pipelineFor(issue),  // matrix above
  });
}

// --sprint 사용 시 P0 Story를 해당 스프린트에 추가
if (options.sprint) {
  // 셀렉터 (rules/zenhub-conventions.md →  " Sprint Selector Resolution "   와 동일 규칙):
  //   current → 활성(getSprint, id 없음) · next → 다음(getUpcomingSprint) · 숫자/이름 → listRecentSprints 매칭
  const targetSprint =
    options.sprint ===  " next "      ? await mcp__zenhub__getUpcomingSprint() :
    options.sprint ===  " current "   ? await mcp__zenhub__getSprint()         :
    (await mcp__zenhub__listRecentSprints()).openSprints
      .find(s = >   s.name.includes(String(options.sprint)));
  if (!targetSprint?.id) throw new Error(`스프린트  ' ${options.sprint} '   해석 실패 — current/next/번호를 확인하라`);
  await mcp__zenhub__addIssuesToSprints({
    issueIds: p0StoryIds,
    sprintIds: [targetSprint.id],
  });
}

## 파이프라인 정렬 완료

| 이슈 | 티어 | 파이프라인 |
|------|------|-----------|
| Epic #{epic_number} | — | Product Backlog |
| #{story_1} 목록 화면 | P0 | Sprint Backlog (Sprint 12) |
| #{story_2} 상세 화면 | P1 | Product Backlog |
| #{story_3} 폼 화면 | P1 | Product Backlog |

 >   파이프라인 내 세부 순서는 MCP가 지원하지 않습니다.
 >   우선순위 순서대로 이동했으며, 미세 조정은 ZenHub 보드에서 드래그로 조정하세요.

.claude/docs/{feature_name}/
├── screenshots/              # 이미지 분석 시 저장 (--images 사용 시)
│   ├── list.png
│   ├── detail.png
│   └── form.png
├── image_analysis.md         # 이미지 분석 결과 (--images 사용 시)
├── requirements.md           # 요구사항 (자동 생성 또는 기존 파일)
├── bdd/                      # BDD 시나리오 (자동 생성)
│   ├── {feature}_list.feature
│   ├── {feature}_detail.feature
│   └── {feature}_form.feature
└── zenhub/
    ├── project.md            # Project 상세 정보 (--project 사용 시)
    ├── epic.md               # Epic 상세 정보
    ├── priority.md           # 우선순위 검토 결과 + 파이프라인 배치 기록
    └── stories/
        ├── list_story.md     # 목록 Story 정보
        ├── detail_story.md   # 상세 Story 정보
        └── form_story.md     # 폼 Story 정보

# Epic: {Feature} 기능 구현

## 📋 개요
{Feature에 대한 간략한 설명}

## 💼 비즈니스 가치
**사용자로서**, {feature_capability}을(를) 원합니다.
**그래서** {business_value}을(를) 얻을 수 있습니다.

## 📊 범위

### 포함
- ✅ {screen_1} 화면
- ✅ {screen_2} 화면
- ✅ {screen_3} 화면

### 제외
- ❌ (필요시 명시)

## 🛠️ 기술 노트
| 항목 | 값 |
|------|-----|
| Entity | `{EntityName}` |
| Backend | Serverpod endpoint |
| Caching | {SWR / Cache-First} |
| Location | `feature/{location}/{feature_name}` |

## 🎨 디자인 스크린샷

 >   `--images` 사용 시 자동 생성됨

### 목록 화면
![목록 화면](https://raw.githubusercontent.com/{owner}/{repo}/{branch}/.claude/docs/{feature}/screenshots/list.png)

### 상세 화면
![상세 화면](https://raw.githubusercontent.com/{owner}/{repo}/{branch}/.claude/docs/{feature}/screenshots/detail.png)

### 폼 화면
![폼 화면](https://raw.githubusercontent.com/{owner}/{repo}/{branch}/.claude/docs/{feature}/screenshots/form.png)

 >   또는 Figma 링크: {figma_urls}

## 📎 관련 Story
- [ ] #{story_1_number} - 목록 화면
- [ ] #{story_2_number} - 상세 화면
- [ ] #{story_3_number} - 폼 화면

---
 >   🤖 Generated by `/zenhub:epic`

# Story: {Screen Name}

## 📋 사용자 스토리
**{user_type}로서**, {screen_capability}을(를) 원합니다.
**그래서** {value}을(를) 얻을 수 있습니다.

## ✅ 인수 기준 (Acceptance Criteria)

### AC1: {scenario_1_name}

- **Priority**: {High/Medium/Low}
- **Tag**: @{tag}

### AC2: {scenario_2_name}

- **Priority**: {High/Medium/Low}
- **Tag**: @{tag}

## 🛠️ 기술 작업

### Backend
- [ ] Serverpod endpoint 구현
- [ ] DTO 정의

### Domain
- [ ] Entity 정의
- [ ] Repository Interface 정의
- [ ] UseCase 구현
- [ ] UseCase 테스트 작성

### Data
- [ ] Repository 구현
- [ ] Serverpod Mixin 구현
- [ ] 캐싱 전략 적용

### Presentation
- [ ] BLoC 구현 (Event/State)
- [ ] Page 위젯 구현
- [ ] Widget 컴포넌트 구현
- [ ] Route 등록
- [ ] BDD 테스트 작성

### Widgetbook
- [ ] Component story 추가

## 🎨 디자인 참조

 >   `--images` 사용 시 자동 생성됨

![{screen_name}](https://raw.githubusercontent.com/{owner}/{repo}/{branch}/.claude/docs/{feature}/screenshots/{screen}.png)

 >   또는 Figma 링크: {figma_link}

## 📐 예상 Story Point
{point_value}

---
 >   🤖 Generated by `/zenhub:epic`
 >   📎 Epic: #{epic_number}

/zenhub:epic community Post

# Create new Project + Epics under it
/zenhub:epic community Post --project  " 어드민 콘솔 v2 " 

 # Multiple Epics under one Project
/zenhub:epic --project  " 어드민 콘솔 v2 "   --epics  " auth,community,payment " 

 # Link Epic to an existing Project issue
/zenhub:epic community Post --parent-project 1024

/zenhub:epic community Post \
  --requirements .claude/docs/community/requirements.md \
  --bdd-dir .claude/docs/community/bdd/

/zenhub:epic community Post \
  --labels  " sprint-1,mvp "   \
  --sprint current

/zenhub:epic community Post \
  --screens  " list,detail,form "   \
  --points  " 5,3,8 "

/zenhub:epic community Post \
  --images  " list.png,detail.png,form.png "

/zenhub:epic community Post \
  --images-dir ./screenshots/community/

/zenhub:epic community Post \
  --images  " list.png,detail.png,form.png "   \
  --labels  " sprint-1,mvp "   \
  --sprint current

/zenhub:epic community Post \
  --images  " list.png,detail.png,form.png "   \
  --attach-images false