/dev:issue

This skill automates the entire development cycle from branch creation to merge for a single ZenHub/GitHub issue.

Execute the full development cycle for a single issue

Overview#

This skill automates the entire development cycle from branch creation to merge for a single ZenHub/GitHub issue.

Usage#

/dev:issue {issue_number}

Parameters#

Parameter	Required	Description
`issue_number`	✅	GitHub issue number

Options#

/dev:issue 25 --no-merge      # PR only, without merge
/dev:issue 25 --skip-tests    # Skip tests (for urgent hotfixes)
/dev:issue 25 --base main     # Change base branch
/dev:issue 25 --bdd           # Force BDD scenario generation
/dev:issue 25 --skip-bdd      # Skip BDD scenarios
/dev:issue 25 --skip-review   # Skip code review (for urgent hotfixes)

Execution Flow#

┌─────────────────────────────────────────────────────────────────┐
│                    /dev:issue                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: 이슈 정보 조회                                           │
│  ├── mcp__zenhub__searchLatestIssues                            │
│  ├── 이슈 타입, 제목, 본문 추출                                     │
│  ├── 화면 타입 감지 (목록/상세/폼)                                  │
│  └── 부모/자식 관계 확인                                           │
│                                                                 │
│  Step 2: 브랜치 생성                                              │
│  ├── Task(subagent_type:  " issue-branch-agent " )                  │
│  ├── issue-state-agent →  " In Progress "   이동                      │
│  └── 결과: feature/{number}-{slug}                               │
│                                                                 │
│  Step 3: BDD 시나리오 작성 (화면 기능 시) ← NEW                     │
│  ├── Task(subagent_type:  " bdd-scenario-agent " )                  │
│  ├── Gherkin Feature 파일 생성                                    │
│  ├── Step Definition 생성                                        │
│  └── 커밋:  " test({scope}): ✅ BDD 시나리오 작성 "                      │
│                                                                 │
│  Step 4: 구현 작업                                                │
│  ├── Task(subagent_type:  " implementation-agent " )                │
│  ├── 이슈 내용 분석 → 레이어 에이전트 위임                            │
│  └── 증분 커밋 생성                                                │
│                                                                 │
│  Step 5: 테스트 작성 및 검증 (필수 게이트) ⚠️                        │
│  ├── [프론트엔드 테스트 - 필수]                                      │
│  │   ├── UseCase 단위 테스트 (unit-test-agent)                     │
│  │   └── BLoC 단위 테스트 (bloc-test-agent)                        │
│  ├── [백엔드 테스트 - Backend 변경 시 필수]                           │
│  │   ├── 엔드포인트 단위 테스트 (serverpod-test-agent)               │
│  │   ├── 서비스 로직 단위 테스트 (serverpod-test-agent)              │
│  │   └── 엔드포인트 통합 테스트 (serverpod-test-agent)               │
│  ├── BDD Widget 테스트 (화면 기능 시)                                │
│  ├── test-runner-agent 호출 (require_tests: true)                │
│  ├── ⚠️ 모든 테스트 통과 필수 (게이트 실패 시 PR 생성 차단)            │
│  └── 실패 시 자동 수정 시도 (최대 3회)                               │
│                                                                 │
│  Step 6: PR 생성                                                  │
│  ├── gh pr create                                                │
│  ├── Closes #{issue_number} 자동 포함                             │
│  └── issue-state-agent →  " Review/QA "   이동                        │
│                                                                 │
│  Step 7: 코드 리뷰 진행 ← NEW                                      │
│  ├── /code-review 자동 실행                                       │
│  ├── 리뷰 피드백 자동 반영 (format, analyze --fix)                  │
│  ├── /checklist:feature-complete 실행                            │
│  └── 재검토 필요 시 반복                                            │
│                                                                 │
│  Step 8: 머지 승인 대기                                            │
│  ├── 최종 상태 요약 표시                                            │
│  ├── 사용자 승인 요청 (AskUserQuestion)                            │
│  ├── 승인 시 스쿼시 머지 실행                                       │
│  └── GitHub  " Closes # "   키워드로 이슈 자동 Close                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Auto Screen Type Detection#

Detects screen keywords from issue title/body to decide whether to write BDD scenarios:

Pattern	Screen Type	BDD
"목록", "리스트", "list", "조회"	List	✅ Generate
"상세", "detail", "보기"	Detail	✅ Generate
"추가", "생성", "등록", "form"	Form	✅ Generate
"수정", "편집", "edit"	Form	✅ Generate
"리팩토링", "개선", "최적화"	-	❌ Skip
"설정", "환경", "빌드"	-	❌ Skip

Detailed Implementation#

Step 1: Query Issue Info#

// 이슈 정보 조회
const issueResult = await mcp__zenhub__searchLatestIssues({
  query: issue_number.toString()
});

const issue = issueResult.find(i = >   i.number === issue_number);

// 추출할 정보
const issueInfo = {
  id: issue.id,                    // GraphQL ID
  number: issue.number,            // GitHub 번호
  title: issue.title,              // 이슈 제목
  body: issue.body,                // 이슈 본문 (Acceptance Criteria 포함)
  type: issue.issueType?.name,     // Feature, Task, Bug, Sub-task
  pipeline: issue.pipelineIssue?.pipeline?.name,
  parentIssue: issue.parentIssue,  // 부모 이슈 정보
  labels: issue.labels,            // 라벨 목록
};

Step 2: Branch Creation#

// 브랜치 에이전트 호출
const branchResult = await Task({
  subagent_type:  " issue-branch-agent " ,
  prompt: `
    issue_number: ${issueInfo.number}
    issue_title: ${issueInfo.title}
    issue_type: ${issueInfo.type}
    base_branch: development

    이 이슈를 위한 브랜치를 생성해주세요.
  `
});

// Pipeline 이동: In Progress
await Task({
  subagent_type:  " issue-state-agent " ,
  prompt: `
    issue_number: ${issueInfo.number}
    action: move_pipeline
    target_pipeline:  " In Progress " 
   `
});

Step 3: BDD Scenario Writing (for screen features)#

// 화면 타입 감지
const screenKeywords = {
  list: [ " 목록 " ,  " 리스트 " ,  " list " ,  " 조회 " ,  " 검색 " ],
  detail: [ " 상세 " ,  " detail " ,  " 보기 " ],
  form: [ " 추가 " ,  " 생성 " ,  " 수정 " ,  " 편집 " ,  " form " ,  " 등록 " ],
};

const screenType = detectScreenType(issueInfo.title + issueInfo.body);
const requiresBdd = screenType !== null  & &   !options.skipBdd;

if (requiresBdd || options.bdd) {
  // BDD 시나리오 에이전트 호출
  await Task({
    subagent_type:  " bdd-scenario-agent " ,
    prompt: `
      feature_name: ${extractFeatureName(issueInfo)}
      entity_name: ${extractEntityName(issueInfo)}
      screen_type: ${screenType ||  " list " }

      화면 타입에 맞는 BDD 시나리오를 생성해주세요.
    `
  });

  // 커밋
  const scope = extractScope(issueInfo);
  await Bash(`
    git add .
    git commit -m  " test(${scope}): ✅ BDD 시나리오 작성

    - ${screenType} 화면 시나리오 추가
    - Step Definition 생성

    Co-Authored-By: Claude Opus 4.5  < noreply@anthropic.com > " 
   `);
}

Step 4: Implementation Work#

// 구현 에이전트 호출
const implResult = await Task({
  subagent_type:  " implementation-agent " ,
  prompt: `
    issue_number: ${issueInfo.number}
    issue_body: ${issueInfo.body}
    issue_type: ${issueInfo.type}
    issue_title: ${issueInfo.title}

    이슈 내용을 분석하고 구현해주세요.
    완료된 작업마다 커밋을 생성해주세요.
  `
});

// 커밋 결과 확인
console.log(`생성된 커밋: ${implResult.commits.length}개`);
console.log(`변경된 파일: ${implResult.files_changed.length}개`);

Step 5: Test Writing and Verification (Required Gate)#

// Feature명 추출 (이슈 제목 또는 스코프에서)
const featureName = extractFeatureName(issueInfo);

// Backend 변경 감지
const hasBackendChanges = detectBackendChanges(issueInfo);

// 테스트 유형 결정
const testTypes = [ " unit " ,  " bloc " ];
if (requiresBdd) testTypes.push( " bdd " );
if (hasBackendChanges) testTypes.push( " backend_unit " ,  " backend_integration " );

// 테스트 에이전트 호출 (require_tests: true → 누락 시 자동 생성)
const testResult = await Task({
  subagent_type:  " test-runner-agent " ,
  prompt: `
    feature_name: ${featureName}
    test_types: ${JSON.stringify(testTypes)}
    auto_fix: true
    require_tests: true

    테스트를 작성하고 실행한 후 결과를 보고해주세요.
    ⚠️ 모든 테스트가 통과해야 PR 생성이 가능합니다.
  `
});

// ⚠️ 테스트 실패 시 PR 생성 차단
if (!testResult.success) {
  if (testResult.failures.some(f = >   !f.fixable)) {
    throw new Error(`테스트 실패: ${testResult.failures.length}개 - PR 생성 차단`);
  }
}

Step 6: PR Creation#

// PR 생성
const gitmoji = getGitmoji(issueInfo.type);
const scope = extractScope(issueInfo);

await Bash(`
  gh pr create --title  " ${gitmoji} ${scope}: ${issueInfo.title} "   \
    --body  " $(cat  < < ' EOF ' 
 ## Summary
- ${issueInfo.title}

## Test Plan
- [ ] UseCase 단위 테스트 통과
- [ ] BLoC 단위 테스트 통과
${hasBackendChanges ?  ' - [ ] 백엔드 엔드포인트 단위 테스트 통과 '   :  ' ' }
${hasBackendChanges ?  ' - [ ] 백엔드 서비스 로직 단위 테스트 통과 '   :  ' ' }
${hasBackendChanges ?  ' - [ ] 백엔드 엔드포인트 통합 테스트 통과 '   :  ' ' }
${requiresBdd ?  ' - [ ] BDD 시나리오 통과 '   :  ' ' }

Closes #${issueInfo.number}

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
) " 
 `);

// Pipeline 이동: Review/QA
await mcp__zenhub__moveIssueToPipeline({
  issueId: issueInfo.id,
  pipelineId: reviewQaPipelineId,
});

Step 7: Code Review#

if (!options.skipReview) {
  // /code-review 자동 실행
  await Skill({ skill:  " code-review "   });

  // 자동 반영 가능한 피드백 적용
  await Bash(`melos run format`);
  await Bash(`melos run analyze --fix`);

  // 수정 사항 있으면 커밋
  const hasChanges = await Bash(`git status --porcelain`);
  if (hasChanges.stdout.trim()) {
    await Bash(`
      git add .
      git commit -m  " style(${scope}): 🎨 코드 리뷰 피드백 반영

      - 포맷팅 적용
      - 린트 경고 수정

      Co-Authored-By: Claude Opus 4.5  < noreply@anthropic.com > " 
     `);
    await Bash(`git push`);
  }

  // /checklist:feature-complete 실행
  await Skill({ skill:  " checklist:feature-complete "   });
}

Step 8: Wait for Merge Approval#

// 최종 상태 요약 표시
console.log(`
╔════════════════════════════════════════════════════════════════╗
║  Ready for Merge                                               ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  📋 Issue: #${issueInfo.number} - ${issueInfo.title}           ║
║  🔀 PR: #${prNumber}                                           ║
║  🌿 Branch: ${branchResult.branch_name}                        ║
║                                                                ║
║  ✅ Tests: ${testResult.summary.passed}/${testResult.summary.total} passed
║  ✅ Review: All issues resolved                                ║
║  ✅ Checklist: Passed                                          ║
║                                                                ║
║  🔒 Merge blocked until user approval                         ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝
`);

// 사용자 승인 요청
const approval = await AskUserQuestion({
  questions: [{
    header:  " 머지 " ,
    question:  " PR을 머지하시겠습니까? " ,
    options: [
      { label:  " 머지 승인 " , description:  " 스쿼시 머지 후 이슈 클로즈 "   },
      { label:  " 수정 필요 " , description:  " Step 4로 돌아가서 수정 "   },
      { label:  " 취소 " , description:  " 현재 상태 유지 "   },
    ],
    multiSelect: false,
  }],
});

if (approval ===  " 머지 승인 " ) {
  // 스쿼시 머지 → GitHub  " Closes # "   키워드로 이슈 자동 Close
  // Done 파이프라인 이동 불필요 (머지 = 완료)
  await Bash(`gh pr merge --squash --delete-branch`);
}

Output Format#

On Success#

╔════════════════════════════════════════════════════════════════╗
║  Issue Cycle Complete: #25                                     ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  📋 Issue: feat(community): ✨ 게시글 목록 화면 구현              ║
║  🌿 Branch: feature/25-community-list                          ║
║                                                                ║
║  📝 Commits:                                                   ║
║    1. feat(community): ✨ domain layer 구현                     ║
║    2. feat(community): ✨ data layer 구현                       ║
║    3. feat(community): ✨ presentation layer 구현               ║
║                                                                ║
║  ✅ Tests:                                                     ║
║    - UseCase Unit: 12/12 passed                                ║
║    - BLoC Unit: 8/8 passed                                     ║
║    - Backend Unit: 6/6 (endpoint: 3, service: 3)               ║
║    - Backend Integration: 4/4 passed                           ║
║    - BDD: 5/5 scenarios passed                                 ║
║                                                                ║
║  🔀 PR: #42                                                    ║
║    - URL: https://github.com/owner/repo/pull/42                ║
║    - Reviews: 2 comments (auto-resolved)                       ║
║    - Status: Merged ✅                                         ║
║                                                                ║
║  📊 Duration: 15m 32s                                          ║
║  🏁 Final State: CLOSED (by merge)                             ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

On Failure#

╔════════════════════════════════════════════════════════════════╗
║  Issue Cycle Failed: #25                                       ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  ❌ Failed at: Step 4 (테스트 실행)                              ║
║                                                                ║
║  Error Details:                                                ║
║    - Test: post_list_bloc_test.dart                            ║
║    - Reason: Expected PostLoaded but got PostError             ║
║    - Fixable: No (logic error)                                 ║
║                                                                ║
║  Current State:                                                ║
║    - Branch: feature/25-community-list (exists)                ║
║    - Commits: 3 committed                                      ║
║    - Pipeline: In Progress                                     ║
║    - PR: Not created                                           ║
║                                                                ║
║  Recovery Options:                                             ║
║    1. Fix the test manually and re-run                         ║
║    2. /dev:issue 25 --skip-tests                    ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Error Handling#

Step-by-Step Recovery Strategy#

Failed Step	State	Recovery Method
Branch creation	No changes	Retry
Implementation	Branch exists, some commits	Continue work
Tests	Code complete, tests failed	Manual fix then retry
PR creation	Code complete	Create PR manually or retry
Merge	PR exists, CI pending	Wait for CI pass then retry
Issue close	PR merged	Manual close

Auto Recovery Attempt#

// 최대 재시도 횟수
const MAX_RETRIES = 3;

async function executeWithRetry(step, retries = MAX_RETRIES) {
  for (let i = 0; i  <   retries; i++) {
    try {
      return await step();
    } catch (error) {
      if (i === retries - 1) throw error;
      console.log(`재시도 ${i + 1}/${retries}...`);
      await sleep(5000); // 5초 대기
    }
  }
}

TodoWrite Integration#

Progress Tracking#

// 시작 시
TodoWrite([
  { content:  " 이슈 정보 조회 " , status:  " in_progress " , activeForm:  " 이슈 정보 조회 중 "   },
  { content:  " 브랜치 생성 " , status:  " pending " , activeForm:  " 브랜치 생성 대기 "   },
  { content:  " 구현 작업 " , status:  " pending " , activeForm:  " 구현 작업 대기 "   },
  { content:  " 테스트 작성 및 검증 (필수 게이트) " , status:  " pending " , activeForm:  " 테스트 작성/검증 대기 "   },
  { content:  " PR 생성 및 머지 " , status:  " pending " , activeForm:  " PR 생성 대기 "   },
  { content:  " 이슈 클로즈 " , status:  " pending " , activeForm:  " 이슈 클로즈 대기 "   },
]);

// 각 단계 완료 시 즉시 업데이트
//  " completed " 로 마킹하고 다음 단계를  " in_progress " 로 변경

Key Rules#

Sequential execution: Each step proceeds only after previous step succeeds
State tracking: Record current state at every step
Failure tolerance: Preserve current state on failure and provide clear recovery guide
Issue linking: Reference issue number in all commits and PRs
Auto cleanup: Auto-delete branch on success (after merge)
Parent check: Auto-verify parent issue on issue close

Verification Gates (Required)#

Branch Verification (Before Step 2 Start)#

# 현재 브랜치 확인
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# development/main에서 직접 작업 시작 금지
if [[ $BRANCH ==  " development "   || $BRANCH ==  " main "   ]]; then
  echo  " ❌ development/main에서 직접 작업할 수 없습니다 " 
   echo  " " 
   echo  "     /dev:issue은 Step 2에서 브랜치를 생성합니다. " 
   echo  "     현재 development 브랜치에 있다면 정상입니다. " 
   echo  " " 
   # Step 2가 브랜치를 생성하므로 계속 진행
fi

Pre-PR Verification (Before Step 6)#

# 1. 브랜치 형식 검증
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ ! $BRANCH =~ ^(feature|fix|refactor|chore)/[0-9]+ ]]; then
  echo  " ❌ 브랜치 형식 오류: $BRANCH " 
   echo  "     올바른 형식: feature/{issue_number}-description " 
   echo  " " 
   echo  "     Step 2에서 브랜치가 생성되지 않았습니다. " 
   echo  "     /dev:issue을 다시 실행해주세요. " 
   exit 1
fi

# 2. development/main 직접 커밋 방지
if [[ $BRANCH ==  " development "   || $BRANCH ==  " main "   ]]; then
  echo  " ❌ development/main에 직접 PR을 생성할 수 없습니다 " 
   exit 1
fi

# 3. 커밋 존재 확인
COMMITS=$(git rev-list --count origin/development..HEAD)
if [[ $COMMITS -eq 0 ]]; then
  echo  " ❌ 커밋이 없습니다. " 
   echo  "     Step 4 (구현 작업)을 먼저 완료해주세요. " 
   exit 1
fi

# 4. Pre-push 검증 + 린트 0건 게이트
echo  " 🔍 Pre-push 검증 중... " 
 melos run format || { echo  " ❌ 포맷 오류 " ; exit 1; }
dart fix --apply  # 자동 수정 가능한 린트 이슈 일괄 수정
melos run analyze 2 > & 1 | tee /tmp/analyze_output.txt
LINT_ISSUES=$(grep -c -E  ' \s+(info|warning|error)\s+[•·-] '   /tmp/analyze_output.txt || true)
if [[ $LINT_ISSUES -gt 0 ]]; then
  echo  " ⚠️ flutter analyze 이슈 ${LINT_ISSUES}건 — 수동 수정 후 재검증 필요 " 
   # 수동 수정 시도 (최대 2회 반복) → 0건 달성 필수
  exit 1
fi
echo  " ✅ Pre-push 검증 통과 (린트 0건) "

TodoWrite Integration (Required)#

Initialization (On Step 1 Start)#

TodoWrite([
  { content:  " Step 1: 이슈 정보 조회 " , status:  " in_progress " , activeForm:  " 이슈 조회 중 "   },
  { content:  " Step 2: 브랜치 생성 " , status:  " pending " , activeForm:  " 브랜치 생성 대기 "   },
  { content:  " Step 3: BDD 시나리오 " , status:  " pending " , activeForm:  " BDD 작성 대기 "   },
  { content:  " Step 4: 구현 작업 " , status:  " pending " , activeForm:  " 구현 대기 "   },
  { content:  " Step 5: 테스트 실행 " , status:  " pending " , activeForm:  " 테스트 대기 "   },
  { content:  " Step 5.5: Pre-push 검증 + 린트 0건 게이트 " , status:  " pending " , activeForm:  " 검증 대기 "   },
  { content:  " Step 6: PR 생성 " , status:  " pending " , activeForm:  " PR 생성 대기 "   },
  { content:  " Step 7: 코드 리뷰 " , status:  " pending " , activeForm:  " 리뷰 대기 "   },
  { content:  " Step 8: 머지 승인 " , status:  " pending " , activeForm:  " 머지 대기 "   },
]);

Update Immediately on Step Completion#

// 각 단계 완료 즉시 TodoWrite 호출
// 예: Step 2 완료 후
TodoWrite([
  { content:  " Step 1: 이슈 정보 조회 " , status:  " completed " , activeForm:  " 이슈 조회 완료 "   },
  { content:  " Step 2: 브랜치 생성 " , status:  " completed " , activeForm:  " 브랜치 생성 완료 "   },
  { content:  " Step 3: BDD 시나리오 " , status:  " in_progress " , activeForm:  " BDD 작성 중 "   },
  // ... 나머지 pending 유지
]);

State Tracking Rules#

Rule	Description
Only 1 in_progress	Only 1 in_progress state allowed at a time
Immediate update	Change to completed immediately on step completion
Skip marking	Add "(skip)" to content for N/A steps (BDD, etc.)
Keep on failure	Keep failed step as in_progress, output error message

issue-branch-agent: Branch creation
bdd-scenario-agent: BDD scenario generation (for screen features)
implementation-agent: Code implementation
test-runner-agent: Test execution (including BDD)
pr-lifecycle-agent: PR management
issue-state-agent: Issue state management

/dev:run: Start full cycle with work content
/dev:bugfix: Bug fix dedicated cycle
/dev:parallel: Parallel processing of multiple issues
/dev:sprint: Full Epic orchestration
/code-review: Run code review
/checklist:feature-complete: Completion checklist
/bdd:generate: BDD scenario generation