Native Configuration

Comet saves the project configuration in .comet/config.yaml in the root directory. When running comet init, available configurations will be generated, and most projects do not require manual adjustments. You only need to modify it when you want to change the default workflow, document language, clarification method, memory policy or delivery method.

Recommended Native configuration

The following configuration is suitable for new projects that use Chinese documentation:

# Configuration schema version managed by Comet
schema: comet.project.v1
# /comet enters Native by default
default_workflow: native
# Workflows enabled in this project
workflows:
  - native
# Run a read-only resume probe for natural-language "continue" requests
ambient_resume: true

# Personal Memory (shared by Native and Classic)
memory:
  # Learn reusable personal preferences and collaboration habits from workflow outcomes
  learning: true
  # Retrieve and inject relevant personal memory for the current task
  retrieval: true

# Project Knowledge source
knowledge:
  provider: local

# Native core fields
native:
  # Directory for changes, Specs, and reports: <artifact_root>/comet/
  artifact_root: docs
  # Language for new change briefs, Specs, and reports
  language: zh-CN
  # batch: ask a set of questions per round; sequential: ask one per round
  clarification_mode: batch
  # automatic: archive immediately after Verify passes; required: wait for your confirmation
  archive_confirmation: automatic
  # Consecutive failed implementation rounds allowed for one requirement before pausing
  max_verify_failures: 5

This will cause /comet to default to Native, save the change document in docs/comet/, generate the official product in Chinese, and complete the requirement clarification in Batch mode.

Prioritize using comet init --workflow native to create configurations and comet update to complete or upgrade configuration fields.

Default workflow and natural-language resume

Field	Default value	The influence on you
`schema`	`comet.project.v1`	The configuration format version managed by Comet
`default_workflow`	Select during initialization	Decide whether `/comet` will default to Native or Classic
`workflows`	Select during initialization	Declare that the project has enabled `native`, `classic`, or both
`ambient_resume`	`true`	Natural language seems to be running read-only recovery probes while continuing with old tasks

default_workflow only affects the entry point and does not convert existing changes from Native to Classic, nor does it convert Classic Changes to Native. If you need to enable two workflows simultaneously, run:

comet init --workflow both

To disable natural language-triggered recovery detection, you can set it up:

ambient_resume: false

When explicitly calling /comet, the route will still follow default_workflow.

Native core field

Field	Allowed value/default value	The influence on you
`native.artifact_root`	Project relative path Default: `docs`	change, Spec and reports are saved in `<artifact-root>/comet/`
`native.language`	`en` \|`zh-CN`;” The default is `en`	Determine the brief, Spec and reporting language for the new change
`native.clarification_mode`	`batch` \|`sequential`;” The default is `batch`	Decide whether to conduct centralized inquiries in each round or to ask one option point at a time
`native.archive_confirmation`	`automatic` \|`required`;” The default is `automatic`	Decide whether to wait for additional archiving confirmation after verification is passed
`native.max_verify_failures`	Positive integer Default: `5`	After reaching the continuous failure limit, pause the Loop and wait for the user to handle it

Product Catalogue

artifact_root: docs corresponds to <project>/docs/comet/; artifact_root: . corresponds to <project>/comet/. The path must be located within the project. When existing projects need to migrate directories, do not directly modify YAML and manually move files. Let the Runtime complete the inspection, switching and restoration of records:

comet native root show
comet native root move docs

Document language

native.language has decided to create a new official product language for change later. Existing changes will continue to use the language recorded at the time of creation and will not be automatically rewritten due to configuration changes.

native:
  language: zh-CN

Clarification mode

batch: Raising all the questions for this round at once, where the premises are clear and independent of each other, is suitable for reducing round trips.
sequential: In each round, only one most upstream or most influential question is raised, which is suitable for the need where the answer will change the subsequent questions.

Both modes will first investigate the warehouse facts and require you to confirm the complete goals, scope, selection points, acceptance criteria, and non-goals before entering the Build. Switching modes will not clear the unanswered [blocking] questions in brief.md.

Archiving confirmation

automatic: After the final verification is passed, the Runtime can continue to complete the archiving.
required: After the final verification is passed, we will wait for your explicit consent to file.

automatic only controls whether to wait for additional archive confirmation and does not make the merge, push, or PR decision for you. When using a branch or worktree, Comet will still let you choose the actual delivery method; see Archive and delivery for the options.

Verify failure limit

max_verify_failures limits the number of failed implementation rounds that the same confirmed requirement can go through. When the upper limit is reached, Native will pause and allow you to decide whether to continue, modify the requirements, or stop. It will not retry indefinitely. Runtime execution errors, missing external information, and states that cannot be safely recovered will return await-user or blocked separately and should not be bypassed by modifying the count.

Personal Memory

memory is applicable to both Native and Classic switches. By default, both switches are true.

Field	Function
`memory.learning`	Allow Comet to organize reusable personal preferences and collaboration experiences from workflow results
`memory.retrieval`	Allow Comet to retrieve and inject existing personal memories in related tasks

For example, only using existing memories but not continuing to learn automatically:

memory:
  learning: false
  retrieval: true

Project Knowledge

By default, knowledge.provider is local. Comet will use the built-in project corpus. You can also append the Markdown documents in the project:

knowledge:
  provider: local
  local:
    include:
      - docs/architecture/**/*.md
      - packages/*/README.md

knowledge.local.include only accepts Markdown glob within the project. The path should use / and must not go beyond the project root directory. These paths are appended to the built-in corpus. If your team already has a RAG knowledge system, you can switch to a remote Provider:

knowledge:
  provider: remote
  remote:
    endpoint: https://knowledge.example.com
    token_env: COMET_KNOWLEDGE_TOKEN
    scope: engineering
    timeout_ms: 5000

endpoint is the complete URL where your service actually receives requests. Comet sends POST requests to this address directly. Replace the sample domain with your real endpoint. The remote address must use HTTPS. Only localhost and other loopback addresses can use HTTP. Set token_env to an environment variable name, and avoid writing the token directly in configuration. Timeout can be between 100 and 30000 milliseconds.

Hook write release

hook.allow_paths is an advanced configuration shared by Native and Classic. It allows the specified directory to continue writing during the originally protected phase, which is empty by default. If Shape should still block code changes but you need writes under docs/team-notes while keeping other Hook protections, configure:

hook:
  allow_paths:
    - docs/team-notes

The path must be the project’s relative directory and use /. Configuring docs/team-notes will allow all files under it simultaneously.

This configuration will bypass the stage write restrictions of the corresponding directory. Do not allow source code directories to avoid normal interception by Shape, Verify, or Archive. The .comet, Native official product area and Classic official product area are still protected by dedicated rules and cannot be bypassed through the allow list.

Custom PR creation command

By default, when you choose push + create PR during Archive, Comet runs gh pr create --fill and fills the title and body from commit messages. If your repository requires a custom PR template (for example, checklist fields or linked issue fields), or requires post-create remote validation scripts, the default flow may fail repository rules. native.finish.pull_request lets you replace only the PR creation step with your own command while keeping the rest of delivery unchanged:

native:
  finish:
    pull_request:
      provider: repository-command
      command: [pwsh, -NoProfile, -File, scripts/comet-create-pr.ps1]
      timeout_ms: 120000

The repository command is responsible for generating PR title, body, and template, and for repository-specific validations. Comet still handles commit, branch push, existing PR lookup, base/head/head SHA checks, and failure retry. Please note the following restrictions:

Currently, provider only supports repository-command.
command must be a non-empty parameter array; The first item should use the command name in the PATH or the relative path of the project. Absolute paths cannot be used.
The default timeout_ms is 120000, and the maximum is 600000.
The command is executed in the project root directory, receiving comet.native.pull-request-finish-input.v1 JSON via stdin and returning comet.native.pull-request-finish-result.v1 JSON via stdout.
Even if custom commands are configured, it is necessary to install and authenticate the GitHub CLI (gh) for Comet to independently verify the remote status.

Continue reading: User Selection Points and Requirements Clarification Protocol , Products and Status and Recovery Manual .

Get started

Understand Comet Native

Advanced

Practical scenarios

Native Configuration

Recommended Native configuration

Default workflow and natural-language resume

Native core field

Product Catalogue

Document language

Clarification mode

Archiving confirmation

Verify failure limit

Personal Memory

Project Knowledge

Hook write release

Custom PR creation command

​Recommended Native configuration

​Default workflow and natural-language resume

​Native core field

​Product Catalogue

​Document language

​Clarification mode

​Archiving confirmation

​Verify failure limit

​Personal Memory

​Project Knowledge

​Hook write release

​Custom PR creation command

Recommended Native configuration

Default workflow and natural-language resume

Native core field

Product Catalogue

Document language

Clarification mode

Archiving confirmation

Verify failure limit

Personal Memory

Project Knowledge

Hook write release

Custom PR creation command