🛡️ 开发周期协议（`dev-cycle-protocol` v4）

路径：<skills_root> 是包含该技能的文件夹（该 SKILL.md 所在文件夹的父文件夹）。运行命令时，请使用实际的绝对路径。从项目的仓库运行它们（或传递 --dir）：如果会话从项目目录之上启动，例如在 /home/user 的云会话中，则可能会读取错误的文件夹。

引擎：已翻译为 Rust（IMP-005）的脚本通过启动器运行，在此写为 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" <skill> <script> [args]（sh shell：Linux、macOS、Git Bash）。在 PowerShell 中，运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" <skill> <script> [args]。首次运行会下载适用于本机的引擎并校验其校验和。

dev-cycle-protocol 像一支专家团队一样编排软件工作。它拥有阶段、门控以及每个角色何时运行；每个角色技能拥有自己的工件、规则和检查器。它既语言无关也项目无关。

语言：使用用户使用的语言与用户交流，但所有项目工件都用英语编写：代码、注释、文档、ADR、计划、手动测试、提交消息和拉取请求描述。项目可以在 .dev-cycle.json 中设置另一种文档语言（architecture_docs.language）。

🧭 启动会话（`/dev-cycle`）

用户通过一个命令 /dev-cycle 开始（附带一个产品想法或一个请求，或者单独运行）。它运行诊断（引擎上的 onboard diagnose），如果项目是最新的，则用一行说明并继续，否则按推荐顺序显示选项：进行中的计划、待定的发布候选、未修复的阻塞性错误、缺失的设置（配置、分支模型、集成分支、Spec Kit）、缺失的产品基线、当前发布的下一个项目、该请求。新仓库进入第 0 阶段。从未使用过该协议的仓库会获得一个初始设置列表，可以一次性确认或逐项确认；在用户确认之前，不会写入任何内容。当用户在没有该命令的情况下请求工作时，首先运行相同的诊断。

👥 角色

角色	技能	拥有
编排者	`dev-cycle-protocol`	阶段、门控、每个变更的路径、`.dev-cycle.json`、`/dev-cycle` 诊断、Spec Kit 设置和生成的章程
产品	`product-inception`	第 0 阶段：产品基线，`docs/product/VISION.md` 和 `TECH_SPEC.md`
规划者	`plan-memory`	包含史诗的待办事项列表（`docs/BACKLOG.md`，`/backlog` 命令）、路线图（`docs/ROADMAP.md`）、`docs/plans` 中的计划文件、里程碑、偏离检测
架构师	`software-design`	设计原则、架构风格、计划中的设计部分、结构审查
技术文档	`architecture-docs`	`TECDOC.md`、`docs/architecture`、ADR
QA	`quality-assurance`	自动化测试策略、精心策划的手动测试套件、发布候选运行
DevOps	`devops-release`	分支模型、CI、版本、发布候选、发布、可观测性
技术写作者	`user-docs`	README 和最终用户文档
审查者	`code-review`	对平台上的每个拉取请求进行审查：带有等级的行内评论，从不批准
会话记忆	`session-memory`	开发者自己的会话上下文
Gedo 反馈（临时，默认关闭）	`gedo-feedback`	Gedo 在实际工作中的错误记录，当项目使用 Gedo（`gedo.enabled`）时，为 Gedo 的待办事项列表记录
Spec 执行者（可选）	GitHub Spec Kit	第 1、2 和 4 阶段中功能的细节：`specs/NNN-slug/`（规范、计划、任务）

角色是一组规则和一个检查器，而不是一个独立的人：在其阶段开始时加载角色技能，遵循它，并在离开阶段前运行其检查器。Spec Kit 是一个工具，不是一个角色：协议决定它何时运行并检查它产生的内容（参见“Spec Kit”）。

🏛️ 原则

设计：模块化代码，职责清晰、SOLID、整洁代码、明确的错误、仅在有需要时使用模式，采用项目的架构风格（software-design）。
证据：每个变更都由自动化测试证明；手动测试仅覆盖无法自动化的内容，位于一个精心策划的套件中（quality-assurance）。
文档描述当下：技术文档和 README 就地编辑；历史记录保存在 Git 和发布说明中（architecture-docs、user-docs）。
计划是共享且完整的：已批准的计划是项目中的版本化文件（plan-memory）。
安全交付：基于项目分支模型的短生命周期分支，每个拉取请求运行 CI，发布候选，用户的发布门控（devops-release）。
安全：Git 中无秘密，向后兼容的数据迁移，每个发布都有回滚路径。
错误优先：在开始新功能、改进和调整之前，先规划并修复开放的 critical、high 和 medium 级别的错误；low 级别的错误最迟放入下一个发布；没有已知的错误保持未分类状态（具有严重性，并且对于不阻塞的错误，指定一个发布版本）。只有用户可以明确接受风险。没有发现的问题会被丢失，要么立即修复，要么被捕获到待办事项列表中。
跟进到底：代理会跟踪 CI 和发布直到结束，并修复失败的内容；用户的决策（计划批准、候选接受、发布门控）绝不会由代理做出。
无 AI 归属：任何工件的作者、合著者、审查者或来源都不应提及 AI、模型或编码代理：提交及其尾注、标签、分支、拉取和合并请求、审查及审查评论、问题、计划、文档、发布说明和代码注释。所有内容均由仓库的 Git 身份（devops-release）创作。项目所需工具的配置（代理的设置文件夹、集成名称）是技术性的，而非归属。通过 pr_sync 以外的任何工具（平台工具、连接器、网页）发布的文本，首先使用 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol _no_ai --file <text> 进行检查，并在发布后重新读取：工具附加的页脚、链接或标记（“由...生成”，代理的会话或线程链接）会被立即编辑掉。门控 8 也拒绝作者或提交者为 AI 身份的提交。

🧭 选择路径

路径	适用场景	阶段
构思	从想法出发的新产品，或尚无产品基线的现有项目（采用）	0，每个产品一次；然后为路线图的第一批项目使用完整路径
完整路径	新功能、重构、数据或 schema 变更、命令、配置、文件格式或公共 API 的变更、CI/发布变更、跨多个模块的任何变更	每个变更执行阶段 1 到 7；每个发布执行阶段 8 到 10
快速路径	小型错误修复、仅文档、仅测试或仅拼写错误的变更，这些变更适合作为一个小型拉取请求，并且不改变任何接口或数据	1, 4, 5, 6（仅受影响的部分）, 7

对于快速路径，当用户的请求明确命名了变更时（“修复 X 中的崩溃”），该请求即视为批准；否则，用一两句话描述变更并等待用户同意。如有疑问，请使用完整路径。

🔄 周期

graph TD
    P0["0. 产品构思（一次性）<br/>product-inception，门控 0（用户）"] -.-> P1
    P1["1. 发现<br/>编排者、plan-memory、software-design"] --> P2["2. 计划<br/>plan-memory + 所有角色"]
    P2 --> G3{"3. 计划批准<br/>（用户）"}
    G3 -- "问题/变更" --> P1
    G3 -- "已批准" --> P4["4. 在分支上实现<br/>software-design"]
    P4 --> P5["5. 自动化测试<br/>quality-assurance"]
    P5 --> P6["6. 文档<br/>architecture-docs、user-docs、quality-assurance"]
    P6 --> P7["7. 审查和 PR 并入工作基线，CI 变绿<br/>审查者、software-design、devops-release"]
    P7 -. "下一个变更" .-> P1
    P7 --> P8["8. 发布候选<br/>devops-release、quality-assurance"]
    P8 --> G9{"9. 验收<br/>（用户运行手动测试）"}
    G9 -- "失败/阻塞" --> P4
    G9 -- "全部通过" --> G10{"10. 发布门控（用户）<br/>将 dev 合并到 main，或提升候选版本"}
    G10 --> P11["最终发布跟踪并验证<br/>devops-release、plan-memory、session-memory"]

第 0 阶段每个产品运行一次。阶段 1 到 7 为每个变更运行。阶段 8 到 10 在用户想要发布已累积在工作基线中的内容时运行。

分支模型（devops.branching，devops-release）：下面的每个阶段都提及 工作基线、候选分支 和 发布门控；模型给出了它们（引擎上的 branching show："<skills_root>/dev-cycle-protocol/bin/dev-cycle" devops-release branching show）：

模型	工作基线（从中分支，向其中提 PR）	候选分支	发布门控（用户）
`integration`（默认）	`dev`	`dev`	将 `dev` 合并到 `main`
`trunk`	`main`	`main`	运行已接受候选版本的 promote 工作流
`release-branches`	`main`（某个发布的修复：`release/X.Y`）	`release/X.Y`	运行已接受候选版本的 promote 工作流

标记为 Spec Kit 的步骤仅适用于 speckit.enabled 为真的项目的功能计划（参见“Spec Kit”）。

0. 🌱 产品构思（每个产品一次性）

遵循 product-inception：访谈、业务文档、架构、技术规范、章程（Spec Kit）、包含史诗的产品待办事项列表、路线图，每项都需用户批准。它以门控 0 结束，即用户批准产品基线：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 0

对于已有一定进展但尚无基线并且正在进行的项目，可以采用它（采用模式）或跳过它：第 0 阶段对于新产品是必需的，对于现有产品是推荐的。

1. 💡 发现

保持咨询性：当用户提问、讨论或提出建议时，不要编辑文件或开始编写代码。

检查项目及其配置：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol inspect_project
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol project_config --validate

日志优先：对于任何报告的错误，在形成假设之前先阅读实际日志。
阅读活跃计划（引擎上的 list_plans："<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans；plan-memory check_milestone --list）以及架构风格和结构（software-design）。
阅读待办事项列表和路线图（引擎上的 plan-memory backlog summary、roadmap current："<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap current；inspect_project 显示两者）。向用户展示新工作之前需要处理的开放错误，然后是当前发布的开放项目和与请求相关的项目；由用户决定升级、重新排序、移动或删除哪些内容（参见“待办事项列表和路线图”）。
要规划待办事项列表项，请提升它们（backlog promote <ID> ...）：草案计划（错误的错误计划）是记录发现的地方。
Spec Kit：签出工作基线，然后使用项目描述运行 /speckit-specify：它将创建工作分支 feat/NNN-slug 和 specs/NNN-slug/spec.md。运行 /speckit-clarify 直到没有剩余的 [NEEDS CLARIFICATION] 标记；用户回答其问题。被提升的计划是信封；发现存在于规范中。
穷尽开放问题并与用户就方法达成一致。

2. 📋 计划

使用以下模板编写完整计划，收集每个角色的部分：

目标和决策：改变了什么以及为什么；带有替代方案的决策成为 ADR（architecture-docs）。
设计（software-design）：每个部分的位置、接口、数据流、错误策略、依赖关系、明确不进行抽象的内容。
受影响的表面和文件：architecture.surfaces 中会变化的接口；文件和模块。
测试（quality-assurance）：要添加的自动化测试（每个错误一个回归测试）、要添加、更改或删除的手动测试、验收标准。
文档（architecture-docs、user-docs）：子系统页面和 ADR、README 部分。
CI、发布和可观测性（devops-release）：工作流更改、版本影响、要添加的日志、诊断和遥测及其测试方式。
安全、迁移和回滚：秘密、数据迁移（向后兼容）、如何回滚。
执行步骤和里程碑。

Spec Kit：运行 /speckit-plan（其计划通过 dev-cycle 预设携带上述协议部分：测试、文档、CI 和发布、安全和回滚）、/speckit-tasks 和 /speckit-analyze，并修复分析报告的问题。docs/plans 中的计划文件成为信封：目标和决策、待办事项列表项、指向规范文件夹的链接（--spec-dir）以及取自 tasks.md 阶段的里程碑；细节不会被复制（搜索和偏离检测会通过它读取规范文件夹）。

检查偏离并完整保存计划：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "<proposal summary>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan --title "<title>" --file "<plan.md>" --version "<target version>" --milestones "<m1,m2,...>" [--spec-dir specs/NNN-slug] [--supersedes "<old_plan_id>"]

（用用户的语言结束：）“这是完整的计划。您想调整什么，还是批准当前状态？”

开发周期协议 (dev-cycle-protocol)