zenhub-integration-agent

// 1. Repository ID + Pipeline ID
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.githubRepositories.find(r => /* select GitHub repo */).id;

// 2. Issue Type ID (level: 1=Initiative, 2=Project, 3=Epic, 4=Feature/Bug/Task, 5=Sub-task)
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId: repoId });
const initiativeType = issueTypes.find(t => t.name === "Initiative"); // may be absent → fallback to Project/Epic top-level
const projectType = issueTypes.find(t => t.name === "Project"); // may be absent → fallback to Epic top-level
const epicTypeId = issueTypes.find(t => t.name === "Epic").id;
const featureTypeId = issueTypes.find(t => t.name === "Feature").id;
const bugTypeId = issueTypes.find(t => t.name === "Bug").id;
const taskTypeId = issueTypes.find(t => t.name === "Task").id;
const subtaskTypeId = issueTypes.find(t => t.name === "Sub-task").id;

function inferScale(requestText, flags) {
  if (flags.initiative || flags.parentInitiative) return "initiative";
  if (flags.project || flags.parentProject || (flags.epics?.length ?? 0) >= 2) return "project";
  if (flags.noEpic) return "no-epic";

  // Auto-inference (no explicit flag) — judged by meaning, not keywords.
  // 1) Jev reflex judgment (cc-dev:jev-reflex, set `scale`) — used only when it is confident (route "reflex").
  //    This agent has no Bash: the caller (/cc-dev:zenhub:breakdown, /cc-dev:go) runs the set and passes the
  //    decisions in as `reflex.scale`. Absent → judge by meaning below.
  const s = reflex?.scale ?? {};
  if (s.scale?.route === "reflex") return s.scale.value.replace("_", "-");   // no_epic → no-epic
  // 2) deliberate / unavailable → Claude judges the same four levels by meaning (signals below are hints, not triggers)
  //    initiative: roadmap, quarters, several teams · project: several features or areas · no-epic: one small
  //    screen/bug/task (≤3 points) · epic: one feature with several issues (default)
  return judgeScaleByMeaning(requestText);
}

-1. Hierarchy scale inference (see Step -1 above) → initiative | project | epic | no-epic
   ↓
-0.5. ⛔ Existing-children check — 부모(Epic/Project/Initiative/Work item)가 **이미 존재하는**
   이슈일 때는, 그 아래 자식을 만들기 전에 `listChildren(parent.number)` 로 기존 자식을 전수 조회한다
   (`rules/zenhub-conventions.md` → "Child Enumeration Contract" / "Existing-Children Reuse").
     · 같은 작업을 담은 자식이 이미 있으면 → **새로 만들지 않고 그 이슈를 반환**(재사용)
     · 본문·AC 가 낡았으면 → `updateIssue` 로 그 자식을 갱신
     · `known === false`(조회 실패) → **생성 전에 멈추고 확인받는다**
   ⚠️ 이걸 건너뛰면 원본 자식이 열린 채 남고 부모가 Parent Closure Invariant 위반 상태로 닫힌다
      (2026-07-31 `#3451`: `#3478`–`#3482` 대신 `#3514`–`#3518` 을 새로 만들어 처리한 사고).
      완전히 새로 만드는 계층(부모도 이번에 생성)에서는 자식이 있을 수 없으므로 no-op.
   ↓
0. Priority review (score dependency/value/risk/effort → p0/p1/p2 per issue)
   ↓ (labels are immutable after creation — review MUST precede creation)
0.4. Split narrative from the contract block (see "Issue Body HTML Contract" below)
   ↓ bodies are created with contract block + short summary only — no link block at creation time
0.5. Create Initiative issue, if inferred/requested (createGitHubIssue + issueTypeId=Initiative)
   ↓
1. Create Project issue, if inferred/requested (createGitHubIssue + issueTypeId=Project, parentIssueId=Initiative when created)
   ↓
2. Create Epic issue, unless scale=no-epic (createGitHubIssue + issueTypeId=Epic, parentIssueId=Project, or =Initiative directly if no Project)
   ↓
3. Create Work Item issues — classify each item as Feature/Bug/Task (see "Work Item Type Classification" below), createGitHubIssue + issueTypeId=resolveWorkItemType(item) × N, parentIssueId=Epic (or Project/Initiative/none if scale=no-epic)
   ↓
4. Create Sub-tasks (createGitHubIssue + issueTypeId=Sub-task × M, parentIssueId=work item)
   ↓
5. Verify parent-child relationships (already set via parentIssueId; fix with setParentForIssues)
   ↓
5.5. Write detailed-plan HTML locally (.claude/docs/{scope}/issue-{number}.html) — issue numbers exist now;
     never commit (no work branch yet — run/batch commit it and add the body link later)
   ↓
6. Set Story Points (setIssueEstimate — ALL issues, always) AND timeline dates (setDatesForIssue — Epic/Project/Initiative only). When 2+ Epics are created together, resolve dependency edges first (`--epic-deps` > text signals > default independent) and schedule accordingly — see `rules/zenhub-conventions.md` → *Epic Dependency & Parallel Scheduling*
   ↓ ⚠️ SP without dates leaves the Epic off the Goals & Planning roadmap; dates without SP is not possible here since SP is always set first
7. Pipeline sorting (moveIssueToPipeline, descending priority order: P0 → P1 → P2)
   ↓
8. Sprint assignment for P0 work items when requested (addIssuesToSprints)

// 키워드 정규식을 쓰지 않는다 — "수정" 이 든 편집 폼 기능("주문 수정 화면 추가")이 Bug 가 되던 원인이다.
// cc-dev:jev-reflex 세트 work-shape 로 판단하고(reflex 만 채택), 그 밖에는 Claude 가 의미로 정한다.
function resolveWorkItemType(item) {
  const d = item.reflex ?? {};   // 호출자가 work-shape 판정을 항목마다 넘긴다(이 에이전트는 Bash 가 없다) — 없으면 의미 판단
  const type = d.work_type?.route === "reflex" ? d.work_type.value : judgeTypeByMeaning(item.description);
  return type === "feat" ? featureTypeId : type === "fix" ? bugTypeId : taskTypeId;
}

mcp__zenhub__createGitHubIssue({
  title: "{strategic goal name}",
  body: buildBody(contract, summary),  // 계약 블록 + 짧은 요약 (전략 서술은 로컬 HTML — Step 5.5)
  repositoryId: repoId,      // Dynamic query
  issueTypeId: initiativeType.id, // Dynamic query (fallback if absent)
  labels: ["initiative", "p0"]
})

mcp__zenhub__createGitHubIssue({
  title: "{project/milestone name}",
  body: buildBody(contract, summary),  // 계약 블록 + 짧은 요약 (우선순위 표는 본문 유지)
  repositoryId: repoId,      // Dynamic query
  issueTypeId: projectType.id, // Dynamic query (fallback if absent)
  parentIssueId: "{initiative_graphql_id}", // When under an Initiative
  labels: ["project", "p0"]
})

const epic = await mcp__zenhub__createGitHubIssue({
  title: "{feature} feature implementation",
  body: buildBody(contract, summary),  // 계약 블록 + 짧은 요약 (Step 0.4 분리분)
  repositoryId: repoId,      // Dynamic query
  issueTypeId: epicTypeId,    // Dynamic query
  parentIssueId: "{project_graphql_id}" // When under a Project (or the Initiative's id directly, if no Project level)
})

// ⚠️ Story Point is ALWAYS set — regardless of --no-dates/--sprint. When no child breakdown
// exists yet (common when creating several sibling Epics at once), estimate top-down via the
// T-shirt→Fibonacci table instead of leaving it null. SoT: rules/zenhub-conventions.md →
// "Mandatory Story Point Estimate"
await mcp__zenhub__setIssueEstimate({ issueId: epic.id, estimate: epic.points });

// Dates are set unless --no-dates. duration = points ÷ measured team velocity — NOT a fixed
// constant — and, when 2+ Epics are created together, start dates come from a dependency-aware
// schedule (independent Epics share a start date = parallel; dependent Epics run sequentially).
// SoT: rules/zenhub-conventions.md → "Epic Velocity Calculation" + "Epic Dependency & Parallel Scheduling"
await mcp__zenhub__setDatesForIssue({
  issueId: epic.id,
  startDate: scheduledStart,                       // "YYYY-MM-DD" — from scheduleEpics()
  endDate: scheduledEnd,                            // "YYYY-MM-DD"
  zenhubOrganizationId: workspace.zenhubOrganization.id,
});

mcp__zenhub__createGitHubIssue({
  title: "{feature} list screen",           // Feature example — Bug/Task titles use fix:/chore: prefix
  body: buildBody(contract, summary),        // 계약 블록(AC·범위·DoD) + 짧은 요약 (서술 20행 초과분은 로컬 HTML)
  repositoryId: repoId,         // Dynamic query
  issueTypeId: resolveWorkItemType(item),    // Feature/Bug/Task — classified per item, never hardcoded
  parentIssueId: "{epic_graphql_id}"         // or Project/Initiative id, or omitted, when scale=no-epic
})

mcp__zenhub__createGitHubIssue({
  title: "[{PREFIX}-001-01] Table column definition",
  body: "{body}",  // Sub-task 는 상세 기획 HTML 대상이 아니다 — 현행 마크다운 유지
  repositoryId: repoId,         // Dynamic query
  issueTypeId: subtaskTypeId,    // Dynamic query
  parentIssueId: "{work_item_graphql_id}"
})

project, {project_slug}, p{priority}

epic, feature, {feature_name}, kobic, p{priority}

{feature|bug|task}, {feature_name}, {screen_type if Feature}, kobic, p{priority}

New Issues → Icebox → Product Backlog → Sprint Backlog → In Progress → Review/QA

.claude/docs/{feature}/zenhub/
├── epic.md
└── stories/
    ├── list_story.md
    ├── detail_story.md
    └── form_story.md