Gh issue workflow

Skill uzysjung/uzys-agent-harness/templates/skills/gh-issue-workflow

Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity

Install

npx -y skills add uzysjung/uzys-agent-harness --skill gh-issue-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Treats GitHub Issues as the async backlog + decision channel between user and AI agent. Use when a non-blocking todo / bug / decision needs to persist beyond the chat session. Enforces 5-section body template (Background / Given / Decision / AC / Next) so issues become reusable agent context, not just sticky notes.

SKILL.md

7.3 KB, as published. Nobody here has run it

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 활용)

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 <N> --add-label <name> / --remove-label <name> 사용.

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

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

Pre-condition:

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

자동 동작:

새 issue 생성 시 → gh project item-add <number> --owner <owner> --url <issue-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	`<type>: ... (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

후속 이슈 body (선행 작업에 의존하는 경우)

## 배경
선행 이슈 #N 에서 <완료된 것>. 이 이슈는 그 위에 <남은 범위>를 얹는다.

## 전제 (Given)
- [x] #N 완료 (<그 이슈가 만든 것>)

## 방향성 (확정)
- <채택한 방침 1 — 대안 대신 이걸 고른 이유 한 줄>
- <하지 않기로 한 것 + 왜> ← 안 하기로 한 것을 적어야 나중에 다시 논의되지 않는다

## 적용 대상 / AC
- [ ] <When 조건 → Then 관측 가능한 결과> 형태로 쓴다
- [ ] ...

## 후속 작업
- [ ] #M 으로 분리: <이 이슈에서 뺀 것>