plan-features

目的

使用此技能将讨论中的项目意图转化为持久设计和有序工作。Beads 管理实时功能／任务状态。design.md 记录详细的功能意图。planned-features.md 保持为简洁的人工可读路线图。将 <core-dir> 解析为已安装的 ../dstack-core 技能目录，以便功能选择使用其确定性解析器。

启动时的版本证据

在创建或更新项目规划状态之前，按照 ../dstack-core/references/SKILL-VERSION.md 中针对 plan-features 的说明操作。只读检查项目后，捕获精确的单行输出，并在修改状态之前将其纳入规划回复或选定的 Beads／设计证据中。stale 结果会提示使用 npx skills update；unavailable 表示未对新鲜度作出声明，不会阻止离线工作。

输入

结合用户请求以及以下内容：

• bd prime、当前功能根节点、可开展的工作和受阻工作；
• docs/src/SUMMARY.md 及其链接的页面；
• docs/src/planned-features.md；
• 现有功能设计和已实现功能记录；
• 在完善现有项目时，参考当前代码、测试、配置和架构证据。

输出

创建或更新：

• Beads 功能根节点、生命周期步骤、实现子项和依赖关系；
• docs/src/planned-features.md；
• 近期功能或已充分理解的功能对应的 docs/src/features/<slug>/design.md；
• 为确立持久方向所需的项目专属读者文档页面；
• 导航发生变化时更新 docs/src/SUMMARY.md。

执行

1. 加载项目状态

运行：

bd prime
bd list --all --type epic --label workflow:feature --json --limit 0
bd ready --json
bd blocked --json

在选择详细页面前，先阅读文档目录。只阅读与规划范围相关的项目专属页面，以及相关的已完成功能记录和设计。

2. 规范化规划输入

如果规划输入包含文字稿、会议记录或先前的 Agent 会话，请按时间顺序处理决策：

• 后续明确的用户决策优先于早期提议；
• 将已被取代的名称、载荷、依赖关系和约束标记为历史信息，不要沿用；
• 区分仓库观察结果与持久的产品意图；
• 将每项持久决策复制到每个受影响的 design.md 中，而不只是路线图；
• 将尚未解决的矛盾记录为问题，不要自行选择方便的解释。

3. 进行设计问题循环

每次提出一个有针对性的问题。优先询问答案会改变以下内容的问题：

• 用户、运营者、集成者或维护者的结果；
• 功能边界和非目标；
• 所有权、数据、状态和生命周期；
• 架构、集成和信任边界；
• 故障、恢复、支持、推出或兼容性行为；
• 确切的读者文档页面；
• 验证和验收；
• 依赖顺序和并行性。

持续询问，直到每个已分配实现任务的功能都有明确结果、清晰边界、已知依赖关系、确切的文档影响、验证策略，以及足够的设计意图，使每项任务都能在不自行决定产品策略的情况下执行。逐项审查每个拟议任务：实现 Agent 必须能够满足验收标准，而无需询问用户来选择行为、架构、UX、兼容性、依赖关系、所有权或推出策略。

现在就询问所有可能实质性改变任务实现或验收标准的决策。只有当未知事项不会阻塞或改变任何计划任务时，才将其记录为延期决策，并注明负责人和重新审议的触发条件。可供实现的设计不得存在任务所需的未决决策。如果用户在问题循环完成前结束规划，不要为尚未解决的范围创建任务；应说明规划尚未完成。

4. 拆分功能

创建具有独立价值且便于评审的功能。如果一个条目包含彼此无关的成果、所有权边界、迁移或运维风险，请拆分工作。优先安排能够尽早消除架构不确定性或为多个后续功能扫清障碍的功能。

使用小写且适用于文件系统的 slug 作为稳定的功能标识。若某个 slug 已被其他功能使用，则拒绝使用；文档和路线图顺序应明确记录，绝不能编码进标识中。

当成果、边界、依赖、验证和文档影响均已明确时，创建持久化设计和生命周期。如果这些要素仍未明确，则只将功能保留在路线图中，但不要为其创建实现任务。原生规划绝不能将尚未做出的用户决策记作实现阻塞；只有导入的迁移工作可以暂时保留此类缺口。

5. 设计文档结构

根据读者的问题选择具体页面：

• 简介：目的、受众、范围和边界；
• 架构：结构、所有权、交互、不变量和持久化决策；
• 运维手册 / 使用指南：部署、配置、可观测性、操作、维护、恢复和故障排查（如适用）；
• 开发指南：构建、测试、扩展、迁移和维护；
• 参考：精确的命令、配置、接口、架构、字段、状态、默认值、限制、术语和验收约定。

复用已涵盖该主题的页面。针对新的持久化读者需求创建专门页面。在 docs/src/SUMMARY.md 中登记每个新页面。

6. 创建功能设计

创建功能目录，并根据以下内容起草 design.md：

docs/src/features/_template/design.md

保留具体的用户措辞、示例、约束、已拒绝的方向和规划决策。在 docs/src/SUMMARY.md 的功能设计标记之间登记创建的每份设计，以便路线图和审计链接在渲染后的书籍中有效。在 文档影响 中列出确切文件，并将每项计划变更分配给一个实现 bead。

7. 创建 Beads 生命周期

对于每个已准备好进行持久化设计的功能，套用仓库公式：

bd mol pour dstack-feature \
  --var feature_name="<title>" \
  --var feature_slug=<slug> \
  --var design_path=docs/src/features/<slug>/design.md \
  --var implemented_path=docs/src/features/<slug>/index.md \
  --var base_branch=<base> \
  --json

返回的根节点是功能 epic（套用公式生成的 molecule 是带有工作流语义的 epic）。该根节点必须且只能带有一个 workflow:feature 标签；生命周期任务和实现任务仍是后代节点，并使用各自的标签。立即规范化并记录标识。对于在其他仓库中实现的工作，请明确设置 implementation_repository、implementation_path 和该仓库的 base_branch：

bd update <root-id> \
  --type epic \
  --title "<title>" \
  --add-label workflow:feature \
  --spec-id docs/src/features/<slug>/design.md \
  --set-metadata feature_slug=<slug> \
  --set-metadata feature_name="<title>" \
  --set-metadata design_path=docs/src/features/<slug>/design.md \
  --set-metadata implemented_path=docs/src/features/<slug>/index.md \
  --set-metadata base_branch=<base> \
  --set-metadata implementation_repository=<repository> \
  --set-metadata implementation_path=<absolute-or-repo-relative-path>

使用 bd mol show <root-id> --json 一次性解析生命周期 ID，然后将其持久化到根节点，以便后续 Agent 只需加载 bd show <root-id> --json：

bd update <root-id> \
  --set-metadata design_id=<id> \
  --set-metadata review_specification_clarity_id=<id> \
  --set-metadata review_execution_readiness_id=<id> \
  --set-metadata spec_reconcile_id=<id> \
  --set-metadata implementation_id=<id> \
  --set-metadata docs_reconcile_id=<id> \
  --set-metadata validation_id=<id> \
  --set-metadata review_implementation_integrity_id=<id> \
  --set-metadata review_delivery_integrity_id=<id> \
  --set-metadata delivery_id=<id> \
  --set-metadata workflow_kind=molecule

Beads 不会在结构化元数据中替换公式变量。解析生命周期 ID 后，为每个生命周期任务设置具体的标识和路径元数据；绝不能保留 {{variable}} 值：

for lifecycle_id in \
  <design-id> <review-specification-clarity-id> <review-execution-readiness-id> \
  <spec-reconcile-id> <implementation-id> \
  <docs-reconcile-id> <validation-id> <review-implementation-id> <review-delivery-integrity-id> <delivery-id>
do
  bd update "$lifecycle_id" \
    --set-metadata feature_slug=<slug> \
    --set-metadata feature_name="<title>" \
    --set-metadata design_path=docs/src/features/<slug>/design.md \
    --set-metadata implemented_path=docs/src/features/<slug>/index.md \
    --set-metadata base_branch=<base>
done

当 bd show <root-id> --json 报告该节点为 epic、包含所有必需的生命周期 ID、每个 ID 都指向预期的子节点，并且根节点或生命周期元数据中均不含公式占位符时，生命周期创建即告完成。确认人类可读选择器能够解析回该根节点：

uv run <core-dir>/scripts/resolve-feature.py <slug> --json

在路线图建议或面向用户的工作流命令中，不要使用不透明的 Beads 哈希作为主要功能引用。若审计需要，请在元数据、报告和提交记录中保留根节点 ID。

迁移的旧版根节点可能是普通 epic，而非 molecule。它们的导入器会存储相同的生命周期 ID 元数据，因此下游技能可使用同一接口处理这两种类型。

8. 创建实施 Beads

在生命周期实施协调器下创建范围明确的任务。每项任务都包含：

• 一个具体结果和明确范围；
• 无需新的用户决策即可满足的验收标准；
• 相关设计章节；
• 明确的文档归属；
• 验证命令或证据；
• 实际前置条件；
• 适用时的并行元数据；
• 实用的提交边界。

选择范围最窄且适用的 Beads 类型：普通的范围明确的工作使用 task，已知缺陷使用 bug，带明确退出标准且有时间限制的实施事实调查使用 spike，维护工作使用 chore。如果在 spec-reconcile 之前必须解决明确的架构或产品选择，请在规划期间记录为 decision；切勿将此类选择推迟到可直接实施的子任务中。仅在明确管理用户故事待办事项时使用 story，不要将 milestone 用作可执行工作。

使用 parent-child 表示层级关系，使用 blocks 表示实际前置条件。独立的同级任务保持并行。每个实施子任务都必须依赖生命周期中的 spec-reconcile 步骤，以确保在规格评审前实施工作无法就绪。为范围明确的任务命名，使其在树形视图之外也易于识别：

<feature-slug> <task-key> — <concrete outcome>

在每个生命周期任务和实施任务上保存 feature_slug 和 feature_name。功能 epic 保持为唯一的父项／容器；实施协调器是一个任务门控节点，其下包含范围明确的任务，而不是第二个功能 epic 或里程碑。

完成任务图之前，拒绝或重写任何包含 TBD、未解决的备选方案、“decide”、“choose”，或其研究结果会决定必要产品行为的原生任务。只有当任何可能的研究结果都符合已决定的契约时，研究任务才可以收集实施事实。

9. 完成规划状态

当草拟设计和实施任务图均已存在时，关闭生命周期设计步骤：

bd close <design-step-id> --reason "Planning Q&A complete; draft design and implementation graph created"

让四个独立的评审步骤保持就绪，以供 /start-feature 使用。

更新 docs/src/planned-features.md，加入简洁的路线图说明、规范的 <slug> 功能引用、便于审计的 Beads 根 ID、依赖项、设计链接、排序依据和状态快照。将详细意图保留在 design.md 中，并将实时状态保留在 Beads 中。

如果下游工作树需要规划文档，请提交这些文档。提交信息中包含功能根 ID。

完成标准

当路线图内容连贯、每项功能都是一个由人工命名且其下包含生命周期步骤和任务的 Beads epic、近期功能拥有稳定的 slug 和设计、实施工作已拆分为范围明确的任务、明确分配了具体文档变更和验证工作，并且每项原生实施任务都无需其他用户决策即可执行时，规划即告完成。仅当工作由 /migrate-workflow 导入且带有明确的协调溯源信息时，才允许存在未解决的决策阻碍。

从 Beads 中选择推荐功能，而不要手动复制哈希值：

uv run <core-dir>/scripts/resolve-feature.py --next --json

返回 helper 的 recommended_command，例如 /start-feature conduit-rest-list-response-validation，并附上人工可读的功能名称和根 ID。绝不要在 Beads ID 后追加字符；如果规范 slug 或准确的功能名称可用，也不要推荐不透明的 ID。