comet-native
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseComet Native
Comet Native
Native 把需求、完整目标规格、当前进度和验收结论保存在项目中。每完成一个阶段都回到 Runtime 读取下一步,当前只处理 Runtime 指定的阶段。
Native stores requirements, complete target specifications, current progress, and acceptance conclusions in the project. After completing each phase, it returns to the Runtime to read the next step, and currently only processes the phase specified by the Runtime.
硬性边界
Hard Boundaries
- 磁盘中的 、当前 change、
.comet/config.yaml和正式 Markdown 是工作依据,聊天记忆只作辅助。comet-state.yaml - Runtime 管理工作流状态、本机任务、日志、锁和事务;所有阶段推进都通过 PATH 中公开的 命令完成。
comet native - 命令不可用时报告 Comet 安装不完整并停止。参数和输出以 为准。
comet native <command> --help - Builder 提交候选,新的只读 Verifier subagent 或独立 Agent 任务作出验收判断。
- Native 主流程由本 Skill 和 Runtime 完成,不依赖任何外部 Skill。
- , current change,
.comet/config.yaml, and official Markdown files in the disk are the basis for work; chat memory is only for assistance.comet-state.yaml - Runtime manages workflow status, local tasks, logs, locks, and transactions; all phase advancements are completed via the command exposed in the PATH.
comet native - If the command is unavailable, report incomplete Comet installation and stop. Parameters and output are subject to .
comet native <command> --help - Builder submits candidates, and a new read-only Verifier subagent or independent Agent task makes acceptance judgments.
- The main Native workflow is completed by this Skill and Runtime, and does not depend on any external Skill.
开始或恢复
Start or Resume
- 已知 change 名称时,直接运行 ;名称未知时才运行
comet native status <change-name> --details --json,确定目标后再查询该 change 的详细状态。comet native status --json - 当前阶段需要完整验收列表时才执行 中的分页命令;需要编辑或核对正式正文时才运行
nextPageArgs或读取对应 brief/Spec。show - active change 已存在时,进入返回的 并
workspace.projectRoot。多个合理候选才让用户选择。select - 没有对应 active change 时才创建,并使用配置指定的产物目录。
- When the change name is known, directly run ; only run
comet native status <change-name> --details --jsonwhen the name is unknown, then query the detailed status of the change after determining the target.comet native status --json - Only execute the pagination command in when the current phase requires a complete acceptance list; only run
nextPageArgsor read the corresponding brief/Spec when editing or checking the official content.show - When an active change exists, enter the returned and
workspace.projectRoot. Let the user choose only when there are multiple reasonable candidates.select - Create a change only when there is no corresponding active change, and use the product directory specified in the configuration.
创建 change
Create Change
先确定小写 kebab-case 名称,再按工作区选择参考决定使用当前目录、创建分支还是创建 worktree。
CLI 会完成分支或 worktree 绑定、维护仓库本地排除规则、核对配置并创建可跨设备恢复的状态。随后进入命令返回的 。
preparation.projectRoot如果准备没有完成,保留已经创建的资源,展示 中的失败原因,并按 Runtime 或用户给出的恢复方向继续。
preparationFirst determine the lowercase kebab-case name, then decide whether to use the current directory, create a branch, or create a worktree according to the Workspace Selection Reference.
The CLI will complete branch or worktree binding, maintain repository local exclusion rules, check the configuration, and create a state that can be restored across devices. Then enter the returned by the command.
preparation.projectRootIf the preparation is not completed, retain the already created resources, display the failure reason in , and continue according to the recovery direction given by the Runtime or user.
preparation按需读取
On-Demand Reading
确认 phase 后只读取需要的一份 reference:
- Shape:必须读取并执行澄清参考;
- 实际编辑 brief/完整目标规格,或查看验收报告时读取产物参考;
- 正常推进时,直接执行 Runtime 在 中给出的命令。只有返回字段含义不清、命令输入被拒绝、无法启动 Verifier、Verifier 执行报错,或 Verifier 要求用户补充信息时,才读取命令参考;
continuation - 只有任务因进程中断、换设备后本机状态缺失、连续多轮没有进展、并发冲突、旧版本迁移失败或状态损坏而无法继续时,才读取恢复参考。
After confirming the phase, only read the required reference:
- Shape: Must read and execute the Clarification Reference;
- Read the Artifact Reference when actually editing the brief/complete target specifications or viewing the acceptance report;
- During normal advancement, directly execute the command given by Runtime in . Only read the Command Reference when the returned field meaning is unclear, command input is rejected, Verifier cannot be started, Verifier execution reports an error, or Verifier requires the user to supplement information;
continuation - Only read the Recovery Reference when the task cannot continue due to process interruption, missing local status after switching devices, no progress for consecutive rounds, concurrency conflicts, failed migration from old versions, or damaged status.
Shape
Shape
先调查能够从仓库、工具和运行环境确定的事实;彼此独立的事实可以交给 subagent 调查。按 和澄清参考维护决策树,只把会改变用户可见结果、又无法可靠推断的决定交给用户。
native.clarification_mode确认后的用户可见决定和重要约束立即同步到 Decisions、brief 和完整目标规格;普通实现选择保留在实现和测试中,只有影响用户可见行为时才进入正式需求。验收项必须具体、可观察且互不重复。
未解决问题保持 ;有阻塞项时不修改项目实现。完成标准:所有会影响用户可见结果的选择和未明说的假设均已处理,没有 ,用户明确确认目标、范围、关键决定、验收项和非目标,并且 Runtime 已进入 Build。只有用户明确确认后才使用后续指令中含 的命令推进。
[blocking][blocking]--confirmedFirst investigate the facts that can be determined from the repository, tools, and operating environment; independent facts can be assigned to subagents for investigation. Maintain the decision tree according to and the Clarification Reference, and only hand over decisions that will change user-visible results and cannot be reliably inferred to the user.
native.clarification_modeImmediately synchronize the confirmed user-visible decisions and important constraints to Decisions, brief, and complete target specifications; keep ordinary implementation choices in implementation and testing, and only enter formal requirements when they affect user-visible behavior. Acceptance items must be specific, observable, and non-repetitive.
Unresolved issues remain marked as ; do not modify the project implementation when there are blocking items. Completion criteria: All choices that affect user-visible results and unstated assumptions have been processed, there are no items, the user explicitly confirms the goal, scope, key decisions, acceptance items, and non-goals, and the Runtime has entered Build. Only use commands with in subsequent instructions to advance after the user explicitly confirms.
[blocking][blocking]--confirmedBuild ↔ Verify Loop
Build ↔ Verify Loop
Build 和 Verify 组成一个有界验收循环(Loop):Builder 提交候选,Runtime 执行必要检查,再由新的只读 Verifier 验收。验收未通过时回到 Build,完成修改并提交下一轮候选;全部通过时进入 Archive。
iterationattemptcontinuationBuild and Verify form a bounded acceptance loop: Builder submits candidates, Runtime performs necessary checks, and then a new read-only Verifier conducts acceptance. When acceptance fails, return to Build, complete modifications, and submit the next round of candidates; when all items pass, enter Archive.
iterationattemptcontinuationBuild
Build
首次实现时读取当前 brief、完整目标规格和全部验收项。如果 Verify 未通过并返回 Build,先处理 Verifier 指出的未通过项、无法继续验证的问题和失败检查;再次提交前重新核对完整规格与全部验收项,避免只修报错点而遗漏其他要求。
需求变化时先判断归属:
- 当前需求只是实现有遗漏:从 Verify 或 Archive 使用 回到 Build;
--return-to-build - 用户可见行为或验收标准发生变化:回到 Shape,更新正式产物并重新确认;
- 与当前需求无关:保留给另一个 change。
用户明确补充当前范围时,按同一规则处理。
候选完成后,按 Runtime 在 中提供的输入模板提交一份精简的 Builder 交接摘要,包括:本轮做了什么、处理了哪些验收项、实际运行或没有运行哪些开发期检查,以及还有哪些已知限制。
continuation这份 handoff 保存在 中,不会生成单独文件,也不代表已经验收通过。Runtime 会把它交给 Verifier,Builder 提交一次即可。
comet-state.yaml完成标准:实现和相关检查达到可验收状态,完整验收项已重新核对,Runtime 接受 handoff 并进入 Verify。
When implementing for the first time, read the current brief, complete target specifications, and all acceptance items. If Verify fails and returns to Build, first handle the failed items pointed out by Verifier, problems that prevent continued verification, and failed checks; recheck the complete specifications and all acceptance items before submitting again to avoid only fixing error points and missing other requirements.
When requirements change, first determine the attribution:
- Current requirements only have missing implementations: Return to Build from Verify or Archive using ;
--return-to-build - User-visible behavior or acceptance standards change: Return to Shape, update official artifacts, and reconfirm;
- Unrelated to current requirements: Reserve for another change.
When the user explicitly supplements the current scope, handle it according to the same rules.
After completing the candidate, submit a streamlined Builder handoff summary according to the input template provided by Runtime in , including: what was done in this round, which acceptance items were handled, which development-phase checks were actually run or not run, and what known limitations remain.
continuationThis handoff is stored in , does not generate a separate file, and does not mean acceptance has been passed. Runtime will hand it over to Verifier, and Builder only needs to submit it once.
comet-state.yamlCompletion criteria: The implementation and related checks reach an acceptable state, all acceptance items have been rechecked, and Runtime accepts the handoff and enters Verify.
Verify
Verify
Runtime 要求启动 Verifier()时,先把当前候选需要运行的测试和检查命令填入 ,由 Runtime 统一执行。Runtime 会复用已经完成的检查;是否重试或补充检查,以最新 为准。
dispatch-verifierinputOptions.templatecontinuationRuntime 返回 后,立即启动一个新的只读 Verifier subagent。平台不支持 subagent 时,启动一个与 Builder 会话分开的新 Agent 任务。
verifierDispatchVerifier 先读取验收项、brief、完整目标 Spec、实际实现和 Runtime 检查结果,最后再把 Builder handoff 当作调查线索,保持验收判断独立。
Verifier 保持只读。如果现有检查不足,就在 Runtime 返回的 中列出还需要运行哪些检查,由 Runtime 执行并把结果返回给 Verifier。
inputOptions.templateVerifier 最终必须逐项标记为通过()、未通过()或暂时无法验证(),一项不能漏,也不能重复。未通过或无法验证时,写出下一轮 Build 可直接处理的原因。无法启动 Verifier、Verifier 执行出错或缺少外部信息时,按命令参考和最新 处理。
passedfailedblockedcontinuation完成标准:Runtime 已接受完整的 Verifier 结果,并明确进入 Build、Archive、等待用户()、阻塞()或完成()中的一种状态。
await-userblockeddoneWhen Runtime requires starting the Verifier (), first fill the test and check commands that need to be run for the current candidate into , and Runtime will execute them uniformly. Runtime will reuse completed checks; whether to retry or supplement checks is subject to the latest .
dispatch-verifierinputOptions.templatecontinuationAfter Runtime returns , immediately start a new read-only Verifier subagent. If the platform does not support subagents, start a new Agent task separate from the Builder session.
verifierDispatchVerifier first reads the acceptance items, brief, complete target Spec, actual implementation, and Runtime check results, and finally uses the Builder handoff as an investigation clue to maintain independent acceptance judgments.
Verifier remains read-only. If existing checks are insufficient, list the additional checks that need to be run in returned by Runtime, and Runtime will execute them and return the results to Verifier.
inputOptions.templateVerifier must finally mark each item as , , or , with no omissions or duplicates. When items fail or cannot be verified, write the reasons that can be directly handled in the next round of Build. When Verifier cannot be started, Verifier execution errors occur, or external information is missing, handle according to the Command Reference and latest .
passedfailedblockedcontinuationCompletion criteria: Runtime has accepted the complete Verifier results and clearly enters one of the states: Build, Archive, , , or .
await-userblockeddoneArchive
Archive
只有 允许 Archive 时才继续。Archive 直接使用已经接受的验收结果。 或 需要收尾选择时,一次展示实际 change 分支、目标分支和目录,让用户选择合并(merge)、推送(push)、创建 PR、保留工作区(keep)或暂不归档。
continuationbranchworktree只提交属于当前 change 的实现和正式产物,保留其他用户改动。执行 Runtime 返回的 ,再检查工作区收尾结果 ;结果为阻塞()时保留现场,并执行 中的恢复命令。
commandArgsworkspaceFinishResultblockedrecoveryArgs完成标准:状态为 ,并且用户授权的工作区收尾结果为已完成()或已保留();其他结果按 继续。
donecompletedkeptcontinuationOnly continue when allows Archive. Archive directly uses the accepted acceptance results. When or requires finishing choices, display the actual change branch, target branch, and directory at once, and let the user choose to merge, push, create a PR, keep the workspace, or postpone archiving.
continuationbranchworktreeOnly submit the implementation and official artifacts belonging to the current change, and retain other user modifications. Execute the returned by Runtime, then check the workspace finishing result ; if the result is , retain the scene and execute the recovery command in .
commandArgsworkspaceFinishResultblockedrecoveryArgsCompletion criteria: The status is , and the user-authorized workspace finishing result is or ; handle other results according to .
donecompletedkeptcontinuation后续指令
Subsequent Instructions
每次命令后只处理最新的 :
continuation- :执行
continue,并按模板填写commandArgs;inputOptions - :等待列出的用户决定;
await-user - :先处理列出的阻塞原因或恢复动作;
blocked - :结束。
done
执行会修改状态的命令后,重新查询该 change 的详细状态,确认当前阶段、验收循环、状态版本和工作目录。只有需要正式正文时才运行 。
showOnly process the latest after each command:
continuation- : Execute
continueand fillcommandArgsaccording to the template;inputOptions - : Wait for the listed user decisions;
await-user - : First handle the listed blocking reasons or recovery actions;
blocked - : End.
done
After executing commands that modify the status, re-query the detailed status of the change to confirm the current phase, acceptance loop, status version, and working directory. Only run when official content is needed.
show