contract-testing-flywheel

contract-testing-flywheel

チームのコントラクトテスト導入に向けた一括オンボーディングバックログを生成します。設計上の変更により、7 段階の Contract Testing Flywheel のうち、メンテナンスフェーズを教訓の共有と任意の管理ダッシュボードに置き換えています。Jira、GitHub Issues/Projects、Azure DevOps に対応しています。いずれも接続されていない場合は、バックログ全体を手動インポート用の Markdown として出力します。

Step 1 — スクラムツールを選択する

次のように尋ねます。「このバックログをどのツールに登録しますか？ Jira · GitHub Issues/Projects · Azure DevOps · その他／手動エクスポート」

$ARGUMENTS に 3 つのツールのいずれかが明確に指定されている場合（例：--tool=github）に限り、この質問を省略します。それ以外の場合は質問してください。

次に、lib/scrum-tool-adapters.md でそのツールの利用可能性チェックを行います。

• 利用可能 → アダプターの行（階層の用語、冪等性クエリ、作成／リンク／コメントの方法）を確認してから、ライブ作成モードで Step 2 に進みます。
• 利用不可（ツールは選択されているが、その MCP／CLI が接続されていない）、または**「その他／手動エクスポート」**が選択された → 手動エクスポートモードで Step 2 に進みます。これはエラーではありません。特定のツールが選択されているものの接続されていない場合は、次回ライブ作成を可能にするための接続方法（Jira では Atlassian MCP、GitHub では gh auth login または GitHub MCP、Azure DevOps では az login + az extension add --name azure-devops または Azure DevOps MCP）を一度だけ伝えてから、そのままエクスポートを進めてください。処理を中断してはいけません。

選択したツールに MCP サーバーと CLI の両方が使える場合、接続されている MCP に相当するツールがあれば、MCP を優先してください。それ以外の場合は CLI を使用します。

Step 2 — 入力を集める

各入力を順番に解決します。入力 1 に $ARGUMENTS があれば使用し、まだ判明していない項目だけを尋ねてください。

#	入力	解決方法
1	プロジェクト／ワークスペース識別子	まず $ARGUMENTS を確認し、なければ Step 1 で選んだツールに応じて尋ねます。Jira のプロジェクトキー（例：PACT）· GitHub の owner/repo · Azure DevOps の org/project。ツールを選択せずに手動エクスポートモードにする場合は省略します。
2	チーム／ユニット名	尋ねます。ルート項目のタイトルとチケットのラベルに使用します。
3	コンシューマーシステム名	尋ねます。単一の値を指定します。
4	プロバイダーシステム名	尋ねます。単一の値を指定します。
5	主な言語／スタック	1 つだけ選ぶ形式で尋ねます：Node/TS · JVM · Python · Go · .NET · Ruby · Rust · その他
6	CT モード	1 つだけ選ぶ形式で尋ねます：CDCT · BDCT · 両方
7	ブローカー URL（任意）	尋ねます。空欄も許可します。空欄の場合、チケットの文面では「お使いの Pact Broker または PactFlow テナント」を使用します。
8	CI ツール	1 つだけ選ぶ形式で尋ねます：GitHub Actions · GitLab CI · Buildkite · Jenkins · CircleCI · その他
9	任意の Phase 8（管理ダッシュボード）を含めますか？	はい／いいえ。
10	（Azure DevOps のみ） プロセステンプレート	1 つだけ選ぶ形式で尋ねます：Agile（デフォルト）· Scrum · Basic — lib/scrum-tool-adapters.md に従って {{delivery_term}} を決定します。その他のツールでは省略します。

推測してはいけません。確認する手間はわずかですが、誤った場所にバックログが登録されると困ります。

Step 3 — 冪等性チェック

手動エクスポートモードでは、このステップを完全に省略します。

それ以外の場合は、lib/scrum-tool-adapters.md にある、選択したツールの冪等性チェック用クエリを実行し、Step 2 のプロジェクト／チームの値を代入します。一致するルート項目がすでにある場合は処理を停止し、ユーザーに次のように伝えます。

<team> のルート {{root_term}} はすでに存在します：<id>（）。同じチームの別のコンシューマー／プロバイダーの組み合わせなどで 2 つ目のバックログを作成する場合は、--force を指定して再実行してください。

$ARGUMENTS に --force が指定されている場合、または一致する項目が見つからなかった場合は続行します。

ステップ 4 — チケット一式を作成する

templates/ からテンプレートを読み込み、プレースホルダーを置換します。各テンプレートは # {{title: <text>}} の行で始まります。<text>（それ自体にさらにプレースホルダーを含みます）は項目のタイトル／要約フィールドです。項目を作成する際は、{{title: ...}} のラッパーを取り除き、置換後の内容をタイトルとして使い、ラッパー行は項目の本文から削除します。

プレースホルダーの一覧：

トークン	参照元
{{team}}	ステップ 2.2
{{consumer}}	ステップ 2.3
{{provider}}	ステップ 2.4
{{stack}}	ステップ 2.5
{{pact_library}} + {{pact_library_url}}	lib/stack-pact-libraries.md で確認
{{ct_mode}}	ステップ 2.6 — CDCT、BDCT、Both のいずれか
{{broker_url_or_phrase}}	ステップ 2.7 — URL、または "your Pact Broker or PactFlow tenant"
{{ci_tool}} + {{ci_docs_url}}	ステップ 2.8 + lib/ci-snippet-pointers.md で確認
{{openapi_path}}	デフォルトは openapi.yaml（プレースホルダー。プロバイダー側リポジトリのチームが調整します）
{{root_term}}	ステップ 1 で選択したツール。lib/scrum-tool-adapters.md で確認（手動エクスポートモードでは中立的なデフォルト値として "Epic"）
{{delivery_term}}	同じ参照先で確認（中立的なデフォルト値は "Story"。Azure DevOps では、ステップ 2.10 のプロセステンプレートから決定します）

CDCT／BDCT ブロックの選択。 テンプレート 03b-design-demo.md、04-implementation-consumer.md、04b-implementation-provider.md、05-testing.md には、明示的な ... および ... セクションがあります。次のように残します。

• CDCT のみ → CDCT ブロックを残し、BDCT ブロックを削除します。
• BDCT のみ → BDCT ブロックを残し、CDCT ブロックを削除します。
• Both → 両方を残し、CDCT、次に BDCT の順に配置します。BDCT ブロックの前に区切り見出し ## BDCT track を入れます。

BDCT または Both を選択した場合は、これら 4 つのテンプレートの「参考リンク」セクションに、lib/drift-helpful-links.md の Drift リンク一式を追加します。

ステップ 2.9 でユーザーが「no」と回答した場合は、08-management-dashboard.md を完全にスキップします。

課題タイプのマッピング

各テンプレートは作業項目のタイプに対応します。{{root_term}}／{{delivery_term}} は lib/scrum-tool-adapters.md から決定します。"Task" はすべてのツールで固定です。

テンプレート	フェーズ	項目タイプ
00-root-epic.md	ルート	{{root_term}}
01-planning.md	1	Task
02-requirements.md	2	Task
03a-design-knowledge.md	3a	Task
03b-design-demo.md	3b	Task
04-implementation-consumer.md	4	{{delivery_term}}
04b-implementation-provider.md	4b	{{delivery_term}}
05-testing.md	5	{{delivery_term}}
06-deployment.md	6	{{delivery_term}}
07-lessons-learned.md	7	Task
08-management-dashboard.md	8	{{delivery_term}}

理由：フェーズ 1、2、3a、3b、7 は範囲が限定された「実行して完了にする」作業（計画セッション、指標のベースライン設定、学習、デモ、ドキュメントの記録）であるため、Task が適しています。フェーズ 4、4b、5、6、8 はユーザー価値を提供する作業であるため、そのツールのデリバリー項目タイプが適しています。

Markdown に関する注意点

各チケット本文の受け入れ条件には、GitHub 形式のタスクリスト構文（- [ ]）ではなく、通常の箇条書き（-）を使います。これはツールごとに特別扱いするものではなく、普遍的に安全なデフォルトです。Jira など一部のツールでは、タスクリスト構文がエスケープされた角括弧としてそのまま表示されてしまいます。「受け入れ条件」という見出しによって、これらが検証する条件であることはすでに示されています。このプラグインのテンプレートはすでにこのルールに従っています。

ステップ 5 — ドライランのプレビュー

ターミナルに出力します。ライブ作成モードでは：

About to create in <tool> · <project/workspace>:

  Root  ─ {{root_term}}   ─ "Contract Testing Onboarding: <team> (<consumer> ↔ <provider>)"
  ├──── Task   ─ "1. Planning"
  ├──── Task   ─ "2. Requirements Analysis"
  ├──── Task   ─ "3a. Design — Knowledge ramp-up"
  ├──── Task   ─ "3b. Design — Local CT demo"
  ├──── {{delivery_term}}  ─ "4. Consumer-side contract tests"
  ├──── {{delivery_term}}  ─ "4b. Provider-side verification"
  ├──── {{delivery_term}}  ─ "5. Testing — first CI trigger"
  ├──── {{delivery_term}}  ─ "6. Deployment — can-i-deploy + record-deployment"
  ├──── Task   ─ "7. Internal docs — lessons learned + best practices"
  └──── {{delivery_term}}  ─ "8. Management dashboard"        (only if opted in)

Mode: <ct_mode>      Stack: <stack>      CI: <ci_tool>      Broker: <broker_url_or_phrase>

Each item will be assigned to you, labelled 'contract-testing-flywheel',
'contract-testing-onboarding', and '<cdct|bdct|both>'. Children will be
linked to the root {{root_term}}. Status: Backlog. No sprint assignment.

Proceed? (y/N)

手動エクスポートモードでは、代わりに次を出力します。

No live tool connected (or manual export chosen) — rendering the full
backlog below as markdown. Copy the sections you need into <tool of choice>.

Mode: <ct_mode>      Stack: <stack>      CI: <ci_tool>      Broker: <broker_url_or_phrase>

...その直後に、バックログ全体をレンダリングして出力します（ルート項目の本文、その後にフェーズ順で各子項目を、それぞれ独自の ## <phase> — <title> 見出しの下に配置します）。追加の確認プロンプトは不要です。何も作成されないため、確認するものはありません。

ライブ作成モードでユーザーが y と回答しなかった場合は、問題なく中止します。何も作成されなかったことを出力します。

ステップ 6 — 実行

手動エクスポートモードでは完全にスキップします（ステップ 5 ですでに完全な出力が生成されています）。

1. レンダリング済みの 00-root-epic.md の本文でルート項目を作成します。
2. 選択したアダプターの作成呼び出しを使って、各子項目（1、2、3a、3b、4、4b、5、6、7、必要に応じて8）を作成します。これらは並列で実行できます。
3. 各子項目を、選択したアダプターのリンク機能を使ってルートにリンクします。
4. 作成が1件でも失敗した場合は、残りの作成を続けます。失敗をリストにまとめ、ステップ 7 で報告します。

ステップ 6.5 — レンダリング済みの CLAUDE.md を実装チケットに添付する

手動エクスポートモードでは完全にスキップします（ステップ 5 のエクスポートでは、CLAUDE.md のスニペットがすでにフェーズ 4／4b の下にインラインで含まれています）。

ステップ 6 で作成した各実装チケットについて、選択したアダプターのコメント機能を使ってコメントを1件投稿します。

• コンシューマーチケット（フェーズ 4） — プレースホルダーをステップ 4 の値で置換した、レンダリング済みの examples/CLAUDE.md.cdct-consumer.md。担当者が新しいコンシューマーリポジトリにそのままコピーできるよう、本文をフェンス付きの Markdown ブロックで囲みます。
• プロバイダーチケット（フェーズ 4b） — {{ct_mode}} が BDCT または Both の場合は、レンダリング済みの examples/CLAUDE.md.bdct-drift-provider.md。それ以外の場合は examples/CLAUDE.md.cdct-provider.md を使います。同様にフェンスで囲みます。

各コメントの先頭には、## 新しい<repo>リポジトリ用のCLAUDE.mdテンプレート のような短い見出しと、担当者にフェンスで囲まれたブロックを新しいリポジトリのルートにある CLAUDE.md にコピーするよう伝える1行の指示を記載します。チームが正式なバージョンを確認できるよう、プラグインリポジトリ内のソーステンプレートへのリンクを含めます。

これはベストエフォートです。2つのチケットのいずれかでコメントの作成に失敗した場合は、そのまま続行し、ステップ 7 で失敗を報告します（実装チケット自体はロールバックしません）。

ステップ 7 — 結果を出力する

ライブ作成モードの場合：

Created in <tool> · <project/workspace>:

  {{root_term}}   <id-1>   Contract Testing Onboarding: <team> (<consumer> ↔ <provider>)
                   <item-url-1>
  {{delivery_term}}  <id-2>   1. Planning
                   <item-url-2>
  ...

Next steps:
  - Open the root {{root_term}} and triage into your sprint plan.
  - When Phase 4 / 4b kicks off, drop the matching CLAUDE.md from this
    plugin's examples/ folder into the new consumer / provider repo:
      examples/CLAUDE.md.cdct-consumer.md
      examples/CLAUDE.md.cdct-provider.md
      examples/CLAUDE.md.bdct-drift-provider.md
  - For end-to-end help authoring tests, see /swagger-contract-testing.

ステップ 6 で作成が失敗した場合は、エラーメッセージとともに失敗を明確に列挙します。ただし、成功した項目はロールバックしません。サポート対象の3つのツールはいずれも課題の作成がトランザクション処理ではないため、一部だけでもバックログとして役立ちます。

手動エクスポートモードでは、ステップ 5 の出力がすでに成果物です。ステップ 7 では同じ「次のステップ」ブロックだけを出力します（まだ ID や URL がないため、項目の表は含めません）。

スキル保守担当者向けの注記

• 内容はテンプレートにあります。 この SKILL.md はオーケストレーションを担います。実際のチケット本文は templates/ と lib/ にあります。更新する場合はそちらを編集してください。
• lib/scrum-tool-adapters.md はツール抽象化の境界です。 4つ目の主要ツール（Linear など）を追加する場合は、そこに1行を追加し、利用可否／冪等性／作成／リンク／コメントの各メカニズムを記載します。SKILL.md 自体を変更する必要はありません。
• CDCT/BDCT ブロックマーカーが規約です。 `` などの名前を変更した場合は、それに合わせてステップ 4 も更新してください。
• ステップ 6 のエラー時に続行する動作は意図的なものです。 不安定な作成／リンク呼び出しが、バンドル全体の失敗につながるべきではありません。
• スプリントの割り当ても、見積もりもありません。 このバックログは、チームが独自の計画サイクルに合わせてトリアージすることを想定しています。