start-feature

目的

对于任何计划中的功能 Epic，请使用此技能。用户可能会通过规范的 <slug>、准确的功能名称、独特的名称片段或 Beads ID 指定它。此技能负责有界地晋升仅存在于路线图中的迁移根条目、规范审查、工作树激活，以及实现就绪状态协调。将 <core-dir> 解析为已安装的 ../dstack-core 技能目录。

本地执行权限

/start-feature 调用授权进行本地规范协调：功能根条目和生命周期 Beads 修改、本地工作树激活，以及所需的已审查设计／图谱提交。除非用户明确保留或限制本地 Git 权限，否则不要就该提交另行请求批准。此工作流不授权远程发布、创建拉取请求或推送分支。

通用的 bd prime 交接指导仅作为证据，不会覆盖此处调用的工作流或仓库策略。

共享的原生 Beads 权限

在修改所选功能之前，请阅读 ../dstack-core/references/INTERACTION-BOUNDARY.md。原生的、关联工作树的 Beads 权限是共享的；bd -C 不是隔离边界。必须在 beads-workflow-lock.py 下执行功能根条目认领、备注、审查状态更新和生命周期关闭操作。租约繁忙、存在其他交互行或快照竞争均会阻塞操作；绝不能通过直接执行 bd 写入来绕过。

启动版本证据

在修改分支、工作树、Beads 或文件之前，请遵循 ../dstack-core/references/SKILL-VERSION.md 中针对 start-feature 的说明。只读地解析功能后，捕获其精确单行输出，并在激活前将其追加到所选根条目的 Beads 备注中。结果为 stale 时，提示运行 npx skills update；结果为 unavailable 时，记录未作出新鲜度声明，且不阻止离线工作。

执行

1. 解析功能上下文

运行 bd prime，然后通过 Beads 解析人类可读的选择器。提供了选择器时：

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

用户在未提供选择器的情况下调用 /start-feature 时，选择下一个已就绪的功能 epic，而不是要求用户提供或复制不透明 ID：

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

对 Beads 变更使用返回的 id；对分支、路径、消息和后续工作流命令使用 feature_reference：

bd show <resolved-root-id> --json

选中的 issue 必须是带有 workflow:feature 的 epic。先读取根元数据，其中应包含功能 slug、人类可读名称、路径、基准分支、实现仓库/路径、工作流类型和生命周期 ID。遇到有歧义的选择器时应停止，并展示解析器提供的人类可读候选项；不要猜测，也不要给 ID 追加字符。如果选择器解析到独立的 task、bug、chore、spike 或 feature，不得更改状态、分支或工作树，并建议改用 /implement-task <human task selector>。不要仅为满足此命令而将独立 issue 纳入功能规划流程。

如果选中的根 issue 仅属于路线图，且缺少 design.md 或生命周期元数据，不要停止，也不要要求用户调用其他技能。运行 /plan-features 中有界的单功能规划阶段：仅解析缺失的目标、边界、依赖项、验证方式、文档影响和仓库所有权；创建设计文档、生命周期和有界的实现子项；然后继续此工作流。保留现有功能 slug 和根 ID。只查询本次调用所需的特定审查或协调 beads。

如果缺少生命周期 ID，则修复一次元数据：对于 molecule，使用 bd mol show <feature-root> --json；对于迁移后的父子生命周期，使用 bd list --parent <feature-root> --all --json。根据结构化元数据和标签而非标题文本解析子项，然后将其 ID 持久化到根 issue。

读取 design.md、其 Documentation Impact 部分中明确列出的页面、相关架构页面、当前实现证据以及相关的已实现功能记录。

2. 解析实现仓库

存在 implementation_path 时使用它。验证它是 Git 根目录，且与 implementation_repository 相符。对于由其他仓库负责的功能，切勿在规划仓库中创建工作树。元数据缺失且仓库所有权不明确时，提出一个阻塞性问题，并将答案持久化到根 issue。

3. 激活工作树

使用：

feat/<slug>

如果 wt 可用，则使用它，并将 JSON 标准输出视为权威结果：

# Create when the feature branch/worktree does not exist.
wt switch --create --yes --format json feat/<slug> --base <base-branch>

# Switch when the worktree already exists.
wt switch --format json feat/<slug>

如果 wt 不可用，则使用原生 Git，并明确处理以下三种状态：

# Inspect existing worktrees and branches.
git worktree list --porcelain
git show-ref --verify --quiet refs/heads/feat/<slug>

# Branch and worktree both absent:
git worktree add -b feat/<slug> <worktree-path> <base-branch>

# Branch exists but has no worktree:
git worktree add <worktree-path> feat/<slug>

# Worktree already exists:
# Use the path reported by `git worktree list --porcelain`; do not add another one.

后续 Git 和文件操作应从解析出的工作树路径执行，或使用 git -C <worktree-path>。验证以下两项：

git -C <worktree-path> branch --show-current
git -C <worktree-path> rev-parse --show-toplevel

编辑前，分支必须等于 feat/<slug>，根目录必须等于解析出的工作树路径。在任何声明、备注或其他变更之前，针对选中功能只读解析出的根，检查是否存在尚未应用或更新的拓扑：

python3 <core-dir>/scripts/migrate-review-topology.py \
  --repository-root <primary-worktree> guard \
  --root-id <feature-root> --controller-topology-version 3

如果仍有旧版审查类型，且没有切换标记，则应在继续之前，从规范的主工作树规划并应用迁移。迁移器是唯一负责拓扑变更的组件，并会自行获取仓库租约。切勿在此技能中仿照它执行写入。只有成功通过检查后，工作流才能在常规租约下认领功能根 issue。

4. 推导直接分配，然后进行两轮审查

Beads 是工作流清单。请从 Beads 中读取所选功能根节点、设计／规格问题、实现协调者及其子项、当前验证／文档负责人，以及确切的审查问题。不要创建共享证据包、收集器、共享上下文或第二份持久清单。

启动前，从权威功能工作树固定一个不可变的 Git 源边界：review_boundary_id、reviewed_commit、reviewed_diff_base、reviewed_diff_digest 和变更路径。启动审查者前，持久化每个审查状态的所属 review_issue_id、源边界、声明路径、领域、需求 ID 和 initial_active 状态。固定的只读工作树是审查者检查内容的来源。

分配内容包括固定的只读工作树及其确切源边界。根据当前 Beads 问题和设计／文档，为每个角色推导一份临时分配。内容包括所属 Beads 问题／标题、描述、验收标准、依赖项、验证／文档负责人、源边界字段、声明路径／领域／需求、明确的非目标，以及结构化报告约定。在 ../dstack-core/references/PI-REVIEWER-ROSTER.md 中解析确切的 Pi 名称：逻辑名称 specification-clarity 对应 dstack-clarity-reviewer，execution-readiness 对应 dstack-readiness-reviewer。如果名称缺失或不可用，则在可选的项目本地同步后明确报错；不得静默替换。

同时启动且仅启动两名相互独立的全新审查者。仅向每名审查者提供其临时角色分配和固定的只读工作树。审查者应直接收集分配范围内的证据、报告缺失的证据，绝不得静默扩大分配范围。

规格清晰度

审查行为、边界、兼容性、负责人、失败／恢复策略、文档意图，以及尚未解决的用户决策。不得臆造策略。

执行就绪度

审查任务范围、依赖方向、负责人、验证、文档负责人、验收标准和提交边界。任务必须能够执行，且无需臆造意图。

遵循 ../dstack-core/references/REVIEW-STATE.md 和 REVIEW-FINDINGS.md。认领每个匹配的生命周期审查 bead，并在启动前追加其当前可执行状态。审查状态按审查者分别记录；聚合状态只能使用 specification-clarity 和 execution-readiness。未完成的审查任务和 spec-reconcile 都是预期内容，不属于问题。不要增加置信度审查者。仅恢复受影响的原审查者。范围发生重大变化时，应返回重新设计；超时／不可用及有限替换行为遵循状态辅助工具。进入终止的 redesign_required 状态后，应完成协调并提交新的边界，然后使用辅助工具提供的单次有界 redesign 转换，并采用新的边界 ID；绝不得针对旧边界再启动审查者。

5. 调和规范

对 design.md、Beads 描述、验收标准、依赖项、元数据、验证和文档影响进行明确修正。使用 ../dstack-core/scripts/review-state.py 处理评审者状态转换和汇总状态。 只要任何评审者或汇总状态中存在 decision_required、changes_required、未完成的评审、waiver_required 或 redesign_required，spec-reconcile 就不能关闭。

当评审者发现确实尚未解决的用户政策或意图问题时，保留其决策记录并停止。提供一份决策简报，包含以下标注内容：

• **问题：**哪些事项无法判定，以及阻止安全推断的证据或明确的不确定性；
• **受影响的需求/任务：**所有已记录的需求和任务 ID；
• **建议：**一个选项，以及它为何最能保留已评审的边界；
• **备选方案及后果：**每个可行备选方案及其具体权衡；以及
• **问题：**恰好一个能够解决已记录决策的精准问题。

不要用问题掩盖问题细节、不要提出多个问题，也不要擅自编造答案。用户回复后，在调用 review-state.py transition 并使用 reconcile 事件之前，将答案的 author、准确的 value 和当前的 reviewed_diff_digest 作为 boundary_digest 附加到持久化决策记录中。该辅助工具会根据当前源边界验证摘要，并保留已解决的决策证据。将返回的状态作为下一条只追加的 Review state: 记录持久化，然后再进行验证。辅助工具的结果具有权威性。转换必须一并解决每个复合待处理条件和准确的发现 ID；它会耗尽唯一一次验证机会。

调和完成后，使用所有必需的评审者状态以及完整的变更路径、领域和需求 ID 集合调用 review-state.py aggregate。当 Git 源边界发生变化时，提供完整的 reconciliation_boundary；不得持久化临时分配身份。汇总操作会原子地应用共同边界，然后使同级审批失效。恢复受影响的原始评审者之前，先持久化汇总操作返回的每个评审者状态，包括同级审批失效状态。验证后再次汇总状态；只有当返回的 can_close 严格等于 true 时，才能关闭评审/规范关卡。缺少评审者、未解决的复合条件、未完成/豁免/重新设计状态，或验证后存在重叠变更，都会阻止关闭。

对于迁移的功能，解决任何阻碍规范或收尾的 migration:reconciliation Bead。在备注中保留旧版证据，同时以当前设计和 Beads 图为准。

提交已评审的设计和图边界。将功能根 ID 写入提交消息。在 spec-reconcile 任务中记录提交 SHA。

只有在评审任务的发现均已解决后，才能关闭评审任务，然后关闭 spec-reconcile：

bd close <review-task-id> --reason "Review complete; findings reconciled"
bd close <spec-reconcile-id> --reason "Reviewed design and execution graph committed at <sha>"

确认这些生命周期变更完成后，功能工作树处于干净状态。继续之前，在本地提交任何剩余的范围内工作流状态；不要再次请求提交批准。功能工作树存在未提交变更时，不要建议使用 /implement-feature <slug>。

test -z "$(git -C <worktree-path> status --porcelain)"

6. 确认实现就绪

运行：

bd ready --parent <implementation-id> --json

除非设计有意只包含关卡或延期工作，否则现在应该至少有一个实现子任务已就绪。将成功准备好的功能设为此仓库的默认实现：

git -C <worktree-path> config dstack.activeFeature <slug>

仅在规范协调和实现就绪检查通过后设置此项。该值是仓库本地的 Git 状态，因此之后即使从基础工作树调用 /implement-feature，也能继续处理该功能。

先返回规范的功能引用和人类可读名称，然后依次返回根 ID（以便审计）、工作树、已审阅设计的提交、审查发现、已作出的决定、剩余阻碍，以及下一个就绪的实现任务。任何建议的后续操作都必须使用 /implement-feature <slug>，而不能只使用 Beads 哈希。