Gh Issue Workflow

GitHub Issue Workflow

Purpose

채팅(휘발성)과 plan.md(정적) 사이의 빈 곳을 GitHub Issue가 채운다. 1인 사용자 + AI agent 협업에서:

• 사용자가 발견한 bug/feature 요청 → issue로 backlog (chat을 끊지 않고)
• 의사결정이 필요한 갈림길 → issue body에 옵션 정리 → 사용자가 비동기로 결정 → AI agent가 fetch해서 작업
• 모든 결정의 영구 검색 가능 기록 (cross-link #N, label, milestone 활용)

dyld-vantage 프로젝트의 실제 운용 패턴(#52~#55)을 일반화. 1인 시나리오에 최적화 (팀 assign / reviewer 자동화 같은 건 안 함).

When to Invoke

| 트리거 | 행동 | |--------|------| | 프로젝트 착수 + GitHub remote 존재 | "epic issue 만들까?" 1회 권유 (선택) | | 작업 계획 시작 | OPEN issue 목록 fetch → 우선순위 결정 후 todo.md로 이관 | | 구현 중 사용자가 새 bug/req 발견 | "issue로 backlog?" 권유 | | 구현 commit | message에 Refs #N (작업 진행 기록) | | PR 작성 시 | body에 Closes #N (자동 close) | | 의사결정 갈림길 등장 | issue body에 방향성 (OPEN) 로 등록 → 사용자 대기 |

Pre-conditions

• 프로젝트가 GitHub remote 보유 (git remote -v로 확인)
• gh CLI 설치 + 인증 (gh auth status로 확인). MCP mcp__github__* 사용 가능하면 우선.
• docs/SPEC.md에 issue_tracking: enabled 라인 있을 때만 활성 (opt-in). 기본 비활성.

조건 미충족이면 본 skill 자동 skip — 에러 X.

Process

1. ISSUE.template.md 5섹션 강제

새 issue 생성 시 본 skill 디렉토리의 ISSUE.template.md를 body로 채운다.

## 배경         — Why
## 전제 (Given) — 시작 전 의존성/조건
## 방향성       — OPEN | YYYY-MM-DD 확정
## 적용 대상 / AC (When → Then)
## 후속 작업    — Next

비어있는 섹션은 통째로 삭제 (placeholder 금지). BDD 매핑: 전제(Given) → 적용 대상(When) → AC(Then).

2. 방향성 상태로 작업 가능 여부 판정

| 상태 | 의미 | AI agent 행동 | |------|------|--------------| | OPEN | 사용자 결정 대기 | 본 issue 작업 차단. 다른 issue 우선 처리 또는 사용자에게 결정 요청 | | YYYY-MM-DD 확정 | 결정 완료 | 작업 가능. AC 충족 후 close |

확정 날짜 미달 시 → 사용자에게 1회 결정 요청 (Escalation Gate) → 응답 후에만 진행.

3. 전제(Given) 체크

작업 시작 전 전제 조건 모두 충족됐는지 확인:

• 체크박스 [x] 모두 채워졌나?
• 미충족 항목 → 차단 사유 + 책임 분기 보고

전제가 다른 issue 완료에 의존하면 → 의존 issue가 close 됐는지 확인 후 진행.

4. Label 체계 (자동 토글 가이드)

3-축 label 체계 — 각 축에서 1개씩 부착 권장:

| 축 | Label | 부착 시점 | |----|-------|---------| | type | bug / feature / refactor / docs / infra | issue 생성 시 1회 | | 상태 | decision-pending / ready / in-progress / blocked | 방향성·전제 변화에 따라 토글 | | 우선순위 | P0 / P1 / P2 (선택) | 사용자 결정 |

상태 자동 토글 규칙 (skill이 사용자에게 권유):

방향성: OPEN          → decision-pending
방향성: YYYY-MM-DD 확정 → ready (decision-pending 제거)
전제 체크박스 미완      → blocked (ready 제거)
PR open               → in-progress
PR merged             → 자동 close (label 무관)

label 부착은 hook 차원 강제 X — skill 가이드. 사용자 또는 PR 자동화로 명시 적용. gh issue edit --add-label / --remove-label 사용.

5. GitHub Projects (V2) 연계 (선택, opt-in)

GitHub Projects board를 칸반 형태 backlog로 활용 시:

Pre-condition:

• docs/SPEC.md에 github_project: 명시 (예: https://github.com/users/uzysjung/projects/3)
• 사용자가 Project 미리 생성 + status field 정의 (Backlog / Ready / In Progress / Done)

자동 동작:

• 새 issue 생성 시 → gh project item-add --owner --url 호출
• 상태 변화 시 → status field 갱신:
• decision-pending → Project status Backlog
• ready → Ready
• PR open → In Progress
• merged + close → Done

Project 미사용 프로젝트 → 본 섹션 skip (issue label만 활용).

비대상:

• iteration field / 자동 sprint 분배 (1인 시나리오 over-engineering)
• 복수 Project board 동기화 (1 SPEC = 1 Project 권장)

본 섹션은 GitHub Projects 활용을 강제하지 않음 — 사용자 선호에 따라.

6. 백로그 자동 처리 시퀀스

작업 사이클 시작 시 다음 시퀀스:

1. gh issue list --state open --json number,title,labels,body
   → OPEN issue 목록을 backlog 후보로
2. 각 issue body에서 "방향성 (YYYY-MM-DD 확정)" 패턴 grep
   → 확정된 것만 작업 가능 후보
3. 전제 미충족 issue 제외
4. 우선순위 정렬 (label P0 > P1 > P2 > unlabeled)
5. 상위 1-3개를 docs/todo.md로 이관 + 계획 단계 진입

7. Commit / PR 컨벤션

| 시점 | 메시지 컨벤션 | |------|-------------| | Build 중 진행 commit | : ... (refs #N) | | Ship PR body | Closes #N 또는 Fixes #N (자동 close) | | 부분 진행 (close 안 함) | Refs #N | | 후속 issue 생성 시 | 원본 issue body의 "후속 작업" 섹션에 #M cross-link |

Output

• GitHub Issue 생성/갱신 (5섹션 body)
• docs/todo.md — issue list에서 이관된 task
• commit/PR 메시지에 issue 번호 자동 포함

Anti-Patterns

• issue body가 한 줄 ("login 안 됨")만 — 5섹션 의무. 최소 배경 + AC는 채울 것.
• 방향성 미명시 — OPEN인지 확정인지 모르면 작업 시작 불가.
• 전제 무시하고 진행 — 의존 issue 미해결 상태로 작업 진입 금지.
• PR에서 Closes #N 누락 — 수동 close 잊기 쉬움. 컨벤션 강제.
• 모든 issue에 label 다 붙임 — 노이즈. 핵심 분류만.
• 팀 기능 도입 (assignee 자동, code owner 자동 review) — 본 skill 범위 밖. 팀 사용은 별도 워크플로우.

Boundary

• GitHub remote 없는 프로젝트 → skill 자동 비활성
• docs/SPEC.md에 issue_tracking: enabled 없으면 자동 비활성 (opt-in)
• private repo 접근 권한 없으면 fetch 실패 → 사용자에게 보고

Examples

dyld-vantage 실제 패턴 (참고)

## 배경
Issue #52에서 Feature Flag 재편(16→18) + Blur gate 인프라 구축 완료.
이 이슈는 페이지별 blur 적용 + API 수량 제한의 후속 작업.

## 전제 (Given)
- [x] Issue #52 완료 (Feature Flag 인프라)
- [x] Blur gate 컴포넌트 사용 가능

## 방향성 (2026-04-22 확정)
- 메뉴 접근은 유지 (사이드바 풀 노출, 401/403 없음)
- 페이지 단위 blur: outer max-w-* mx-auto 안쪽에 blur_gate 1개만
- 개별 블록별 blur 금지 (복잡도 대비 가치 낮음)

## 적용 대상 / AC
- [ ] 모든 _content.html에 blur_gate 적용 (When Free user 방문 → Then blur 노출)
- [ ] API 수량 제한 미들웨어 (When tier 미충족 요청 → Then 403)

## 후속 작업
- [ ] Issue #56로 분리: Pricing 페이지 CTA 디자인

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uzysjung
• Source: uzysjung/uzys-agent-harness
• License: MIT
• Homepage: https://uzysjung.github.io/uzys-agent-harness/

Install and usage instructions live in the source repository linked above.