Agent skills
github-issue-state-management

Agent skill

github-issue-state-management

GitHub Issueのラベルとメタデータを使用した環境状態管理。container-use/worktree/ホスト環境すべてからアクセス可能なSingle Source of Truth

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/github-issue-state-management

SKILL.md

GitHub Issue 状態管理

Single Source of Truth: GitHub Issue のラベルとメタデータによる環境状態管理

概要

なぜ GitHub Issue で管理するのか？

課題（ローカルファイル）	解決策（GitHub Issue）
container-use内からホストファイルにアクセス不可	`gh` CLI はどこからでも使用可能
worktree間でファイル共有不可	Issue は全環境で同一
並列実行時の競合リスク	ラベル操作は GitHub がアトミック処理
ローカルファイルのため可視性が低い	GitHub UI で状態が一目瞭然

ラベル体系

ステータスラベル（排他: 1つのみ）

ラベル	説明	色（推奨）
`env:active`	作業中	`#0E8A16` (緑)
`env:blocked`	人間の介入が必要	`#D93F0B` (赤)
`env:pr-created`	PR作成済み	`#1D76DB` (青)
`env:merged`	マージ完了	`#6F42C1` (紫)

Phase ラベル（排他: 1つのみ）

ラベル	説明
`phase:0-branch`	ブランチ作成
`phase:1-env`	環境構築
`phase:2-design`	設計書参照
`phase:3-check`	設計書実現性チェック
`phase:4-red`	テスト作成（Red）
`phase:5-green`	実装（Green）
`phase:6-refactor`	リファクタリング
`phase:7-review`	レビュー依頼/修正
`phase:8-stress`	ストレステスト（任意）
`phase:9-approval`	ユーザー承認待ち
`phase:10-pr`	PR作成
`phase:11-ci`	CI監視
`phase:12-merge`	マージ & クリーンアップ

領域ラベル（任意: 複数可）

ラベル	説明
`area:backend`	バックエンド
`area:frontend`	フロントエンド
`area:infra`	インフラ
`area:database`	データベース

メタデータ管理

Issue Body へのメタデータ埋め込み

Issue 作成時または環境開始時に、Issue body の末尾に以下のブロックを追加：

markdown

<!-- ENV_METADATA
env_id: abc-123-def
branch: feature/issue-42-user-auth
env_type: container-use
worktree_path: 
created_at: 2026-01-17T10:00:00Z
last_updated_at: 2026-01-17T15:30:00Z
-->

フィールド定義

フィールド	型	必須	説明
`env_id`	string	✅	container-use 環境ID または worktree 識別子
`branch`	string	✅	Git ブランチ名
`env_type`	string	✅	`container-use` / `worktree` / `host`
`worktree_path`	string		worktree 使用時のパス
`pr_number`	string		PR作成後に設定（途中再開時のCI監視に必要）
`created_at`	string	✅	作成日時（ISO 8601）
`last_updated_at`	string	✅	最終更新日時（ISO 8601）

メタデータの抽出

bash

# Issue body からメタデータを抽出
gh issue view 42 --json body -q '.body' | \
  grep -oP '(?<=<!-- ENV_METADATA)[\s\S]*?(?=-->)' | \
  grep -E '^[a-z_]+:' | \
  sed 's/^/  /'

Blocked 状態の詳細記録

Blocked コメント形式

Blocked 発生時は、ラベル変更と共に以下形式のコメントを追加：

markdown

## Blocked: [reason_code]

**Description**: [問題の詳細説明]

**Suggested Action**: [推奨される解決アクション]

**Context**:
- [関連情報1]
- [関連情報2]

**Blocked at**: 2026-01-17T14:00:00Z

---
> このコメントは `env:blocked` ラベルと連動しています。
> 問題解決後、ラベルを `env:active` に変更し、このコメントに「Resolved」と返信してください。

Blocked Reason コード

Reason	説明	推奨アクション
`design_ambiguity`	設計書実現性チェックNG	設計書修正
`review_loop_exceeded`	レビュー3回失敗	設計書見直し
`dependency_missing`	依存Subtask未完了	依存解決待ち
`external_blocker`	外部要因（API未提供等）	人間エスカレーション
`resource_limit`	環境リソース不足	Docker cleanup
`ci_persistent_failure`	CI 3回連続失敗	手動調査必要

API 操作

主要関数（CLI ラッパー）

関数	用途	コマンド例
`register_env`	環境開始時に登録	`issue-state.sh register 42 abc-123 feature/auth container-use`
`update_phase`	Phase更新	`issue-state.sh phase 42 5-green`
`set_blocked`	Blocked状態に設定	`issue-state.sh block 42 design_ambiguity "設計に矛盾"`
`clear_blocked`	Blocked解除	`issue-state.sh unblock 42`
`get_state`	現在の状態取得	`issue-state.sh get 42`
`list_active`	アクティブな環境一覧	`issue-state.sh list`

直接 gh コマンド

bash

# 環境登録（ラベル追加）
gh issue edit 42 --add-label "env:active,phase:1-env,area:backend"

# Phase 更新（ラベル入れ替え）
gh issue edit 42 --remove-label "phase:4-red" --add-label "phase:5-green"

# Blocked 設定
gh issue edit 42 --remove-label "env:active" --add-label "env:blocked"
gh issue comment 42 --body "## Blocked: design_ambiguity..."

# PR作成済みに更新
gh issue edit 42 --remove-label "env:active" --add-label "env:pr-created"

# 状態取得（JSON）
gh issue view 42 --json number,title,labels,body,comments

# アクティブな環境一覧
gh issue list --label "env:active" --json number,title,labels

# Blocked な環境一覧
gh issue list --label "env:blocked" --json number,title,labels

必須更新ポイント (NON-NEGOTIABLE)

トリガー	アクション	ラベル操作
環境作成開始	ラベル追加 + メタデータ埋め込み	`+env:active`, `+phase:1-env`
Phase 遷移	ラベル入れ替え	`-phase:X`, `+phase:Y`
Blocked 発生	ラベル変更 + コメント追加	`-env:active`, `+env:blocked`
Blocked 解除	ラベル変更	`-env:blocked`, `+env:active`
PR 作成	ラベル変更	`-env:active`, `+env:pr-created`, `+phase:10-pr`
PR マージ	ラベル変更	`-env:pr-created`, `+env:merged`, `+phase:12-merge`
環境削除	ラベル削除	全 `env:`, `phase:` ラベルを削除

セッション復旧（途中再開）

resume コマンド（推奨）

bash

# 復旧情報をJSON形式で取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

出力例:

json

{
  "issue_number": 42,
  "status": "env:active",
  "phase": "5-green",
  "env_id": "abc-123-def",
  "branch": "feature/issue-42-user-auth",
  "env_type": "container-use",
  "action": "reopen_environment",
  "command": "environment_open with env_id=abc-123-def"
}

復旧判定マトリクス

ステータス	Phase	アクション	具体的な操作
`env:active`	`0-branch`	環境作成	`environment_create(from_git_ref=branch)`
`env:active`	`1-env`〜`6-refactor`	環境再開	`environment_open(env_id=...)`
`env:active`	`7-review`〜`8-stress`	レビュー再開	環境を開いてレビューループを継続
`env:active`	`9-approval`	承認待ち	ユーザーに承認ゲートを提示
`env:active`	`10-pr`〜`11-ci`	CI監視	`gh pr checks <pr_number>`
`env:blocked`	-	人間の介入	Blockedコメント確認 → 解決 → `unblock`
`env:pr-created`	-	PR確認	`gh pr view` で状態確認
`env:merged`	-	クリーンアップ	環境削除（残っている場合）
(なし)	-	初期化	`register` で環境を登録

手動復旧手順（参考）

bash

# 1. アクティブな環境を検索
gh issue list --label "env:active" --json number,title,labels

# 2. 特定 Issue の復旧情報を取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

# 3. 出力された action/command に従って再開

並列実行時のルール

Actor	責任
`container-worker`	作業完了後、自身で `phase` ラベルを更新可能
Main agent (Sisyphus)	複数 Issue を並列処理する場合、各 Issue を独立して管理

競合回避:

同一 Issue への同時編集は避ける（既存ルールと同じ）
ラベル操作は GitHub がアトミックに処理するため、ファイルベースより安全

ラベル初期設定

リポジトリに必要なラベルを一括作成：

bash

# ステータスラベル
gh label create "env:active" --color "0E8A16" --description "作業中"
gh label create "env:blocked" --color "D93F0B" --description "人間の介入が必要"
gh label create "env:pr-created" --color "1D76DB" --description "PR作成済み"
gh label create "env:merged" --color "6F42C1" --description "マージ完了"

# Phase ラベル
gh label create "phase:0-branch" --color "FBCA04" --description "ブランチ作成"
gh label create "phase:1-env" --color "FBCA04" --description "環境構築"
gh label create "phase:2-design" --color "FBCA04" --description "設計書参照"
gh label create "phase:3-check" --color "FBCA04" --description "設計実現性チェック"
gh label create "phase:4-red" --color "FBCA04" --description "TDD Red"
gh label create "phase:5-green" --color "FBCA04" --description "TDD Green"
gh label create "phase:6-refactor" --color "FBCA04" --description "リファクタリング"
gh label create "phase:7-review" --color "FBCA04" --description "レビュー"
gh label create "phase:8-stress" --color "FBCA04" --description "ストレステスト"
gh label create "phase:9-approval" --color "FBCA04" --description "承認待ち"
gh label create "phase:10-pr" --color "FBCA04" --description "PR作成"
gh label create "phase:11-ci" --color "FBCA04" --description "CI監視"
gh label create "phase:12-merge" --color "FBCA04" --description "マージ完了"

# 領域ラベル
gh label create "area:backend" --color "C2E0C6" --description "バックエンド"
gh label create "area:frontend" --color "C2E0C6" --description "フロントエンド"
gh label create "area:infra" --color "C2E0C6" --description "インフラ"
gh label create "area:database" --color "C2E0C6" --description "データベース"

CLI スクリプト

使用方法:

bash

bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh <command> [args...]

コマンド	説明	使用例
`register`	環境を登録	`issue-state.sh register 42 abc-123 feature/auth container-use`
`phase`	Phase を更新	`issue-state.sh phase 42 5-green`
`block`	Blocked 状態に設定	`issue-state.sh block 42 design_ambiguity "説明"`
`unblock`	Blocked を解除	`issue-state.sh unblock 42`
`pr-created`	PR作成済みに更新	`issue-state.sh pr-created 42 25`
`merged`	マージ完了に更新	`issue-state.sh merged 42`
`get`	状態を取得	`issue-state.sh get 42`
`list`	アクティブ一覧	`issue-state.sh list`
`resume`	途中再開情報を取得	`issue-state.sh resume 42`
`init-labels`	ラベル一括作成	`issue-state.sh init-labels`

エラーリトライ

スクリプトはネットワークエラーやGitHub APIのレート制限に対して自動リトライを行います。

設定	環境変数	デフォルト
最大リトライ回数	`MAX_RETRIES`	3
リトライ間隔（秒）	`RETRY_DELAY`	5

レート制限時: 60秒待機後にリトライ ネットワークエラー時: RETRY_DELAY秒待機後にリトライ

bash

# カスタムリトライ設定
MAX_RETRIES=5 RETRY_DELAY=10 bash issue-state.sh phase 42 5-green

ハードブロック (違反禁止)

違反	結果
環境開始時にラベル未追加	FORBIDDEN - 復旧不可
Phase 遷移時にラベル未更新	FORBIDDEN - 状態不整合
Blocked 時にコメント未追加	FORBIDDEN - 理由が不明

変更履歴

日付	バージョン	変更内容
2026-01-17	1.0.0	初版作成

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/github-issue-state-management
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

GitHub Issue 状態管理

概要

ラベル体系

ステータスラベル（排他: 1つのみ）

Phase ラベル（排他: 1つのみ）

領域ラベル（任意: 複数可）

メタデータ管理

Issue Body へのメタデータ埋め込み

フィールド定義

メタデータの抽出

Blocked 状態の詳細記録

Blocked コメント形式

Blocked Reason コード

API 操作

主要関数（CLI ラッパー）

直接 gh コマンド

必須更新ポイント (NON-NEGOTIABLE)

セッション復旧（途中再開）

resume コマンド（推奨）

復旧判定マトリクス

手動復旧手順（参考）

並列実行時のルール

ラベル初期設定

CLI スクリプト

エラーリトライ

ハードブロック (違反禁止)

変更履歴

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state