ZenHub Conventions

Issue management rules using ZenHub.

Per-Project Configuration#

ZenHub workspace information is managed in .mcp.json at the project root. Pipeline ID, Repository ID, Issue Type ID, and Organization ID are not hardcoded but dynamically queried via MCP tools.

Workspace Info Query (required on first call)#

// 1. Pipeline ID + Repository ID query
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
// → pipelines[]: { id, name }  (New Issues, Icebox, Product Backlog, ...)
// → githubRepositories[]: { id, name }
// → zenhubOrganization: { id, name }
const repositoryId = workspace.githubRepositories.find(r = >   /* select GitHub repo */).id;

// 2. Issue Type ID query
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId });
// → issueTypes[]: { id, name, level }  (Initiative, Project, Epic, Feature, Bug, Task, Sub-task, ...)

Rule: Always query the current workspace IDs via the above two calls before creating/moving ZenHub issues. IDs can be cached and reused within the same session.

Issue Type Hierarchy#

Issue types are hierarchical (level field, lower = higher level). Standard workspace hierarchy:

Hierarchy rules:

• Parent-child links use parentIssueId (at creation) or setParentForIssues (after creation)
• A child's type level must be greater than its parent's level (e.g., Epic(3) under Project(2) ✅, Epic under Epic ❌)
• Project/Initiative types may not exist in every workspace — always check via getIssueTypes() first; if absent, fall back to Epic as the top level and warn the user

const projectType = issueTypes.find(t = >   t.name ===  " Project " );
if (!projectType) {
  // Fallback: skip Project level, create Epic(s) without parent + warn
}

Issue Creation Rules#

Use GitHub Issues (required)#

All issues must be created as GitHub issues (ZenHub issues are prohibited)

// ✅ CORRECT: Create GitHub issue
mcp__zenhub__createGitHubIssue({
  title:  " Feature development " ,
  repositoryId: repositoryId, // From getWorkspacePipelinesAndRepositories()
  issueTypeId: epicTypeId,    // From getIssueTypes()
})

// ❌ WRONG: Create ZenHub issue (prohibited)
mcp__zenhub__createZenhubIssue({...})

Reasons:

• GitHub issues support pipeline moves
• Timeline settings work correctly
• Auto-link with GitHub PRs
• Easy search and filtering

ID Query Patterns#

Finding Pipeline ID#

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const pipelines = workspace.pipelines;

// Find by name
const inProgress = pipelines.find(p = >   p.name ===  " In Progress " );
const reviewQA = pipelines.find(p = >   p.name ===  " Review/QA " );
// Note: do NOT route completed issues to  " Done "   — Done ≠ closed (see Issue Closure Policy).

Finding Issue Type ID#

const types = await mcp__zenhub__getIssueTypes({ repositoryId });

// Find by name (each type has { id, name, level })
const projectType = types.find(t = >   t.name ===  " Project " );
const epicType = types.find(t = >   t.name ===  " Epic " );
const featureType = types.find(t = >   t.name ===  " Feature " );
const bugType = types.find(t = >   t.name ===  " Bug " );
const subtaskType = types.find(t = >   t.name ===  " Sub-task " );

Finding Repository ID#

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repos = workspace.githubRepositories;

// Find GitHub repo (by name)
const githubRepo = repos.find(r = >   r.name ===  " my-repo " );

Issue Creation Examples#

Project Creation (top-level)#

const projectTypeId = issueTypes.find(t = >   t.name ===  " Project " ).id;

// Create Project (GitHub issue) — wraps multiple Epics
const project = await mcp__zenhub__createGitHubIssue({
  title:  " Service name/milestone name " ,
  body:  " Project description, goals, Epic list... " ,
  repositoryId: repoId,
  issueTypeId: projectTypeId,
  labels: [ " project " ,  " p0 " ], // Priority label decided BEFORE creation
});

// Link Epics created later as children
await mcp__zenhub__setParentForIssues({
  parentIssueId: project.id,
  childIssueIds: [epic1.id, epic2.id],
});

Epic Creation#

// 1. Dynamic ID query
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.githubRepositories[0].id; // Or find by name
const issueTypes = await mcp__zenhub__getIssueTypes({ repositoryId: repoId });

const epicTypeId = issueTypes.find(t = >   t.name ===  " Epic " ).id;
const orgId = workspace.zenhubOrganization.id; // Organization ID

// 2. Create Epic (GitHub issue)
const epic = await mcp__zenhub__createGitHubIssue({
  title:  " Feature name " ,
  body:  " Epic description... " ,
  repositoryId: repoId,
  issueTypeId: epicTypeId,
});

// 3. Set timeline
await mcp__zenhub__setDatesForIssue({
  issueId: epic.id,
  startDate:  " 2026-01-27 " ,
  endDate:  " 2026-02-17 " ,
  zenhubOrganizationId: orgId,
});

// 4. Move pipeline
const backlogPipeline = workspace.pipelines.find(p = >   p.name ===  " Product Backlog " );
await mcp__zenhub__moveIssueToPipeline({
  issueId: epic.id,
  pipelineId: backlogPipeline.id,
});

Story Creation#

const featureTypeId = issueTypes.find(t = >   t.name ===  " Feature " ).id;

// Create Story (under Epic)
const story = await mcp__zenhub__createGitHubIssue({
  title:  " Feature name " ,
  body:  " Story description... " ,
  repositoryId: repoId,
  issueTypeId: featureTypeId,
  parentIssueId: epic.id, // Link to Epic
});

// Set Story Points
await mcp__zenhub__setIssueEstimate({
  issueId: story.id,
  estimate: 5,
});

Priority Review and Pipeline Sorting (required after creation)#

After creating Project/Epic/Story issues, always run a priority review and place each issue in the appropriate pipeline.

Priority Scoring Criteria#

Score each issue on 4 axes and assign a priority tier:

⚠️ Labels must be set at creation time — updateIssue does not support label changes. Therefore, the priority review happens before issue creation; labels are passed to createGitHubIssue.

Priority → Pipeline Placement#

Within-Pipeline Ordering#

moveIssueToPipeline does not support a position parameter, so exact in-pipeline ordering cannot be set via MCP. Approximate it with:

1. Move in descending priority order — move P0 issues first, then P1, then P2 (one moveIssueToPipeline call each, sequentially)
2. Record the priority table in the parent issue body — Epic/Project body includes a ## 🔢 우선순위 table (rank / issue # / tier / rationale) as the source of truth
3. Fine-grained drag ordering, if needed, is adjusted manually on the ZenHub board (guide the user)

Sprint Selector Resolution#

--sprint 값을 스프린트로 해석하는 표준 규칙 — 모든 커맨드(/dev:run, /zenhub:epic, …)가 동일하게 따른다:

⚠️ getUpcomingSprint() 는 '다음' 스프린트다 — '활성'이 아니다. current 를 getUpcomingSprint 로 해석하면 이슈가 한 스프린트 뒤로 밀려 활성 스프린트/번다운에서 비게 된다. current 는 반드시 getSprint() 를 쓴다.

async function resolveSprint(selector) {
  if (selector ===  " next " ) return await mcp__zenhub__getUpcomingSprint();
  if (!selector || selector ===  " current " ) return await mcp__zenhub__getSprint(); // 활성
  const { openSprints } = await mcp__zenhub__listRecentSprints();
  return openSprints.find(s = >   s.name.includes(String(selector)));
}

Roadmap Visibility Contract (모든 이슈를 타임라인에 노출)#

로드맵 타임라인은 setDatesForIssue 의 start/end 로 렌더되며, setDatesForIssue 는 상위 타입(Epic/Project/Initiative) 전용이다(MCP 스키마 제약). 따라서 2-레인 규칙으로 모든 추적 이슈가 보이게 한다:

저수준 타입에 setDatesForIssue 를 쓰지 말 것 — 스키마상 off-spec 이며 로드맵 렌더가 비정상일 수 있다. 스프린트 레인으로 노출한다.

Matrix Signals (impact × effort)#

ZenHub Matrix 는 impact(가치) × effort(노력) 2축으로 이슈를 plot 한다. 두 축을 모두 영속화해야 매트릭스가 채워진다:

⚠️ 라벨은 생성 후 변경 불가(updateIssue 미지원) → 생성 시점에 createGitHubIssue 의 labels 로 확정한다. impact 에 effort 를 섞으면 매트릭스에서 이중 계산되므로 분리한다. P0/P1/P2 티어는 정렬용이고, impact 라벨은 매트릭스 축용으로 별개다.

Blocked Issue Contract#

작업이 차단되면 보드에 반영해 활성 작업과 구분한다(차단된 이슈를 In Progress 에 방치 금지):

createBlockage 는 차단 의존 관계를 기록하고, 파이프라인 이동은 차단 상태를 보드에 가시화한다 — 둘은 보완 관계다. 차단 사유는 이슈 코멘트로 남긴다.

// Example: priority-ordered placement after creation
const backlog = workspace.pipelines.find(p = >   p.name ===  " Product Backlog " );
// fail-closed: 못 찾으면 throw (이름 불일치 시 부분 배치 후 무음 중단 방지)
if (!backlog) throw new Error(` ' Product Backlog '   파이프라인 없음. 라이브: ${workspace.pipelines.map(p = >   p.name).join( " ,  " )}`);
const sorted = stories.sort((a, b) = >   a.priorityRank - b.priorityRank); // P0 → P1 → P2
for (const s of sorted) {
  await mcp__zenhub__moveIssueToPipeline({ issueId: s.id, pipelineId: backlog.id });
}

Issue Title Conventions#

Note: Epic/Story는 ZenHub Issue Type으로 이미 구분되므로 제목에 [Epic], [Story] 접두사를 붙이지 않습니다.

Issue Closure Policy ("merge = Close") ⚠️#

ZenHub tracks two independent states — confusing them leaves issues stuck open:

• Done pipeline ≠ closed. An issue moved to Done is still open on GitHub. Done means "ready to close", not closed.
• Closed pipeline = GitHub closed, 1:1. Judge open/closed by GitHub state, never by a column.
• An issue truly closes via exactly one of: (1) drag to Closed pipeline, (2) close on GitHub, (3) a PR merging with Closes #N — but (3) fires ONLY when the PR merges into the repository's default branch (a hard GitHub rule).

⚠️ 이 워크스페이스에는 Closed 컬럼이 없다 (라이브 6종: New Issues · Icebox · Product Backlog · Sprint Backlog · In Progress · Review/QA). 따라서 정식 close 메커니즘은 gh issue close --reason completed + updateIssue({state:"CLOSED"}) 이며, 아래의 "Closed 파이프라인으로 이동" 경로는 Closed 컬럼을 노출하는 워크스페이스에서만 적용된다(find(p=>p.name==="Closed") 가 undefined 면 그 경로는 not-applicable — 무음 skip 을 close 성공으로 오인 금지).

🚫 Never moveIssueToPipeline a closed issue into a non-Closed pipeline (Product Backlog, In Progress, Review/QA, Done, …). Those board columns render open issues only, so dropping a closed issue into one reopens it on GitHub to materialize the card. This is the move to avoid.

✅ The Closed pipeline is the exception — routing there never reopens. It is wired 1:1 to GitHub closed, so the move is safe in both directions: for an already-closed issue it is a no-op (it is already in Closed; no reopen), and for an open issue it actively closes it on GitHub (valid close mechanism #1, equivalent to gh issue close). So moveIssueToPipeline({ pipelineId: <Closed>.id }) is an acceptable explicit-close / fallback — resolve the id with getWorkspacePipelinesAndRepositories().pipelines.find(p => p.name === "Closed") (skip gracefully if the workspace does not expose it). gh issue close remains the simplest path; this is a sanctioned alternative, not a prohibition.

Once an issue is closed on GitHub, ZenHub auto-syncs it to Closed via webhook with no pipeline move needed. If you accidentally moved a closed issue into a non-Closed column and it reopened, re-close it on GitHub (gh issue close) or move it to the Closed pipeline — do not leave it parked open in the wrong column.

✅ GitHub close → ZenHub Closed is automatic (webhook), zero extra setup. ZenHub auto-provisions the repo webhook and also periodically rescans, so a GitHub close propagates to the board on its own. If it is NOT syncing, the cause is almost always a webhook-permission gap: a repo admin must have logged into ZenHub at least once (ZenHub manages the webhook under that admin's token). Prefer verifying the repo's sync/connection state in workspace settings; if you do need to force the state, move the issue to the Closed pipeline (safe — see above), never to a non-Closed column.

⚠️ Hierarchical (work-base) merges never auto-close. In the branch hierarchy (task/ → story/ → epic/ → development), Sub-task and Story PRs merge into a parent work-base branch, not the default branch — so GitHub's Closes #N never fires, the issue stays open, and ZenHub never reaches Closed. Even epic/ → development does not auto-close unless development is the repo's default branch. For any merge whose base ≠ default branch, the explicit close (step 3 below) is the PRIMARY mechanism, not a fallback. See branch-hierarchy.

This repo's policy = (B) "merge = Close". AI agents run full-stack E2E tests + review before merge, so a merged PR counts as Done and Closed. Therefore:

1. Every PR body includes Closes #{number}. Squash merge auto-closes GitHub → ZenHub syncs to Closed only if the base is the default branch. If the base is a parent work-base branch (hierarchical merge), it will NOT auto-close — you must close explicitly (step 3).
2. Never park completed issues in Done (it would leave them open).
3. After every merge, close + verify — unconditionally. This is mandatory (not optional) for non-default-base merges, and also covers silent miss / sync lag on default-branch merges:

// 0. `Closes #N` auto-closes ONLY on default-branch merges. For hierarchical merges
//    (base = story/ or epic/) it never fires, so step 1 IS the close, not a safety net.
const defaultBranch = (await Bash(`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`)).trim();

// 1. GitHub is the source of truth — close explicitly whenever still open
const state = await Bash(`gh issue view ${n} --json state -q .state`);
if (state.trim() !==  " CLOSED " ) await Bash(`gh issue close ${n} --reason completed`);

// 2. Confirm ZenHub synced to Closed; force if lagging
const closed = await mcp__zenhub__searchClosedIssues({ query: `#${n}` });
if (!closed.find(i = >   i.number === n)) {
  await mcp__zenhub__updateIssue({ issueId, state:  " CLOSED "   });
}

Reporting note: ZenHub reports/burndown count Closed as Done by default. Issues left only in a Done column are not counted as complete — another reason to always reach Closed.

Notes#

1. ZenHub Issues vs GitHub Issues

   • ZenHub issues: Cannot move pipelines/set timelines
   • GitHub issues: All ZenHub features work correctly

2. Parent-Child Relationships

   • Link on creation via parentIssueId parameter
   • Or link later with setParentForIssues

3. Search

   • searchLatestIssues: Only searches GitHub issues
   • ZenHub issues are not searchable