SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场candidate-to-spec

candidate-to-spec

智能体与模型

查看项目

更新于 10-19 00:23

技能介绍

用途

candidate-to-spec 用于承接 improve-codebase-architecture 评审报告中产生的 deepening 候选，为每个候选生成一份已批准的 spec，以及可供 implement-feature 运行的 ready-for-agent 工单。智能体负责回答设计问题，用户只需对每个候选的一份平实英语规格做批准决定。该技能唯一编写的代码是运行目录下的原型。

主要能力

  • 按依赖排序与分类：规划 worker 依据依赖关系排列候选项，查找已有 spec，并将其划分为本轮执行（this-run）、延期（deferred）和搁置（held）三类，同时列出依赖边、延期原因、搁置原因和开放问题。
  • 设计循环：每个候选依次经过 designer、按需触发的 alternative wave、reviewer 和 designer 修订，开放问题以平实英语加推荐答案的形式逐条提交用户。
  • 规格发布与用户决策：spec worker 发布规格，向用户展示检查点并等待用户决定；批准后规格标记为 ready-for-agent，被拒绝则关闭并记录原因到 rejection.md。
  • 工单拆分：通过三轮派发（工单 worker 起草、reviewer 回答测验、工单 worker 应用答案并发布）产出工单，每个工单带 ready-for-agent 标签并以该 spec 为父项。
  • 运行报告：报告以已发布 spec 及其工单数量开头，列出延期与搁置候选及其阻塞原因、规格已回答的开放问题及推荐答案、需用户提交的策略文件与 ADR，以及每个阻塞 spec 的精确重跑命令 candidate-to-spec <spec#>。

使用方式

该技能采用 orchestrator-mode 常驻模式：主线程负责规划、派发并与用户对话，worker 负责读取、设计、评审和发布。所有退出（包括 Setup 和步骤 0、1 中的提前停止）都会结束常驻模式并报告原因。

环境准备（Setup）：一个 setup worker 按 orchestrator-mode 选择运行目录，解析各技能的安装根路径并记录到 <run>/setup.md。必需依赖包括 orchestrator-mode、codebase-design、to-spec、to-tickets，以及支持 --parent 的 gh（2.102 或更高版本，含原生 sub-issue 和 blocked-by 标志）；不满足的 gh 视为缺失必需依赖。可选依赖包括 prototype、ponytail-review、technical-writing、unslop、domain-modeling，各自在用到时步骤中有回退方案。setup 还会记录项目的 issue-tracker 文档和 triage-label 文档，按 Labels 规则以不区分大小写方式比对仓库标签，并指出缺失的 needs-triage、ready-for-agent、spec 三个标签；同时记录目标项目中 docs/architecture-policy.md 是否存在。缺失必需依赖会在此处停止运行并说明缺口；缺失标签则逐个询问用户是创建还是停止。

工作流：

  1. 加载候选：输入为评审报告路径（<tmpdir>/architecture-review-<timestamp>.html），或在重跑时携带延期候选的 spec 编号。worker 为每张卡片写一个 <run>/candidates/<slug>.md，slug 取卡片 <article> 的 id，否则取标题的 kebab-case 形式。选择依据参数与 slug 或标题匹配；未提供时取评审报告的 Top recommendation，或该 spec 携带的全部候选。若 Setup 记录的策略文件缺失，则进入 Policy bootstrap：主线程询问，同一 worker 恢复后写文件、记录路径并返回 policy_path。

  2. 规划顺序：每个 Planning 一个规划 worker 按依赖排序、查找既往 spec、拆分为本轮、延期和搁置集合。向用户展示返回的 order、edges、deferred、held 和 open_questions，并就每个搁置候选询问：重开 ADR、暂存还是放弃；将答案（含开放问题）回传给规划器。被用户拒绝后重开的 spec 会以 slug 作为 pick 从评审报告重新运行。本轮集合为空时直接进入步骤 5。

  3. 设计每个候选：步骤 2 至 4 按计划顺序逐个候选执行，每个候选完成到工单后再开始下一个。重开的 spec 按本轮候选处理，spec worker 编辑其已有 issue；needs-tickets 的 spec 仅执行步骤 4。步骤 2 是设计循环：designer、按需的 alternative wave、reviewer、designer 修订。每个 open_questions 条目到达时以平实英语加推荐答案提交用户，同时保持独立工作推进。循环期间到达的答案会引用到修订派发或已完成的 spec worker；其行变为 decided 并以所引答案作为证据。修订返回报告 rows_without_evidence: 0 即完成。

  4. 发布 spec 并获取用户决策：spec worker 按 Spec 规则发布，向用户展示该节描述的检查点并等待，然后应用 User decision。spec 标记为 ready-for-agent，或关闭并在 <run>/<slug>/rejection.md 记录原因，即完成。

  5. 拆分为工单：每个 Tickets 三次派发：工单 worker 起草、reviewer（恢复）回答测验、工单 worker（恢复）一次性应用答案并发布。已关闭的 spec 跳过此步。needs-tickets 的 spec 以 decision-log 评论为日志，测验交给按 Reviewer 规则简报的新 reviewer。工单 worker 返回列出每个带 ready-for-agent 标签且父项为该 spec 的工单，或返回 edges: body，即完成。

  6. 报告：运行报告以已发布 spec 和工单数开头，随后列出延期与搁置候选及阻塞原因、规格回答的开放问题及推荐答案、本次运行写入并需用户提交的策略文件和 ADR，以及每个阻塞 spec 的精确重跑命令 candidate-to-spec <spec#>。提醒用户保留评审报告文件，暂存候选可用其 slug 作为 pick 重跑。后续步骤为按计划顺序对每个 spec 运行 implement-feature <spec#>，再对每个功能 PR 运行 ponytail-review。

容量与写入：各步骤依次执行，同一时间只有一个 worker 活跃，唯步骤 2 的 alternative wave 例外，主线程最多并行运行三个 alternative worker，且不并行其他工作。worker 仅在运行目录和 tracker 中写入。目标仓库只接收运行报告列出的未提交文件，最多两个，替代 orchestrator-mode 的 docs/research/ 保存：引导产生的策略文件，以及用户拒绝候选时要求的 ADR。已批准 spec 的术语表和 ADR 变更放入其 docs 工单。

适用场景

适用于已有架构评审报告、需要把架构深化候选系统化落地为可执行任务的数据与工程团队；也适用于按 spec 编号重跑以处理延期候选，或对已有 needs-tickets spec 仅生成工单的场景。

限制

  • 依赖 orchestrator-mode、codebase-design、to-spec、to-tickets 以及 gh 2.102 或更高版本；缺失必需依赖时运行会在 Setup 阶段停止。
  • tracker 固定为通过 gh 访问 GitHub，标签名称需按 triage-label 文档做映射替换。
  • 每个候选需要用户批准一份规格，被拒绝的候选需保留评审报告文件以便重跑。
  • 技能本身仅编写运行目录下的原型代码；目标仓库最多接收两个未提交文件。
  • 官方文本未提供具体收费、价格或效果数据，相关事实暂未提供。