comet-native

Comet Native

Native 会在项目中保存完整的需求、进度和验收结果。Agent 仅处理 Runtime 指定的阶段。每次操作后，都要读取最新的 continuation 并遵循其指示，直到任务完成、需要用户决策或外部依赖阻碍进展。

必须遵守的规则

• 继续执行已确认的实现、文档修复、证据复用和恢复工作。遇到新的决策、授权或外部信息时暂停。使用当前的 continuation 命令、模板和软件包；在同一任务中修正输入。
• 将 .comet/config.yaml、当前变更、comet-state.yaml 和磁盘上的正式工件视为权威信息；聊天记忆仅作补充。在正式工作流文件中，Agent 只能编辑 brief、完整的目标 Specs、关联的 delta.yaml 和 children.yaml。状态、检查结果、报告、锁和事务均由 Runtime 管理。
• 通过 PATH 中的公开 comet native CLI 推进；不要让用户手动运行命令。如果命令不可用，报告安装不完整并停止。使用 comet native <command> --help 查看参数。
• 使用 CLI 创建变更；遵循其返回的路径，并在重试前按照拒绝命令或目标的指示操作。自定义写入和非 Comet 写入应保持中立。
• Builder 提交代码作为候选实现。每次迭代都需要由新的只读 Verifier 独立评估每项验收要求。评估每项要求并不意味着要重新运行每条命令：复用仍与当前候选实现匹配的 Runtime 检查记录，只补充缺失或已失效的检查。失败、受阻、未执行和超时的工作均不得视为通过。
• 仅在用户明确确认完整 Shape、接受最终结果或选择相关交付选项后，才运行确认命令。复用 Runtime 保存的已确认范围和用户选择。Archive、合并、推送、创建 PR 和清理工作区的授权不可互换。
• 本 Skill 和 Runtime 提供 Native 工作流，无需依赖外部 Skill。Agent 应选择能够保留已确认需求和约束的实现方法。

开始或恢复

1. 如果已知名称，运行 comet native select <change-name> --json。存在活动变更时，进入返回的 workspace.projectRoot；select 返回与 status 相同的发现和状态信息，因此无需单独调用 status。否则运行 comet native status --json。让 Runtime 定位工作区；只有在多个工作区匹配程度相同时才询问用户。
2. 如果没有匹配的活动变更，选择隔离方式并使用 workspace selection 创建变更，然后进入 preparation.projectRoot。如果准备失败，保留已创建的分支和目录，并处理报告的原因。
3. 进入工作区并获取 phase 后，使用 memory integration 一次性检索上下文。仅在需要时展开详情，记录实际使用结果，在任务完成时分别处理 Project Memory 和 Personal Memory，并按其中的说明调用 comet task --complete。

切勿将任务摘要、进度、命令输出或测试结果保存为 Personal Memory；请完成学习检查。

项目经验和个人偏好应分别存储：任务完成前，使用 comet knowledge remember 将经项目验证且可复用的经验写入 Project Memory；只有用户偏好和稳定的协作习惯才写入 Personal Memory。有关命令和完成条件，请参阅 memory integration。

只阅读当前操作所需内容

阅读当前操作对应的章节。只有在其中注明的条件适用时，才跟进该章节内的链接；不要一次性加载整个命令参考或所有参考资料。

• Shape：阅读并遵循 澄清，并根据项目配置使用 Sequential 或 Batch 步骤。对于大型请求，遵循其中的 Supervisor 分解流程和确认链接，然后再进行最终确认。
• 在编辑 brief、Specs 或 children.yaml，或检查验收报告之前，阅读 正式制品。作为需求来源提供的文件、附件、链接或本地路径，需要进行来源文档完整覆盖。仅用于调试、收集证据、审查或实施参考的材料不会自动触发此要求。
• 首次填写 Runtime 模板或通过 returnAction 返回结果之前，阅读填写命令输入。
• 提交 Builder 候选项之前，阅读 Builder 交接。启动 Verifier、为其添加检查或等待其结果之前，阅读 Verify 协议。
• 当状态包含 childSummary 时，在派发、接收结果或集成之前，阅读 Supervisor 协调。仅处理 readyChildren 中列出的子项和 Supervisor 协调操作。
• 如果字段不明确、输入被拒绝、Verifier 不可用、执行失败或缺少外部信息，请阅读命令输入和异常。对于常规操作，直接使用 Runtime 返回的命令和模板。
• 等待外部输入时，遵循外部输入与监控；同时继续独立工作。发生中断、设备变更、反复没有进展、并发冲突、迁移失败或状态损坏时，阅读故障恢复。

Shape

调查无需用户参与即可确定的事实。只询问会改变用户可见结果且无法可靠推断的决策。对于简单请求，列出未解决的问题和依赖项；只有在多个决策相互影响时才维护决策树。在 native.clarification_mode 下提问之前，将本轮未解决的问题保存到 brief 中。确认结论后立即复制到相关 brief 章节并补全目标 Specs。未回答的部分保留为 [blocking]。

完成条件：在覆盖范围内完整处理并按用途分类需求来源，解决所有影响结果的决策和假设，不再有 [blocking]，用户明确确认结果、范围、关键决策、所有验收项和非目标，并且 Runtime 已进入 Build。

新建或重新确认的 brief 需要包含结果、范围、非目标和验收示例。适用时，添加约束、决策、未解决问题或特殊验证要求。Runtime 还会检查正式路径以及完整的目标 Spec，或检查不改变产品行为的具体原因。修复报告的问题制品并重新运行后续流程。现有 brief 在后续阶段发生的变更会保留进度，直到进入 Shape。

Build ↔ Verify 循环

Builder 提交候选结果后，Runtime 会运行必要检查，并由新的只读 Verifier 进行评估。如果失败，则返回 Build 阶段进行修复并重新提交。所有项目通过后，等待用户接受结果。

iteration 统计实现提交次数；attempt 统计针对同一候选结果启动 Verifier 的次数。Runtime 会更新所有计数器。如果连续失败或进展停滞达到配置的限制，请遵循最新指示，等待用户决定或解决阻塞问题。

Build

首次实现前，请阅读当前简述、完整的目标 Specs 和每一项验收要求。在确认的范围内编辑项目代码和测试。修复时，优先处理 Verifier 判定失败或受阻的项目及失败检查，然后在提交前重新检查其他已确认的行为。previous_unresolved_ids 用于确定修复重点；下一次正式验证仍会覆盖每一项验收要求。

Build、Verify 和 Archive 阶段都会重新检查正式绑定。新的 Shape 会绑定 Markdown 内容：空行和软换行不会影响确认；内容、结构、代码、链接或验收要求发生变更时，则需要重新确认。编辑后，Hooks 会在下一次实现写入前检查实际内容；Runtime 也会在推进阶段前进行检查。现有 Shape 会保留其绑定。无效文档或报告会返回修复操作并保留工作。普通文档默认会保留候选结果；如需严格行为，请使用 native.document_writes: revert。路径请参阅正式产物。

User Hook 输出可以在 .comet/config.yaml 中使用 hook.allow_paths；请参阅 User Hook 写入。

在执行当前 continuation 允许的操作前，请先对需求变更进行分类：

• 已确认功能的实现缺失：在 Verify 阶段使用 --revise-implementation，保留已确认的范围并返回 Build 阶段。
• 用户可见行为或验收标准发生变化：在 Verify 或 Archive-ready 阶段使用 --revise-requirements，更新正式产物并重新确认 Shape。
• 无关需求：使用其他变更。

用户明确要求扩展当前范围时，也请遵循相同规则。

一个已确认的 Supervisor Shape 即可授权该范围内的所有子项。按 Runtime 的指示进行派发和整合，然后自动对每一项 Supervisor 验收要求执行最终验证。关于协调者、Builder 和 Verifier 的职责，请遵循 Supervisor 协调。只有在 Runtime 接受其验证结果并确认整合后，子项才算完成。

当实现和相关检查已准备好接受验证、Runtime 接受 Builder 移交且阶段为 Verify 时，即视为完成。

验证

根据 Verify 协议，立即使用未更改的任务包启动一个新的只读 Verifier。只有在平台接受启动请求且 Verifier 报告 verifier-started 后，才报告其正在运行；启动失败时立即处理。使用内联验收文本，或翻阅每个 scopeId。Verifier 会独立评估所有验收项，复用与实现、工作区和输入相匹配的 Runtime 检查，并补充缺失或已失效的证据。按需读取文件和日志。

等待工具超时后，继续等待同一个 Verifier。如果缺少其回执且没有响应，检查启动是否成功。仅在确认失败、执行超时、任务丢失或完成但没有可用结果时报告错误。Runtime 接受结果后，遵循当前状态。只有在用户明确接受后才运行 --accept-result，包括仅包含自动化检查的结果。对于隔离工作区，在同一条回复中接受结果并选择交付方式，使用 --finish；如果未选择完成方式，则另行询问。

当 Runtime 接受每项判定并提供下一步操作时，即为完成。在 Build 阶段继续修复，或处理指定的等待条件或阻塞条件。阶段结束并不意味着任务已完成。

归档

当 continuation 允许 Archive 时，阅读 Archive completion，复用已接受的结果，并遵循 continuation。明确选择完成方式后，执行其完整的 --confirmed --finish 命令；Runtime 会预检并重新检查事务。如果返回 dry-run，在 ready: true 后预览并运行其唯一的确认命令。处理返回的阻塞项。

仅提交本次变更的实现和正式制品；保留无关编辑。检查 workspaceFinishResult，保留工作区，并在受阻时遵循 recoveryArgs。在现有授权范围内修复提交消息和本地阻塞项并继续；仅在需要新的授权或外部信息时询问。

当状态为 done、已授权的工作区完成操作状态为 completed 或 kept，且已通过记忆集成记录任务完成时，即为完成。继续处理任何其他结果。

继续执行

• continue：在返回的工作目录中执行完整的 commandArgs，并使用 inputOptions 模板填写输入。
• await-user：转达 userCommunication.message 和 suggestedReply，然后等待列出的决定。执行匹配的 commandAlternatives，保留 --expected-state-version 和 --expected-action。如果已过期，则读取最新状态；不要构造未受保护的命令。
• blocked：处理列出的阻塞项或恢复操作；仅暂停依赖这些条件的工作。
• done：检查 Archive completion 标准后结束。

成功响应中包含 agent 后，复用共享工作流守卫的轻量级所有权结果，并继续使用响应中的阶段、状态版本、workspace.cwd 和 continuation。仅当字段缺失、命令因版本或所有权问题被拒绝，或操作需要额外的制品文本时，才读取详情。仅在新会话、没有响应状态的压缩恢复、仓库／分支／变更切换或明确的外部变更时，再次查询 status。不要因为等待工具超时而重新分派现有 Verifier 或子任务。

仅在当前操作需要验收文本、交接摘要或历史记录时添加 --details。使用 nextPageArgs 翻阅覆盖所有 scopeIds 的每一页。仅在需要制品正文时运行 show。对于 CLI 文本，先读取 summary、唯一的 NEXT: 和任何转达消息。使用 --json 进行程序化解析；仅在诊断本地执行时使用 --verbose。