comet-native
Comet Native workflow. Use when the user explicitly invokes /comet-native, asks to start or resume a Native change, or the entry routes to Native.
- License 许可
- MIT
- 所属仓库
- rpamis/comet
- 最近更新
- 2026-11-15
- Stars
- ★ 3.3k
- Forks
- 314
01 前言 Front Matter
- name
- comet-native
- description
- Comet Native workflow. Use when the user explicitly invokes /comet-native, asks to start or resume a Native change, or the entry routes to Native.
02 资源文件 21
- 参考文档agents/openai.yaml126 B
- 参考文档reference/artifacts.md13.8 KB
- 参考文档reference/clarification.md15.7 KB
- 参考文档reference/commands.md53.4 KB
- 参考文档reference/edit-review.md5.2 KB
- 参考文档reference/recovery.md8.6 KB
- 参考文档reference/workspace.md10.4 KB
- 脚本scripts/comet-native-archive.mjs1.0 MB
- 脚本scripts/comet-native-cancel.mjs881.5 KB
- 脚本scripts/comet-native-doctor.mjs1.1 MB
- 脚本scripts/comet-native-hook-guard.mjs924.6 KB
- 脚本scripts/comet-native-init.mjs884.3 KB
- 脚本scripts/comet-native-new.mjs1.0 MB
- 脚本scripts/comet-native-next.mjs1.0 MB
- 脚本scripts/comet-native-root.mjs914.9 KB
- 脚本scripts/comet-native-runtime.mjs1.4 MB
- 脚本scripts/comet-native-select.mjs1.0 MB
- 脚本scripts/comet-native-show.mjs977.0 KB
- 脚本scripts/comet-native-spec.mjs977.3 KB
- 脚本scripts/comet-native-status.mjs1.0 MB
- 脚本scripts/comet-native-transfer.mjs900.4 KB
03 SKILL.md 正文
Comet Native
Identify runtime format before acting; Runtime stores requirements and acceptance in the project.
For older SDK Actions, claim with the returned claimRequest template, preserving the original Run and execution identity.
Required rules
- Continue confirmed implementation, document repairs, evidence reuse, and recovery. Pause for new decisions, authorization, or external information. Use current continuation commands, templates, and packages; correct inputs within the same task.
- SDK progression follows the Runtime Run, while the current change's
comet-state.yamlsupplies boundary recovery. The legacy Runtime retains its state-file contract. Read actual configuration and formal artifacts, using chat memory only as supporting context. The Agent edits the brief, complete target Specs for new capabilities or legacy changes, associationdelta.yaml, andchildren.yaml. Runtime generates associated capabilities' complete target Specs before Shape confirmation. Runtime stores business state, user approvals, check reports, and transactions; the Agent executes ordinary checks with platform tools. - Advance through the public
comet nativeCLI on PATH; do not ask the user to run commands manually. If the command is unavailable, report an incomplete installation and stop. Consultcomet native <command> --helpfor arguments. - Create changes with the CLI; use returned paths and follow denial commands or targets before retrying. Custom and non-Comet writes stay neutral.
- The Builder submits code and related files as the candidate implementation. Verify covers every acceptance item, reusing matching checks and collecting only missing or invalidated evidence. When the current Action has
sessionRequirements.independent: false, choose a separate read-only reviewer according to uncertainty and user requirements. When it istrue, use a separate session. Failed, blocked, unexecuted, and timed-out work cannot count as passed. - Run confirmation commands only after the user explicitly confirms the complete Shape, accepts the final result, or selects the relevant delivery option. Reuse confirmed scope and user choices saved by Runtime. Authorization for Archive, merge, push, PR creation, and workspace cleanup is not interchangeable.
- This Skill and Runtime provide the Native workflow without an external Skill dependency. The Agent chooses implementation methods that preserve confirmed requirements and constraints.
Start or resume
On a new task or Agent platform change, check public CLI availability and result reporting. When the current Action requires a separate session, read the platform capability check and arrange that executor.
- When an active change exists, continue directly if the current response supplies the workspace, task, and next step. Otherwise run
comet native select <change-name> --jsonfor a known name, orcomet native status --jsonto discover it. Enter itsworkspace.projectRoot; ask only when workspace ownership is ambiguous. If local Run history is missing, read fault recovery. - If there is no matching active change, select isolation using workspace selection. Run
native newwith the user's original request in--task, without first rewriting it as a solution summary, then enterpreparation.projectRoot. If preparation fails, preserve any branches and directories already created and address the reported cause. - After entering the workspace and obtaining
phase, retrieve applicable context using memory integration. On a phase change, handoff to a new Agent, or context recovery, the receiver executescontextRequestto obtain current preferences and project constraints. Uninterrupted work in the same phase needs no repeated retrieval. Handle Project Memory and Personal Memory separately at task completion, then callcomet task --completeas specified there.
Submit learning only for an explicit user correction, a long-term memory request, or a verified reusable lesson. Ordinary completion needs no tool call to prove that there is nothing to learn and no queue draining. Never save task summaries, progress, command output, or test results as Personal Memory.
Project experience and personal preferences are stored separately: use comet knowledge remember for reusable verified project facts and Personal Memory for stable user preferences. See memory integration for completion conditions.
SDK Run path
First follow ordinary commands and checks. Older business data is adapted automatically, retaining the original Run and valid approvals. Claim ordinary or Supervisor tasks in current Runs with native next <change> --session <actual-session-id> --json. During Shape, the Agent extracts and submits acceptance criteria and waits for explicit user confirmation before Build. A comet.native.task-result.v1 response contains the phase, actual workspace, acceptance text, result template, and next step. When several tasks are available, select the actual scope from availableTasks and claim its Action with the real session. Follow task.child, task.scope, and the supplied workspace.
- After implementation, write the actual business result from
resultTemplateto a temporary UTF-8 JSON file and submit withnext.commandArgs. Preserve--actionand the actual--session. The Agent runs necessary checks with platform tools, waits for actual results, and records commands, directories, results, and log references in checks name/result/note. The Builder submits implementation and checks together; the Verifier records the actual results accepted for this review in output.checks. Failed, unrun, or unknown results cannot count as passing. Do not submit verificationChecks, request-checks, or custom receipts. Retired check scheduling no longer executes; use current business templates. Choose--review current-sessionto continue verification in this session, or--review independentfor a separate reviewer who claims with their own session identity. - Verify every acceptance requirement, reuse valid checks, and collect only missing evidence. Submit the actual conclusion and follow the returned user-acceptance step. Explicit user requests for independent review require a separate reviewer.
- Add
--accept-on-pass <user-authorization-summary>to the Verify submission only when the user explicitly delegated acceptance and Archive after all criteria pass. The summary binds to that result. Otherwise wait for the user to accept and execute the returned decision command. Git delivery still requires its corresponding authorization.
New built-in tasks do not require the lower-level protocol. Parallel children work only in their own worktrees and return results. The parent submits them in sequence with the original Action, actual child session, and claim identity, preserving the original resultTemplate or resultRequest; do not reclaim the task or substitute the parent session. After Supervisor results, Runtime continues Git integration and Child Archive; receive the next child with its actual execution session. Parent acceptance retains all requirements, reuses applicable child results, and fills integration gaps. Read SDK Run commands and recovery for older comet.native.sdk-status.v1, comet.native.dispatch-result.v1, or comet.native.run-view.v1 responses where the high-level entry does not apply, fixed applications, or a specific protocol question. Use --details when needed. Do not query status again to identify an existing response.
Both runtimes use the latest continuation; --runner-input and legacy Archive inputs apply only to the legacy Runtime. SDK requires approval, the current Action's verification conditions, and workspace authorization. Known legacy changes are adapted at their entry without recovering processes or replaying external operations.
Read only what the action needs
Read the section for the current action. Follow links within it only when their stated conditions apply; do not load the entire command reference or all references at once.
- Shape: read and follow clarification, using Sequential or Batch steps according to project configuration. For large requests, follow its Supervisor decomposition and confirmation link before final confirmation.
- Before editing the brief, Specs, or
children.yaml, or checking an acceptance report, read formal artifacts. A file, attachment, link, or local path supplied as a requirements source requires source-document full coverage. Material used only for debugging, evidence gathering, review, or implementation reference does not trigger this automatically. - Read the relevant part of SDK Action protocol, SDK Builder handoff, or SDK Verify protocol when needed fields are missing or the task uses an older SDK Run or fixed application.
- Before first filling a Compat Runner template or returning through
returnAction, read filling command inputs, then the applicable Builder handoff or Verify protocol. - When state contains
childSummary, read Supervisor coordination before dispatching, receiving results, or integrating. Handle only children listed inreadyChildrenand Supervisor coordination actions. - If fields are unclear, input is rejected, a Verifier is unavailable, execution fails, or external information is missing, read command inputs and exceptions. For normal actions, use Runtime's returned commands and templates directly.
- When waiting for external input, follow external input and monitoring; continue independent work. For interruption, a device change, repeated lack of progress, concurrency conflicts, failed migration, or damaged state, read fault recovery.
Shape
Investigate facts that can be established without the user. Ask only about decisions that change user-visible outcomes and cannot be inferred reliably. For simple requests, list unresolved questions and dependencies; maintain a decision tree only when several decisions affect one another. Before asking under native.clarification_mode, save this round's unresolved questions in the brief. Immediately copy confirmed conclusions into the relevant brief sections and complete target Specs. Keep unanswered parts [blocking].
Record the user's explicitly requested file locations, required sections, and artifact formats in the brief constraints, and prepare those contents as requested. Do not move them to another file because of a default location in a template. During handoff and recovery, check artifacts against these confirmed constraints rather than retaining only the business examples.
After drafting Shape, compare its outcome, acceptance criteria and non-goals with the original request and public project materials. Before excluding behavior needed by the implementation, explain how that changes the requested outcome. When several interpretations remain possible, state the evidence and impact; an Agent's chosen interpretation is not a user-confirmed requirement. Simulated approval in a fixed benchmark cannot change the original task.
Complete when requirements sources are fully processed within the coverage boundary and classified by purpose, all outcome-affecting decisions and assumptions are resolved, no [blocking] remains, the user explicitly confirms the outcome, scope, key decisions, all acceptance items, and non-goals, and Runtime has entered Build.
For new or reconfirmed Shape, the Agent judges whether goals, scope, non-goals, acceptance, and necessary Specs are sufficient and organizes documents for the task. Runtime checks formal paths, nonempty inputs, machine structure, and user confirmation. New ordinary SDK Runs can submit explicit criteria through next --session without rewriting prose for a parser.
When files change during Build, Verify, or before Archive, the current Agent follows edit continuation, judges the actual impact, and retains the original Run and valid approvals. File edits do not automatically invalidate acceptance. Do not submit fingerprints, content hashes, or edit-review records. Add only the checks that the changed behavior needs. Revision commands do not grant user authorization; request only the affected decision when authorization is missing.
Build ↔ Verify Loop
The Builder implements and runs checks with platform tools, then submits the candidate and actual results together. The Agent claiming Verify evaluates acceptance. On failure, return to Build, repair, and resubmit. Once every item passes, wait for the user to accept the result.
The Verifier reads the original request before comparing the Spec and implementation, checking for omissions, unauthorized scope reductions and interface behavior changes. SDK Runs record the conclusion in requestReview in the same verification result; retain fail or blocked for conflicts or unresolved questions affecting delivery. For older Runs and Compat without a saved original request, consult handoff materials and user records rather than treating the generated Spec as the only requirements source; Compat keeps its existing result format. Use the current Verifier for this semantic review; add no Agent or fixed test rounds.
iteration counts implementation submissions; attempt counts Verifier executions for one candidate. Runtime retains actual failure budgets and execution limits. The Agent judges progress from changes and results. Repeated unresolved IDs or a nonshrinking set do not add warnings, pauses, or confirmation steps.
Build
Before the first implementation, read the current brief, complete target Specs, and every acceptance item. Edit project code and tests within confirmed scope. During repair, prioritize the Verifier's failed or blocked items and failed checks, then recheck other confirmed behavior before submission. previous_unresolved_ids identifies the repair focus; the next formal verification still covers every acceptance item.
Build, Verify, and Archive recheck the binding between formal files and the approved original text. When something changes, the current Agent judges its semantics and impact; an unchanged contract keeps its approval, and only a material change to the goal, acceptance criteria, or authorization requests the related decision. After an edit, Hooks verify actual content before the next implementation write or advancement, and the verification also runs when a Hook did not fire. Existing Shapes retain their binding; invalid documents or reports preserve work and address only the specific gaps. Ordinary documents preserve candidates by default; use native.document_writes: revert for strict behavior. See formal artifacts for paths.
User Hook output can use hook.allow_paths in .comet/config.yaml; see User Hook writes.
Classify requirement changes before taking an action allowed by the current continuation:
- Missing implementation of confirmed functionality: use
--revise-implementationfrom Verify, retain confirmed scope, and return to Build. - Changed user-visible behavior or acceptance criteria: use
--revise-requirementsfrom Verify or Archive-ready, update formal artifacts, and follow reconfirmation after requirement changes to explain changes and effects before presenting and reconfirming the complete current Shape. - Unrelated requirements: use another change.
Apply the same rules when the user explicitly adds to the current scope.
One confirmed Supervisor Shape authorizes all children within that scope. Dispatch and integrate as Runtime directs, then automatically perform final verification of every Supervisor acceptance item. Follow Supervisor coordination for coordinator, Builder, and Verifier responsibilities. A child is complete only after Runtime accepts its verification and confirms integration.
Before submitting a candidate, check files, sections, and formats at the original locations recorded in the brief, and complete missing artifacts. The Agent chooses applicable automated checks, runs them with platform tools against the original files' actual contents, and records the check targets and results; equivalent content in another file does not replace those checks. Follow the existing revision and confirmation flow when changing approved formal content.
Complete when the implementation and relevant checks are ready for verification, Runtime accepts the Builder handoff, and the phase is Verify.
Verify
For new ordinary SDK tasks, follow the current task and resultTemplate. When Builder submission already ran checks and claimed Verify, continue that task directly. Older SDK Runs use SDK Verify protocol, follow sessionRequirements.independent, and prefer resultRequest, falling back to outcomeRequest when absent. Every executor uses its actual session identity.
For Compat, immediately launch a new read-only Verifier under Verify protocol, passing the unchanged task package. Dispatch alone is registration: report running only after the platform accepts startup and the Verifier reports verifier-started. Handle startup failures immediately. Use inline acceptance text or page through every scopeId.
The Verifier independently assesses all acceptance items and checks the artifact locations, required sections, and formats recorded in the brief. Equivalent content in another file does not satisfy these requirements; report missing or misplaced content and do not pass the current candidate. The reviewer judges whether actual existing checks still apply and adds necessary evidence. New v4 Runs use platform tools for checks; older Runs retain their Runtime check protocol. Read files and logs on demand. After a wait-tool timeout, keep waiting for the same Verifier. Record errors only for platform-confirmed failure, execution timeout, task loss, or completion without a usable result. Continue from current state after Runtime accepts the complete outcome.
Run --accept-result after explicit user acceptance of the current result. If the user previously delegated acceptance and Archive after a pass, use --accept-on-pass with that authorization summary as described above. Fail, blocked, and execution failures cannot trigger acceptance. Compat retains its returned acceptance and delivery alternatives.
Complete when Runtime accepts each verdict and supplies the next action. Continue repairs on Build, or address the specified waiting or blocking condition. Ending a phase does not mean the task is finished.
Archive
After SDK result acceptance, Runtime advances through Archive. If the response already reports completion, proceed to Git delivery under its existing authorization. Otherwise execute the returned Archive command. Read Archive completion only for Compat finishing, workspace delivery choices, or an unclear recovery requirement. Address the blockers in the current response.
Commit only this change's implementation and formal artifacts; preserve unrelated edits. For Compat, inspect workspaceFinishResult, preserving the workspace and following recoveryArgs if blocked; for SDK, verify Run archival and actual Git delivery separately. Fix commit messages and local blockers under existing authorization and continue; ask only for new authorization or external information.
Complete when state is done; SDK Run is completed and authorized Git delivery has actually completed and been verified, or Compat workspace finishing is completed or kept; then record completion through memory integration. Continue handling any other result.
Continuation
When the response includes continuation.mode, use it to decide the current action: execute uses the complete returned arguments, input templates, and task package; wait waits for the original task; ask presents the current proposal and awaits the user decision; reconcile checks the original execution or addresses blockers using the returned evidence; done ends after checking the criteria for this completion or cancellation. Fill commandArgs placeholders using requiredInputs and the input templates; a template is neither completed input nor user approval. inputRef points to complete input in the same response; read it without querying state again. After each write, use only the new response’s identity, version, and working directory. When details are essential, use the retrieval command in that response rather than querying to discover the next step.
For older responses without mode, use the original disposition:
continue: execute the completecommandArgsin the returned working directory and fill inputs frominputOptionstemplates.await-user: relayuserCommunication.messageandsuggestedReply, then wait for the listed decisions. Execute the matchingcommandAlternatives, retaining--expected-state-versionand--expected-action. Read the latest state if stale; do not construct an unguarded command.blocked: address listed blockers or recovery actions; pause only dependent work.done: finish after checking the Archive completion criteria.
After a successful response containing agent, reuse the shared workflow guard's lightweight ownership result and continue with the response's phase, state version, workspace.cwd, and continuation. Read details only when fields are missing, the command is rejected for version or ownership, or the action needs additional artifact text. Query status again only for a new session or compression recovery without response state, a repository/branch/change switch, or clear external changes. Do not redispatch an existing Verifier or child task because a wait tool timed out.
Add --details only when the current action needs acceptance text, handoff summaries, or history. Follow nextPageArgs through every page covering scopeIds. Run show only when artifact bodies are needed. For CLI text, read summary, the single NEXT:, and any relay message first. Use --json for programmatic parsing and --verbose only to diagnose local execution.
Optional change walkthrough
For Native, generate walkthrough.html only when the user requests a visual change explanation. The project setting change_walkthrough is enabled by default; explicit false skips generation. When enabled and requested, read Change walkthrough, reuse existing differences and results, generate or update the same page, and provide its link. Ordinary completion uses a short summary. Archive preserves existing pages and links to their archived location without generating missing pages, adding confirmation, or rerunning checks for page updates.
04 同仓库更多 Skills
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes