Imported from rpamis/comet (
assets/skills-zh/comet-native/SKILL.md). Install upstream withnpx skills add rpamis/comet --skill comet-native. Copyright stays with the author.
Comet Native
Native 在项目中保存需求和验收结论。先确认 change 的运行格式,再执行当前动作。
旧 SDK Action 继续使用响应中的 claimRequest 模板领取,保留原 Run 和执行身份。
必须遵守的规则
- 已确认范围内的实现、文档修复、证据复用和恢复连续推进;只在需要新决定、授权或外部信息时暂停。使用最新 continuation 的命令、模板和任务包,修正输入后沿用当前任务。
- SDK 的推进以 Runtime Run 为准,当前 change 的
comet-state.yaml用于边界恢复;旧 Runtime 继续使用其状态文件。读取实际配置和正式文件,聊天记忆只作辅助。Agent 编辑 brief、新能力或旧格式的完整目标 Spec、关联能力的delta.yaml和children.yaml;关联能力的完整目标 Spec 由 Runtime 在 Shape 确认前生成。业务状态、用户批准、检查报告和事务由 Runtime 保存;普通检查由 Agent 使用平台工具执行。 - 通过 PATH 中公开的
comet native命令推进,用户不手工执行命令。命令不可用时报告安装不完整并停止;参数以comet native <command> --help为准。 - 新建 change 走 CLI 并使用响应路径;拒绝后按信息中的命令或目标修正并重试;自定义 Hook、非 Comet 工作和普通同名文件保持中立。
- Builder 提交本轮待验收的代码和相关文件,称为“候选实现”。Verify 覆盖全部验收项,复用仍与当前候选匹配的检查,只补缺失或失效证据。当前 Action 的
sessionRequirements.independent为false时,由当前 Agent 根据不确定性和用户要求决定是否另请只读 Verifier;为true时使用独立会话。失败、阻塞、未执行和超时不能算通过。 - 只有用户明确确认完整 Shape、接受最终结果或选择相应交付方式后,才执行对应的确认命令。沿用已确认的需求范围和 Runtime 保存的用户选择。归档、merge、push、PR 和工作区清理各自需要的授权不能互相代替。
- Native 主流程由本 Skill 和 Runtime 完成,不依赖外部 Skill;不改变已确认的需求和约束时,实现方法由 Agent 自行选择。
开始或恢复
首次开始任务或更换 Agent 平台时,核对公开 CLI 和结果回报能力。当前 Action 要求独立会话时,再读取平台能力核对并安排执行者。
- 当前响应已包含工作区、任务和下一步时直接继续。缺少这些信息时,已知名称运行
comet native select <change-name> --json,否则运行comet native status --json。active change 已存在时进入workspace.projectRoot;工作区有歧义时才让用户选择。Run 记录丢失时读取故障恢复。 - 没有对应 active change 时,按工作区选择参考确定隔离方式,运行
native new,用--task传入用户原始请求,不先改写成方案摘要,再进入preparation.projectRoot。准备失败时,保留已创建的分支和目录,按返回的原因处理。 - 进入工作区并取得
phase后,按记忆接入获取适用上下文。进入新阶段、交接给新 Agent 或恢复上下文时,由接收方执行contextRequest,重新取得当前适用偏好和项目约束;同一阶段连续执行无需重复获取。任务结束时按该节分别处理项目记忆和个人记忆,再调用comet task --complete。
仅在出现明确的用户纠正、长期记忆要求或已验证的可复用经验时提交学习内容。普通收尾无需调用工具证明没有观察,也无需清空学习队列。任务摘要、进展、命令输出和测试结果不写入个人记忆。
项目经验与个人偏好分开保存:可由当前项目验证、且未来任务仍可复用的经验在任务结束前执行 comet knowledge remember 写入项目记忆;用户偏好和稳定协作习惯才进入个人记忆。两者的命令和完成条件见记忆接入。
SDK Run 路径
先读取并执行普通命令与检查。旧业务数据自动适配,沿用原 Run 和有效批准。普通任务和 Supervisor 任务使用 native next <change> --session <真实会话标识> --json 领取。Shape 中由 Agent 提取验收条目并提交,等待用户明确确认后进入 Build。响应 comet.native.task-result.v1 给出阶段、实际工作区、验收正文、结果模板和下一步,直接照此执行。多个任务可领取时,从 availableTasks 选择真实执行范围,并用其 Action 和实际会话领取;按 task.child、task.scope 和工作区完成当前任务。
- Builder 完成实现后,将
resultTemplate的实际业务结果写入临时 UTF-8 JSON,用返回的next.commandArgs提交。保留命令中的--action和真实--session。Agent 使用平台工具运行必要检查,等待真实结果,并在 checks 的 name/result/note 中记录命令、目录、结果和日志引用。Builder 一次回报实现与检查;Verifier 的 output.checks 填写本次采信的实际结果。失败、未运行和未知结果不能算通过,不提交 verificationChecks、request-checks 或自制收据。旧检查调度不再执行,使用当前返回的业务模板。当前会话继续验收时使用--review current-session,另请审查者时使用--review independent,由接收者以自己的真实会话领取。 - Verify 覆盖全部验收项,复用有效检查,只补缺失证据;提交实际结论后,Runtime 返回用户接受结果的步骤。用户明确要求独立审查时必须选择独立会话。
- 只有用户事前明确委托“验收通过后接受并归档”时,才在本次 Verify 回报中加
--accept-on-pass <用户授权摘要>。该摘要绑定本次通过结果。其他情况等待用户接受,再执行返回的确认命令。Git 交付仍使用已有的对应授权。
新建内置任务无需读取底层协议。并行子任务只在各自 worktree 工作并返回结果;主 Agent 按原 Action、真实子会话和领取身份顺序提交,保留原 resultTemplate 或 resultRequest,不重新领取或改用主会话。Supervisor 回报后,Runtime 连续处理 Git 集成和子归档;接收下一个子任务需使用其真实执行会话。父级验收保留全部要求,复用适用的子结果并补足集成缺口。当前响应为旧 comet.native.sdk-status.v1、comet.native.dispatch-result.v1、comet.native.run-view.v1,且高层入口不适用,或属于固定应用时,读取SDK Run 命令与恢复。完整协议需要时用 --details,不额外查询 status 来识别已有响应。
两种 Runtime 均使用最新 continuation;--runner-input 和旧 Archive 输入仅用于旧 Runtime。SDK 路径遵守用户确认、当前 Action 的验收要求和工作区授权。已知旧 change 在入口自动适配业务数据,不恢复旧进程或重播外部操作。
按需读取
只读取当前动作对应的章节。章节中的链接写明了适用条件,满足条件时再读取链接内容;不一次加载整份命令参考或所有参考。
- Shape:必须读取并执行澄清,按项目配置选择 Sequential 或 Batch 的提问步骤。大型需求在最终确认前,必须按该节链接读取 Supervisor 拆分与确认要求。
- 编辑 brief/Spec/
children.yaml或核对验收报告前,必须读取正式产物。文件、附件、链接或本地路径作为需求来源时,必须进入源文档完整覆盖模式;仅用于排错、取证、审查或实现参考的材料不自动触发。 - 高层任务响应缺少所需字段,或使用旧 SDK、固定应用时,读取平台 Action 协议、SDK Builder 交接或SDK Verify 协议中当前需要的章节。
- Compat 首次填写 Runner 模板或通过
returnAction回传前,读取填写命令输入,再按阶段读取Builder 交接或Verify 协议。 - 状态包含
childSummary时,必须在分配任务、接收结果或集成前读取Supervisor 协作,只处理readyChildren列出的子任务和 Supervisor 统筹动作。 - 字段含义不清、命令输入被拒绝、Verifier 不可用、执行错误或缺少外部信息:读取命令输入与异常。正常动作直接使用 Runtime 返回的命令和模板。
- 等待外部输入时,按恢复参考中的等待外部输入与监控处理;独立工作继续。进程中断、换设备、连续无进展、并发冲突、迁移失败或状态损坏时,读取故障恢复。
Shape
Agent 先调查能够查明的事实,只询问会改变用户可见结果、又无法可靠推断的决定。简单问题列出未决项及其依赖关系;多个决定相互影响时才建立决策树。按 native.clarification_mode 提问前,先把本轮尚未解决的问题写入 brief。用户确认的结论立即同步到 brief 的相关章节和完整目标规格;未明确回答的部分保持 [blocking]。
把用户明确指定的文件位置、必需章节和产物格式写入 brief 的约束,按原要求准备这些内容;不能因模板默认位置而改放其他文件。交接和恢复时以这些已确认约束核对产物,不能只保留业务示例。
写完 Shape 后,回到原始请求和公开项目资料核对目标、验收项与非目标。把实现必需的行为列为非目标前,先说明它会怎样改变用户要求;有多种解释时,写清依据和影响,不把自行选择的解释当作用户已确认的要求。固定评估任务中的模拟批准不能修改原题。
完成标准:需求来源已在用户指定的覆盖边界内完整处理并按用途分类,所有影响结果的决定和假设已处理,没有 [blocking],用户明确确认目标、范围、关键决定、全部验收项和非目标,并且 Runtime 已进入 Build。
新建需求或重新确认 Shape 时,由 Agent 判断目标、范围、非目标、验收和必要 Spec 是否充分,按任务需要组织文档。Runtime 保留正式路径、非空输入、机器结构和用户确认检查。新建普通 SDK Run 可通过 next --session 提交明确验收条目,不要求为解析器改写文档。
Build、Verify 或待归档阶段发生编辑时,按编辑后续行由当前 Agent 判断影响,沿用原 Run 和有效批准,只补必要检查。文件变化不自动作废验收,不提交指纹、hash 或编辑复核记录。修订命令不构成用户授权;缺授权时只请求受影响的决定。
Build ↔ Verify Loop
Builder 完成实现并用平台工具执行检查后,一次提交候选与实际结果,再由领取 Verify Action 的 Agent 完成验收。未通过则回 Build 修复并重新提交;全部通过后,等待用户接受验收结果。
Verifier 先读原始请求,再对照 Spec 和实现,核对有无遗漏、未经授权的范围缩减或接口行为变化。SDK Run 使用同一份验收结果中的 requestReview 说明结论;有冲突或仍影响交付的疑问时,保留 fail 或 blocked。旧 Run 和 Compat 没有保存原始请求时,从交接材料和用户记录补查,不把新生成的 Spec 当成唯一需求来源;Compat 沿用原结果结构。语义核对沿用当前 Verifier,不增加 Agent 或固定测试轮次。
iteration 表示提交实现的轮次,attempt 表示同一候选的 Verifier 执行次数。Runtime 保留真实失败次数预算和执行上限;Agent 根据实际修改和结果判断进展。未解决验收项 ID 相同或集合未缩小,不触发额外提示、暂停或重新确认。
Build
首次实现前,读取当前 brief、完整目标规格和全部验收项,在已确认的需求范围内修改项目代码和测试。修复时优先处理 Verifier 指出的未通过项、无法验证的原因和失败检查;提交前仍要核对其他已确认行为。previous_unresolved_ids 只提示本轮修复重点,下一次正式验收仍覆盖全部验收项。
Build、Verify 和 Archive 由 Agent 对照实际文件和用户要求判断变化,不以内容摘要决定批准或验收是否失效。需求未变则保留批准,目标、验收标准或授权发生实质变化且原决定未覆盖时才重新确认。正式产物位置和阶段权限见正式产物。
用户 Hook 的共享输出目录可通过 .comet/config.yaml 的 hook.allow_paths 放行;该配置对 Native 和 Classic 共用,工作流产物目录不在白名单范围。详见用户 Hook 写入。
需求变化时,先判断变化属于哪种情况,再执行当前 continuation 允许的动作:
- 已确认的功能有实现遗漏:从 Verify 使用
--revise-implementation,保留已确认的需求范围,回 Build 修改。 - 用户可见行为或验收标准发生变化:从 Verify 或 Archive-ready 使用
--revise-requirements,更新正式文件,按需求变化后的重新确认先说明变化与影响,再展示完整当前 Shape 并重新确认。 - 与当前需求无关:交给另一个 change。
用户明确补充当前范围时,按同一规则处理。
用户确认一次 Supervisor Shape,就授权执行该范围内的全部子任务。按 Runtime 的指令分配和集成子任务,随后自动进行 Supervisor 主任务的最终验收,覆盖全部验收项。按Supervisor 协作区分统筹、Builder 和 Verifier 的职责;只有 Runtime 接受了子任务的验收结果并确认集成成功,才算完成。
提交候选前,按 brief 中登记的原位置检查文件、章节和格式,补齐遗漏产物;Agent 选择适用的自动检查,用平台工具检查原文件的实际内容,并记录检查对象和结果;不能用另一文件中的同类内容代替。修改已批准正式内容时沿用现有修订和确认流程。
完成标准:实现和相关检查可供验收,Runtime 接受 Builder 交接并进入 Verify。
Verify
新 SDK 普通任务按当前 task 和 resultTemplate 完成验收;Builder 回报已包含内部检查与领取时,直接继续本次任务。旧 SDK 按 SDK Verify 协议 与 sessionRequirements.independent 领取,优先使用 resultRequest,缺少时使用 outcomeRequest。所有执行者使用真实会话身份。
Compat 按 Verify 协议 立即启动新的只读 Verifier,原样传递任务包。派发只代表登记:平台接受启动调用、且 Verifier 回报 verifier-started 后,才说明它已运行;启动失败立即按异常流程处理。任务包含验收正文时直接使用,否则按分页读取全部 scopeIds。
Verifier 独立判断全部验收项,同时核对 brief 中登记的产物位置、必需章节和格式,不能用另一文件中的同类内容代替;缺项或错位时报告实际差异,不能给当前候选通过结论。由验收者判断已有真实检查是否仍适用,只补必要证据;新旧 Run 均通过平台工具执行检查;文件和日志正文按需读取。等待工具超时后,继续等待同一个 Verifier。只有平台确认执行失败、超时、任务丢失或结束后无结果时才登记错误。Runtime 接受完整结果后按最新状态继续。
用户明确接受当前结果后执行 --accept-result。用户事前明确委托通过后接受并归档时,按上文使用带授权摘要的 --accept-on-pass;fail、blocked 和执行失败均不能触发接受。Compat 的接受与交付方式仍按当前备选命令处理。
完成标准:Runtime 接受每项验收结论并给出下一步;返回 Build 就继续修复,返回等待或阻塞就处理对应条件,不把阶段结束当任务完成。
Archive
SDK 接受结果后由 Runtime 连续完成归档。响应已说明归档完成时直接核对用户授权的 Git 交付;返回 Archive 命令时执行该命令。只有 Compat 收尾、工作区交付选择或具体恢复要求不清时,才读取Archive 收尾。只处理当前响应列出的阻塞。
只提交本 change 的实现和正式产物,保留无关修改。Compat 检查 workspaceFinishResult,阻塞时按 recoveryArgs 保留现场并恢复;SDK 以 Run 与实际 Git 结果分别核对归档和交付。已有授权足以处理的提交说明和本地阻塞由 Agent 修复后继续,不要求用户再次说“重试”;需要新增授权或外部信息时才询问。
完成标准:状态为 done;SDK Run 为 completed 且用户授权的 Git 交付已实际完成并核对,Compat 工作区收尾为 completed 或 kept;随后按记忆接入协议记录任务完成。其他结果继续处理。
后续指令
响应带有 continuation.mode 时,以它决定当前动作:execute 使用返回的完整参数、输入模板和任务包;wait 等待原任务;ask 展示当前提案并等待用户决定;reconcile 按返回证据核对原执行或处理阻塞;done 核对本次完成或取消的条件后结束。commandArgs 中的占位值必须按 requiredInputs 和输入模板填写,不能把模板当成已经完成的输入或用户批准。inputRef 指向同一响应内的完整输入,直接读取,不另查状态。每次写入后只使用新响应的身份、版本和工作目录;需要详情时执行同一响应给出的读取命令,不为寻找下一步再查询。
旧响应没有 mode 时,按原 disposition 继续:
continue:在返回的工作目录执行完整commandArgs,按inputOptions模板填写输入。await-user:先转述userCommunication.message和suggestedReply,等待列出的决定;按用户选择执行commandAlternatives,保留--expected-state-version和--expected-action。过期时读取最新状态,不自行拼接无保护命令。blocked:处理列出的阻塞或恢复动作;仅暂停依赖该条件的工作。done:核对 Archive 完成标准后结束。
命令成功且响应包含 agent 时,直接复用共用 workflow guard 的轻量所有权读取结果和 continuation 继续。只在字段缺失、命令因版本或所有权被拒绝,或需要额外正文时读取详情;新会话或上下文压缩恢复缺少响应状态、仓库/分支/change 切换或有明确外部变化迹象时,才重新查询 status。不因等待工具超时重复派发已有的 Verifier 或子任务。
当前动作需要验收文字、交接摘要或历史详情时,才加 --details,并按 nextPageArgs 读取 scopeIds 涉及的全部页面。需要正式文件的正文时,才运行 show。阅读 CLI 文本时,先看 summary、唯一的 NEXT: 和可选转述消息;程序解析使用 --json,排查本机执行状态时才用 --verbose。
可选变更说明
Native 仅在用户要求可视化变更说明时生成 walkthrough.html。项目 change_walkthrough 默认开启,显式 false 时跳过;允许生成且用户需要时读取变更说明,复用已有差异和结果,生成或更新同一页面并给出链接。普通收尾直接提供简短摘要。Archive 保存已有页面并提供实际归档链接,不补生成、不新增确认、不为页面更新重跑代码检查。
