spec-to-issue

spec-to-issue — Spec から GitHub Issue を作成

Spec ディレクトリ（.specs/{feature}/）から GitHub Issue を自動生成します。

言語ルール

1. 入力言語を自動検出 → 同じ言語で出力
2. 日本語の入力 → 日本語の Issue を作成し、テンプレートの参照には references/issue-template.ja.md を使用
3. 英語の入力 → 英語の Issue を作成し、テンプレートの参照には references/issue-template.md を使用
4. 明示的な上書き指定を優先

参照ファイルの選択：検出した出力言語に基づいて、対応するテンプレートを使用します：

• 英語 → references/issue-template.md
• 日本語 → references/issue-template.ja.md

実行フロー

1. Spec ディレクトリの特定

引数あり：spec-to-issue auth-feature → .specs/auth-feature/ を使用します

引数なし：.specs/ をスキャンして一覧を表示 → ユーザーに選択を求めます

Spec directories found in .specs/:
1. auth-feature (requirement.md, design.md, tasks.md)
2. member-management (requirement.md, tasks.md)
Which spec do you want to create an issue from?

2. ファイルの検証

必須：requirement.md が存在する必要があります。存在しない場合は、エラーで終了します。 推奨：design.md と tasks.md。 いずれかが存在しない場合、残りのドキュメントから具体的なスコープと受け入れ基準を定義できるときに限り、処理を続行します。Issue の作成前に、欠落している情報源を報告します。

3. Spec の分析

Spec ファイルはコピーするセクションではなく、候補となる情報源として扱います。 以下を抽出して選定します：

requirement.md：

• タイトル：最初の # 行から、「Requirements」「要件定義書」などの接尾辞を除去
• 問題と、完了後に観測できる状態
• 現在の動作と期待される動作
• 含まれるスコープと除外されるスコープ
• 要件レベルの受け入れ基準

design.md：

• 互換性、セキュリティ、外部との契約、または他の要件によって制約される決定事項とその理由
• 実装者だけでは安全に決定できない未解決の質問

tasks.md：

• 補足となる実装の詳細と、追加の完了根拠
• 既定では、フェーズ見出し、タスク見出し、見積もり、技術一覧をコピーしないでください

削除すると実装上の決定または完了の判定が変わる場合に限り、その候補を残します。選定手順の詳細は、該当する言語の Issue テンプレート参照ファイルを確認してください。

4. プロジェクト設定の解決

次の優先順位でデフォルト値を決定します：

Command arguments > .specs/.config.yml > CLAUDE.md > Built-in defaults

CLAUDE.md から：

• ブランチ名：Git Workflow セクションの PR ターゲットブランチ → --branch のデフォルト値
• GitHub Organization：リポジトリ URL から推定

.specs/.config.yml（任意）：

default-branch: develop
default-labels: [feature, spec-generated]
project-number: 7
assignee: username

5. プロジェクトテンプレートの確認と Issue 本文の作成

本文を作成する前に、リポジトリの Issue フォーム、Issue テンプレート、コントリビューションルール、必須フィールドを確認します。プロジェクトテンプレートがある場合はそれを優先し、見出し、順序、フィールド、チェックボックスを維持したうえで、選定した情報を当てはめます。

テンプレートの詳細は、言語ルールに基づく該当する参照ファイルを確認してください：

• 英語：references/issue-template.md
• 日本語：references/issue-template.ja.md

プロジェクトテンプレートがない場合は、問題、完了後の状態、現在と期待される動作、含まれるスコープと除外されるスコープ、受け入れ基準、制約となる決定事項、未解決の質問を明示した実行契約を作成します。タスクの分解と補足情報については、Spec ファイルへのリンクを記載します。

6. Issue の作成

--preview なし（デフォルト）：簡単な概要を表示し、gh issue create を実行します

Creating Issue:
  Title: [Feature] Member Management
  Labels: feature, spec-generated
  Outcome: Members can be invited and assigned a repository role
  Acceptance criteria: 4
→ Running gh issue create...
Issue #42 created: https://github.com/org/repo/issues/42

--preview あり：Issue の全文を表示して確認を求めた後、実行します

7. 追加アクション（任意）

• --label：指定したラベルを適用
• --project：gh project item-add を使用して GitHub Project ボードに追加
• --assignee：担当者を設定

オプション

オプション	説明	デフォルト
--preview	確認用に Issue 本文を表示	OFF
--label <labels>	カンマ区切りのラベル	.config.yml の値、またはなし
--project <number>	GitHub Project に追加	.config.yml の値、またはなし
--branch <name>	Spec のリンクに使用するベースブランチ	CLAUDE.md、または main
--assignee <user>	担当者を設定	.config.yml の値、またはなし

spec-generator との統合

spec-generator の full フェーズが完了した後、次のように提案します。

All three spec documents have been generated.
→ Create a GitHub Issue from them? (Y/n)

はいの場合、同じディレクトリで spec-to-issue を実行します。

エラー処理

状況	対応
.specs/ が存在しない	エラー：仕様ディレクトリが見つかりません
requirement.md がない	エラー：requirement.md が必要です
design.md または tasks.md がない	具体的なスコープと受け入れ基準が残っている場合に限り続行します。それ以外の場合は停止し、欠落しているソースを報告します
gh CLI が認証されていない	エラー：ユーザーに gh auth login を案内します
具体的な受け入れ基準がない	Issue の作成前に停止します。一般的な完了確認項目を作り出さないでください
プロジェクトテンプレートが見つかった	組み込みテンプレートを追加するのではなく、必須の見出しと項目を維持します

使用例

# With argument
/spec-to-issue auth-feature

# Auto-detect and select
/spec-to-issue

# With preview
/spec-to-issue auth-feature --preview

# With labels and Project
/spec-to-issue auth-feature --label "feature,priority:high" --project 7

# After spec-generator
"Create full spec for todo-app" → done → "Turn this into an issue"

# Japanese
「仕様書を全部作って」→ 完了 →「これをIssueにして」