comet-native

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Comet 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

  • 磁盘中的
    .comet/config.yaml
    、当前 change、
    comet-state.yaml
    和正式 Markdown 是工作依据,聊天记忆只作辅助。
  • Runtime 管理工作流状态、本机任务、日志、锁和事务;所有阶段推进都通过 PATH 中公开的
    comet native
    命令完成。
  • 命令不可用时报告 Comet 安装不完整并停止。参数和输出以
    comet native <command> --help
    为准。
  • Builder 提交候选,新的只读 Verifier subagent 或独立 Agent 任务作出验收判断。
  • Native 主流程由本 Skill 和 Runtime 完成,不依赖任何外部 Skill。
  • .comet/config.yaml
    , current change,
    comet-state.yaml
    , and official Markdown files in the disk are the basis for work; chat memory is only for assistance.
  • Runtime manages workflow status, local tasks, logs, locks, and transactions; all phase advancements are completed via the
    comet native
    command exposed in the PATH.
  • 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

  1. 已知 change 名称时,直接运行
    comet native status <change-name> --details --json
    ;名称未知时才运行
    comet native status --json
    ,确定目标后再查询该 change 的详细状态。
  2. 当前阶段需要完整验收列表时才执行
    nextPageArgs
    中的分页命令;需要编辑或核对正式正文时才运行
    show
    或读取对应 brief/Spec。
  3. active change 已存在时,进入返回的
    workspace.projectRoot
    select
    。多个合理候选才让用户选择。
  4. 没有对应 active change 时才创建,并使用配置指定的产物目录。
  1. When the change name is known, directly run
    comet native status <change-name> --details --json
    ; only run
    comet native status --json
    when the name is unknown, then query the detailed status of the change after determining the target.
  2. Only execute the pagination command in
    nextPageArgs
    when the current phase requires a complete acceptance list; only run
    show
    or read the corresponding brief/Spec when editing or checking the official content.
  3. When an active change exists, enter the returned
    workspace.projectRoot
    and
    select
    . Let the user choose only when there are multiple reasonable candidates.
  4. 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
如果准备没有完成,保留已经创建的资源,展示
preparation
中的失败原因,并按 Runtime 或用户给出的恢复方向继续。
First 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
preparation.projectRoot
returned by the command.
If the preparation is not completed, retain the already created resources, display the failure reason in
preparation
, and continue according to the recovery direction given by the Runtime or user.

按需读取

On-Demand Reading

确认 phase 后只读取需要的一份 reference:
  • Shape:必须读取并执行澄清参考
  • 实际编辑 brief/完整目标规格,或查看验收报告时读取产物参考
  • 正常推进时,直接执行 Runtime 在
    continuation
    中给出的命令。只有返回字段含义不清、命令输入被拒绝、无法启动 Verifier、Verifier 执行报错,或 Verifier 要求用户补充信息时,才读取命令参考
  • 只有任务因进程中断、换设备后本机状态缺失、连续多轮没有进展、并发冲突、旧版本迁移失败或状态损坏而无法继续时,才读取恢复参考
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
    continuation
    . 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;
  • 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 和完整目标规格;普通实现选择保留在实现和测试中,只有影响用户可见行为时才进入正式需求。验收项必须具体、可观察且互不重复。
未解决问题保持
[blocking]
;有阻塞项时不修改项目实现。完成标准:所有会影响用户可见结果的选择和未明说的假设均已处理,没有
[blocking]
,用户明确确认目标、范围、关键决定、验收项和非目标,并且 Runtime 已进入 Build。只有用户明确确认后才使用后续指令中含
--confirmed
的命令推进。
First 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
native.clarification_mode
and the Clarification Reference, and only hand over decisions that will change user-visible results and cannot be reliably inferred to the user.
Immediately 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
[blocking]
; 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
[blocking]
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
--confirmed
in subsequent instructions to advance after the user explicitly confirms.

Build ↔ Verify Loop

Build ↔ Verify Loop

Build 和 Verify 组成一个有界验收循环(Loop):Builder 提交候选,Runtime 执行必要检查,再由新的只读 Verifier 验收。验收未通过时回到 Build,完成修改并提交下一轮候选;全部通过时进入 Archive。
iteration
表示实现候选的轮次,
attempt
表示同一候选启动 Verifier 的次数。连续失败、没有实际进展或 Verifier 多次执行出错时,Runtime 会在预算上限处进入等待用户或阻塞状态。所有计数都由 Runtime 更新,Agent 只执行最新
continuation
Build 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.
iteration
represents the round of implementation candidates, and
attempt
represents the number of times Verifier is started for the same candidate. When consecutive failures occur, there is no actual progress, or Verifier execution errors occur multiple times, Runtime will enter a waiting for user or blocked state at the budget upper limit. All counts are updated by Runtime, and Agent only executes the latest
continuation
.

Build

Build

首次实现时读取当前 brief、完整目标规格和全部验收项。如果 Verify 未通过并返回 Build,先处理 Verifier 指出的未通过项、无法继续验证的问题和失败检查;再次提交前重新核对完整规格与全部验收项,避免只修报错点而遗漏其他要求。
需求变化时先判断归属:
  • 当前需求只是实现有遗漏:从 Verify 或 Archive 使用
    --return-to-build
    回到 Build;
  • 用户可见行为或验收标准发生变化:回到 Shape,更新正式产物并重新确认;
  • 与当前需求无关:保留给另一个 change。
用户明确补充当前范围时,按同一规则处理。
候选完成后,按 Runtime 在
continuation
中提供的输入模板提交一份精简的 Builder 交接摘要,包括:本轮做了什么、处理了哪些验收项、实际运行或没有运行哪些开发期检查,以及还有哪些已知限制。
这份 handoff 保存在
comet-state.yaml
中,不会生成单独文件,也不代表已经验收通过。Runtime 会把它交给 Verifier,Builder 提交一次即可。
完成标准:实现和相关检查达到可验收状态,完整验收项已重新核对,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
continuation
, 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.
This handoff is stored in
comet-state.yaml
, 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.
Completion 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(
dispatch-verifier
)时,先把当前候选需要运行的测试和检查命令填入
inputOptions.template
,由 Runtime 统一执行。Runtime 会复用已经完成的检查;是否重试或补充检查,以最新
continuation
为准。
Runtime 返回
verifierDispatch
后,立即启动一个新的只读 Verifier subagent。平台不支持 subagent 时,启动一个与 Builder 会话分开的新 Agent 任务。
Verifier 先读取验收项、brief、完整目标 Spec、实际实现和 Runtime 检查结果,最后再把 Builder handoff 当作调查线索,保持验收判断独立。
Verifier 保持只读。如果现有检查不足,就在 Runtime 返回的
inputOptions.template
中列出还需要运行哪些检查,由 Runtime 执行并把结果返回给 Verifier。
Verifier 最终必须逐项标记为通过(
passed
)、未通过(
failed
)或暂时无法验证(
blocked
),一项不能漏,也不能重复。未通过或无法验证时,写出下一轮 Build 可直接处理的原因。无法启动 Verifier、Verifier 执行出错或缺少外部信息时,按命令参考和最新
continuation
处理。
完成标准:Runtime 已接受完整的 Verifier 结果,并明确进入 Build、Archive、等待用户(
await-user
)、阻塞(
blocked
)或完成(
done
)中的一种状态。
When Runtime requires starting the Verifier (
dispatch-verifier
), first fill the test and check commands that need to be run for the current candidate into
inputOptions.template
, and Runtime will execute them uniformly. Runtime will reuse completed checks; whether to retry or supplement checks is subject to the latest
continuation
.
After Runtime returns
verifierDispatch
, 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.
Verifier 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
inputOptions.template
returned by Runtime, and Runtime will execute them and return the results to Verifier.
Verifier must finally mark each item as
passed
,
failed
, or
blocked
, 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
continuation
.
Completion criteria: Runtime has accepted the complete Verifier results and clearly enters one of the states: Build, Archive,
await-user
,
blocked
, or
done
.

Archive

Archive

只有
continuation
允许 Archive 时才继续。Archive 直接使用已经接受的验收结果。
branch
worktree
需要收尾选择时,一次展示实际 change 分支、目标分支和目录,让用户选择合并(merge)、推送(push)、创建 PR、保留工作区(keep)或暂不归档。
只提交属于当前 change 的实现和正式产物,保留其他用户改动。执行 Runtime 返回的
commandArgs
,再检查工作区收尾结果
workspaceFinishResult
;结果为阻塞(
blocked
)时保留现场,并执行
recoveryArgs
中的恢复命令。
完成标准:状态为
done
,并且用户授权的工作区收尾结果为已完成(
completed
)或已保留(
kept
);其他结果按
continuation
继续。
Only continue when
continuation
allows Archive. Archive directly uses the accepted acceptance results. When
branch
or
worktree
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.
Only submit the implementation and official artifacts belonging to the current change, and retain other user modifications. Execute the
commandArgs
returned by Runtime, then check the workspace finishing result
workspaceFinishResult
; if the result is
blocked
, retain the scene and execute the recovery command in
recoveryArgs
.
Completion criteria: The status is
done
, and the user-authorized workspace finishing result is
completed
or
kept
; handle other results according to
continuation
.

后续指令

Subsequent Instructions

每次命令后只处理最新的
continuation
  • continue
    :执行
    commandArgs
    ,并按模板填写
    inputOptions
  • await-user
    :等待列出的用户决定;
  • blocked
    :先处理列出的阻塞原因或恢复动作;
  • done
    :结束。
执行会修改状态的命令后,重新查询该 change 的详细状态,确认当前阶段、验收循环、状态版本和工作目录。只有需要正式正文时才运行
show
Only process the latest
continuation
after each command:
  • continue
    : Execute
    commandArgs
    and fill
    inputOptions
    according to the template;
  • await-user
    : Wait for the listed user decisions;
  • blocked
    : First handle the listed blocking reasons or recovery actions;
  • done
    : End.
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
show
when official content is needed.