create-jira-ticket

ユーザーの指示に基づき、Atlassian CLI（acli）を使って JIRA チケットを作成します。ブランチ名に JIRA キーが含まれていて現在のブランチのプロジェクトを推測できる場合は、同じプロジェクトを優先してください。それ以外の場合は、どのプロジェクトにするかユーザーに尋ねてください。そのプロジェクトのエピックを読み込み、新しい作業に最適なエピックを推測し、プレビューを表示してから、課題を作成する前に明示的な確認を得てください。

使い方：

• /create-jira-ticket — チケットの説明を $ARGUMENTS として同じメッセージに渡します（概要、バグか機能か、受け入れ条件、リンクなど）。

手順：

1. acli がインストールされ、認証済みであることを確認します。

   • acli auth status を実行します。
   • コマンドが見つからない場合は、以下のエラーを表示して停止します。

     Atlassian CLI (acli) is not installed.
     Install with: brew tap atlassian/acli && brew install acli
     

   • 認証に失敗した場合は、以下のエラーを表示して停止します。

     Atlassian CLI is not authenticated.
     Run: acli auth login
     

2. JIRA プロジェクトキーを特定します。

   • git branch --show-current を実行します。detached HEAD の場合はその旨を記録しますが、プロジェクトを選択できる場合は続行します。
   • ブランチ名から、パターン [A-Z][A-Z0-9]+-[0-9]+（大文字と小文字を区別しない。大文字に正規化）に一致する JIRA 課題キーを探します。見つかった場合は、- より前の部分をプロジェクトキーに設定します（例：PROJ-123 → PROJ）。
   • キーが見つからない場合は、次を実行します。

     acli jira project list --json
     

     AskUserQuestion を使って、ユーザーにプロジェクトキーを選んでもらいます。

3. $ARGUMENTS から指示を読み取ります。

   • 空の場合は、AskUserQuestion を使って作成するチケットの内容を確認してから続行します。
   • 可能な範囲で次の内容を推測します。
     • 概要（簡潔で、命令形のタイトル）
     • 課題タイプ（Bug、Story、Task など）— 文言から判断します（「fix」「broken」→ Bug、「add」「implement」→ Story／Task）。
     • 説明 — 明確なセクションに分けて下書きします（バグの場合は問題の内容、手順、期待される結果と実際の結果。Story／Task の場合は目標と受け入れ条件）。JIRA の説明フィールドでは Markdown がレンダリングされないため、これを JIRA 用の ADF に変換します（以下のADF 形式のリファレンスを参照）。
     • 任意項目：優先度、ラベル、Figma URL（https://www.figma.com/...）
     • ユーザーが特定のエピック名（PROJ-100 のようなキー、またはタイトル）を指定した場合は、手順 5 で手動で指定されたエピック候補として扱います。

4. プロジェクト内のエピックを一覧表示します。

   • 次を実行します。

     acli jira workitem search --jql "project = <PROJECT-KEY> AND issuetype = Epic" --json --limit 50
     

     <PROJECT-KEY> を実際のキーに置き換えます。結果が空の場合は、JIRA のバージョンで必要な場合に限り、issuetype = Epic を type = Epic に置き換えて再試行します。それでも結果が空の場合は、このプロジェクトにエピックが見つからなかったことを報告します。
   • JSON から各エピックのキー、概要、ステータス（存在する場合）を取得して表示します。

5. エピックを推奨します。

   • 手順 3 でユーザーが手動でエピックを指定し、そのキーが一覧に存在する場合（または acli jira workitem view <KEY> --fields summary,issuetype --json で Epic タイプとして確認できる場合）は、そのエピックを推奨エピックにします。
   • それ以外で、エピックがない場合は、推奨エピックを「なし」に設定して照合をスキップします。
   • それ以外の場合は、新しいチケットの概要と説明（キーワード、製品領域、コンポーネント）を各エピックの概要（および返されている場合は説明）と比較します。テーマが最もよく一致するエピックを選びます。同程度の場合は、Done／Closed ではないエピックを優先します。
   • 推奨理由を1 文で記述します（例：「決済フローに関する作業のため、『Checkout』エピックと一致します。」）。

6. 確認用プレビュー（必須）：

   • 明確なプレビューを表示します：
     • プロジェクト、課題タイプ、要約
     • 推奨するエピック（キー＋要約＋理由）、または「なし — プロジェクトにエピックがありません」／「なし — ユーザーが親課題を辞退しました」
     • 説明の概要または箇条書き（プレビューではADF全体を表示する必要はありません）
     • FigmaのURL（ある場合）
   • AskUserQuestion を使って、ユーザーが次の操作を行えるようにします：
     • 推奨するエピックを指定して作成（子課題の作成時は、ステップ7を参照して parent にそのエピックのキーを設定します）
     • 一覧から別のエピックを選択（キー＋要約を表示）
     • エピックを親に指定せず作成（parentを省略します。課題タイプが許可する場合のみ。選択された場合、エピックを強制しないでください）
     • 編集 — ユーザーが指示を修正します。ステップ3に戻ります
     • キャンセル — 停止
   • ユーザーが作成を確認するまで（上記のいずれかの「作成」方法を選択するまで）、acli jira workitem create を呼び出さないでください。

7. acli で作業項目を作成します：

   • 作成した内容からADF 説明を作成します（見出し、段落、箇条書き、受け入れ条件のタスクリスト）。以下の ADF形式リファレンスに従うか、acli jira workitem create --generate-json を実行し、サイトのスキーマに合わせます。
   • JSONファイルを書き込み、次を実行します：

     acli jira workitem create --from-json <temp-file.json> --json
     

   • "project": "<PROJECT-KEY>"、"type": "<IssueType>"、"summary": "..."、および "description": { ... ADF ... } を含めます。
   • 親課題／エピック： ユーザーがエピックを確認した場合、課題タイプが Epic でない限り、"parent": "<EPIC-KEY>" を含めます（ユーザーが明示的に依頼した場合を除き、Epicを別のEpicの下に設定しないでください）。APIが parent を拒否する場合（一部のクラシックプロジェクトでは、代わりに Epic Link カスタムフィールドを使用します）、エラーを読み、プロジェクトの --generate-json を確認して、正しいフィールド形式で一度再試行します。それでも失敗する場合は、Jira UIでエピックを設定するようユーザーに伝え、親課題なしで課題が作成されていた場合は、作成されたキーを報告して停止します。
   • 成功した場合は、JSONに含まれていれば、新しい キー と 閲覧URL を出力します。

8. Figmaデザインを添付します（指定されている場合）：

   • 指示にFigmaのURLが含まれている場合は、Figma for Jiraの Add Design の方法で添付します。
   • デザインは課題レベルのエンティティプロパティとして保存されます。作成した課題のJSONレスポンスからサイトURLを取得し、次の手順を実行します：
     1. Figmaプロパティキーを特定する： 課題のエンティティプロパティを一覧表示します：

        curl -s -H "Authorization: Bearer $(acli auth token)" \
          "https://<site>.atlassian.net/rest/api/3/issue/<JIRA-ID>/properties/"
        

     2. デザインプロパティを設定する： プロパティキーと値の形式はFigma for Jiraアプリによって異なります。通常は次のようになります：

        curl -s -X PUT -H "Authorization: Bearer $(acli auth token)" \
          -H "Content-Type: application/json" \
          "https://<site>.atlassian.net/rest/api/3/issue/<JIRA-ID>/properties/<figma-property-key>" \
          -d '{"figmaDesigns": [{"url": "<figma-url>", "name": "<design-name>"}]}'
        

   • REST呼び出しに失敗した場合は、代わりにFigmaのURLを説明に記載し、ユーザーが手動で Add Design を使用できることを伝えます。

9. 例外的なケース：

   • 必須のカスタムフィールド：作成時に検証エラーが発生した場合は、フィールドを表示してユーザーに値を尋ね、その後再試行します。
   • issuetype = Epic の検索結果がないものの、プロジェクトで別のエピックタイプ名が使われている場合は、プロジェクトの課題タイプを一覧表示し（acli／REST）、JQLを一度調整します。

ユーザーへの出力の概要： プロジェクト、新しい課題キー、URL、使用したエピック（またはなし）、Figmaの添付結果（または代替方法）。

ADF 形式のリファレンス

JIRA は Markdown をレンダリングしません。説明にはAtlassian Document Format（ADF）（JSON ベースのドキュメント形式）を使用する必要があります。--description-file フラグはファイルの内容をプレーンテキストとして扱うため、リッチな説明には --from-json を使用してください。

重要： JSON ペイロードの description フィールドは、文字列ではなく ADF オブジェクトである必要があります。acli jira workitem create --generate-json を実行すると、サイトで期待されるスキーマを確認できます。

一般的な ADF ノードタイプ：

Markdown	ADF type	備考
## Heading	attrs.level を持つ heading	レベル 1～6
プレーンテキスト	text の子要素を持つ paragraph
**bold**	marks: [{"type": "strong"}] を持つ text
*italic*	marks: [{"type": "em"}] を持つ text
- item	bulletList > listItem > paragraph
1. item	orderedList > listItem > paragraph
- [ ] task	taskItem（状態：TODO／DONE）を持つ taskList
`code`	marks: [{"type": "code"}] を持つ text	インラインコード
コードブロック	attrs.language を持つ codeBlock
---	rule	水平線
[link](url)	marks: [{"type": "link", "attrs": {"href": "url"}}] を持つ text

ADF の説明の例：

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Description" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "What needs to be done and why." }]
    },
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Acceptance Criteria" }]
    },
    {
      "type": "taskList",
      "attrs": { "localId": "ac-list" },
      "content": [
        {
          "type": "taskItem",
          "attrs": { "localId": "ac-1", "state": "TODO" },
          "content": [{ "type": "text", "text": "First criterion" }]
        },
        {
          "type": "taskItem",
          "attrs": { "localId": "ac-2", "state": "TODO" },
          "content": [{ "type": "text", "text": "Second criterion" }]
        }
      ]
    }
  ]
}