リポジトリのIssueとプロジェクトを初期化する
他の issue-* スキルが前提とする規約を設定します。ここではすべてGitHubに対して書き込みを行います(ラベル、プロジェクト、リポジトリリンク)。作成する内容を明示し、ユーザーの許可を得てから実行してください。gitへのプッシュは行いません。
前提条件: gh auth status で repo と project のスコープが表示されること(そうでない場合は gh auth refresh -s project を実行)。jq がインストールされていること。
1. 確認(読み取り専用)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"
2. ラベル
以下の標準ラベルを作成します(name|description|colour)。リポジトリ固有のコンポーネントラベル(デフォルト backend、frontend; 必要に応じて追加・削除)も追加します。GitHubのデフォルトラベル(enhancement、documentation など)は、依頼がない限りそのままにします。
while IFS='|' read -r n d c; do
gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Something isn't working|d73a4a
feature|New user-facing capability|a2eeef
tech-debt|Tracked technical debt|fbca04
epic|Multi-issue effort|5319e7
backend|Backend / services|0e8a16
frontend|Frontend / web app|1d76db
performance|Performance|fef2c0
security|Security|d93f0b
testing|Tests / CI / E2E|c5def5
privacy|Privacy / GDPR|bfdadc
ai|Addressable by an AI agent without human intervention|7057ff
needs-context|AI-addressable once a quick check or decision is answered (also carries ai)|fbca04
needs-human|Needs a device, store/legal/owner decision, external access or a roadmap choice|d93f0b
wontfix|This will not be worked on|ffffff
EOF
gh label list --repo "$REPO" # create は成功時に出力しないので確認
3. ボード
A. 参照ボードをコピーする(フィールドとビューのみ。項目はコピーしません):
gh project copy <source-number> --source-owner <owner> --target-owner "$OWNER" --title "<リポジトリ名>"
B. 新規作成する:
gh project create --owner "$OWNER" --title "<リポジトリ名>" --format json -q '.number' # 番号を $N として記録
for f in Reach Impact "Confidence (%)" "Effort (days)" RICE; do
gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done
新しいボードにはすでに Status フィールド(Todo、In Progress、Done)があります。これで十分です(Defer オプションはボードのUIで追加できます)。
次にリンクして確認します:
gh project link "$N" --owner "$OWNER" --repo "$REPO"
# その後、issue-project-fields の「最初にIDを解決する」に従って、ボードとすべてのフィールドが見つかることを確認します
4. リポジトリにドキュメント化する
リポジトリのエージェント指示ファイル(AGENTS.md、CLAUDE.md、またはその両方)に以下のセクションを追加し、<...> プレースホルダー(リポジトリ、ボードURL、手順2で作成したコンポーネントラベル)を埋めます。スキルがプラグインから提供されている場合は、その旨とプラグイン名を記載してください。デフォルトブランチではなく、ブランチ上でコミットしてください。
## 作業追跡(GitHub Issues)
バックログは **GitHub Issues**(`<owner/repo>`)にあり、**<ボードタイトル>** プロジェクト(<ボードURL>)で追跡されます。Issueはコンテキスト*および*ステータスの信頼できる情報源です。作業はIssue番号(`#123`)とラベルで参照します。ワークフロースキル: `issue-search`、`issue-file`、`issue-start`、`issue-pr-refs`、`issue-close-out`、`issue-project-fields`、`issue-score`、`issue-link`、`issue-plan-doc`、`issue-file-found`、`issue-audit-scores`、`issue-project-init`(<提供元>)。
### ラベル
| グループ | ラベル | ルール |
|---|---|---|
| タイプ | `bug`、`feature`、`tech-debt`、`epic` | 1つのIssueにつき正確に1つ |
| コンポーネント | <例: `backend`、`frontend`> | 該当するものすべて |
| トピック | `performance`、`security`、`testing`、`privacy` | オプション |
| エージェントルーティング | `ai`、`needs-context`、`needs-human` | オプション。`ai` = エージェントが無人で実行可能。`needs-context` = 簡単な質問に回答すればエージェントが対応可能(`ai`も付与)。`needs-human` = デバイス、外部アクセス、またはオーナーの決定が必要 |
### プロジェクトフィールド
| フィールド | 値 | 備考 |
|---|---|---|
| Status | Todo / In Progress / Done | オーケストレーションエージェントのみが設定 |
| Reach | 1–5 | 影響を受けるユーザー数 |
| Impact | 0.5–3 | 影響の大きさ |
| Confidence (%) | 整数のパーセント(例: `70`) | |
| Effort (days) | 数値 | |
| RICE | `(Reach × Impact × Confidence) / Effort` | Issue本文にも `**Score:** RICE x = (R × I × C%) / Ed` と記載し、Issue単体で読めるようにする |
### Issue本文とワークフロー
**Issue本文**には、説明、現在の状態、やるべきこと、重要な理由、関連ファイル、見積もりなど、すべての記録を記載します。関連作業は `#n` でリンクし、「blocked by」(本文および依存関係API。`issue-link` を参照)で順序を表現します。大規模な作業は `epic` とし、計画はIssue本文に、各スライスはサブIssueとして管理します。
- **開始前:** まず検索(`issue-search`)し、重複を避けるため再利用または拡張する。
- **作業中:** 項目を In Progress に設定し、アサインする(`issue-start`)。ブランチ名にはIssue番号を含める(`feat/123-short-desc`)。バグやテックデットは、失敗するテストから始める。スコープを広げる代わりに、無関係な発見は新しいIssueとして登録する(`issue-file-found`)。
- **完了時:** すべてのPRはそのIssueを参照する(Issueごとに `Closes #n`、エピックには `Part of #n`。`issue-pr-refs`)。マージ後、Status = Done に設定し、関連Issueを更新する(`issue-close-out`)。
- `gh` には `project` スコープが必要(`gh auth refresh -s project`)。Issue/プロジェクトのステータス変更はオーケストレーションエージェントのみが行う。委任されたサブエージェントはIssueの作成、編集、クローズを行わない。
5. オプション: エピックの種をまく
issue-file(タイプ epic)→ issue-plan-doc → 各スライスに対して issue-file + issue-link + issue-project-fields + issue-score。
落とし穴
gh label create、gh project copy|link|item-editは成功時に出力しないため、必ず確認すること。- コピーされたボードは空で始まります。
item-addは冪等です。 - サブIssueと依存関係のREST呼び出しでは、Issueの数値データベースIDを使用します(
issue-linkを参照)。 - Confidence は整数のパーセント(
70)です。IDはボードごとに異なるため、常に再検出してください(issue-project-fields)。