zenhub:init-workspace

ZenHub workspace pipeline initialization and standard structure setup

항목	내용
Category	dev-cycle-workflow
Complexity	simple
MCP Servers	zenhub

/zenhub:init-workspace#

Initializes ZenHub pipelines to the standard structure after creating a new repo/workspace. Removes the Done pipeline and sets up a workflow that uses Closed status for completion.

Triggers#

Right after adding a new GitHub repo to a ZenHub workspace
When you want to standardize workspace pipeline structure
Initial setup before starting development workflows like /dev:run

Context Trigger Pattern#

/zenhub:init-workspace [--workspace-id  < id > ]

Parameters#

Parameter	Required	Description	Example
`--workspace-id`	Optional	Workspace ID (reads from `.mcp.json` if omitted)	`69c4c110fc3a90000f3387d9`

Standard Pipeline Structure#

After initialization, the workspace should contain only these pipelines:

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

Pipeline	Purpose	Notes
New Issues	Newly created issues	Auto-placement
Icebox	On hold/low priority	Optional
Product Backlog	Approved backlog	After triage
Sprint Backlog	Assigned to current sprint	During sprint planning
In Progress	Work in progress	On branch creation
Review/QA	Code review/QA	On PR creation

Done pipeline is not used. Issues auto-close via GitHub Closes # keyword on PR merge.

Execution Flow#

Step 1: Query Workspace Info#

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();

Extract from query results:

workspace.pipelines → Current pipeline list
workspace.repositories → Connected repo list
workspace.organizationId → Organization ID

Step 2: Analyze Current Pipelines#

Compare current pipeline list with the standard structure:

const STANDARD_PIPELINES = [
   " New Issues " ,
   " Icebox " ,
   " Product Backlog " ,
   " Sprint Backlog " ,
   " In Progress " ,
   " Review/QA " 
 ];

const PIPELINES_TO_REMOVE = [ " Done " ];

const currentNames = workspace.pipelines.map(p = >   p.name);
const missing = STANDARD_PIPELINES.filter(name = >   !currentNames.includes(name));
const toRemove = workspace.pipelines.filter(p = >   PIPELINES_TO_REMOVE.includes(p.name));
const extra = currentNames.filter(name = > 
   !STANDARD_PIPELINES.includes(name)  & &   !PIPELINES_TO_REMOVE.includes(name)
);

Step 3: Analysis Report#

Report current state and required actions to the user:

╔════════════════════════════════════════════════════════════════╗
║  ZenHub Workspace Pipeline Analysis                           ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  Workspace: {workspace_id}                                     ║
║  Repositories: {repo_names}                                    ║
║                                                                ║
║  Current Pipelines:                                            ║
║  ✅ New Issues                                                 ║
║  ✅ Product Backlog                                            ║
║  ✅ In Progress                                                ║
║  ✅ Review/QA                                                  ║
║  ⚠️  Done (needs removal)                                      ║
║  ❌ Icebox (missing)                                           ║
║  ❌ Sprint Backlog (missing)                                   ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Step 4: Handle Done Pipeline#

When the Done pipeline exists:

Check issues in the Done pipeline:

const doneIssues = await mcp__zenhub__getIssuesInPipeline({
  pipelineId: donePipeline.id
});

Close issues if any exist:

for (const issue of doneIssues) {
  await mcp__zenhub__updateIssue({
    issueId: issue.id,
    state:  " closed " 
   });
}

Guide Done pipeline removal:

The ZenHub MCP API does not support pipeline deletion. Please manually remove the Done pipeline at the following URL:

https://app.zenhub.com/workspaces/{workspace_id}/board
→ Done pipeline header (...) → Delete pipeline

Step 5: Query and Cache Issue Types#

const issueTypes = await mcp__zenhub__getIssueTypes();

Step 6: Generate zenhub-conventions.yaml#

Generate a .claude/config/bmad/zenhub-conventions.yaml file at the project root to cache IDs:

# Auto-generated by /zenhub:init-workspace
# Date: {current_date}

repository:
  id:  " {repo.id} " 
   owner:  " {repo_owner} " 
   name:  " {repo_name} " 

 organization:
  id:  " {workspace.organizationId} " 

 issue_types:
  epic:  " {epicType.id} " 
   feature:  " {featureType.id} " 
   task:  " {taskType.id} " 
   bug:  " {bugType.id} " 

 pipelines:
  new_issues:  " {newIssuesPipeline.id} " 
   icebox:  " {iceboxPipeline.id} " 
   product_backlog:  " {backlogPipeline.id} " 
   sprint_backlog:  " {sprintBacklogPipeline.id} " 
   in_progress:  " {inProgressPipeline.id} " 
   review_qa:  " {reviewQAPipeline.id} " 
   # Done pipeline not used — Closed on PR merge

sprints:
  active:
    id:  " " 
     name:  " " 
   upcoming:
    id:  " " 
     name:  " " 

 issue_creation:
  method:  " github " 
   title_prefixes:
    epic:  " " 
     story:  " " 
     sub_task:  " " 
     bug:  " [Bug] " 

 last_updated:  " {ISO_8601_timestamp} "

Step 7: Verify .mcp.json#

Verify that ZenHub MCP configuration exists in the project root's .mcp.json:

// Read .mcp.json file
const mcpConfig = readFile( " .mcp.json " );

// Check zenhub server configuration
if (!mcpConfig.mcpServers?.zenhub) {
  // Need to create .mcp.json or add zenhub configuration
}

Step 8: Completion Report#

╔════════════════════════════════════════════════════════════════╗
║  Workspace Initialization Complete                             ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  ✅ Pipeline analysis complete                                 ║
║  ✅ Done issues ({N}) → Closed                                 ║
║  ⚠️  Done pipeline manual removal needed (URL guided)          ║
║  ✅ zenhub-conventions.yaml generated                          ║
║  ✅ .mcp.json verification complete                            ║
║                                                                ║
║  📋 Missing Pipelines:                                         ║
║     → Manual addition needed in ZenHub Board: {missing_names}  ║
║                                                                ║
║  🏁 Next Steps:                                                ║
║     1. Manually remove Done pipeline                           ║
║     2. Manually add missing pipelines                          ║
║     3. Start development with /dev:run                         ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Completion Rules#

All issues in Done pipeline are Closed (automatic)
Done pipeline deletion is manual (MCP API limitation)
Missing pipeline addition is manual (MCP API limitation)
zenhub-conventions.yaml is auto-generated (ID caching)
Re-run after pipeline changes to refresh cache

Command	Description
`/zenhub:manage`	PR linking and pipeline state management
`/zenhub:epic`	Epic & Story creation
`/dev:run`	Full development cycle automation