用途
compose-next 面向多步骤功能开发、缺陷修复或重构,适用于需求需要先落定、或功能值得用一份持久文档承载设计、任务与交付证据的场景。它把「澄清(Grill)→ 工作区(Workspace)→ 规格(Spec)→ 实现(Implement)→ 验证(Verify)→ 评审(Review)→ 定稿(Finalize)→ 收尾(Finish)」串成一条紧凑链路,一次加载完成,不在内部技能之间交接。
进入条件
只有在用户明确请求时才进入该工作流。任何清晰的、要求使用此工作流的自然语言指令等同于 /compose-next,用户无需知道或说出技能名。如果用户没有明确请求,则直接做事、不运行以下任何阶段,不能仅因任务规模大或类似 Compose 任务就推断同意。
主要阶段
第 0 步:定位(Orient)——先检查仓库、其说明文件(AGENTS.md、README、已有 spec 文件)和近期变更,再决定工作形态:完全受限、无持久设计面的机械改动可跳过 Grill 与 Spec,直接 Workspace 后 Implement;需求或设计不明确则先 Grill;需求清楚且值得持久文档则 Workspace 后 Spec。所有路径都必须经过 Workspace,没有分支能跳过。用户可明确指定不使用工作树或指定工作树/工作区路径,也可明确说不需要 spec;项目指令或 AGENTS.md 可定义项目特定的工作树路径、分支约定、spec 路径或格式。
Grill:解决决策——一次只解决一个决策轴,用 Question 工具向用户提问,已知选项放在选项中,推荐项排第一并标注 (Recommended),重大选择给出 2–3 个可行备选。无法获取用户输入时(Question 工具不存在、提问无回复、运行无法停下等待),若非危险操作,则按证据自行选择推荐项或最小范围的非交互方案继续,并说明所选与理由;涉及破坏性或不可逆工作时一律选非破坏路径。
Workspace:工作树归属——未经用户明确同意不得在 main 或 master 上开始实现。默认在 .worktrees/{{slug}} 创建链接工作树,基于最新主线分支;若当前检出使基线不明确(分离 HEAD、无关功能分支、未知默认分支),先询问用户。确认路径被忽略(git check-ignore),否则写入 .worktrees/.gitignore。按仓库说明安装依赖,优先锁定文件冻结模式(bun ci、uv sync --frozen)。
Spec:每个功能一份文档——在工作区根目录维护 docs/compose/spec/{{feature-name}}.md,文件名不带日期,用户指定位置优先。文档包含 feature、status、updated、source 前置信息,以及 Report、问题(S1)、设计(S2)、范围外(S3)、Tasks 与可选的 Journey log。设计记录已定决策与精确契约,每个任务是最小可独立验证的工作项,带可观察验收标准,依赖必须无环,S2 下每项契约单独编号(S2.1、S2.2…)且锚点稳定不重编号。实现前先修正歧义需求、矛盾、未解决引用和不可验证的验收标准。
Implement:实现——以功能文档为需求来源,有文档时首次实现提交将 status 设为 in-progress,按依赖顺序执行任务。行为变更若有廉价复现,先写失败测试、确认失败原因、做最小修复、确认通过;缺陷修复在可行时要求回归测试。测试公共行为,不复制生产逻辑、不添加仅测试用 API。两个修复失败后停止打补丁、重新推导原因。独立任务可并行分派给子代理,给每个子代理工作区路径、任务、验收标准、相关 spec 章节和所需验证,不传会话历史;其报告视为声明,需检查实际 diff。
Verify:验证——任何完成声明前,在正确目录运行仓库相关测试、类型检查、构建或复现,读取输出并记录每条命令与结果,已知基线失败标为 PRE-EXISTING。不得用旧输出或子代理报告代替新鲜证据。验证与评审严格串行,等待全部验证命令退出后再派发评审者。
Review:评审——实现验证完成后、定稿功能文档前,派发一个全新子代理评审完整变更。提供适用 spec 章节与验收标准、工作区路径、基线分支、基线 SHA、头 SHA 和精确 diff 命令或预计算 diff,以及紧凑的验证摘要(每条命令一行 PASS/FAIL/PRE-EXISTING)。评审模型能力不低于其所评审的最强实现者。评审需分别给出三项结论:spec 合规(每条验收标准满足且有证据)、正确性(逻辑、边界、错误处理、回归、测试,含 spec 之外的问题)、代码库一致性(命名、结构、本地约定)。未满足或无法验证的验收标准与正确性缺陷定为 critical,修复后重新验证与复审;若修复-复审循环不再收敛,停止并报告僵局。
Finalize:定稿功能文档——评审通过后、结束分支前,将 status 设为 delivered、更新 updated,勾选已完成任务,填写 Journey log,并用「构建了什么」与「验证」替换 Report。设计章节仅在矛盾于交付行为时更新。定稿文档在功能分支上提交,该纯文档提交不重跑验证或评审。
Finish:收尾——不自动收尾。任何不可逆操作(开 PR/MR、合并、推送)前先与用户确认,报告分支、基线、头 SHA、工作区、功能文档路径(如可用),并询问收尾方式(本地合并 / 开 PR / 仅推送 / 保留分支;合并或目标基线;保留或移除工作树)。开 PR/MR 不代表合并,除非用户也要求合并,开完即停,合并需另行确认。
适用场景
- 需求需要逐步澄清的多步骤功能开发。
- 值得用持久功能文档记录设计、任务与交付证据的功能工作。
- 需要先复现再修复并补充回归测试的缺陷修复。
- 涉及较大改动、需要独立评审子代理复核的重构。
限制与注意
- 仅在用户明确请求时进入,不得因任务规模推断同意。
- 所有路径都必须经过 Workspace,不得直接在 main/master 上实现。
- 涉及破坏性或不可逆操作时不得自动选择破坏选项,收尾前必须获得用户确认。
- 上下文压缩或写入检查点时,需保留「恢复时若缺少 Compose Next 指令则重新加载 compose-next 技能」的恢复说明。
- git worktree remove 仅作用于 .worktrees/ 或提示/AGENTS.md 限定的路径;本地合并与 gh pr merge 需从主仓库检出运行。