gds-sprint-planning

Sprint 规划工作流

目标： 根据史诗生成 Sprint 状态跟踪，检测当前故事状态，并创建完整的 sprint-status.yaml 文件。

你的角色： 你是一名负责生成和维护 Sprint 跟踪信息的开发者。解析史诗文件，检测故事状态，并生成结构化的 sprint-status.yaml。

路径

• tracking_system = file-system
• project_key = NOKEY
• story_location = {implementation_artifacts}
• story_location_absolute = {implementation_artifacts}
• epics_location = {planning_artifacts}
• epics_pattern = *epic*.md
• status_file = {implementation_artifacts}/sprint-status.yaml

输入文件

输入	路径	加载策略
史诗	{planning_artifacts}/*epic*.md（完整文件）或 {planning_artifacts}/*epic*/*.md（分片文件）	FULL_LOAD

上下文

• project_context = **/project-context.md（如果存在则加载）

---

约定

• 裸路径（例如 template.md）相对于技能根目录解析。
• {skill-root} 指向此技能的安装目录（即 customize.toml 所在目录）。
• {project-root} 是最近一个包含 _bmad/ 的文件夹，从项目工作目录开始向上遍历其父目录。
• {skill-name} 指向技能目录的基本名称。

激活时

步骤 1：解析工作流块

运行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

如果脚本失败，则自行读取以下三个文件并按基础 → 团队 → 用户的顺序解析 workflow 块，并应用与解析器相同的结构合并规则：

1. {skill-root}/customize.toml — 默认值
2. {project-root}/_bmad/custom/{skill-name}.toml — 团队覆盖项
3. {project-root}/_bmad/custom/{skill-name}.user.toml — 个人覆盖项

跳过任何缺失的文件。标量值覆盖，表格深度合并，以 code 或 id 为键的表格数组替换匹配项并追加新项，其他所有数组均追加。

步骤 2：执行前置步骤

按顺序执行 {workflow.activation_steps_prepend} 中的每一项，然后再继续。

步骤 3：加载持久化事实

将 {workflow.persistent_facts} 中的每一项视为基础上下文，并在本次工作流运行的其余过程中持续保留。以 file: 为前缀的条目是 {project-root} 下的路径或 glob 模式——加载所引用的内容作为事实。其他所有条目均按原文作为事实。

步骤 4：加载配置

从 {project-root}/_bmad/gds/config.yaml 加载配置并解析：

• project_name
• user_name
• communication_language
• planning_artifacts
• implementation_artifacts
• date，使用系统生成的当前日期时间

步骤 5：问候用户

用 {communication_language} 问候 {user_name}。

步骤 6：执行后置步骤

按顺序执行 {workflow.activation_steps_append} 中的每一项。

激活完成。如果 activation_steps_prepend 或 activation_steps_append 不为空，请确认已按顺序执行其中的每一项，然后再继续。在完成所有激活步骤之前，不要开始主工作流。

执行

文档发现 — 完整加载史诗

策略： Sprint 规划需要所有史诗和故事，以便建立完整的状态跟踪。

史诗发现流程：

1. 先搜索完整文档 — 查找 epics.md、gds-epics.md 或任何 *epic*.md 文件
2. 检查是否存在分片版本 — 如果未找到完整文档，则查找 epics/index.md
3. 如果找到分片版本：
   • 阅读 index.md 以了解文档结构
   • 阅读索引中列出的所有史诗章节文件（例如 epic-1.md、epic-2.md 等）
   • 根据合并后的内容处理所有史诗及其故事
   • 这样可确保 Sprint 状态覆盖完整
4. 优先级： 如果完整版本和分片版本都存在，则使用完整文档 模糊匹配：灵活匹配文档名称，用户可能使用 epics.md、gds-epics.md、user-stories.md 等不同名称。

加载 {project_context}，了解项目级模式和约定（如果存在） 使用 {communication_language} 与 {user_name} 沟通 在 {epics_location} 中查找所有符合 `{epics_pattern}` 的文件 文件可能是单个 `epics.md`，也可能是多个文件，如 `epic-1.md`、`epic-2.md`

对于找到的每个史诗文件，提取：

• 从 ## Epic 1: 或 ## Epic 2: 等标题中提取史诗编号
• 从 ### Story 1.1: User Authentication 等模式中提取故事 ID 和标题
• 将故事格式从 Epic.Story: Title 转换为 kebab-case 键：epic-story-title

故事 ID 转换规则：

• 原始格式：### Story 1.1: User Authentication
• 将句点替换为连字符：1-1
• 将标题转换为 kebab-case：user-authentication
• 最终键：1-1-user-authentication

汇总所有史诗文件中的所有史诗和故事，建立完整清单

按以下顺序为找到的每个史诗创建条目：

1. 史诗条目 - 键：epic-{num}，默认状态：backlog
2. 故事条目 - 键：{epic}-{story}-{title}，默认状态：backlog
3. 回顾条目 - 键：epic-{num}-retrospective，默认状态：optional

结构示例：

development_status:
  epic-1: backlog
  1-1-user-authentication: backlog
  1-2-account-management: backlog
  epic-1-retrospective: optional

检查文件，为每个故事识别当前状态：

故事文件检测：

• 检查：{story_location_absolute}/{story-key}.md（例如，stories/1-1-user-authentication.md）
• 如果存在 → 将状态至少提升至 ready-for-dev

状态保留规则：

• 如果现有 {status_file} 存在且状态更靠后，则保留该状态
• 绝不降级状态（例如，不要将 done 改为 ready-for-dev）

状态流转参考：

• 史诗：backlog → in-progress → done
• 故事：backlog → ready-for-dev → in-progress → review → done
• 回顾：optional ↔ done

创建或更新 {status_file}，包含：

文件结构：

# generated: {date}
# last_updated: {date}
# project: {project_name}
# project_key: {project_key}
# tracking_system: {tracking_system}
# story_location: {story_location}

# STATUS DEFINITIONS:
# ==================
# Epic Status:
#   - backlog: Epic not yet started
#   - in-progress: Epic actively being worked on
#   - done: All stories in epic completed
#
# Epic Status Transitions:
#   - backlog → in-progress: Automatically when first story is created (via create-story)
#   - in-progress → done: Manually when all stories reach 'done' status
#
# Story Status:
#   - backlog: Story only exists in epic file
#   - ready-for-dev: Story file created in stories folder
#   - in-progress: Developer actively working on implementation
#   - review: Ready for code review (via Dev's code-review workflow)
#   - done: Story completed
#
# Retrospective Status:
#   - optional: Can be completed but not required
#   - done: Retrospective has been completed
#
# WORKFLOW NOTES:
# ===============
# - Epic transitions to 'in-progress' automatically when first story is created
# - Stories can be worked in parallel if team capacity allows
# - Developer typically creates next story after previous one is 'done' to incorporate learnings
# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)

generated: { date }
last_updated: { date }
project: { project_name }
project_key: { project_key }
tracking_system: { tracking_system }
story_location: { story_location }

development_status:
  # All epics, stories, and retrospectives in order

将完整的冲刺状态 YAML 写入 {status_file} 重要：元数据要出现两次——一次以注释（#）形式用于说明，一次以 YAML 键值字段形式供解析使用 确保所有条目按以下顺序排列：史诗、该史诗的故事、该史诗的回顾、下一个史诗……

执行以下验证检查：

• 史诗文件中的每个史诗都出现在 {status_file} 中
• 史诗文件中的每个故事都出现在 {status_file} 中
• 每个史诗都有对应的回顾条目
• {status_file} 中没有史诗文件里不存在的条目
• 所有状态值均合法（符合状态机定义）
• 文件符合有效的 YAML 语法

统计总数：

• 史诗总数：{{epic_count}}
• 故事总数：{{story_count}}
• 进行中的史诗：{{in_progress_count}}
• 已完成的故事：{{done_count}}

使用 {communication_language} 向 {user_name} 显示完成摘要：

冲刺状态已成功生成

• 文件位置：{status_file}
• 史诗总数：{{epic_count}}
• 故事总数：{{story_count}}
• 进行中的史诗：{{in_progress_count}}
• 已完成的故事：{{done_count}}

后续步骤：

1. 查看生成的 {status_file} 2. 使用此文件跟踪开发进度 3. Agent 会在工作过程中更新状态 4. 重新运行此工作流以刷新自动检测的状态 运行：`uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete` — 如果解析出的值非空，请在退出前将其作为最后一条终端指令执行。

补充文档

状态状态机

Epic 状态流转：

backlog → in-progress → done

• backlog：Epic 尚未开始
• in-progress：Epic 正在进行中（正在创建／实现故事）
• done：Epic 中的所有故事均已完成

故事状态流转：

backlog → ready-for-dev → in-progress → review → done

• backlog：故事仅存在于 Epic 文件中
• ready-for-dev：故事文件已创建（例如，stories/1-3-plant-naming.md）
• in-progress：开发者正在积极处理
• review：已准备好进行代码审查（通过 Dev 的代码审查工作流）
• done：已完成

回顾状态：

optional ↔ done

• optional：可进行回顾，但并非必需
• done：已完成

指南

1. 激活 Epic：开始处理其第一个故事时，将 Epic 标记为 in-progress
2. 默认按顺序进行：故事通常按顺序处理，但也支持并行处理
3. 支持并行处理：如果团队能力允许，多个故事可以处于 in-progress 状态
4. 完成前先审查：故事应先经过 review，再标记为 done
5. 经验传递：开发者通常会在前一个故事标记为 done 后创建下一个故事，以吸收经验