go

⛔ ITP 工作流 — 停下并阅读

不要凭假设行事。请先阅读此文件。

这是一个结构化的工作流命令。请按顺序执行各阶段。

你现在的第一个也是唯一的操作：执行下方的 TodoWrite。

自我演进的技能：此技能会在使用中不断改进。如果指令有误、参数发生偏移，或需要采取变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

⛔ 必须执行的第一步：与计划关联的待办整合

你的第一步必须是合并后的 TodoWrite，并保留现有待办。

不要：

• ❌ 覆盖计划文件或之前会话中的现有待办
• ❌ 忽略 ~/.claude/plans/*.md 处的计划文件
• ❌ 未检查现有待办就自行创建待办
• ❌ 未完成步骤 0 就开始编码
• ❌ 在 TodoWrite 之前创建分支

请遵循完整的合并策略（步骤 0.1-0.5）和 TodoWrite 模板：待办合并策略

TodoWrite 完成后，继续执行下方的预检部分。

---

快速参考

调用的技能

技能	阶段	用途
implement-plan-preflight	预检	创建 ADR + 设计规范
impl-standards	阶段 1	错误处理、常量
adr-code-traceability	阶段 1	代码到 ADR 的引用
code-hardcode-audit	阶段 1	发布前验证
semantic-release	阶段 3	版本标记 + 发布
pypi-doppler	阶段 3	发布到 PyPI（如适用）

文件位置

产物	路径	备注
ADR	/docs/adr/$ADR_ID.md	永久保存
设计规范	/docs/design/$ADR_ID/spec.md	永久保存，预检后作为 SSoT
全局计划	~/.claude/plans/<adj-verb-noun>.md	临时文件——新计划会替换它

规范 YAML 前置内容

---
adr: YYYY-MM-DD-slug # Links to ADR (programmatic)
source: ~/.claude/plans/<adj-verb-noun>.md # Global plan (EPHEMERAL)
implementation-status: in_progress # in_progress | blocked | completed | abandoned
phase: preflight # preflight | phase-1 | phase-2 | phase-3
last-updated: YYYY-MM-DD
---

注意：source 字段会保留全局计划文件名以便追溯，但创建新计划后，该文件可能不再存在。

ADR ID 格式

ADR_ID="$(date +%Y-%m-%d)-<slug>"

示例：2025-12-01-clickhouse-aws-ohlcv-ingestion

文件夹结构

/docs/
  adr/
    YYYY-MM-DD-slug.md          # ADR file
  design/
    YYYY-MM-DD-slug/            # Design folder (1:1 with ADR)
      spec.md                   # Active implementation spec (SSoT)

命名规则：ADR 和设计文件夹必须使用完全相同的 YYYY-MM-DD-slug。

---

关键：必须执行工作流

此工作流不可协商。不得跳过任何阶段。

无论任务复杂度如何，你都必须按顺序执行所有阶段：

1. 步骤 0：初始化 TodoWrite（第一步——无例外）
2. 预检：创建 ADR + 设计规范
3. 阶段 1：根据 spec.md 实施
4. 阶段 2：格式化并推送
5. 阶段 3：发布（如果当前位于 main/master 分支）

禁止的行为：

• ❌ 认为“这很简单，可以跳过工作流”
• ❌ 未执行 TodoWrite 就直接开始实施
• ❌ 以“修正文档”或“小改动”为由跳过 ADR/设计规范
• ❌ 擅自判断并绕过各阶段

如果任务看起来过于简单，不适合此工作流：停下来询问用户是否要在不使用 /itp:go 的情况下继续。不得默默跳过阶段。

参数

解析 $ARGUMENTS：

参数	简写	描述	默认值
slug	-	ADR ID 的功能名称（例如，clickhouse-aws-ohlcv-ingestion）	根据 Global Plan 上下文推导
--branch	-b	从 main/master 创建 {type}/{adr-id} 分支	在当前分支上工作
--continue	-c	继续进行中的工作；可选择提供决策	上次的“建议的后续步骤”
--release	-r	在阶段 3 中启用 semantic-release（在 main 上发布时必需）	跳过阶段 3 的 release
--publish	-p	在阶段 3 中启用 PyPI 发布（在 main 上发布时必需）	跳过阶段 3 的发布

详细用法示例、分支类型和 slug 推导规则：参数参考

---

工作流预览

开始前检测分支并显示预期工作流。 有关分支检测脚本和条件表，请参阅工作流预览。

---

步骤 0：初始化待办列表（已完成）

如果你遵循了顶部的 STOP 指令，此步骤已完成。

TodoWrite 模板位于待办合并策略。如果你还没有执行，请停止并返回顶部。

开始处理每项待办前，将其标记为 in_progress；完成后标记为 completed。

预检门槛（必须完成）

只有所有预检待办都标记为 completed 后，才能进入阶段 1。

开始“阶段 1：执行实现任务”前：

1. 确认所有 Preflight: 待办都显示为 completed
2. 确认 ADR 文件存在于 /docs/adr/$ADR_ID.md
3. 确认设计规范存在于 /docs/design/$ADR_ID/spec.md

如果有任何预检项目尚未完成，请停止并先完成该项目。不要跳过。

---

预检：工件设置

必须调用 Skill 工具：implement-plan-preflight——继续之前立即激活。

此 Skill 提供有关创建 ADR 和设计规范的详细说明（MADR 4.0 前置元数据、视角分类法、验证）。

预检步骤（通过 Skill 执行）

1. P.0：首先创建功能分支（如果使用了 -b 标志）——必须在任何文件操作之前完成
2. P.1：必须调用 Skill 工具：implement-plan-preflight——立即激活以获取 ADR/规范说明
3. P.2：创建 ADR 文件——路径见快速参考
4. P.3：创建设计规范——路径见快速参考
5. P.4：验证检查点

为何 P.0 必须最先执行：在 git checkout -b 之前创建的文件会留在 main/master 上。必须先创建分支，再创建 ADR/规范。

预检检查点（必须完成）

停止。进入阶段 1 前，确认工件已存在。 完整清单和验证脚本：预检检查点

---

阶段 1：实现

1.1 恢复协议

适用于全新开始和继续工作的入口。 完整协议（继续状态检测、分支验证、同步检查）：阶段 1 协议

1.2 实现规范

执行 spec.md 中的每项任务：

1. 在待办列表中将当前任务标记为 in_progress
2. 实现更改
3. 验证其正常运行
4. 更新 spec.md 以反映完成情况
5. 将任务标记为 completed
6. 继续下一项任务

1.3 工程标准

技能执行顺序（按顺序调用）：

1. impl-standards —— 首先应用错误处理和常量模式
2. adr-code-traceability —— 其次在代码中添加 ADR 引用
3. code-hardcode-audit —— 最后进行审核（第二阶段之前）

必须调用 Skill 工具：impl-standards —— 现在立即启用，以获取详细标准。

必须调用 Skill 工具：adr-code-traceability —— 现在立即启用，以在代码中添加 ADR 引用。

必须调用 Skill 工具：code-hardcode-audit —— 发布前现在立即启用。

1.4 决策记录

当实现需要用户决策时，请遵循决策记录协议：决策记录

1.5 状态同步协议

规范中的 implementation-status 驱动 ADR status 更新。完整的同步表和脚本：状态同步协议

第一阶段成功标准

• 按照 spec.md 完成实现
• 所有工件均已同步（ADR <-> 规范 <-> 待办事项 <-> 代码）
• 新文件的文件头中包含 ADR: {adr-id}
• 不明显的改动包含内联 ADR: 注释

---

第二阶段：格式化并推送

执行 Prettier 格式化、git push 和打开浏览器。完整脚本：第二阶段脚本

第二阶段成功标准

• Markdown 已使用 Prettier 格式化
• 已推送到 GitHub
• 可在浏览器中查看文件

---

第三阶段：发布与分发（在主分支上需要 -r 或 -p 标志）

第三阶段需要显式标志，不会自动运行。

有关入口门控逻辑和特定分支的消息，请参阅第三阶段门控逻辑。

3.1 发布前验证

发布前：

• 设计规范中的所有成功标准项均已勾选
• 设计规范中的状态值已更新（例如 Accepted、Implemented）
• ADR 和 spec.md 与最终实现保持同步
• 版本字段采用 semantic-release 模式（不使用动态版本控制）

3.2 语义化发布（如果使用 -r 标志）

条件：仅当提供了 -r 或 --release 标志时才执行。

必须调用 Skill 工具：semantic-release —— 现在立即启用，以进行版本标记和发布。

• 遵循本地发布工作流（已移除）
• Conventional commits -> 标记 -> 发布 -> 更新变更日志 -> 推送

3.3 PyPI 发布（如果使用 -p 标志）

条件：仅当提供了 -p 或 --publish 标志时才执行。

仅当软件包已预先发布到 PyPI 时：

• 必须调用 Skill 工具：pypi-doppler —— 现在立即启用以进行发布

3.4 Earthly 流水线

将 Earthly 用作规范流水线：非阻塞，以可观测性为先；确保 GitHub Release 存在；记录统计数据和错误；发送 Pushover 警报；接入 GitHub Actions。

第三阶段成功标准

• ADR 状态已更新为 accepted 或 implemented
• 已通过 semantic-release 完成发布
• 如果位于功能分支：已创建 PR，跳过第三阶段

---

故障排除

问题	原因	解决方案
未找到 TodoWrite	跳过了强制的第一步	从文件顶部开始，执行 TodoWrite
未创建 ADR 文件	预检未完成	运行 Skill(itp:implement-plan-preflight)
分支不匹配	在错误的分支上工作	使用 git checkout 切换到正确的分支
跳过第三阶段	不在 main/master 上	先合并到 main，然后运行 /itp:go -r
semantic-release 失败	没有 GITHUB_TOKEN	使用 echo $GITHUB_TOKEN 检查令牌
规范验证失败	缺少 frontmatter 字段	在快速参考中检查必填字段

执行后复盘

此技能完成后，在结束任务前进行复盘：

0. 确认位置。 — 编辑前，通过 Glob 查找此技能的名称，确定此 SKILL.md 的规范路径。所有修正仅针对此文件及其同级目录 references/——绝不修改其他文档。
1. 哪里出了问题？ — 修正导致问题的指令。如果问题可能再次发生，将其添加为反模式。
2. 哪些做得比预期更好？ — 将其提升为推荐做法，并记录原因。
3. 哪些内容出现偏差？ — 任何不再符合实际情况的脚本、引用或外部依赖，都要立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修正内容和证据。

不要推迟。下一次调用会继承你留下的一切。