cawplan-coding-commit

CawPlan Coding Commit

ブートストラップ

cawplan skill check

ワークフロー

このスキルでは、次の 2 つのワークフローをサポートします。

• 単日ワークフロー： 収集 → 割り当て → レビュー → アップロード → 当月分のバックフィル
• 月単位の欠落分ワークフロー： ある月のクラウド上の欠落日を照会 → 欠落日のみ収集してアップロード

サポートされている単日の引数：

• 日付の指定なし、today → 今日の日付
• yesterday、yestoday → 昨日の日付（yestoday はよくある誤記として受け付けます）
• YYYY-MM-DD → 指定されたレポートの日付
• 昨日の日次レポートのアップロードを求める自然言語のリクエスト → 昨日の日付
• 特定の YYYY-MM-DD の日次レポートのアップロードを求める自然言語のリクエスト → 指定された日付

サポートされている月単位の欠落分の引数：

• last month → 前の暦月
• YYYY-MM → 指定された暦月
• 特定の月の日次レポートの欠落分のアップロードまたは補完を求める自然言語のリクエスト → 指定された暦月

例：

• /cawplan-coding-commit
• /cawplan-coding-commit yesterday
• /cawplan-coding-commit 2026-06-20
• /cawplan-coding-commit last month
• /cawplan-coding-commit 2026-06

ユーザーが単日の引数を指定した場合は、ステップ 1 の前にその日付を解決し、以下のすべてのコマンドでその日付を使用してください。ユーザーが月単位の欠落分の引数を指定した場合は、単日ワークフローをスキップし、以下の月単位の欠落分ワークフローに従ってください。ユーザーがサポートされていない引数を指定した場合は、推測せず、有効な日付または月を尋ねてください。

アップロードの前に、AI が要約したレビューを必ず収集して提示してください。レビュー後に 2 回目の確認を待たず、すぐにアップロードしてください。

権限の最小化

レポートの収集中に表示される権限プロンプトを最小限に抑えてください。

• 細かいコマンドを多数実行するのではなく、論理的なフェーズごとに 1 つのシェルブロックとして実行してください。
• Cursor エージェントのシェルツールを使用して収集フェーズを実行する場合は、シェルブロック全体に対して 1 回だけ完全なネットワークアクセスを要求してください（required_permissions: ["full_network"]）。収集時に Cursor Dashboard API（cursor.com）が呼び出されることがあるためです。
• 生成された ai-daily-*.json レポートはすべて、現在のリポジトリではなくシステムの一時ディレクトリに保存してください。これにより、リポジトリへの書き込みプロンプトを避け、生成されたレポートファイルが作業ツリーに含まれないようにできます。
• collect、assign、review、upload には、ワークフロー内で同じ一時ディレクトリを再利用してください。
• Web で割り当てる場合は、すべてのファイルを 1 つの cawplan session assign --web --files ... コマンドにまとめてください。レポートごとに割り当てコマンドを実行しないでください。

レポートの収集前に、CLI を使ってワークフロー専用の一時ディレクトリを 1 つ作成してください。これにより、macOS、Linux、Windows で同じコマンドを使用できます。

report_dir="$(cawplan session temp-dir)"

以降の collect、assign、review、upload の各ステップでは、このディレクトリ配下の絶対パスを使用してください。

report_file="$report_dir/ai-daily-<YYYY-MM-DD>.json"

ユーザーが出力パスを明示的に指定しない限り、生成された日次レポートの JSON ファイルを現在の作業ディレクトリに書き込まないでください。

月次不足分ワークフロー

ユーザーから、ある月のレポートのアップロード／不足分の補完を求められた場合、または last month や YYYY-MM などの月を指定された場合に、このワークフローを使用します。

ステップ M1 — 月の範囲を決定します：

• last month の場合、前暦月の初日から末日までを指定します。
• 過去の YYYY-MM の場合、その月の初日から末日までを指定します。
• 現在の YYYY-MM の場合、その月の初日から今日までを指定します。
• 指定された月以外の日付を含めないでください。

ステップ M2 — クラウド上の不足日を照会します：

cawplan session backfill --from <YYYY-MM-01> --to <YYYY-MM-last-or-today> --dry-run

このドライランでは missing_dates のみを使用します。すでにアップロード済みの日付を収集したり、上書きしたりしないでください。missing_dates が空の場合は、指定された月に不足しているレポートはないことをユーザーに伝え、終了します。

ステップ M3 — 並行数を制限して不足日を収集します：

collect_concurrency="${CAWPLAN_COLLECT_CONCURRENCY:-5}"
i=0
for date in <date1> <date2> ...; do
  cawplan session collect --date $date --output "$report_dir/ai-daily-$date.json" &
  i=$((i + 1))
  if [ $((i % collect_concurrency)) -eq 0 ]; then
    wait
  fi
done
wait

収集処理では Cursor Dashboard API を呼び出す場合があるため、並行数を制限してください。デフォルトの並行数は 5 です。ネットワークまたは Cursor API が不安定な場合にのみ、CAWPLAN_COLLECT_CONCURRENCY を下げてください。

ステップ M4 — 製品／リポジトリ／チケットの割り当て：

新たに収集したすべてのファイルに対して、製品／リポジトリ／チケットの割り当てを実行します。

ステップ M5 — チケットの進捗を書き戻します：

sessions[].ticket_ids を含む、新たに収集した不足日のレポートすべてに対して、以下のチケット進捗の書き戻しを実行します。

ステップ M6 — 不足しているレポートをアップロードします：

新たに収集した不足日のファイルを、日付順に個別にアップロードします：

cawplan session report --file "$report_dir/ai-daily-<YYYY-MM-DD>.json"

アップロード後、指定された月、アップロードした日付、アップロードした各レポートのセッション数、各サーバー応答コードを報告します。

1 日のワークフロー

ステップ 1 — 収集：

report_file="$report_dir/ai-daily-<YYYY-MM-DD>.json"
cawplan session collect --date <YYYY-MM-DD> --output "$report_file"

ステップ 2 — プロダクト／リポジトリ／チケットの割り当て：

$report_file に対して プロダクト／リポジトリ／チケットの割り当て を実行し、続行する前にレビューを完了して、プロダクト、リポジトリ、チケットの表示 ID を確認または編集できるようにします。

ステップ 3 — ユーザーとレポートをレビューする：

レビュー内容の契約 で説明されているレビュー全体を提示します。統計表だけを表示してはいけません。

ステップ 4 — チケットコンテキストの確認：

レポート作成時に、ユーザーにチケット ID を手動で提示するよう求めてはいけません。cawplan session collect は、ticket_id、ticket_display_id、CawPlan の課題 URL、表示 ID など、セッションの human_inputs にある明示的なチケット参照を自動的に解析します。解決済みのチケットは、Web 割り当てページでのレビュー用に保持されます。割り当てでは、選択したプロダクト、または同じプロダクトラインに属する別のプロダクトのチケットを選択できます。

$report_file をレビューする際は、すでに含まれている sessions[].ticket_ids と sessions[].ticket_display_ids があれば、それについて言及します。チケットコンテキストは、明示的なユーザー入力の参照または割り当てページでの編集に基づくものとし、キーワード検索や推測でチケットを探してはいけません。

ステップ 5 — チケットの進捗を書き戻す：

$report_file に sessions[].ticket_ids が含まれている場合は、以下の チケットの進捗の書き戻し を実行します。このステップはスキルのワークフローに属し、cawplan session assign --web の一部ではありません。割り当てでは、プロダクト／リポジトリ／チケットのリンクを日次レポートに保存するだけです。

ステップ 6 — アップロード：

cawplan session report --file "$report_file"

ステップ 7 — 今月のレポートの不足日を確認する：

cawplan session backfill --from <YYYY-MM-01> --to <YYYY-MM-DD> --dry-run

レポートの月の初日を --from に、レポート日を --to に指定します。返された missing_dates をユーザーに提示します。不足日がなければ、その旨を伝えて終了します。

ステップ 8 — 並行数を制限して不足日ごとに収集する：

不足日を少数の並行数で開始します：

collect_concurrency="${CAWPLAN_COLLECT_CONCURRENCY:-5}"
i=0
for date in <date1> <date2> ...; do
  cawplan session collect --date $date --output "$report_dir/ai-daily-$date.json" &
  i=$((i + 1))
  if [ $((i % collect_concurrency)) -eq 0 ]; then
    wait
  fi
done
wait

日付ごとの処理は独立していますが、制限なしで並行収集すると Cursor Dashboard API に過度な負荷がかかり、タイムアウトが発生することがあります。デフォルトの並行数は 5 です。ネットワークが不安定な場合は CAWPLAN_COLLECT_CONCURRENCY を 1 または 2 に減らしてください。

ステップ 9 — 不足レポートのプロダクト／リポジトリ／チケットの割り当て：

新たに収集したすべてのファイルに対して、プロダクト／リポジトリ／チケットの割り当て を実行します。

ステップ 10 — 不足レポートのチケット進捗を書き戻す：

sessions[].ticket_ids が含まれる新たに収集したファイルごとに、以下の チケットの進捗の書き戻し を実行します。

ステップ 11 — 不足レポートをアップロードする：

日付順に、各ファイルを個別にアップロードします：

cawplan session report --file "$report_dir/ai-daily-<YYYY-MM-DD>.json"

バックフィルは、アップロードしたレポートの当月内にとどめ、月をまたいではいけません。

---

チケットの進捗書き戻し

このステップは、製品／リポジトリ／チケットの割り当てを確認して保存した後にのみ実行してください。チケットの詳細を更新するために cawplan session assign --web に依存しないでください。この書き戻しはスキルが担当します。

1. レポートの JSON ファイルを読み込み、sessions[].ticket_ids を確認します。

2. セッションを ticket_id ごとにグループ化します。

3. グループ化したすべてのチケットを Cloud で解決します。

   cawplan tickets search --unique_ids "<ticket_id_1>,<ticket_id_2>" --page_size 100
   

4. 各グループについて、Cloud の結果に unique_id、product_id、version_id があり、グループ内のすべてのセッションの product_id が返されたチケットの product_id と一致する場合にのみ書き戻します。解決できないチケット、product_id／version_id がないチケット、製品が一致しないチケットはスキップします。

5. グループ化したセッションの human_inputs を要約し、簡潔な HTML の progress_comment を作成します。生のプロンプトをそのまま転記したり、分類されたトピックを列挙するだけにしたりしないでください。チケットグループごとに、次のようにします。

   • レポートレベルの human_inputs[] のうち、グループ内の session_id と一致するものと、グループ内の各 session.human_inputs[] の両方から、人間による入力を収集します。
   • 収集した人間による入力ごとに、content のみを読み取ります。チケットの進捗を書き戻す際に、assistant_message を読んだり要約したりしないでください。
   • 最も重要な変更結果、決定／方針、未解決のフォローアップのみを、1～3個の短い箇条書きにまとめます。
   • 各箇条書きは簡潔にし、できれば1文、120文字未満にします。
   • タイトル、エージェント、プロジェクト、ファイル数、行数の差分などのセッションメタデータは、補足情報としてのみ使用します。
   • 「Updated from ...」のような独立した段落は追加せず、コメント全体を視覚的に簡潔に保ちます。
   • 最終的な HTML に空行を入れないでください。隣接するタグは連続させ、<p>、<ul>、<li> の間に空行を入れないでください。
   • グループ内のセッションに人間による入力がない場合は、チケットへの書き戻しをスキップし、その根拠となる人間による入力がなかったことを記載します。

   次の形式を使用します。

   <p><strong>AI session progress CWP-14471</strong> (2026-07-09)</p><ul><li><strong>Guardrails:</strong> only attach Cloud-resolved tickets that match the session product.</li><li><strong>Write-back:</strong> summarize human inputs in this skill before uploading the report.</li></ul>
   

   見出しに表示する ID には、利用可能な場合は sessions[].ticket_display_ids を使用します。HTML に入れる前に、ユーザー／セッションのテキストをエスケープしてください。箇条書きのテキストは、human_inputs[].content に基づく、読みやすい要約にします。生の入力テキストは使用しないでください。

6. CLI を使用して HTML を progress_comment に書き戻します。直接 HTTP を使用しないでください。

   cawplan tickets update "<product_id>" "<version_id>" "<ticket_id>" --progress_comment "$progress_comment"
   

   手順 3 の検索結果にある unique_id を優先して使用します。CLI ではチケットの display_id（例：CAWP-20544）も指定でき、自動的に解決されてから PUT されます。解決せずに raw HTTP で display_id を使用すると、製品オーナーであっても RBAC の INSUFFICIENT_PERMISSIONS が発生します。

書き戻し後、更新したチケットの display ID と、スキップしたチケットの display ID を報告します。チケットの書き戻しを1件スキップまたは失敗したからといって、アップロードのワークフローを中止しないでください。失敗について記載し、レポートのアップロードを続行します。

---

レビュー内容の要件

アップロード確認を求める前に、次のセクションを含めてください。

• 基本情報：日付、作成者、エージェント別のセッション合計数、合計コスト、変更ファイル数、対象リポジトリ。
• 全体の概要：レポートに summary フィールドがある場合はそれを使用します。ない場合は、セッション、リポジトリ、人間による入力に基づいて2～4文で記述します。
• セッションレビュー：重要なセッションごとに、タイトル／名前、エージェント、時間範囲、コスト、リポジトリ／変更ファイル、実施内容を説明する1～2文を記載します。タイトル／時間／コストだけを列挙しないでください。
• 人間による入力の要点：注目すべき human_inputs をカテゴリ（decision、direction、correction、planning）別に要約し、必要に応じて代表的なプロンプトを含めます。
• データ品質に関する注記：コストの欠落／推定値、API の警告、コストのないセッション、空のモデルについて記載します。

数値の表示には簡潔な表を使用してもかまいませんが、物語形式の概要とセッションレビューのテキストは必ず含めてください。

製品／リポジトリ／チケットの割り当て

レポートごとに、セッションにすでに product_id があるかどうかにかかわらず、収集または確認の後、レビュー／アップロードの前にこのフローを実施します。Web の割り当てページでは、チケットの display ID の確認や編集もできます。 ユーザーに割り当てモードを選ばせないでください。常にローカルの Web 割り当てフローを使用してください。レポート内のすべてのセッションにすでに製品が設定されている場合（既存のマッピングから自動割り当てされた場合など）、cawplan session assign --web は通知を表示して、ページを開かずにすぐ終了します。そのまま確認に進んでください。ページを開くようユーザーから明示的に依頼された場合（チケットの編集など）に限り、--force を指定してください。

レポートが 1 つの場合は、次を実行します。

cawplan session assign --file <absolute-ai-daily-file> --web

複数のレポートの場合は、次を優先してください。

cawplan session assign --web --files <absolute-ai-daily-file-1> --files <absolute-ai-daily-file-2>

処理するすべてのレポートファイルを指定して、エージェントのシェルから 1 つのコマンドを実行してください。ローカルの割り当てページが自動的にブラウザーで開き、すべてのレポートがまとめて処理されます。このコマンドは、必ずバックグラウンド／ノンブロッキングのシェルタスクとして開始してください（例：Bash の run_in_background: true）。フォアグラウンドで通常の呼び出しをしてはいけません。このコマンドはブラウザーでの入力を最大 10 分間待機します。待機中のフォアグラウンド呼び出しは、ユーザーが操作を終える前にシェルのジョブ制御によって一時停止され、ポートを保持したままプロセスが停止するおそれがあります。ユーザーがブラウザーで操作を終えるまで、実行中の cawplan session assign --web コマンドは必ず 1 つだけにしてください。ユーザーが 割り当てを保存 をクリックするか、閉じる をクリックするか、ターミナルで Ctrl+C を押すか、ローカルの割り当てサーバーが 10 分のタイムアウトに達すると、コマンドは終了します。

終了を待つには、起動時に PID を記録し、その PID をポーリングしてください（コマンドラインは絶対にポーリングしないでください）。kill -0 を使う bash／zsh／Git Bash の例：cawplan session assign --web --files ... > "$dir/assign.log" 2>&1 & echo $! > "$dir/assign.pid" を実行し、その後に pid=$(cat "$dir/assign.pid"); for i in $(seq 1 58); do kill -0 "$pid" 2>/dev/null || { echo exited; break; }; sleep 10; done; tail -5 "$dir/assign.log" を実行します。pgrep -f "session assign" や ps | grep "session assign" を使ったポーリングは絶対にしないでください。ポーリング中のシェル自身のコマンドラインにその文字列が含まれるため、自分自身に一致し、コマンドの終了を検出できず、ユーザーが保存した後もループがタイムアウトまで続いてしまいます。PowerShell などの別のシェルでは、同じループ構造で同等の PID チェック（例：Get-Process -Id $pid -ErrorAction SilentlyContinue）を使用してください。PID がまだ実行中の状態でポーリングループが終了した場合は、完了したと判断せず、ポーリングを続けてください。

バックグラウンドの割り当てコマンドを開始した後、実行中のままエージェントのターンを終了したり、最終応答を返したりしないでください。短い間隔でコマンドをポーリングし、同じエージェントのターンを継続してください。ユーザーがページを操作する必要がある場合は、中間更新として URL を送信し、ポーリングを続けてください。ユーザーからの入力をワークフローの完了として扱ってはいけません。コマンドが終了したら、終了コードを確認し、同じターン内で確認、チケットの進捗状況の書き戻し、アップロード、当月分のバックフィル確認へ進んでください。これらの手順が完了するか、割り当てに関する実際のエラーを報告するまで、ターンを終了しないでください。バックグラウンドのシェルプロセスがあっても、後続のエージェントターンが自動的に再開されるわけではありません。そのため、URL だけを返してターンを終了するのは無効です。

ページの保存、終了、中断、またはタイムアウトによって割り当てコマンドが終了した場合は、ディスク上のレポートファイルを使用して、確認、チケットの進捗状況の書き戻し、アップロードを自動的に続行してください。割り当てページが閉じた後に、ユーザーへ 2 回目の確認を求めないでください。編集されずにページが閉じられた場合は、コレクターに既存の製品／リポジトリ／チケットのマッピングがあればそれを維持して続行してください。レポートファイルが見つからない場合、または割り当てコマンドで実際のエラーが報告された場合に限り、処理を停止してください。割り当てコマンドが終了する前にエージェントのターンが中断された場合、次のターンではまず既存のプロセスとレポートファイルを確認し、その後、割り当てコマンド終了後の状態から再開してください。自動アップロードがすでに行われたと主張してはいけません。 以前の割り当てコマンドが同じレポートに対して実行中の場合、待機時間が長くても、cawplan session assign --web を再実行しないでください。長時間の待機は、ページがユーザーの操作を待っていることを意味し、コマンドが失敗したことを意味するわけではありません。進捗を伝える必要がある場合は、すでに開いている割り当てページで保存または閉じる操作を完了してもらい、その後、既存のコマンドが終了するかタイムアウトするまで待つようユーザーに伝えてください。

割り当てページが読み込めない場合や、以前の実行が停止しているように見える場合は、コマンドが失敗したと判断する前に、まず停止中のプロセスがないか確認してください（記録された PID を使って ps -o pid,stat,cmd -p "$pid" を実行します。STAT が T の場合、そのプロセスは一時停止しており、サービスを提供していません）。プロセスが実際に停止している場合に限って、終了して再起動してください。単に待機中の場合は終了しないでください。

このページには session / human inputs / product / repo / tickets が表示され、product は必須です。product のみの割り当てにも対応しており、ticket の表示 ID を編集でき、新しい GitHub リポジトリ URL を https://github.com/owner/repo 形式で関連付けられます。

product ピッカー（および cawplan session products）では、controls 配列に coding-insights が含まれていない product はすでに除外されています。そのような product は session データを保持できないため、割り当て先として表示されません。別の product に割り当てたり、JSON の product_id を直接編集したりして回避しないでください。ユーザーが指定した product が一覧にない場合は、代わりの product を推測せず、その product では coding insights が有効になっていないことを伝えてください。

ルール

• --date が指定されていない場合、今日の日付がデフォルトになります。
• session データを捏造しないでください。エージェントがローカルで生成した内容のみを報告してください。
• 収集中に product/repo の割り当てを求められた場合は、ユーザーが明示的に選択した内容、または既存のマッピングのみを使用してください。
• Web 割り当てフローでは、すべての session で product の選択が必須です。repository の選択は任意です。
• ユーザーが product と GitHub リポジトリ URL を明示的に選択または確認しない限り、新しい product-repo マッピングを作成しないでください。
• --file を使用する場合、ファイルには author（git username）と date（YYYY-MM-DD）のフィールドが含まれている必要があります。
• 1 日分のアップロードが成功したら、手順 7～11 に従って、そのレポートの現在の月における不足日を --dry-run で照会してください。その後、不足日ごとに個別に収集 → 割り当て → アップロードを行ってください。--dry-run なしで cawplan session backfill を使用しないでください。
• 1 日分のワークフロー中に、前月分や月をまたぐ期間を自動的にバックフィルしないでください。月単位の不足分ワークフローを使用できるのは、ユーザーが月を指定した場合、またはその月のレポートの不足分をアップロード／補完するよう明示的に依頼した場合に限ります。
• human_inputs の未加工フィールド（例：start_time、end_time、assistant_message、files_changed、lines_added、lines_deleted）を保持してください。
• human_inputs の未加工の内容を要約した内容に置き換えないでください。このワークフローのどの段階でも、各 human_inputs[].assistant_message と human_inputs[].category/topic/topic_confidence/topic_reason/topic_source は収集時の内容をそのまま保持し、分類し直したり、書き換えたり、要約したりしないでください。

確認

アップロード後、次の内容を報告してください。

• サーバーが受け付けたレポートの日付。
• 確認済みファイルのサマリーに記載された、エージェントごとの session 数。
• Code フィールド（SUCCESS / FAILURE）。
• FAILURE の場合は、エラーメッセージを表示してください。

参照

• references/CAWPLAN_OPEN_API.md