acli-jira

目的

Jira とのやり取りが必要なときは、このスキルを使用します。チケットの閲覧、新しい作業項目の作成、既存の作業項目の更新、JQL による検索、ステータスの遷移、担当者の割り当て、コメントの追加、プロジェクトの閲覧などに利用できます。acli jira を使うと、CLI から Jira Cloud を全面的に管理できます。

用途に応じたコマンド

• acli jira workitem view：キーを指定して特定のチケットを閲覧します。チケットの詳細、説明、ステータス、担当者などの確認に使用します。
• acli jira workitem search：JQL クエリを使ってチケットを検索します。作業項目の検索、絞り込み、一覧表示に使用します。
• acli jira workitem create：新しいチケットを作成します。ユーザーがバグ、タスク、ストーリー、エピックの登録を希望する場合に使用します。
• acli jira workitem edit：既存のチケットの要約、説明、ラベル、タイプ、担当者を変更します。
• acli jira workitem transition：チケットを新しいステータス（例：「In Progress」、「Done」）に移行します。
• acli jira workitem assign：チケットの担当者を変更または解除します。
• acli jira workitem comment create：チケットにコメントを追加します。
• acli jira workitem comment list：チケットのコメントを読み込みます。
• acli jira project list：利用可能なプロジェクトを一覧表示します。プロジェクトキーの確認に使用します。
• acli jira project view：特定のプロジェクトの詳細を閲覧します。
• acli jira sprint list-workitems：スプリント内のチケットを一覧表示します（--sprint と --board の ID が必要です）。
• acli jira board search：名前またはキーワードでボードを検索します。

主な概念

• 読み取りコマンド（view、search、comment list、project list など）では、機械可読な出力を得るため、必ず --json を使用します。
• 変更コマンド（edit、transition、assign）では、非対話型シェルで処理が停止する原因となる確認プロンプトを省略するため、必ず --yes を使用します。
• 検索には JQL（Jira Query Language）を使用します。--jql "..." で指定します。
• @me は認証済みユーザーを表す省略形です（--assignee で使用できます）。
• ラベルはカンマ区切りで指定します：--label "bug,backend,urgent"。
• 作業項目のタイプには Jira の課題タイプを使用します：Task、Bug、Story、Epic、Sub-task など。--type で指定します。
• キーは PROJ-123 のようなプロジェクト接頭辞付きの ID です。複数のキーはカンマ区切りで指定します：--key "PROJ-1,PROJ-2"。

推奨ワークフロー

1. プロジェクトを確認する：acli jira project list --json を実行して、利用可能なプロジェクトキーを確認します。
2. チケットを検索する：acli jira workitem search --jql "project = PROJ AND ..." --json を実行して、関連する作業項目を検索します。
3. チケットを閲覧する：acli jira workitem view PROJ-123 --json を実行して、詳細を確認します。
4. 必要に応じて、以下のコマンドを使って作成、編集、ステータス遷移を行います。

よく使う JQL パターン

# All open tickets in a project
--jql "project = PROJ AND status != Done"

# Tickets assigned to me
--jql "assignee = currentUser()"

# Bugs created this week
--jql "project = PROJ AND type = Bug AND created >= startOfWeek()"

# Tickets with a specific label
--jql "project = PROJ AND labels = backend"

# Search by summary text
--jql "project = PROJ AND summary ~ \"search term\""

# High priority open items
--jql "project = PROJ AND priority in (High, Highest) AND status != Done"

# Recently updated
--jql "project = PROJ AND updated >= -7d ORDER BY updated DESC"

例

チケットの閲覧

acli jira workitem view PROJ-123 --json

# View specific fields only
acli jira workitem view PROJ-123 --fields "summary,status,assignee,labels,comment" --json

チケットの検索

# Search with JQL, get JSON output
acli jira workitem search --jql "project = PROJ AND status = 'In Progress'" --json

# Search with specific fields and a result limit
acli jira workitem search --jql "project = PROJ AND assignee = currentUser()" \
  --fields "key,summary,status,priority,labels" --limit 20 --json

# Get count of matching tickets
acli jira workitem search --jql "project = PROJ AND type = Bug" --count

チケットの作成

# Basic creation
acli jira workitem create \
  --project "PROJ" \
  --type "Task" \
  --summary "Implement feature X" \
  --description "Detailed description here" \
  --label "backend,feature" \
  --assignee "@me" \
  --json

# Create a bug with a parent (sub-task)
acli jira workitem create \
  --project "PROJ" \
  --type "Bug" \
  --summary "Fix login timeout" \
  --description "Users report timeout after 30s on the login page" \
  --label "bug,auth" \
  --parent "PROJ-100" \
  --json

# Create with description from a file
acli jira workitem create \
  --project "PROJ" \
  --type "Story" \
  --summary "User onboarding flow" \
  --description-file description.txt \
  --json

チケットの編集

# Edit summary and labels
acli jira workitem edit --key "PROJ-123" \
  --summary "Updated summary" \
  --labels "backend,urgent" \
  --yes --json

# Change assignee
acli jira workitem edit --key "PROJ-123" \
  --assignee "[email protected]" \
  --yes --json

# Remove labels
acli jira workitem edit --key "PROJ-123" \
  --remove-labels "stale" \
  --yes --json

チケットのステータス遷移

# Move to In Progress
acli jira workitem transition --key "PROJ-123" --status "In Progress" --yes --json

# Mark as Done
acli jira workitem transition --key "PROJ-123" --status "Done" --yes --json

# Transition multiple tickets
acli jira workitem transition --key "PROJ-1,PROJ-2,PROJ-3" --status "Done" --yes --json

チケットの担当者割り当て

# Assign to self
acli jira workitem assign --key "PROJ-123" --assignee "@me" --yes --json

# Assign to someone else
acli jira workitem assign --key "PROJ-123" --assignee "[email protected]" --yes --json

# Remove assignee
acli jira workitem assign --key "PROJ-123" --remove-assignee --yes --json

コメント

# Add a comment
acli jira workitem comment create --key "PROJ-123" --body "This is ready for review"

# List comments
acli jira workitem comment list --key "PROJ-123" --json

プロジェクト

# List all projects
acli jira project list --json

# View a specific project
acli jira project view --key "PROJ" --json

# List recently viewed projects
acli jira project list --recent --json

スプリントとボード

# Find a board
acli jira board search --name "My Team" --json

# List sprints on a board
acli jira board list-sprints --id 42 --json

# List tickets in a sprint
acli jira sprint list-workitems --sprint 101 --board 42 --json

重要なヒント

• チケットを作成するときは、まだわかっていない場合、必ずユーザーにプロジェクトキーを確認します。acli jira project list --json を使って、利用可能なプロジェクトを確認します。
• チケットを作成するときは、コンテキスト（例：コードベースの領域、作業の種類）から適切なラベルを判断します。ラベルを付けると、チケットを見つけやすくなります。
• 読み取り操作では、結果を解析し、ユーザー向けに要約できるよう、--json 出力を優先します。
• 対話型プロンプトを避けるため、すべての書き込み操作で --yes を使用します。
• 検索結果が大量になる場合は、--limit で件数を制限するか、--paginate ですべて取得します。
• 遷移先のステータス名はプロジェクトによって異なります。ステータス遷移に失敗した場合、エラーメッセージに有効なステータスが表示されます。
• CLI フラグで公開されていないカスタムフィールドを設定するには、additionalAttributes とともに --from-json を使用します。acli jira workitem create --generate-json でテンプレートを生成できます。

ボード固有の規約

プロジェクト固有のボード規約（必須フィールド、カスタムフィールドのマッピング、ラベル、テンプレート）については、ファイル ~/.config/opencode/skills/acli-jira/boards.md が存在する場合は、その内容を確認してください。このファイルには、既知のボードでチケットを作成または管理する前に必要な、ボード固有の規約が記載されています。

これにより、中核となるスキルを公開したまま、ボード規約を非公開にできます（バージョン管理に含めずに済みます）。