contract-testing-flywheel

contract-testing-flywheel

为团队的契约测试推广生成一次性入门待办事项列表，参照 7 阶段契约测试飞轮（根据插件设计，将维护阶段替换为经验总结，并可选加入管理仪表板）。可与 Jira、GitHub Issues/Projects 或 Azure DevOps 配合使用；如果这些工具均未连接，则会将完整待办事项列表导出为 Markdown，供手动导入。

步骤 1 — 选择 Scrum 工具

询问：“这份待办事项列表应放入哪个工具？Jira · GitHub Issues/Projects · Azure DevOps · 其他/手动导出”

只有当 $ARGUMENTS 明确指定了三个工具之一（例如 --tool=github）时，才跳过此问题；否则请询问。

然后检查 lib/scrum-tool-adapters.md 中该工具的可用性检查：

• 可用 → 记录适配器对应行的信息（层级术语、幂等性查询、创建/关联/评论机制），然后以实时创建模式继续步骤 2。
• 不可用（已选择工具，但其 MCP/CLI 未连接），或选择了“其他/手动导出” → 以手动导出模式继续步骤 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 已连接，优先使用其对应工具；否则使用 CLI。

步骤 2 — 收集输入

按顺序解析每项输入。如果存在输入 1，则使用 $ARGUMENTS；只询问尚未确定的信息。

#	输入	解析方式
1	项目 / 工作区标识符	优先使用 $ARGUMENTS；否则根据步骤 1 选择的工具询问：Jira 项目键（例如 PACT）· GitHub owner/repo · Azure DevOps org/project。如果处于手动导出模式且未选择工具，则跳过。
2	团队 / 单位名称	询问。用于为根条目命名并为工单添加标签。
3	消费方系统名称	询问。单个值。
4	提供方系统名称	询问。单个值。
5	主要语言 / 技术栈	单选询问：Node/TS · JVM · Python · Go · .NET · Ruby · Rust · 其他
6	CT 模式	单选询问：CDCT · BDCT · 两者
7	Broker URL（可选）	询问，可留空。若留空，工单措辞使用“你的 Pact Broker 或 PactFlow 租户”。
8	CI 工具	单选询问：GitHub Actions · GitLab CI · Buildkite · Jenkins · CircleCI · 其他
9	是否包含可选的第 8 阶段（管理仪表板）？	是/否。
10	（仅限 Azure DevOps） 流程模板	单选询问：Agile（默认）· Scrum · Basic — 根据 lib/scrum-tool-adapters.md 确定 {{delivery_term}}。其他所有工具均完全跳过此项。

不要猜测。询问很容易；待办事项列表归错位置则不然。

步骤 3 — 幂等性检查

在手动导出模式下，完全跳过此步骤。

否则，使用 lib/scrum-tool-adapters.md 中所选工具的幂等性检查查询，并代入步骤 2 的项目/团队值。如果已存在匹配的根条目，则停止并告知用户：

已存在一个属于 <team> 的根{{root_term}}：<id>（）。如果你打算创建第二份待办事项列表（例如，为同一团队下不同的消费方/提供方配对创建），请使用 --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，则将 lib/drift-helpful-links.md 中的 Drift 链接集附加到这四个模板的“Helpful links”部分。

如果用户在步骤 2.9 中回答“no”，则完全跳过 08-management-dashboard.md。

工作项类型映射

每个模板都映射到一种工作项类型。从 lib/scrum-tool-adapters.md 确定 {{root_term}} / {{delivery_term}}；所有工具中的“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）会将任务列表语法错误处理为带转义符的字面括号——而不是针对特定工具的特殊处理。本插件中的模板已遵循此规则。“Acceptance criteria”标题已表明这些是需要验证的条件。

步骤 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. 如果任何单项创建失败，继续处理其余项目。将失败项收集到列表中，以便在步骤 7 中报告。

步骤 6.5 — 将渲染后的 CLAUDE.md 附加到 Implementation 工单

在手动导出模式下完全跳过（步骤 5 的导出已在第 4 / 4b 阶段内联了 CLAUDE.md 片段）。

对于步骤 6 中创建的每个 Implementation 工单，通过所选适配器的评论机制发布一条评论：

• Consumer 工单（第 4 阶段） — 渲染后的 examples/CLAUDE.md.cdct-consumer.md，并替换步骤 4 中的占位符。将正文包裹在 Markdown 围栏代码块中，方便受派人直接复制到新的 consumer 仓库。
• Provider 工单（第 4b 阶段） — 如果 {{ct_mode}} 为 BDCT 或 Both，则使用渲染后的 examples/CLAUDE.md.bdct-drift-provider.md；否则使用 examples/CLAUDE.md.cdct-provider.md。采用相同的包裹方式。

每条评论都应以简短标题开头，例如 ## 新 <repo> 仓库的 CLAUDE.md 模板，并附上一行说明，告知受派人将围栏代码块复制到新仓库根目录下的 CLAUDE.md。附上插件仓库中源模板的链接，以便团队查看规范版本。

此操作尽力而为：如果其中一个工单的评论创建失败，继续处理并在步骤 7 中报告失败（不要回滚 Implementation 工单本身）。

步骤 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 中有任何创建失败，请清楚列出失败项及错误消息，但不要回滚已成功创建的项目 — 三种受支持工具的工单创建都不是事务性的，部分完成的待办列表仍然有用。

在手动导出模式下，步骤 5 的输出本身就是交付内容 — 步骤 7 只需打印相同的“后续步骤”区块（不含项目表，因为此时还没有任何项目的 ID 或 URL）。

给技能维护者的说明

• 内容由模板承载。 此 SKILL.md 负责编排；实际工单文案位于 templates/ 和 lib/ 中。请在这些位置更新。
• lib/scrum-tool-adapters.md 是工具抽象边界。 添加第四种一等工具（例如 Linear）意味着在其中添加一行，以及相应的可用性 / 幂等性 / 创建 / 关联 / 评论机制 — SKILL.md 本身不应需要更改。
• CDCT/BDCT 区块标记是约定。 如果重命名 `` 等标记，请相应更新步骤 4。
• 步骤 6 中出错后继续执行是有意设计的。 不稳定的创建 / 关联调用不应导致整个任务包失败。
• 不分配冲刺，不估算工作量。 待办列表旨在由团队根据自己的规划节奏进行分类。