Changelog

​

Changed

• Node.js requirements: Use Node.js 22.16 or later within the 22.x line, or Node.js 24 or later. Check local and CI environments before upgrading.

​

Fixed

• Installation and updates: Repeated global initialization preserves existing workflows and policies, and updates preserve the installed English or Chinese language. Uninstall preserves user content and active changes, and returns a failing exit status when cleanup is incomplete.
• Workflow operations: Classic rejects unsupported arguments and reports status-reading failures. Native provides recovery guidance in the wrong workspace and lists the available choices when a passing verification requires your decision.
• Command results: Installation progress no longer corrupts JSON output. Failed Doctor checks, memory synchronization, and knowledge operations return failing exit statuses; unavailable remote services no longer appear as empty results or success.
• Memory and project knowledge: Memory synchronization supports the first connection to an empty repository or an existing memory branch while preserving remote content. Global memories can be forgotten from projects using another language. Markdown retrieval works through parent-directory aliases, and context expansion hints preserve the original project and task conditions.
• Plugin settings: Concurrent Dashboard or CLI updates preserve each project’s enabled or disabled state.
• LangSmith evaluation: The selected suite’s Python dependencies are installed automatically, and missing required SDKs are reported.

​

Security

• Memory sync and Dashboard: Memory Git operations use a dedicated repository to avoid interfering with project commits or synchronizing unrelated history. Dashboard rejects untrusted requests from other web pages.

​

Added

• Specification reference sync: When a confirmed target spec only needs its local Markdown link destinations corrected, run comet native spec sync. The Runtime records the before and after content and the reason, preserves unaffected acceptance results, and returns affected acceptance items to Build for re-verification; prose or acceptance changes still return to Shape.

​

Changed

• Supervisor child verification: Child tasks now use the same coverage and verdict checks as ordinary verification. The Runtime executes repeatable checks, serializes integration checks in the integration worktree, binds registered reports to the tested candidate and execution, and rejects stale or altered evidence. Child verifier results use pass, fail, or blocked with per-criterion results, and passing results require a Runtime receipt. Interrupted checks distinguish process instances when recovering, and incomplete legacy records remain inspectable with recovery guidance.

​

Fixed

• Classic worktree initialization: New and recovered worktrees retain local Comet and OpenSpec configuration so workflow commands remain usable before initialization files are committed. Existing workspace configuration is preserved, conflicting Classic or OpenSpec settings require resolution, interrupted configuration setup can be retried, and managed worktree directories no longer make the parent workspace appear dirty.
• Supervisor workspace delivery: Keep, push, and pull-request finishes collect implementation on the parent change branch first, preserving the chosen delivery boundary. Archive cleans child worktrees using their registered locations, including when the parent runs in a linked worktree.
• Native continuation and recovery: Supervisor progression returns executable dispatch commands and recoverable task packages without redispatching active children, honors single-session scheduling, and tolerates unchanged configuration copies created by the Runtime. Concurrent changes sharing a specification receive an executable Archive ordering choice before confirmation, and interrupted Archive preserves concurrent edits to already-applied specifications.
• Archived status discovery: Completed changes are no longer hidden by stale active copies in linked worktrees when creation identity and committed Git history prove the archive supersedes them; ambiguous records are reported as conflicts.
• Published-spec revision guidance: Write rejections on published specs point to the current change’s supported revision path, and recovery preserves actionable protocol diagnostics for incompatible state schemas.
• Verification report guidance: Failed and blocked verification results direct you to repair the implementation or resolve blockers before verification resumes, instead of asking you to confirm an unsuccessful result.

​

Added

• Host Agent knowledge review: Use comet knowledge review to inspect pending experiences, check sources, and submit reusable knowledge through the current Agent without a separate model or API key. New knowledge starts in trial and is promoted after successful use in later tasks.
• Task adoption evidence: Context feedback can include decisions, verification commands, and actual results. The Dashboard separates delivery records from adoption evidence, and retries do not count twice.

​

Fixed

• Project Knowledge models and retrieval: Module records include entry points, dependencies, callers, registration points, and test evidence. Only Markdown enters the retrieval corpus; code and configuration remain record evidence. Missing or stale models are restored, and tasks can discover relevant knowledge without a known file path.
• Personal Memory management: Reduces duplicate candidates and makes phase-scoped records available for inspection. Permanent deletion clears matching text and associated state while preserving other memories and unresolved conflicts.
• Dashboard views and editing: Retrieval results support scrolling and detail previews. Knowledge corrections use a wider, centered editor that preserves drafts on save failure. Verified, integrated, and archived Supervisor children count toward completion; children needing re-verification are marked separately.
• Historical project registry cleanup: After upgrading, reading the project list automatically removes missing temporary project entries left by older tests. Ordinary missing projects and inaccessible directories remain registered.

​

Changed

• Dashboard theme text: Placeholders, disabled states, and workflow status labels remain readable in light and dark themes, while active and archived states remain distinct.
• Native Archive preflight: After reaching Archive-ready, the Runtime runs one --dry-run and shows workspace and generated-file blockers together with the next confirmation command. Isolated workspaces continue to use explicit delivery options.
• Memory and Project Knowledge display: The Dashboard separates current records, historical or forgotten records, indexed sources, evidence, version chains, and actual query statistics, so learned records can be distinguished from searchable sources.

​

Fixed

• Native Shape confirmation: Native now has a separate user-confirmation step before Build. Unresolved blocking questions from vague requirements or supplied documents prevent confirmation from being skipped, and changed Shape content or expired confirmation commands require confirmation again.
• Project Knowledge source refresh: Refresh now rechecks source content and detects changes even when file size and modification time are unchanged. Dashboard counts cover all project records instead of only the currently displayed list.
• Personal Memory state: Forgotten or conflicted records remain in history but are no longer treated as current memory or written back to Markdown projections.
• Native Supervisor archive recovery: Runtime handles stale-state recovery, cleanup of delivered branches, and final archive-state commits, reducing the need to delete branches, edit Runtime state, or repeat archiving manually.
• Dependency security updates: Transitive dependencies and the npm and pnpm lockfiles were updated to address reported URL normalization, SSRF, and Browserslist stats-processing risks.

​

Fixed

• Devin Desktop OpenSpec compatibility: comet init, comet update, and OpenSpec integration now use Devin Desktop’s .devin/ Skill root while keeping windsurf as the stable platform selector and recognizing legacy .windsurf/ installations.
• Global configuration recovery: comet init and a Home-directory comet update now recover known legacy or project-schema global configurations automatically, without asking users to edit or delete .comet/config.yaml.
• Windows atomic writes: Comet now refreshes temporary-file and Native lock metadata after a successful close, so NTFS close-time metadata finalization no longer makes Comet treat its own files as externally changed. Identity and post-close mutation checks remain enforced before publish or release.
• Dashboard Project Knowledge consistency: Dashboard now uses the same default Local Project Knowledge cache as comet task and comet knowledge, so rebuilt records and indexed Markdown sources appear in the plugin center and records created there are available to CLI retrieval. Records from the former ~/.comet/plugins/knowledge-cache Dashboard location are imported into the canonical cache during upgrade.
• Native Supervisor final verification: Supervisor Changes can now include committed parent-level fixes made after the last Child integration. Final verification records the exact forward integration commit it checked, and continuing a Change automatically repairs an interrupted record or reruns final Verify when needed, so affected users do not need to edit Runtime state or reset their branch while rewritten or divergent integration history remains blocked.
• Native Supervisor repair recovery: After final parent verification fails, repair Children can retain failed Spec-derived acceptance through the automatic return to Shape and reconfirmation. Existing Child integration history remains intact, so users can continue the current workflow after upgrading Comet without editing Runtime state or repeating completed Child work.
• Native Verifier retry: When independent verification is unavailable, Native now offers an immediate retry alongside the explicit degraded-result choice, preserving the current candidate, completed checks, and repair scope so users can continue without restoring files, starting a separate service, or configuring a callback.

​

Added

• CLI output envelope: Native and Classic CLI --json output now includes summary, next, and user_message while retaining existing machine fields. summary explains what happened, next gives the single follow-up action, and user_message provides ready-to-relay bilingual text for user decisions.

​

Changed

• Human-first default CLI text: Native no longer prints raw internal state JSON by default. Output now leads with a summary, NEXT:, and a RELAY TO USER: block when a decision is required; the full machine projection is available through the global --verbose flag. Stable error codes render as readable sentences with machine detail on a DETAIL: line. Classic commands, handoff, archive, manual guard checks, and phase-guard write blocks also prepend bilingual summaries. comet status adds one plain-language line above each Native and Classic change’s machine details.
• CLI envelope consistency: Direct Classic --json commands and verbose Native errors retain the structured envelope and machine detail. User-decision relays take precedence over internal confirmation commands so the Agent asks before resuming a paused workflow.

​

Fixed

• Native verification loop stop: After repeated failures or repeated no-progress results, Runtime now returns an explicit user decision request with ready-to-relay bilingual text. The same applies when a Verifier is blocked on information only the user can provide.
• Native status with stale child indexes: A stale children.yaml acceptance index no longer blocks the whole Native status view. comet status and comet native status continue listing other changes and mark the drifted copy for Shape reconfirmation. Dashboard rendering of parent-child progress continues, while state-advancing commands still enforce strict index validation.
• Prerelease update detection: comet init and comet update now compare complete SemVer values and correctly detect beta-to-RC, RC-to-stable, future patch, and future minor prerelease upgrades.

​

Added (New

• **Dashboard Workspace ** : A new three-column Dashboard for Native and Classic Changes has been added, and it uniformly provides Personal Memory, Project Knowledge, plugin Settings, archive history, Git worktree, and website interaction preview.
• ** Personal Memory ** : New first-party comet-memory Skill and comet memory commands have been added to manage reusable user profiles, collaboration policies, and task experiences, and support retrieval, correction, forgetting, rollback, synchronization, and bounded context.
• Agent Learning Loop : Classic, Native, Hotfix and Tweak will record structured workflows, validations, reviews, archives and contextual application results, and consolidate stable preferences and collaboration experiences through bounded Reflection.
• ** Project Knowledge and Project Strategy ** : comet task and comet knowledge offer sourced project topologies, facts, dependencies, decisions, processes, constraints, and troubleshooting experiences through independent Local Providers and optional Remote Providers.
• ** Configurable Project Knowledge corpus ** : Projects can index the corresponding Markdown glob of the project through knowledge.local.include; Local indexes, records, Provider diagnostics, and correction results are saved by default outside the project repository.
• ** Progressive Agent Context ** : Personal Memory and Project Knowledge can be selected by task, path, operation and stage; The core content is provided directly, and longer records are expanded as needed through the interpretable Context Manifest.
• “Native Supervisor Change v2” : Large Native Changes can be split into dependent children, assigned to independent Codex sessions or Claude Code Agent teams, verified separately, integrated sequentially, and automatically enter the final verification of the parent Change.
• **Native Portable Status and Recovery ** : comet-state.yaml, comet status, and the reconfigurable verification.md offer phase, acceptance, handover, inspection, verification, workspace, and Supervisor summaries.
• **Oh My Pi and DeepSeek Harness support ** comet init, comet update, comet doctor and comet uninstall can manage Comet Skill, Rule, OpenSpec integration and Hook Bridge in project-level and user-level environments of the two platforms.
• “Native CodeGraph Initialization” : When choosing Native or Both, comet init can provide an optional CodeGraph setting and manage the project index and Agent integration separately from the OpenSpec and Superpowers dependencies of Classic.

​

”Changed

• **Native Verification Loop ** : Native reuses completed checks to avoid duplicate scanning of items and repeated execution of Archive checks. It continuously writes command outputs to the local log and displays acceptance, evidence, child, integration, and recovery information through a compact pagination state and details.
• **Native Supervisor Collaboration Recovery ** : Supervisor Change will remember the multi-session or single-session mode selected by the user; When the independent Codex session or Claude Code Agent Team cannot be used, Comet will continue to execute the ready child through the Subagent without re-inquiring about the collaboration mode. At the same time, retain the constraints of the Runtime on worktree, task identity, verification, and integration.
• **Native Workspace and Delivery Process ** : The discovery and reuse of branches and worktrees remain consistent across commands; After the Supervisor parent Change is completed, it directly enters the final Verify. After a successful merge, clean up the worktree created by Comet and retain the branches. Archive will clearly display the actual impact of local submission, merge, push and PR.
• **Native Clarification and Classic Context Settings ** : Batch clarification is used by default for new Native projects; The RC1 project template enables beta context compression for Classic, while continuing to clearly manage the product language, Review mode, automatic advancement and memory, and knowledge strategy through project configuration.
• **Classic Build and Workflow Scheduling ** : The writing and self-checking of the Classic plan continue to be handled by writing-plans; The main session uniformly collects execution, TDD and Review selections. When continuing the workflow in a supported host, /comet can load configured stages and preset skills.
• **Classic Superpowers Dependency Installation ** : comet init and comet update will install and update the actual Superpowers skills in use, no longer adding user-level using-superpowers startup skills, and retain the existing copies for users.
• ** Workflow Context Integration ** : Native, Classic, and workflow parsing can use the same set of bounded Personal Memory and Project Knowledge contexts, record lifecycle results, and provide context in a non-blocking manner without changing ownership of the workflow state.
• **Dashboard Memory and Knowledge Experience ** : Records, source files, Markdown/JSON/YAML previews, Provider Settings, application history, diagnostics, and project control all use compact toolbars, stable loading states, internal scrolling, full-screen and restore pop-up Windows, as well as aligned desktop layouts.
• **CodeGraph Diagnosis ** : comet init and comet doctor respectively display CLI installation, project index status, MCP registration, and the actual available capabilities of the Agent.
• **Native Status and Validation Copy ** : CLI, reports, and Dashboards use user-oriented language to describe independent validation, automatic checks, necessary confirmations, child progress, integration evidence, and next steps, while retaining stable machine status values.

​

”Fixed

• **Windows Hook Startup ** : Claude Code no longer has a brief command window when running Comet Hook Router and Classic branch binding probing on Windows, while continuing to securely retain and migrate existing managed hooks.
• **Native Supervisor Collaboration Mode ** : Supervisor Changes containing multiple independent children must explicitly select multi-session or single-session before confirmation. General confirmation will no longer skip the selection of collaboration mode.
• ** Consistency of memory and Project Knowledge ** : Fixed issues such as expired Remote configuration, content provision after source change or deletion, local index recovery, WAL processing, Provider result merging, correction of retention, permanent tombstone forgetting, duplicate management reads, and background Reflection timing.
• **Native Supervisor Recovery ** : Fixed parent Change ambiguity discovery, expired continuation, task binding protection, integrated identity verification, persistent recovery status, portable workspace projection, and final validation evidence processing.
• **Native Portable State Compatibility ** : comet status can read valid Native v4 Portable states, including large documents, pagination details, Supervisor summaries, and explicit project root routes.
• **Native Requirements and Archive Recovery ** : When the user-visible requirements Change, archive-ready Change will return the Shape and invalidate the old validation; When a workspace or Archive operation is interrupted, an executable recovery state will be retained, and unverifiable pass results will no longer be reused.
• **Windows and Cross-platform Execution ** : Common commands such as shim and concurrent snapshot, as well as workspace operations, can run stably on Windows. The packaged Dashboard and Runtime assets can also adapt to the paths and formats of different platforms.
• **Classic Workflow Recovery ** : Fixed issues such as the lack of project context in workspace preparation and parsing, failure fallback in Build plan downloading, phase Skill and Rule contract offset, and the implementation work remaining in the error phase after verification fixes.
• **Dashboard Project and Interface Status ** Fixed issues such as monorepo subdirectory discovery, expired worktree and index sources, long project name display, project selector alignment with titles, switching between empty and loaded states, duplicate reading of Project Knowledge sources, sidebar brand title cropping, source preview status, collapsed sidebar overflow, pop-up controls, and misleading Personal Memory prompts.
• **Issue Triage Rollback ** : When the Issue form area cannot be recognized, the unique repository area will be inferred based on the title and body. Ambiguous reports continue to retain manual triage markers.

​

”Removed

• ** Old Native Acceptance Ledger Chain ** : The new Native Change no longer exposes the old project scan, checkpoint, check, evidence and receipt command chain; The historical archive remains read-only.

​

”Changed

• ** Executable CodeGraph Diagnostics ** : comet init and comet doctor now respectively display the installation status of the CodeGraph CLI, whether the project index is up to date, whether the Agent has registered for MCP, and whether each detected Agent truly has effective capabilities. The latest project index no longer means that the Agent can definitely use CodeGraph.

​

”Fixed

• **Native Portable child Discovery ** : Linking child discovery in worktree no longer rejects valid Portable v4 change documents exceeding 256 KiB due to arbitrary read caps.
• **Native Archive-ready Requirement Modification ** : When Native change stops at archive-ready and waits, users can modify visible requirements or acceptance criteria and return to Shape; The old verification results and archiving authorizations will expire, but change workspace will retain them.
• ** classic skill Scheduling ** : Removed the incorrect disable-model-invocation option in the classic skill

​

Added (New

• **Grok platform support ** : comet init, comet update, comet doctor and comet uninstall now use Grok as their primary host. The Skill, rule and Hook Routers are respectively located in .grok/skills/, .grok/rules/ and .grok/hooks/comet.json; The Router recognizes --platform grok and matches Grok’s native write/search_replace tools.
• ** Native PR finish provider owned by the repository ** : The project can choose to verify PR titles, bodies, templates, and repository policies using structured repository commands; Comet still retains submission, push, remote base/head/SHA verification, reuse of existing PR, recoverable failure status, and secure worktree cleaning. For configuration methods, please refer to Native Configuration · PR End provider
• **CodeBuddy Rule Support ** : Comet will now install and refresh the Markdown workflow rules in the CodeBuddy .codebuddy/rules/ directory.
• ** On-demand Code Review ** : New /comet-review Skill has been added. Review the current Native or Classic change against the implementation diff and existing evidence, and report correctness, security, boundary, and coverage issues by priority. Keep read-only, do not advance the workflow, and do not replace Verify. For details, please refer to Code Review Mechanism
• **Fork PR Bootloader ** : Contributors who initiate PR from fork for the first time will now receive repository bootloader comments through the trusted workflow.
• **PR Template Check ** : When the PR is missing the required template paragraphs or entries, or when the list items are not fully checked, you will now receive an executable comment and a failed check.
• **Issue Triage Label ** : New issues will be automatically marked as pending triage and warehouse area labels will be assigned based on the selection of the structured issue form.

​

”Changed

• **Hook Write Release Document ** : The website now explains how to configure the corresponding hook.allow_paths directory for the protected workflow phase.
• **Native Subplan ** : The new Supervisor Change subplan retains the readable parent acceptance index, and Runtime verification still holds the complete brief and Spec acceptance matrix; The historical sub-plan files remain compatible.
• **Dashboard Product Preview ** : Full-screen preview now supports Escape off, long tables remain horizontally scrolling, table headers remain readable, and directory navigation uses a larger zoom ratio.
• **Native Requirement Sources ** : Requirement sources provided in the form of files or links are now retained in a complete overlay map in the Native brief, mapping each active executable requirement simultaneously to the target Spec and acceptance criteria; Incomplete or unavailable sources continue to block, awaiting clarification.
• **Native Validation Decision ** : Native’s awa-user continuation now allows users to accept the current result, revise the implementation, or revise requirements and acceptance criteria, while invalidating the archiving authorization of the old target cycle.
• PR Title scope : Conventional PR titles now support repository areas such as Native, Classic, Hook, Dashboard, Platform, Workflow, and Eval, including titles like feat(native): ....
• **Ambient Resume Non-Comet Skill Exemption ** : The Ambient Resume description hosted in AGENTS.md and CLAUDE.md now exempts explicitly invoked non-Comet skills and slash commands, and unrelated plugin or tool installation tasks no longer start with comet resume-probe calls. Some projects have obtained the revised description blocks through comet update.

​

”Fixed

• “Windows Initialization Reliability” : comet init is no longer interrupted with “Contained atomic write temporary file changed before commit” on file systems without stable file identifiers such as exFAT/FAT32 (such as removable disks and network disks) Installation of OpenSpec and Skills. The integrity check at the time of submission originally compared the temporary file with the pre-write snapshot, making comet’s own writes appear to be tampered with. Now it is changed to be compared with post-write snapshots, while symbolic link and directory shift detection remain unchanged.
• **Classic design handoff Refresh ** After the OpenSpec product is changed, running comet handoff <change> design --write will no longer report the expired handoff error. The design guard can pass, and the Classic complete process can be advanced from Design to Build. Even if the manually aligned hash is successfully short-circuited during refreshing, the expired context file will still be rewritten. When OpenSpec delta spec is added, changed or deleted, the context package will be regenerated. guard has advanced to the build stage and is still available after refreshing.
• “Classic Ambient Resume” : comet init and comet update now retain hosted Ambient Resume instructions for Classic-only projects when ambient_resume is enabled. Re-running these commands will no longer remove them from AGENTS.md or CLAUDE.md.
• **Classic Workspace Command Context ** : comet classic workspace prepare and comet classic workspace resolve no longer report “Classic command project context is unavailable” for all isolation modes (current, branch, worktree). Fixed the workspace preparation step of the Classic Open process.
• Native Archive : Archive now complies with Git ignore rules when temporarily storing workspace products; Effective portable verification reports are no longer regarded as incomplete migrations.
• **Windows Eval Packaging ** : Packaging no longer traverses the ignored pytest and Eval runtime products before the application package boundary. The outdated Windows test directory will no longer cause pnpm pack to fail with EPERM.
• **Windows Eval Isolation ** : Repeatedly running comet eval will no longer copy the generated .comet cache, run the product, or the Runtime state of the framework itself into the Skill workspace, avoiding nested caches and deep path MAX_PATH failures on Windows.
• **Monorepo Dashboard Workspace ** : When comet dashboard is launched from the monorepo subdirectory that holds .comet/config.yaml, this subdirectory is now used as the root of the workspace, and the sibling Git worktree is mapped to the same subdirectory; When the Comet project root is not the worktree root, the change list is no longer empty.
• **Ambient Resume In-process reply ** : The Agent acting in accordance with the installed Ambient Resume instructions no longer gets stuck on the running Comet Change after the user replies to in-process questions with short options. The managed description block now waivers responses to questions within the Comet process and clarifies that the out_of_scope result will only prevent entry into the workflow and will never interrupt an ongoing process.
• “Windows stdin and File JSON Parsing” : The Runtime command now strips the UTF-8 BOM at the beginning before parsing the JSON. Frame JSON from Windows PowerShell 5.1 redirection or Out-File (default output UTF-8 with BOM) no longer causes comet-intent.mjs route --stdin to report “Invalid JSON”. The same tolerance covers Hook payload parsing in comet-resume-probe.mjs --stdin, comet-hook-guard.mjs and Hook Router, as well as Native evidence format entries read from stdin or --entries files.
• **Classic record-check step Synchronization ** : After the Agent checks the last item of tasks.md during Build, comet state record-check no longer reports “Classic Run step mismatch”. Checking the task will advance the Run step of evidence inference without running the status command, legally leaving the recorded steps behind. Record-check now resynchronizes the Run projection (prints the [RECONCILED] currentStep ... -> ... line and appoints the trajectory transformation) before the record check, allowing the Build evidence to continue recording. The real damage - mismatch of skill identity, snapshot or migration tag - will still result in a hard failure.
• **Classic Build Plan Uninstallation ** : The planned sub-agent in Build Step 1 no longer frequently degenerates back to the main session (#345). The dispatch prompt now tells the sub-agent to skip the interactive skill step (such as the Execution Handoff question of writing-plans), and the complete plan path is fixed by the main session before dispatch. The sub-agent must end the reply with a line of PLAN_PATH: for the coordinator to read first. Children without the Skill tool will fail quickly with SKILL_UNAVAILABLE to avoid idling. The plan scope is limited to tasks.md; If the dispatch fails within the same session, subsequent Step 1 entries will be directly transferred to inline.

​

Added (New

• ** Independent Skill Evaluation Entry ** : You can directly run comet eval ./my-skill to evaluate local skills without having to create comet/eval.yaml first. For the complete usage process, please refer to Quick Start: Evaluating a Skill
• ** task Discovery and Offline Pre-checking ** : Supports inline tasks, tasks within Skill packages, and 2-4 tasks automatically generated and cached when there is no manifest; --collect only performs static discovery and configuration checks and does not start the Agent or Docker.
• ** Optional Evaluation Agent and Independent Judge** : The evaluation can choose Claude Code, Codex, Qoder or CodeBuddy, and configure the model, API address and credentials respectively for the main Agent and LLM-as-Judge.
• **Langfuse Evaluation Suite ** : comet eval --suite langfuse synchronizes task trace, rubric score, pass metrics and experiment summaries, while retaining local reports.
• “Native Supervisor Change Mode” : For large-scale requirements, the Supervisor Change pattern can be confirmed in the Shape stage. The Runtime will advance the sub-changes by dependency and verify the complete goal of the Supervisor Change on the final integration branch.
• ** Cross-Worktree Dashboard** : The Dashboard will discover the registered Git worktree. Independent changes remain as root entries, and Native Supervisor Changes can be expanded to view the status and progress of children.
• **WorkBuddy platform support ** : comet init and comet update will now install and update Comet Skill to project-level .workbuddy/skills/ or user-level ~/.workbuddy/skills/; Project-level installation will also merge Comet Hook into .workbuddy/settings.json while retaining the existing configuration.

​

”Changed

• ** Hook writing whitelist within the project ** : The project can configure the project relative directory in hook.allow_paths of .comet/config.yaml, allowing shared rules or notes to still be written during the non-coding stage of Native Shape or Classic. Comet Runtime and its own products of the workflow are still protected. The Hook itself does not intercept writes outside the project, so there is no need to configure a whitelist for the path outside the project.
• **Classic Workspace Routing ** : When creating or restoring a Classic change, it will be bound to the corresponding working directory based on the current branch and worktree, and the existing worktree will be reused when available.
• **Native Workspace Reuse ** : Native parallel Change will reuse the matching linked worktree; When a branch still exists but the worktree is missing, the recovery process will recreate it.

​

”Fixed

• **Classic Guard Project Root Path Resolution ** : Even when running from a nested working directory within the project, Classic design Guard reads the delta spec from the discovered project root directory and no longer reports that the path does not exist due to a different current working directory.

​

Added (New

• ** Independent Native Subagent Acceptance ** : After the Builder submits the implementation handover, the Runtime runs the necessary checks and dispatches a brand-new read-only Verifier to check A1 item by item… An. Builder self-reporting “completed” cannot be directly archived. The Skill coordination mode still requires a clear user confirmation before archiving.
• **Trae Hook support ** : comet init, comet update, comet doctor and comet uninstall support project-level, global Hook Router configuration for Trae and Trae CN, while retaining the user’s own Hook Settings.

​

”Changed

• ** Faster Native Verify** : Normal checks are performed only once and the completed results are reused, and the output flows into the native log; Verify will no longer scan or fingerprint the entire project, and the Archive normal path will not be re-accepted either. Long Maven, Gradle, npm or Python outputs will not render valid results invalid merely because of their length.
• ** Portable Native states ** : comet-state.yaml save phase, Loop, acceptance result, handover, blocking and next step; verification.md is a reconfigurable user report, while the local execution status and logs remain in .comet/runtime/native/.
• Native Dashboard : Native details display the Build/Verify phase, iterations, attempts, acceptance items, checks, blocks, history, and user-readable products; The machine Runtime file does not appear in the product list, and the old archive can be viewed through the read-only adapter.
• ** Clarification and Workspace Selection ** : New projects default to using Batch clarification. First, organize the problem dependencies and then ask questions. When creating a change, the current, branch, and worktree selections will be displayed, and the correct attribution will be maintained during the restoration and linking of the worktree.
• **Skill and CLI Guidelines ** : The public commands of Native and the Chinese and English skills are subject to the next step returned by the Runtime. The normal process does not require manual concatenation of internal states. The invocation strategy of the stage Skill is also more explicit.

​

”Fixed

• ** Workspace and Recovery Routing ** : Linking Worktrees, cross-device recovery, error checkout, and interrupted archives will first check the current status and will not silently reuse old pass results or route changes to another working directory.
• ** Cross-platform Native Check ** : Windows can correctly execute commands such as npm and pnpm. When a timeout occurs, the child process tree will stop, reducing platform-related Verify failures.
• **Hook and workflow isolation ** : Legacy global hooks without a trusted project context remain neutral; The Classic dedicated reference is only installed and loaded along with Classic. comet doctor can also recognize Superpowers in the plugin directory.

​

”Removed

• ** Old Native Runtime Acceptance Chain ** : The new change no longer generates the old project scan, checkpoint, check, evidence, and receipt chains. The old active changes will be conservatively migrated when necessary, and the archived old changes remain read-only.

​

”Fixed

• ** Coexistence of Classic and independent OpenSpec ** : Classic now only uses the configured product root directory, so projects that do not use Comet can still retain another OpenSpec root directory; When explicitly migrating the root directory, if the target directory is not empty, overwriting will still be refused.
• **Codex Native Hook Parsing ** : Native can now correctly identify Add, Update, Delete in the original apply_patch input, as well as the standard +++ b/... file headers, ensuring that phase protection takes effect consistently across different patch formats.

​

”Security

• ** Rely on security updates ** : Update PostCSS, Undici, and brace expansion to versions where security issues have been fixed.

​

Added (New

• ** Global Project Activation ** : The global Native or Classic default values can now activate an unconfigured project when /comet is explicitly called for the first time. The project product remains within the project, the existing workflow attribution will be retained, and project-level initialization can still be used for local overwriting.
• Native Parallel change : Before entering Shape, Native will detect active changes and can automatically create isolated Git worktrees; When safe, the current, branch and worktree options are still retained. Isolated changes will remember the starting target branch for subsequent completion.

​

”Changed

• **Dashboard change Browser ** : Dashboard now loads a lightweight change line, paginated for active, archived, and all Changes, and only acquires full details when selected; Native and Classic keep the selected detail panel stable during loading. When the detail loading fails, it can be retried to ensure that large projects remain responsive.
• **Hook Lifecycle and Routing ** : Activated projects and isolated Native Worktrees now automatically obtain a project-level Router; Setup, Update, and Doctor will migrate the historical global and legacy Comet hooks, while retaining the Hook configurations owned by the user. They will explicitly report when the cleanup is not completed instead of continuing silently.

​

”Fixed

• ** Global Native Skill Update ** : Global comet update now only refreshes the installed workflows (including Native), and does not add workflows that users have not selected.
• **Native Verify retry ** : Invalid verification reports will be rejected before the necessary check runs; When retrying, the unaltered success required check receipt will be reused to avoid unnecessary and expensive checks being repeated.
• **Native Parallel Recovery ** : Ambient Resume now only performs full recovery checks on explicitly specified, selected, or unique Native Changes, and other irrelevant active changes no longer trigger irrelevant Runtime errors.
• **Subagent Workflow Distribution ** : Classic Build directly runs the selected creative workflow; Comet Any keeps each creative lane on the specified workflow instead of replacing it based on platform-specific Agent tags.
• **Native scope Consistency ** : Native can now detect hidden files in the Git modification file view, avoiding misjudgment that the Build and Verify scopes are inconsistent and blocking verification and archiving.
• **Hook Write Processing ** : When no active Comet Change has a target, the project Hook allows normal writes; Remain neutral towards unknown or external targets (including paths redirected via symlink or junction), while still evaluating in-project writes.
• **Hook Configuration Security ** : Hook installation no longer overwrites Kiro files owned by users or leaves invalid Copilot entries; Doctor will detect outdated legacy files as well as disabled or structurally mismatched processors before reporting the health of the Router.
• **Native receipt scope Recovery ** : When the project file changes after the Build, the verification receipt stops before execution, reports the change path, and provides a command to return the Build to refresh the implementation scope.
• **Classic build Recovery ** : If the full Classic workflow does not effectively implement the plan after context recovery, it will return to the plan creation stage and prevent the project source code from being written until the plan is restored and associated.
• **Ambient Resume Cleanup ** : When Ambient Resume is disabled, Comet management commands will be removed from AGENTS.md and CLAUDE.md, while user-written content will be retained.
• Eval workspace Dockerfile : When a workspace does not have a root directory Dockerfile, the Eval image preparation now uses environment/Dockerfile. These Workspaces can be built without moving files.

​

”Fixed

• ** Incomplete project configuration ** : The comet update and Classic root directory commands will complete the missing Native default fields and accept projects where other configurations are still available.
• ** Update Scope ** : After selecting “Only Current Project”, comet update will only refresh this project. When there are no updatable index items, it will be clearly stated without modifying the global installation.
• **Classic Initialization Compatibility ** : When adding Classic to an existing Native project, the existing root directory openspec/ layout will be retained; Initialization can also be completed on file systems such as exFAT that do not support hard links.
• Codex OpenSpec Skills : The project initialization will install the OpenSpec Skills generated for Codex to the .agents/skills/ directory of its specification.
• ** Uninstallation selection and completion status ** : Project-level uninstallation adopts the same platform batch selection as initialization; Unselected platforms will be retained. The selected Superpowers package Skills will be cleared, and the contents of the user’s working directory will no longer be falsely reported as uninstallation failure. If the actual cleaning fails, the reason will be displayed and output in the selected language.

​

Added (New

• **Native Verification Receipt Refresh ** : New comet native receipt refresh <change> [--apply] has been added, which can check invalid verification receipts and regenerate manual receipts when they can be safely updated. The automatic checks that require a real re-run will be clearly listed and will not be mistakenly marked as passed.

​

”Changed

• ** Selective Workflow Uninstallation ** : The interactive comet uninstall can now choose to remove Native, Classic, or both based on the installation target. When one of them is removed, the other workflow and its shared configuration will be retained. When removing Classic, you can choose whether to clean up OpenSpec and Superpowers Skill. By default, they are retained.
• ** Daily operation response ** : CLI startup, Classic and Native workflow commands, pre-write checks, and Native snapshot updates are all faster; Native will prioritize reusing the existing results of unchanged files while continuing to check for actual changes.
• ** High-frequency Public Workflow Commands ** : High-frequency Native, Classic and workflow parsing commands maintain a stable comet CLI interface, and are internally transferred to the runtime bundle within the package; The cold start overhead can be reduced without relying on the host-specific Skill path.
• **Dashboard Workspace ** : Dashboard offers a clearer experience for project switching, searching, and changing details. When starting from the repository subdirectory, the project can be discovered, and the Classic change in legacy and docs layouts is presented next to the independent, read-only Native workspace.

​

”Fixed

• **Classic Configuration Compatibility ** : Initialization and updates can retain the directory selection of existing Classic projects and more reliably identify directories that can still be used when the configuration of old projects is incomplete.
• ** Portable workflow execution ** : Native and Classic skills now invoke the public comet CLI instead of searching for platform-specific Skill directories or invoking internal bundles. It will clearly stop when the CLI is not installed. The workflow route will still immediately load the selected Skill through the Skill tool.
• **Classic Execution Options ** : Classic now displays all the isolation and execution options supported by the workflow; After the user selects, the corresponding action is directly run. If it fails, the original error is reported and the options are no longer pre-filtered.
• **Dashboard Status Prompt ** : The verification status of Classic change is now distinguished by passed (green), failed (red), pending verification (amber), and neutral colors; Invalid ports will give a clear error before startup.

​

”Security

• **Classic Phase Protection ** : The host configuration directory and worktree no longer bypass the Classic phase restrictions, preventing hidden source code writes through paths such as .claude/ during non-build phases.
• **Dashboard Build Dependencies ** : Update the CSS build dependencies of Dashboard to fix the risk of reading unexpected mapping files through untrusted source map references.

​

”Changed

• **Classic Root Directory Migration ** : comet classic root move docs --dry-run directly reports the current status, conflicts and blocking items, and no longer generates plan ids; --apply can migrate the complete openspec/ directory without a plan ID, including active and incomplete archived changes. The output follows classic.language. Projects that have already used docs/openspec/ will obtain clear results that require no operation.
• **Native Workflow Guidance ** : Native will first identify the current change and stage, and then load the reference corresponding to the stage; Before entering the implementation, always complete the Shape classification, silent hypothesis checking and shared understanding confirmation. When new user decisions arise in the Build process, the implementation will be paused, the updated requirements will be clarified and confirmed again, and then the progress will continue. Project-level and change-level commands are organized by task to reduce information irrelevant to the current stage.
• **Native Verification and Repair ** : Automatically runs and binds the built-in necessary checks when Verify passes. Acceptance evidence can come from manual observation or project commands executed by the Runtime. Command execution supports Windows shim and clears suspected credentials before saving the summary. The Runtime deduces the repair gap from the failure evidence. There is still one time when the Agent proposes a new specific repair hypothesis during override, and a clear user decision is returned only after the override or validation budget is exhausted.

​

”Fixed

• **Classic Dashboard Location ** : When starting the Dashboard from the repository subdirectory, the project root directory will be automatically located, and the Classic change will be read by pressing classic.artifact_layout; A failed collection will display an error and no longer pretend to be an empty workspace.
• ** Explicit Comet Skill Routing ** : /comet enters only when you explicitly invoke it, or explicitly request the use of Comet without specifying Native or Classic. The entry will directly enter Native or Classic according to the project configuration, and retain the original request without re-determining whether the task is relevant or changing the workflow according to the task scale.
• ** Invalid Current change selection ** : When the current selection points to a change that no longer exists or has been archived, Comet will recheck the active change: If there are no candidates, other tasks can be handled normally. The sole candidate is only used for read-only recovery; When there are multiple candidates, you are still required to make a clear choice.
• **Native baseline Recovery Prompt ** : When the baseline is incomplete, the diagnosis will simultaneously prompt native.snapshot.max_files, total bytes and duration budget. If the file count exceeds the limit, the corresponding configuration can be directly located.

​

”Removed

• **Native Cryptography Review ** : Remove controller trust, signature identity, implementation declaration, independent review, waiver receipt and its CLI/Eval handover path. Native now only relies on complete acceptance evidence and built-in necessary checks bound to the current revision, contract, scope, snapshot and product.
• ** Redundant Native CLI input ** : Remove the comet native list alias, the --responsible and --confirmed in manual receipt, and the next --receipt, --evidence-receipt, --failure-category and --failed-check passed in by the caller. View the list using status without the name “change”, and reference the acceptance receipt in verification.md. active changes that still hold v2 receipt need to re-record the schema v3 evidence.

​

”Changed

• ** Project Configuration Default values ** : The new Classic configuration uses classic.artifact_layout: docs by default. comet update will complete the missing Native and Classic hosted fields. Write to legacy only when the openspec/ item in the root directory that needs to be retained is detected.
• ** Trigger Native audits based on risk ** : Independent audits are determined by the actual implementation scope and risk, no longer by the signature pattern at the time of change creation. Ordinary changes can start directly, but high-risk validations remain failed and closed.

​

”Removed

• **Native Creation Authorization ** : comet native new no longer requires --creation-authorization; The signed-v2 creation protocol and comet native trust authorize have been deleted.

​

Added (New

• ** Directional Platform Installation and Update ** : comet init and comet update have added --platform <platform>. When it is necessary to repair or refresh a single platform, there is no need to reprocess other platforms in the project. When this parameter is not specified, the existing automatic detection and rollback behavior will still be used.
• **CodeGraph Index Lifecycle ** : Non-interactive project initialization can explicitly select comet init --codegraph init|skip. comet doctor can distinguish between CLI missing, index missing, incomplete, expired and available states. Only authorized comet doctor --repair --yes will perform initialization, reconstruction or synchronization (#245).
• **Classic Configurable Directory Layout ** : The project can choose between the openspec/ and docs/openspec/ layouts through classic.artifact_layout: legacy|docs. comet classic root show can be used to view the current layout. There are already projects using the comet classic root move docs --dry-run and --apply secure migration products and configurations (#173).
• **Native Evidence Verification Acceptance ** : Each mandatory acceptance item must be bound to valid evidence under the current snapshot and scope. Native can separately record automatic checks, manual observations, implementation declarations, independent reviews, and approved structured exemptions; Failed, skipped, blocked, expired or incomplete overwritten evidence cannot produce a pass result. High-risk changes also require independent review (#240)

​

“Changed

• **Classic Document Directory ** : By default, newly created Classic or dual-workflow projects place OpenSpec products in docs/openspec/, which, together with docs/comet/ and docs/superpowers/, form a unified document directory. Existing projects will continue to use the current root directory openspec/ unless explicitly migrated. All Classic commands will follow the selected layout (#173).
• Native Loop : When the Verify fails, the Runtime will stably backfill the failed/missing acceptance and failure check to the Build. The implementers will repair and re-verify in batches according to the gaps. Only after the complete acceptance is passed will it be entered into the Archive. One Agent turn or code change does not represent completion. Only when the gap is reduced, the check turns green, or the evidence is completed can it be regarded as progress. After reaching the stagnation condition or failing the budget, it will stop and wait for the user’s decision (#209, #242).
• **Native Archive Confirmation ** : native.archive_confirmation: required will require a clear decision on the final archive candidate. Continue to automatically archive while maintaining the default configuration. The intermediate repair round will not trigger the archive confirmation. Choosing not to archive temporarily will also retain the current active change (#238).
• **Native Progressive Guidance ** : The Native entry prioritizes presenting the current stage, acceptance gaps, and the next action, and only loads clarifications, commands, products, and recovery details when necessary.

​

”Fixed

• **Classic Archive Reference ** : During archiving, the handoff and related product references within change will be updated to archive locations with dates, and the references will be verified before completion. After successful archiving, there is no longer a need for manual correction of .comet.yaml (#244)
• ** Auxiliary worktree Diagnosis ** : comet doctor will distinguish between current worktree assets, assets visible only to the main worktree, and available global fallback, and will no longer mistakenly report intentionally uncopied ignored files in the auxiliary worktree as damaged (#246).
• ** Local Eval Execution Environment ** : The local task image now contains the Claude Code required for evaluation and runs as a non-root user. quick and full Eval can stably identify the execution environment and start runner (#229).
• ** Local Eval Validator ** : The lightweight validator copied to the task can reliably load the attached scaffold runtime; workflow Eval only uses tasks that match the Workflow Contract. CONTROL results without Skill are retained as control data and no longer incorrectly block valid Dynamic Skill results (#229).
• **Creator Bundle Portability ** : The workflow Bundle generated by Creator uses project-specific evidence paths and platform-independent creation descriptions, and no longer declares Claude’s dedicated custom Agent as a necessary runtime capability for Codex publishing; A successful local Eval result will be written back to the evaluation evidence of the current Bundle (#229).

​

”Security

• **Native Approval Isolation ** : The approval credentials of the signature workflow are kept outside the project and the implementer, and changes within the project cannot obtain approval permissions on their own (#240).

​

Added (New

• **Sequential Clarification Evaluation ** : A new repeatable Native multi-round evaluation has been added to check whether Sequential first investigates repository facts, resolves interdependent issues that should be decided by the user one by one, records each answer, confirms complete shared understanding before entering the Build, and completes the verified implementation. The response sequence defined by the task enables each decision path to be reproducible, no longer allowing simulated users to supplement their choices on their own.
• comet native evidence format : A new command has been added that can serialize acceptance evidence entries into the standard Markdown blocks required by verification.md. Users no longer need to manually adjust the evidence format, nor will they trigger incorrect “canonical serialization” rejections due to byte-level format differences.

​

”Changed

• **Native Clarification Mode ** : Sequential now recalculates the remaining user-visible decisions after each response, presenting only one upstream decision in each round and explaining the recommendation and impact. Batch will maintain the decision tree of the user-visible results based on the pre-order relationship, and ask the entire ready frontier in each round; When supporting parallel capabilities, environmental fact-finding will not block other issues that are already in place. Both modes require that each behavior in the final shared understanding summary be traceable and be explicitly confirmed by the Runtime before entering the Build. The old implicit change must also be confirmed before leaving the Build.

​

”Fixed

• ** Native baseline for Large Repositories ** : Native content snapshots now support binding to the include/exclude policy of the baseline, as well as the number of configurable files, total bytes, and execution time budget in .comet/config.yaml; The default total budget is 256 MiB, and there is no longer an independent 5 MiB single-file upper limit. The Runtime continues to use the streaming SHA-256 hash of the real workspace content, records the actual policies and constraints for auditing, and provides an executable configuration fix method when the complete baseline cannot be obtained (#226).
• ** global Workflow Selection ** : comet init now provides Native, Classic, or both during global installation and accepts --scope global --workflow native|classic|both; The global Skill installation thus provides the same workflow options as the project level. The non-interactive global installation without explicitly specifying the workflow still defaults to using Classic (#234])
• ** Explicitly invoke Comet Skill** : The Ambient Resume project directive now prioritizes manual Comet Skill calls recognized by the host over recovery probing, avoiding the situation when there is no active change at present. If the result of none or out_of_scope is incorrect, skip /comet (#235).
• **Classic Archive Final Status ** : Classic now confirms immediate remote delivery before irreversible archiving, writes branch_status: handled before unique archive submission, and only pushes this complete submission once. After successful archiving, no unsubmitted .comet.yaml will be left behind, and the remote archiving status will not remain at pending (#237)
• ** Plugin Market Superpowers Detection ** : When a regular file appears in the location that should be the marketplace directory in ~/.claude/plugins/cache/ (or the corresponding Codex path), comet init will no longer crash due to the ENOTDIR error.

​

”Security

• ** Anti-race file reading ** When reading .comet/current-change.json (used every time the Hook Router is called, comet doctor and comet resume-probe are used), the Native lock file and the comet native evidence format --entries input, non-ordinary files are now rejected before opening, and the file identity is verified to remain unchanged after opening and reading. Replacing a file with a symbolic link in the middle of the process will cause the read to fail without revealing the content of the link target. Locking the FIFO on the path no longer causes the process to suspend. When Windows lacks O_NOFOLLOW, it will obtain equivalent protection through the same file identity check.

​

”Fixed

• **Windows Native File Verification ** : When the availability of Windows path metadata and file handle metadata for device or inode identifiers is inconsistent, comet status, comet doctor, and other Native reads no longer mistakenly report stable files as changed while opening. The detection of changes during file replacement and writing remains.

​

”Security

• ** Development Dependency Hardening ** : npm and pnpm dependency resolution are uniformly locked to the fixed brace-expansion 5.0.7 to prevent malicious brace mode from causing exponential CPU consumption in the development toolchain.
• **Classic handoff Validation ** : At runtime, precise line matching is used to validate the recorded handoff source paths instead of treating the spec directory names controllable by the project as regular expressions to prevent the Classic design guard from crashing or being blocked for a long time due to abnormal directory names.

​

Added (New

• **Comet Native Workflow ** : Added an independent /comet-native workflow that does not rely on OpenSpec, Superpowers, or other external skills. It uses four stages: Shape, Build, Verify, and Archive, and supports recoverable checkpoints, complete target specifications, and independent change states. By default, sequential is used for requirement clarification, and only one most upstream issue is processed in each round. You can also switch to batch to answer all the current independent questions at once. See Native Workflow ] and Native Quick Start ]
• **Native and Classic Real Evaluation ** : The two workflows use the same **16 business tasks , with each task repeated 3 times, for a total of 96 runs . Native ‘s strict pass@1 is 95.83%, Classic’ s 89.58%; The pass@3 of both is 100%, the pass^3 of Native is 87.5%, and that of Classic is 75%. The average model time consumption for Native correction is 47.8% lower. Among the 41 pairs of samples that were strictly approved by both sides, Native had 76.8% fewer total tokens and 75.1% lower model costs. The time-consuming data comes from different operation periods and is therefore only used as directional evidence. See the complete comparison report ](https://docs.comet.rpamis.com/en/eval/comet-native-vs-040-experiment).
• **Native Clarification Mode Evaluation ** : On the same task, run Batch and Sequential 10 times each **. The average number of outer interaction rounds of the Batch has decreased from 4.5 to 2.7 (a reduction of 40%). The average cumulative model time consumption dropped from 712 seconds to 617 seconds (a reduction of 13.3%). But Batch ‘s strict pass@1 is 60%, lower than Sequential’ s 70%. This is a single-task small sample, indicating that there is a trade-off between efficiency and reliability between the two modes. It cannot be concluded that Batch is more reliable based on this. See Clarification Mode Evaluation
• ** Optional Eval suite** : comet eval --suite local|langsmith can choose either local or LangSmith evaluation. “Local” remains the default value; LangSmith uses the same set of tasks and scoring logic, and automatically selects tracing runner, report directory, and Claude Code tracing plugin.

​

”Changed

• ** Project Workflow Selection ** : Project-level comet init now offers three options: Native, Classic, and Both. By default, new projects allow /comet to enter Native, and Native products are written to docs/comet/ by default. Both will install two independent workflows, but will not mix their changes, states, and products.
• ** Separation of Entry, status and Recovery ** : /comet-native and /comet-classic are fixed entry points, and /comet only selects one of them according to the project configuration. comet status, comet resume-probe and Dashboard will respectively display and restore Native, Classic and unmanaged OpenSpec changes. Dual workflow projects will not repeatedly intercept the same write.
• **Native Execution and Recovery Boundary ** : Native records the complete project baseline before starting modifications and binds the implementation scope, acceptance conditions, and verification reports to change. When the snapshot is incomplete, it will not be inferred that the file has been deleted. When verification fails consecutively and there is no real code progress, retry will be stopped. After an interruption, the status can be restored, archived, and the product roots can be moved.
• **Node.js Runtime requirements ** : Beta 7 requires Node.js 22 or a higher version. Please confirm the Node.js versions for your local, CI and Docker environments before upgrading.
• ** Update commands no longer implicitly upgrade npm packages ** : When comet update is running in the current project, only the project assets hosted by Comet are refreshed. When the CLI needs to be updated simultaneously, use comet update --self-update. The update will verify the complete pre-release version, reject downgrading, and attempt to restore the original version when installation fails. The configuration of Classic will be migrated to the classic: block of .comet/config.yaml, and the existing explicit configuration will be retained.

​

”Fixed

• ** Initialization and Update Results ** : comet init and comet update return non-zero exit codes when the work is not fully completed, and retain the npm diagnosis. Batch updates distinguish between failed projects and those that have not been attempted. The success banner will no longer be displayed after the component fails.
• **OpenSpec Version Diagnosis ** : If the installed OpenSpec CLI version is too old and you have not chosen to upgrade, the initialization will directly indicate that the version does not meet the requirements and will no longer falsely report as CLI unavailable.
• Windows and Parallel Eval : Windows Docker interaction evaluation prioritized the use of Git Bash, retained the prompt paths within the container, and counted based on the real driver turn. Parallel workers will wait for the shared Docker build lock and no longer mistakenly report normal concurrency as a resource deadlock.

​

Added (New

• comet state rebind : After the user explicitly confirms that the current branch should take over the change, a new command can be used to rebind the working branch and record the audit event. Execution will be refused when the first binding has not been established or when it is in a detached HEAD.

​

”Changed

• ** Workspace Branch Binding ** : The three isolation methods of current, branch, and worktree will all record the Git branch at the time of creation. Subsequent branch switching will be blocked by the build, verify, archive entry checks and the source code write guard. The change that selects drift will also fail and will not silently overwrite the binding. The old change will complete the binding at the next select or check, and non-Git worktree projects are not affected.
• ** Workspace Isolation Selection ** : full, hotfix, and tweak will all allow users to explicitly choose to continue using the current branch, create a new branch, or create a worktree, without silently making decisions for users. full workflow now also supports isolation: current (#190).
• ** Status and Archive Prompt ** : The text and JSON output of comet status will display the isolation method and bound branch; When current isolates and archives, it only asks whether to push the current branch or keep it local, and no longer provides merge /PR options for functional branches.

​

”Fixed

• **Skill Discovery Fault Tolerance ** : YAML frontmatter format errors that are not related to the local Skill no longer interrupt the Bundle Factory guidance or candidate discovery. Comet will skip the corrupted description and continue scanning.

​

”Changed

• **Skill Triggering and Decision Creation ** : The built-in stage Skill and the internal Node Skill generated by Creator clearly define the entry and Runtime boundaries; Creator distinguishes between automatic processing, stop conditions, and manual handovers before generating pause points, reducing unnecessary internal Skill calls and user inquiries.
• ** Workflow checkpoint** : Clear requests skip redundant named confirmations; Build pre-check the executable capability and merge adjacent configuration decisions; Large PRDS use recoverable batch manifesters to restore conversation states that no longer rely on unwritten disks.
• ** Verification of repair and archive ownership ** : Automatically return to Build when the first three executable verifications fail, and save the number of consecutive failures across the recovery period. Verify only records evidence, and Archive only submits the attribution path before branch processing to ensure that the final branch contains specifications and archive metadata.
• **Preset Execution Semantics ** : Hotfix/Tweak will truthfully record the current workspace isolation. The direct mode still retains the regression test. After upgrading the complete workflow, the lightweight execution Settings will be cleared.
• **Dashboard Product Preview ** : Markdown preview supports tables, references, task lists, syntax highlighting, and Mermaid; Full-screen directories, duplicate title anchors, long path copying, and YAML/JSON structured tables are also uniformly processed.

​

”Fixed

• **OpenSpec Compatibility ** : OpenSpec 1.5+ is required, and /comet-open is driven from live schema to verify the relative paths and specific outputs of the items. When restoring split batches, the completed changes are not rebuilt.
• **Codex Hook Configuration ** : Project-level and global Codex installations write to supported .codex/hooks.json and safely migrate the old Comet management configuration (#199).
• ** Standard Superpowers Products ** : The Classic write guard accepts the first design, planning, and verification products in the standard directory, while retaining phase, selection, and repeat placeholder checks.
• **Skill Lifecycle Integrity ** : Initialization, update, Doctor, and uninstallation will consistently report Skill, Rule, and Hook failures, retain damaged user Hook configurations, and prevent partial installations from being registered as successful.

​

”Security

• **Dashboard Preview XSS Protection ** : Markdown/YAML/JSON preview uses DOMPurify to prevent dangerous URL and attribute injection; Mermaid uses a strict security mode to prevent untrusted products from executing scripts.

​

Added (New

• ** Natural Language Recovery Detection ** : New low-noise recovery detection mechanism and project description. When continuing to process existing work, even without explicitly inputting /comet, the Agent can first detect whether the current request is suitable for restoring the active workflow. Confirmation will still be suspended when there is ambiguity, no changes have been submitted, or when user decision-making is required.
• ** Project Installation Index ** : Project-level installations will be registered in the user-level index. The interactive comet update and comet uninstall can be selected between the current project and all registered projects. --json or explicit --current-project will limit the current project, and comet uninstall --force will also maintain the current project. For cross-project operations, explicit use of --all-projects is required.
• ** Stable Classic Commands ** : New top-level comet state, comet guard, comet handoff and comet archive commands have been added. Agents and automation no longer need to rely on the internal script paths in the installation directory (#186).
• ** Custom Project Command Evidence ** : For projects that cannot automatically infer npm, Maven, or Cargo commands, the actual executed build/verify commands and exit results can now be recorded to form auditable evidence, without having to use undocumented skip paths (#192).
• **CodeBuddy Hook Support ** : The project-level and global installation of CodeBuddy Code will now non-destructively merge Comet PreToolUse hook into .codebuddy/settings.json, retaining users’ existing plugins, Settings, and hooks; When the configuration is invalid, the original file will remain unchanged and a failure will be explicitly reported (#193](https://github.com/rpamis/comet/issues/193))

​

“Changed

• ** Hybrid change Status ** : comet status now distinguishes Comet-managed changes from regular OpenSpec changes and only recommends corresponding archive commands for ready entries (#187).

​

”Fixed

• ** Parallel active change Guard ** : When multiple changes are active simultaneously, source code writes are bound to the explicitly selected current change. Legal build work is no longer mistakenly blocked by another change in open, design, or archive. When the selection is not clear, an executable selection prompt will be given (#196).
• **Codex CLI Skill Discovery Path ** : The project-level and global installation of Codex now places Comet Skill in the current .agents/skills discovery directory, while the Codex-specific configuration remains in .codex. Updates and uninstallations will migrate the old .codex/skills content managed by Comet and retain irrelevant skills.
• “Generative Eval manifest” : comet eval resolves the draftHash placeholder value in the Skill Factory manifest to the current version binding value at runtime. Therefore, the product of /comet-any can be directly evaluated without rewriting the generated Bundle file (#183).
• **Eval harness Location ** : The comet eval installed via npm now uses the same version of the harness distributed with the package by default, and reports “harness missing” and “uv unavailable” separately to facilitate accurate location of environmental issues.
• ** Cross-project update result ** : comet update --all-projects will count the failure of npm package update as the failure result of the corresponding project; When the project index is unreadable, it will clearly fail and the problem will no longer be reported as a success or an empty index.
• **Dashboard Responsive Workspace ** : When comet dashboard displays the left navigation, it keeps the change workspace within the viewport. Opening artifact preview will retain the scrolling position, and archived changes will be directly displayed as completed status (#170).
• ** Symbolic link installation of existing Skill directories ** : comet init and comet update --install-mode symlink will retain the existing skills/ directories of the platform and only link to the skills managed by Comet. Local or third-party skills will no longer cause installation failures (#171).
• **OpenSpec CLI Installation Scope ** : Even if project-level Comet installation is chosen, comet init will install or upgrade OpenSpec CLI as a global tool and will no longer create node_modules/ (#175) in the project due to this choice.
• ** Archived Dashboard Product ** : The Dashboard will correctly return from the archived change to the project root resolution path docs/superpowers/. The archived design, plan, and verification reports can still be viewed (#176).
• ** Final Confirmation of Archiving ** : /comet-archive will record the user’s final approval in the Classic status of machine management; Before confirming the success of transition, the real archive command refuses to be modified to avoid directly calling the script to bypass the confirmation.
• ** Archive Comment Format ** : Classic archive comments will retain the normal end of the Markdown file and can be safely repeated to avoid git diff --check format errors (#185)
• ** Global Product Language ** : The global comet init and comet update will save the selected product language to ~/.comet/config.yaml. Classic workflow prioritizes reading the project configuration and then reverts to the global default. The project can still override this setting (#174).

​

”Fixed

• **Doctor scope Diagnosis ** : comet doctor now reports auto scope behavior and Node/ platform environment information; When a global Comet installation is available but the current project does not have a local copy of the Skill, a non-intrusive project-level prompt will be given to allow users to distinguish between “project-level installation optional” and “installation damaged”.
• **PowerShell Initialization Output ** : comet-state.mjs init now writes the successful initialization information to stdout. Windows PowerShell no longer mistakenly reports the successful creation of .comet.yaml as NativeCommandError (#167]).
• ** Version Short Parameter ** : comet -v is now equivalent to comet --version, which conforms to common CLI habits (#167).
• **Classic runtime Safety Net ** : The Classic stage script now retains the embedded runtime package as a safety net. Even if a platform installation lacks the internal runtime/classic asset, the comet-guard.mjs, handoff, and archive processes can still run (#168](https://github.com/rpamis/comet/issues/168)).
• ** Project Configuration Lookup ** : Classic guard now only reads the default configuration of the project from .comet/config.yaml; The workflow status still belongs only to each change’s .comet.yaml. The root directory .comet.yaml/comet.yaml no longer participates in configuration or status resolution (#158).

​

”Removed

• ** Custom guard Command Field ** : The Classic workflow status no longer accepts build_command and verify_command. guard is changed to use built-in items to build probe paths, and old fields will be rejected as unknown fields.

​

”Fixed

• ** Single-language rule Installation ** : comet init and comet update now only install Comet stage guard rule files that match the selected/detected Skill language (such as .claude/rules/comet-phase-guard.md), and no longer install both Chinese and English rule variants simultaneously regardless of language selection.
• ** Symbolic Link Installation Security ** In the symbolic link installation mode of comet init and comet update, if the skills/ directory of the target platform contains files outside the Comet management list, the directory will now be refused to be replaced with symbolic links to avoid deleting local or third-party skills (#159)
• “Parallel change product writing” : The Classic stage guard now writes docs/superpowers/ to the matching design/build/verify change, no longer blocking the shared Design Doc and planned product (#160) due to another earlier created active change.

​

Key changes

• ** Pure Node Runtime ** : All Comet scripts run through Node.js, and the same set of commands is used on macOS, Linux, and Windows, eliminating the need for Bash, Git Bash, or WSL.
• /comet-any Skill Creator : Upgraded from “generating a SKILL.md” to generating stable combined Skill Bundles with reviewable creation content, release evidence chains, and platform-native files.
• **comet eval Evaluation System ** : Quantifies the quality of any local Skill and Comet workflows, including pass@k/pass^k reliability metrics and HTML reports.
• ** Configured Product Language ** : comet init now records project-level product languages, and OpenSpec and Superpowers products are output according to the configured language.
• comet dashboard : Local read-only browser panel, visualizing the stage, product, task and risk of each change.
• ** Routing Context ** : /comet uses a structured routing context for interpretable routing, with risk signals taking precedence over verbal processes.

​

Added (New

• ** Cross-platform Classic Runtime ** : The /comet workflow script distributed with the package is now running through the Node .mjs launcher, backed by the TypeScript Classic runtime. The same workflow runs on Windows, macOS and Linux, eliminating the need for Git Bash, WSL or scripts compatible with the shell.
• comet dashboard : Added a local read-only browser panel that displays ongoing and archived changes, including stage progress, product groups, task progress, verify status, next steps, risk signals, Git context, product previews with metadata, and light/dark UIs. --json, --port, --no-open and GET /api/dashboard expose the same snapshot to the script and CI.
• /comet-any Skill Creator : Add the main process for creating or upgrading reusable skills. The process covers candidate discoveries, confirmed solutions, generated Skill Bundles, creation decision/guidance areas, creation lanes, evaluation readiness of the current draft, review approval, release, distribution, and platform-native documents such as Claude Code custom agents.
• Skill Creator CLI : New comet creator for regular creation/recovery guidance, comet publish for review, approval, release and distribution preview, and the backend Bundle command is retained as an advanced tool.
• ** Local Skill Tool ** : New comet skill add|show|run|continue|check has been added, which is used for installing, inspecting, running, restoring and deterministically verifying local Skill packages (with snapshots).
• “comet eval harness” : New local warehouse assessment has been added, supporting Comet workflow and any local Skill. Including task profile, generated manifest, HTML report, token/cost attribution, pass@k/pass^k reliability metrics, workflow-specific scoring, Skill call evidence checking, configurable simulator prompt words, Anthropic Compatible with proxy authentication, Windows/WSL friendly execution, UTF-8 logging and regression access control.
• **Comet workflow Evaluation Task ** The built-in Comet workflow benchmark has been expanded to 20 tasks New features include dependency-confusion, layered streaming, persistence, approval, noise-resistance, cross-file refactor, and observability Scenarios such as config, graph execution review, agent memory routing, and framework selection are used to compare CONTROL, 0.3.9, and 0.4.0 more stably.
• **Hotfix/tweak Range Decision ** : Add qualitative upgrade signals for hotfix and tweak workflows; The file quantity threshold will now be paused and users are asked to confirm whether to upgrade to the full workflow (#121).
• ** Supported Platforms ** : New support for ZCode, MimoCode, Trae CN and Antigravity 2.0 has been added. Antigravity 2.0 is globally installed in ~/.gemini/config/skills/; ZCode and MimoCode use OpenCode compatible layouts. Trae CN uses .trae-cn/skills.
• ** Symbolic Link Installation Mode ** : comet init and comet update can now choose to install Skill using copy or symbolic link /junction (from the shared .comet/skills/ storage).
• ** Project Skill Preference ** : New .comet/skill-preferences.yaml has been added, allowing projects to boot with preferred Skill, sorting, and Skill Creator schemes without having to manually modify bundle files.
• ** Configured Product Language ** : comet init now writes the project-level product language (en or zh-CN) to .comet/config.yaml. Each new change will snapshot this language to .comet.yaml. OpenSpec and Superpowers products output according to the configuration language and no longer make temporary judgments based on triggered requests. Comet guard will reject workflow products with obvious main language mismatch, fail closed for invalid language, and ignore fenced code blocks to avoid command, path or hash interference in judgment.

​

”Changed

• **Comet Product Positioning ** : README, CLI help, and Skill guidance now present Comet as a workflow and Skill platform: run guided workflows, create skills, evaluate them, publish them, and diagnose stuck changes.
• **Comet Skill Language Instructions ** : The Chinese and English Comet Skill now reads the configured product language (only en/zh-CN, aliases not accepted), and thereby constrases OpenSpec prompt, Superpowers parameters, subagent scheduling, verification reports, and archiving descriptions.
• Eval judge provider : LLM-as-judge must now explicitly set BENCH_JUDGE_MODEL and use the separate BENCH_JUDGE_* provider configuration; When configuring judge endpoint and credentials, Anthropic compatible HTTP should be prioritized. When the configuration is incomplete, report skipped and no longer silently reuse the model under test, endpoint, or credentials.
• “LangSmith eval Configuration” : LangSmith eval now derives Claude Code tracing plugin Settings from the main LANGSMITH_* configuration. The trace remains in the base project of the configuration, and the hook logs are saved to artifacts. And the official Claude Code tracing plugin can be automatically built to eval cache as needed.
• **Eval Comparison Report ** : The report now distinguishes raw, analysis-set, flagged, excluded runs; Take CONTROL as the business-only baseline; pass@k/pass^k for splitting overall, business, workflow; And output the thesis style in Markdown/HTML, including metric descriptions, rubric dimension descriptions, evidence, failure attribution, centered tables, Chinese-English switching, Python-first charts, and inline SVG fallback.
• “README eval Evidence” : README now directly presents the baseline graph of the paper style for pass@5/pass^5 and the core rubric/judge metric, allowing the comparison of no-Comet, 0.3.9, and 0.4.0 to be seen without opening the full report.
• **README Formatting Strategy ** : The root README file is excluded from Prettier checks to prevent the formatter from rewriting user-visible prose and precise document wording.
• **Classic Workflow Status ** : The machine-managed operation checkpoint is moved from .comet.yaml to .comet/run-state.json, while the user-editable workflow fields remain YAML readable. The Classic phase transition is now also written to .comet/state-events.jsonl, forming an auditable state history.
• **Classic Runtime Packaging ** : The Classic control metadata is now placed under comet/runtime/classic, and the command launcher is split into independent Node bundles (comet-state.mjs, comet-guard.mjs, comet-archive.mjs, etc.) while maintaining the existing /comet* command behavior unchanged.
• ** Workflow Diagnosis ** : comet status and comet doctor now share the same runtime evidence path, reporting the current step, runtime mode, malformation status, missing evidence, and recommended recovery actions.
• ** Workflow Routing ** : /comet now uses an explicit routing context model for full, hotfix, tweak, resume, and ambiguous requests. /comet-tweak is now the OpenSpec action path dedicated to tweak, while the complete /comet still follows the design/plan/build path of Superpowers.
• ** Review Workflow ** : review_mode Now defaults to standard for the full workflow. off, standard, and thorough form a clearer review gradient, with Comet taking over the review distribution strategy. Users do not have to pay for the overlapping Superpowers and Comet review cycles.
• ** Interactive Decision Point ** : Comet decision points now prioritize the use of Claude Code’s structured question UI when available, and downgrade to text on other platforms.
• ** Debug Workflow ** : Debug Gate can investigate independent failure groups in parallel before applying fixes serially according to the configured review flow.
• ** Repository Layout ** : The source code is moved into app/, domains/, platform/ and scripts/, and the tests are moved to the corresponding root directories of test/app/, test/domains/, test/platform/, test/scripts/ and test/repository/, making the boundaries of contributors’ responsibilities clearer.

​

”Fixed

• **Windows Path Handling ** : Fixed the path reference of OpenSpec init/update to directories with Spaces on Windows. comet init no longer fails due to project paths containing Spaces.
• **Git Submodule Script Lookup ** : When the agent works within a Git submodule, Comet hook and runtime script parsing now use the root of the project where it is located, and edits within the submodule no longer fail because .claude/skills/comet/scripts/* only exists at the parent project level (#136).
• **Superpowers Workspace Write ** The Comet phase write guard now allows Superpowers to write to the .superpowers/ workspace during the protected phase, no longer misdiagnosing Superpowers progress files as blocked source code edits (#154])
• **Doctor Diagnosis ** : comet doctor now provides clearer version, project/global scope, malformation status, missing evidence, and recovery guidance, allowing users to distinguish between “truly missing project installation” and “valid global installation”, and understand the current status issue of .comet.yaml (#135).
• ** Review Mode consistency ** : English, Chinese, shared rules, and recovery guidelines are now in agreement for review_mode. The installed Skill no longer describes an old dual review process (#126) that conflicts with the runtime guard/state check.
• ** Project Configuration Merge for init/update ** : comet init and comet update are now performing field-level merge on the existing .comet/config.yaml. Retain existing user values, complete missing management fields, refresh comments, and retain additional user fields; The damaged YAML gracefully rolls back to all defaults.
• **init Result Summary ** : comet init now exclude any platforms with failed components from the Installed list and name the failed components. Platforms such as OpenCode will no longer be displayed as both installed and failed simultaneously (#128)
• **.husky/pre-commit Executable bit ** : Fixed the issue where pre-commit hook files were committed in non-executable mode; Previously, after cloning or checkout, Git would silently skip the hook, causing the format:check/lint-staged automation to fail. Now distributed as executable bits.

​

”Removed

• ** Bash-first Classic Scripts ** : The requirement that Classic workflow scripts distributed with packages must run through Bash-compatible shell scripts has been removed.

​

”Security

• “Dependabot Dependency Alert” : Pin the test tool to the patched Vite and esbuild versions (overwriting npm and pnpm lockfile), and clear the unresolved Vite path traversal, launch-editor, and esbuild dev-server alerts. And it does not change the Comet runtime dependencies.

​

Added

• CLI i18n shared module: Extract the translation table at initialization to src/commands/i18n.ts, enabling init, update, and future commands to consistently share English strings and eliminate duplicate command-level translation tables.
• Optional npm dependency prompts in init/update: comet init and comet update now offer optional multiple-choice prompts for OpenSpec CLI, Superpowers (via npx skills add), and CodeGraph CLI. Items that have not been detected on the system are checked by default. Installed items are not selected by default, allowing users to decide for themselves whether to upgrade. The Superpowers option will also recommend installing v6.0.0+ (with a speed increase of approximately 2 times and a token reduction of about 50%).
• --language option for comet init: Added CLI flags (en/zh) to select skill languages in a non-interactive manner, consistent with the existing comet update --language options (#109).
• review_mode field for code review control: In .comet.yaml, add the field review_mode (off/standard/thorough) to control the automatic code review during the build and verify phases. comet-build requires the user to select before execution. comet-verify and sub-agent scheduling adjust behaviors according to the pattern; comet-hotfix defaults to off. Verified by comet-state.sh, comet-guard.sh and comet-yaml-validate.sh.
• Project-level review mode defaults: .comet/config.yaml can now be set to review_mode: off|standard|thorough. This value will be snapshots into the new full workflow change, allowing the team to select the default value for the automatic review of the project scope while retaining the existing change-by-change state behavior. The newly generated configuration file contains enumeration comments for context_compression, review_mode and auto_transition, allowing users to adjust the supported values without referring to the documentation.
• Uninstall by platform selection: comet uninstall now displays a checkbox prompt when multiple platforms are detected, allowing users to uninstall only the selected platforms. For single-target scenarios, use simple yes/no confirmation. The --force and --json logos retain all existing one-time removal behaviors.
• Codex plugin-installed Superpowers detection: comet init can now detect Superpowers that have been installed through the Codex plugin cache (~/.codex/plugins/cache/...) to prevent reinstallation - parallel to the existing Claude Code and OpenCode plugin detection (#115).

​

Changed

• Tagline rebrand: Change the Comet slogan in the comet init banner and the package.json/CLI --description from “OpenSpec + Superpowers dual-star development workflow” to “Agent” “Skill Harness Phase-Guarded Automation From Idea To Archive” Locate Comet based on core values (the agent skill framework for stage guarding) rather than underlying OpenSpec + Superpowers dependencies.
• Change name confirmation as a blocking decision point: comet-open SKILL.md (Chinese and English) now adds a dedicated Step 1c, which pauses before openspec new change to confirm the change name. The agent must derive 2-3 kebab-case English candidate names from the clarification summary and always provide custom input options. And warn that Chinese (or any non-Kebab-case) input will be converted to the compliant kebab-case English name and echo with confirmation - to prevent the agent from automatically generating non-compliant Chinese change names.
• Non-ASCII change name prevention: Explicit ASCII check rules have been added to comet-open SKILL.md (in both Chinese and English) to prevent agents from automatically generating non-compliant change names containing Chinese, Japanese, Korean characters, Spaces, or special characters. The agent must now request a name that conforms to ASCII from the user.
• Chinese gate-term normalization: Updated the wording of the Chinese Comet to avoid directly translating gate as “gate” : Design Step 1e now uses “Active Context Compression”, the shared debugging guidelines now use “Exception Debugging Protocol”, and CLAUDE.md/AGENTS.md now defines it as the standard Chinese translation rule for future skill editing.
• Full i18n coverage for CLI prompts: Expand the translation coverage from only init to also cover update (banner, npm update progress, skill copy progress, summary, codegraph prompts). All user-oriented strings now have both English and Chinese variants (#109).

​

Fixed

• Phase-skip enforcement across all guard layers: Fixed the issue where the agent jumped directly from open to build (skipping design) without being detected. comet-state.sh now mandates evidence at each forward conversion; Direct set phase was blocked (with COMET_FORCE_PHASE=1 escape exits). comet-hook-guard.sh prevents source code writing when design_doc is null. The comet-phase-guard rule has added a self-consistency check for stage entry points, requiring that there be a prerequisite product before writing the source code.
• Hook guard cross-change false positives: Fixed the issue where comet-hook-guard.sh caused the phase of one change to wrongly prevent writing to another change. The operations written to openspec/changes/<name>/ are now controlled by the .comet.yaml phase of the change itself, and each change is independently determined. This covers the two situations that previously prevented the new change product from being written: (1) An old change marked as archived: true but not physically moved to the archive/ subdirectory, and (2) An old change stuck at the archive stage and archived: false (where the archiving script has not yet been run). In addition, the new change directory of .comet.yaml that does not yet exist (during the period of /comet-open, the product was written before the state file) is regarded as open, so the write of proposal/design/tasks/specs is allowed.
• CodeGraph setup detection: Fixed the issue where comet init and comet update would still prompt for CodeGraph setup even if the project already had the .codegraph/ index. The existing project index now skips the optional CodeGraph prompt and installation steps, and the CodeGraph CLI parsing can use the pnpm global binary file and then roll back to the npm global installation.
• Phase guard auto-transition handoff: Fixed the issue where the injected Comet phase guard rule hard-coded the next skill after guard --apply, which might bypass auto_transition: false. This rule now delegates the post-guard handover to comet-state next <change-name> and follows NEXT: auto|manual|done, thereby respecting the boundaries of the manual phase.
• Executable permission loss on macOS after update: All shell scripts under bin/comet.js and assets/skills/comet/scripts/ were previously committed in git mode 100644 (unexecutable). After the npm update, macOS users lost the execution permission of the comet CLI entry point. All 8 files have been changed to 100755 in git to ensure that the npm installation always retains the executable bit.

​

Tests

• Phase-skip enforcement coverage: Added shell script testing Cover the reinforced guard layer - block open-complete when open products are missing, block/allow design-complete based on whether design_doc exists, block archived before verify_result: pass, block direct set phase while allowing COMET_FORCE_PHASE escape exits And when design_doc is null, the source code writing of build for full workflow is blocked, while still allowing the preset workflow and full workflow with valid design_doc.
• Project review mode default coverage: The regression test coverage from review_mode snapshots in .comet/config.yaml to full workflow change, the rejection of invalid project review modes, and the enumeration comments in the generated project configuration file have been added.
• CodeGraph setup coverage: Added regression testing for existing .codegraph/ index detection, skipping redundant CodeGraph installations, pnpm global CLI parsing, and suppressing CodeGraph prompts during updates when the project index already exists.
• Phase guard handoff coverage: A new skill rule regression coverage test has been added to ensure that phase guards are delegated to comet-state next and no longer embed fixed next skill mappings that might ignore auto_transition.
• review_mode integration coverage: Added regression testing to verify that review_mode has the correct specific pattern behavior in comet-build/comet-verify/comet-hotfix across the state, guards, and checksum scripts.
• Uninstall platform selection coverage: Added tests for single-target auto-selection, multi-target checkbox selection, user cancellation, --force skip, --json output, and target not found processing.

​

Added

• Kimi Code CLI support: Kimi Code has been added as the 29th supported platform Including project/global skill installation under .kimi-code/, OpenSpec’s kimi tool integration, Superpowers’ kimi-code-cli mapping, detection, documentation, and cross-platform regression test coverage (#90)
• Version info and update check: comet init and comet update now display the currently installed Comet version at the beginning of the command output and check if there is an updated version in the npm registry. If there are available updates, users will see an upgrade prompt. If it is already the latest version, a confirmation message will be displayed. If the registry cannot be accessed, silently skip the check without reporting an error (#99).
• Official registry enforcement for update: comet update now passes --registry https://registry.npmjs.org to npm when updating the @rpamis/comet package, ensuring that it is always pulled from the official npm registry regardless of the user’s local .npmrc or image configuration. Other packages continue to use the user’s normal registry Settings. If the official registry is inaccessible, a clear error message will be displayed indicating a registry issue (#100).
• Subagent dispatch Comet extensions: Rewrite the inline sub-agent scheduling protocol in comet-build/SKILL.md to comet/reference/subagent-dispatch.md (in both Chinese and English) as a Comet-specific extension superimposed on the Superpowers subagent-driven-development skill. This skill provides the core scheduling loop; The Comet extension adds true background scheduling, persistent task-by-task checkpoints (subagent-progress.md), source code execution only by the coordinator, TDD by the background agent, bounded reverse-fix rounds (up to 3 rounds), continuous task execution without pauses, and precise context recovery from the checkpoint phase.
• task-checkoff subcommand: Added comet-state task-checkoff <file> <task-text> to verify whether a specific task is uniquely selected in a markdown file. The sub-agent scheduling protocol conducts targeted completion verification after the dual review is passed. It includes path traversal protection, CRLF processing and exact match verification.
• comet uninstall command: A new comet uninstall [path] CLI command has been added, which can safely remove Comet’s skills, rules, and hooks distributed to all 29 supported AI coding platforms. Supports --scope (project/global), --force (skip confirmation), and --json output. Automatically detect installed targets, remove only Comet-managed products, while retaining user-defined hooks and non-Comet configurations, and clean up empty directories and working directories (.comet/, docs/superpowers/). And handle all 7 hook formats (Claude Code, Qwen, Qoder, Gemini, Windsurf, GitHub Copilot, Kiro) and all 3 rule formats (md, mdc, copilot) instructions (#95)
• Progressive loading reference docs: Four reference documents were extracted from the inline skill content to achieve on-demand loading and reduce the token cost per call (in both Chinese and English) : auto-transition.md (Automatic Phase Advancement Protocol, replacing approximately 7 × 10 lines of repetitive content in each sub-skill), context-recovery.md (Context Compression recovery, replacing approximately 4 × 8 lines), comet-yaml-fields.md (.comet.yaml field table, approximately 40 lines), and file-structure.md (Directory structure) About 20 lines. The main comet/SKILL.md inline retains the key state machine hard constraints while pointing to the reference documentation for detailed field descriptions. Estimated savings per call: 600-1500 tokens (depending on skill); The complete workflow cumulatively saves approximately 4,100 tokens.
• Pre-commit formatting hook: A new pre-commit hook for husky + lint-staged has been added, which automatically runs prettier --write for the temporary source files in the src/ directory each time git commit occurs (the range is aligned with the CI’s format:check). Editor independent - enforced on all contributors regardless of the IDE or agent used - prevents Prettier formatting issues from entering CI. The prepare script will install this hook at pnpm install, and .husky/ will be excluded from the published packages through the files whitelist.

​

Changed

• Skills progressive loading refactor: All 7 sub-skills in both Chinese and English (comet-open, comet-design, comet-build, comet-verify, comet-archive, comet-hotfix, comet-tweak) now refer to the shared protocol documentation to handle automatic phase advancement and context recovery. And retain the key inline commands (next command and output interpretation) to ensure safe and independent loading.
• Phase guard recovery with durable checkpoints: The recovery steps in comet-phase-guard.md (in both Chinese and English) have been updated. The subagent-driven-development skill of Superpowers has been reloaded, and subagent-progress.md has been read for precise phased recovery (implementation submission, RED/GREEN evidence, passed review, unresolved feedback, review - fix round). And continue from the precise stage recorded at the checkpoint. Both copies of .claude/rules/ and assets/skills/comet/rules/ contain consistent references and use bilingual identifiers to ensure cross-language testing compatibility.
• Decision point protocol extraction: Extract the inlined user decision point texts from all 7 sub-skills (comet-open, comet-design, comet-build, comet-verify, comet-archive, comet-hotfix, comet-tweak) and the main comet/SKILL.md to the shared comet/reference/decision-point.md (in both Chinese and English). Sub-skills now eliminate duplicate blocking point rules through the path reference protocol, reduce the token cost of each call, and ensure consistency among various skills.
• Debug gate protocol extraction: Extract the inline systematic debugging four-stage process from comet-build, comet-hotfix and comet-tweak to the shared comet/reference/debug-gate.md (in both Chinese and English). Sub-skills now debug level protocols through path references, centralizing the rules for investigation, minimum failure testing, fix verification, and verification loops.
• Lightweight verification review: Lightweight verification now requires a Superpowers requesting-code-review review focused on correctness, security, and boundary cases, adding review coverage without running a full spec or design drift check (#86)

​

Fixed

• Pi slash command discovery: comet init and comet update now generate a Pi extension that registers all built-in /comet* workflows as native slash commands and forwards them to /skill:*. The Pi Settings merge in a non-destructive way and enable the skill command. Global resources now use the ~/.pi/agent/ directory recorded in the Pi official documentation. It will detect old ~/.pi/skills/ installations for updates and cleaning. Moreover, comet uninstall only removes Comet managed resources while retaining shared Settings and irrelevant extensions (#89]).
• OpenCode plugin-installed Superpowers detection: comet init can now accurately detect Superpowers that have been installed through the OpenCode plugin system (configured in opencode.json), preventing duplicate installation. Previously, only skills directly placed under ~/.config/opencode/skills/ could be detected, and the plugin source directory of ~/.config/opencode/superpowers/skills/ and the plugin array in opencode.json were omitted. The hasOpenCodePluginSuperpowers() fallback detection has been added, similar to the existing Claude Code plugin cache check (#105).
• Lightweight verification consistency: The hotfix document now describes six lightweight validation paths. Validation failure handling treats CRITICAL and IMPORTANT discoveries as blocking items, keeping the review pass criteria consistent with failure decisions.
• Hook configuration merging during init and update: Shared hook profile for Claude Code, Codex, Amazon Q, Qwen, Qoder, Gemini and Windsurf Now, when Comet installs or updates hooks for the same matcher or event, user-defined hooks are retained. The existing Comet commands identify and replace in place through their list script paths, preventing outdated installation paths, duplicate matcher groups, and the accumulation of duplicate hooks, while not affecting irrelevant Settings.
• Subagent-driven task isolation and continuity: comet-build now loads the mature Superpowers subagent-driven-development loop and applies a stricter Comet extension, requiring each task to use a brand-new background implemencer, a brand-new background reviewer and fix agent, and only the coordinator to execute the source code And tasks are automatically executed consecutively without generating progress summaries or “continue?” Hint. The TDD pattern requires each implementor/fix agent to load the TDD skill and return auditable RED/GREEN evidence before review. Persistent task-by-task checkpoints retain the implementation submission, review phase, feedback, and three-round retry budgets during the context compression process; The task check remains blocked until both rounds of review are passed (#94, #96, #97).
• npm shebang line ending issue on macOS: When npm packages a project on Windows, the shebang line of bin/comet.js gets a CRLF line end, causing macOS to interpret #!/usr/bin/env node\r as content other than #!/usr/bin/env node. “command not found” appears after npm install -g @rpamis/comet. In .gitattributes, an explicit eol=lf rule has been added for all text file extensions (.js, .mjs, .ts, .json, .md, .yaml, .yml). And binary tags (#82) were added to the image file.
• CodeGraph Codex CLI skip on project scope: The project scope’s comet init will pass --target and --location=local to codegraph install, causing the Codex CLI (without project local configuration) to be skipped and display confusing messages. Simplify it to codegraph install --yes, without passing the --target or --location flags, allowing CodeGraph to automatically detect and configure all installed agents. filterSupportedPlatforms and CODEGRAPH_SUPPORTED_TARGETS (#98) have been removed.
• OpenSpec CLI upgrade and —profile fallback: ensureOpenSpecCli now always installs/upgrades openspec to the latest version, even if an old version exists, to ensure that users receive --profile support and other improvements. A rollback logic has been added: if openspec init reports “unknown option —profile” in stderr, it will retry without this flag to deal with the edge situation where the upgrade fails but the old openspec remains (#84).
• Symlink resolution for skill file copies: When the skill directory is a symbolic link (e.g. ~/.claude/skills/comet -> ~/.agents/skills/comet), copyFile and ensureDir will be written to the literal path to avoid following the symbolic link target. Damaged symbolic links can cause silent copy failures. In file-system.ts, add resolveSymlinkPath(). Traverse the path tree upwards and follow the readlink target for damaged symbolic links. It has been applied to ensureDir, copyFile and writeFile (#85)
• comet-tweak missing debug handling: comet-tweak/SKILL.md lacks the systematic debugging requirement that comet-hotfix already has - when the test or build fails during the tweak execution, this skill now explicitly requires loading the systematic-debugging skill before proposing a source code fix. Be consistent with the behavior of hotfix.
• OpenSpec per-artifact instructions compliance: Now, for each standard product, apply the OpenSpec product-by-product directive (openspec instructions proposal/design/tasks --change "<name>" --json) to load context, rules, template, instruction, resolvedOutputPath, and dependencies from the JSON payload. It has replaced hard-coded product copy. When the instruction fails, the product generation will be immediately stopped to avoid silently bypassing the project rules (#66)
• CI Windows path escaping in skill verification: The Pi setting verification step of the init-e2e workflow directly inserts the Windows $RUNNER_TEMP path (including the backslash) into the JS string literal of node -e "require('...')". Among them, \a/\_ was parsed as escape characters and the path was broken (D:\a\_temp → D:a_temp), resulting in the failure of the init-e2e (windows-latest) runner on Node 20 and 22. Now this path is passed through the environment variable (process.env), ensuring it never enters the JS string literal. Linux/macOS is not affected.
• OpenSpec source formatting: The src/core/openspec.ts (long line break) has been reformatted to meet the requirements of prettier --check, removing the blocking of the format:check CI step.
• Symlink-safe removal during uninstall: removeFile/removeDir no longer resolves symbolic links before deletion. Previously, the parsing targets of the skill, rule or hooks directories of symbolic links would be recursively deleted by comet uninstall; Now, symbolic link directories will be directly unlinked. isDirEmpty no longer reports unreadable directories as empty either, so the cleaning operation will not delete directories that it cannot check.
• comet update --json output corruption: The stdio inherited by npm would previously be mixed into JSON documents; Now, in JSON mode, the stdout/stderr of npm is discarded to keep the machine-readable output parsable.
• comet update --json no-targets shape: The early return JSON sent when no installed targets exist now contains codegraph: 'skipped', which is consistent with the normal output structure, allowing consumers not to perform special processing on empty paths.
• ** JSON-MODE Version-check latency**: comet init and comet update can now skip the version check of the npm registry in JSON mode and output without network round-trip.
• Malformed hook settings resilience: When manually edited Settings files store hook groups as non-array values, exceptions are no longer thrown during the hook merge in init/update; Groups with incorrect formats will be forcibly converted to empty.
• Markdown code-fence language tags: The text language tag has been added to the fence code blocks of file-structure.md and subagent-dispatch.md (in both Chinese and English) to meet the MD040 lint check and be consistent with the existing OpenSpec formatted CI fix.
• Skills manifest version drift: Upgrade the assets/manifest.json version from 0.3.3 to 0.3.8 to be consistent with package.json.

​

Tests

• Kimi Code platform coverage: Added detection for Kimi Code, project/global installation, OpenSpec tool mapping, Superpowers agent mapping, CI platform count, and regression test coverage for documents.
• Lightweight verification review regression: A bilingual workflow protection test has been added, covering lightweight code review requirements, congestion severity levels, review criteria with limited scope, and hotfix document consistency.
• Pi command extension lifecycle coverage: New features have been added, including project/global initialization, lister-driven command generation, parameter forwarding, setting retention, invalid setting protection, deterministic coverage and selective offloading regression test coverage, as well as CI assertions for Pi projects and global extension locations.
• Hook merge regression coverage: Real file tests for Claude style, Qwen/Qoder, Gemini and Windsurf hook formats have been added, covering retention of matcher user hooks, replacement of outdated Comet commands, retention of irrelevant configurations, and idempotence reinstallation.
• Subagent dispatch contract coverage: A regression coverage test for both Chinese and English skill content has been added. Covering the Superpowers/Comet combination, only coordinator source code execution with trace file exceptions, a brand-new background agent for each task and role, prompt/status/reviewer evidence contract, persistent recovery checkpoints, TDD attribution, double review checkboxes, bound stop conditions, continuous task execution, Comet Exclusive final handover, and there is no Stop hook.
• Reference doc assertions: Added assertions to verify that all skill files referencing decision-point.md and debug-gate.md contain the correct protocol paths, and the built-in reference documentation contains the expected core rules and fallback behaviors.
• OpenSpec artifact contract coverage: Added bilingual contract assertion, verifying that the comet-open skill contains explicit JSON instruction commands for proposal, design, and tasks; It is required to apply context, rules, template, instruction, resolvedOutputPath and dependencies. It is prohibited to copy context/rules to the product. Refresh the status between products; And stop rather than roll back when the OpenSpec command fails.

​

Added

• Auto-transition config: In the default configuration of the .comet.yaml and .comet/config.yaml projects, auto_transition (true/false) has been newly added, allowing teams to choose whether Comet will automatically advance to the next stage Skill or pause and wait for manual switching. When auto_transition: false is activated, build/design/open/verify skill will stop once the exit condition is met and print the manual operation instructions for the next step. It includes a state machine whitelist, enumeration validation, and schema (comet-yaml-validate.sh) override (#74)
• Deterministic next step resolver: Add comet-state next <change-name>, parse the routing logic after guard based on .comet.yaml (phase, workflow, auto_transition), and output structured results: NEXT: auto|manual|done, SKILL: <skill-name> and HINT (in manual mode). This centralizes the routing logic of the next skill into the script, avoiding repetitive writing in the copy of each skill.
• Workflow output language: The Comet workflow now propagates the language that triggers user requests to the OpenSpec and Superpowers steps through explicit output language rules, ensuring that the generated proposals, designs, plans, verification reports, and archived descriptions are all presented in the user’s language, maintaining readability. When restoring an existing change, the main language of the product will be retained, unless the user explicitly requests a switch (#53, #37).
• Execution benchmark (Claude Code): New benchmark:execution, a benchmark testing framework consisting of three test phases: L1 (Generate design documents based on handover context), L2 (Build Noteboard modules based on handover context and run tests), and L3 (complete workflow - implement a dictionary module according to specifications and run 10 vitest tests). Call Claude Code (claude -p), and measure the actual test pass rate, token usage, retry count, time consumption and cost. Compare the off and beta context compression modes at small, medium and large scales. Support --phase l1|l2|l3|both|all and --dry-run for deterministic verification. Extract the shared utility functions (spawnCapture, parseClaudeJson, buildClaudeArgs, etc.) to scripts/benchmark-utils.mjs.
• Token optimization: TDD skill single load: build skill now loads test-driven-development skill only once before the first task, reducing approximately 44K tokens in a workflow of 10 tasks. It includes the recovery guidance after context compression and reloads once during recovery.
• Token optimization: brainstorming checkpoint: The design skill now writes brainstorm-summary.md after the user confirms the design plan, providing a context compression recovery point to retain the confirmed decision during the context window compression process.
• Token optimization: incremental brainstorming checkpoint: The design skill now incremental updates brainstorm-summary.md during the brainstorming process, retaining confirmed facts, candidate decisions, risks, test notes, and unresolved issues before platform-driven context compression occurs.
• Token optimization: active compaction gate: The design skill now requires an active context compression checkpoint after the finalization of brainstorm-summary.md and before creating the design document, prioritizing the use of the native compression mechanism of the host platform. When unavailable, it will revert to manually prompting the user.
• Token optimization: plan creation subagent offload: build skill offloads the execution of writing-plans to the subagent, releasing the context of the main session. The sub-agent reads the design document and tasks.md from the file and returns the path of the plan file. When the sub-agent fails, it falls back to inline execution.
• Token optimization: verification skill dedup: verify skill now loads verification-before-completion only once before the light/full branch judgment, eliminating duplicate skill content in each branch.
• Token optimization: Tasks.md incremental scan: build skill now uses grep increments to find unfinished tasks, eliminating the cost of re-reading the entire tasks.md after each task is completed.
• Token optimization: hash on-demand read in verify: verify skill checks handoff_hash before re-reading the OpenSpec product. When the hash matches, only tasks.md is skipped (Propose.md and design.md will still be read for comparison checks). Use the newly added comet-handoff.sh --hash-only logo.
• --hash-only flag for comet-handoff.sh: A new backward-compatible flag has been added, which only outputs the context hash without generating a handover file for hash comparison in the verify phase. Before calculating the hash, it will verify whether the necessary files exist.
• CodeGraph integration in comet init: comet init now provides an optional step to install and configure CodeGraph (@colbymchenry/codegraph) for semantic code intelligence. It will automatically detect the supported platforms (Claude Code, Cursor, Codex, OpenCode, Gemini, Kiro, Antigravity), automatically install if the CLI is missing, run codegraph install for agent wiring, and initialize the project index. It will gracefully skip in --json mode.
• Stale PR automation: A new GitHub Actions workflow that is triggered at regular intervals and can be manually run has been added. pull requests that have not been active for 90 days are marked as stale and will be closed after 30 days to help manage long-idle review queues.
• TDD mode field: Add tdd_mode (tdd/direct) in the .comet.yaml state machine, allowing users to choose whether to enforce TDD during build. When tdd_mode: tdd occurs, the sub-agent scheduling will inject explicit TDD hard constraints, bypassing the conditional triggers in implementers -prompt.md. Solve #67.
• subagent_dispatch field: Add subagent_dispatch (null/confirmed) in the .comet.yaml state machine to ensure that build_mode: subagent-driven-development can only leave the build phase after the real background scheduling capability of the platform is confirmed.
• Verify retry limit: verify skill now forces the user to make a decision after three consecutive verification failure cycles, preventing unlimited automatic retries.
• Manual verify_mode override: When the automatically detected mode is inappropriate, users can override the automatic verification scale assessment through comet-state set <name> verify_mode <light|full>.
• Local context compression benchmark: A new benchmark:context, a local Codex benchmark testing framework, has been added. It will create matching context_compression: off and beta Comet test cases, run codex exec for each mode, and report token savings, specification drift rate, task completion rate, parsing success rate, and time consumption. Perform deterministic non-Codex verification using --dry-run.
• Beta-gated context compression switch: The project installation now creates .comet/config.yaml with context_compression: off, allowing the team to enable the beta specification projection of the new change by setting context_compression: beta. This switch only controls the OpenSpec junction projection path (spec-context.*); The above workflow token optimization is enabled by default and does not require beta mode.
• Beta spec projection handoff: /comet-design can now use beta context compression to generate spec-context.json and spec-context.md, retaining the requirements and scene titles as well as source hashes of OpenSpec. This enables a streamlined design handover to reduce the token burden without weakening acceptance coverage.

​

Changed

• executing-plans review gate: When build_mode is executing-plans, the build phase now requires that at least one Superpowers requesting-code-review skill be loaded and one code review be requested before the build→verify phase guard. CRITICAL level issues must be fixed before verify. Accepted non-critical issues must have the reasons for acceptance recorded in the persistent product. The build exit checklist will enforce this level (#76, #41).
• Phase advancement vs handoff wording: Chinese and English Comet skills now consistently distinguish between the stage advancement of the guard driver (--apply, always updated phase) and the next step skill invocation control (auto_transition). The open/design/build/verify/hotfix/tweak now unified through the guidance of comet-state next route by the automatic/manual transfer.
• ** Preset continuous wording **: hotfix and tweak guidelines now explicitly document the auto_transition: false exception in continuous execution mode, removing the contradictory wording surrounding the “always continue” behavior.
• Verify hashing -skip scoped to tasks.md only: Complete verification always reads proposal.md and design.md even if the hash matches, ensuring that the target satisfaction and design consistency checks have complete context.
• Design Doc creation stays in main session: The design document is created inlined (not unloaded to the sub-agent) to retain the complete context of the brainstorming conversation and prevent information loss under complex requirements.
• Subagent failure fallback: The planned subagent offloading contains explicit downgrade fallback - if the subagent fails, the main session will inline load writing-plans.
• Beta spec verbatim projection: beta context compression now projects the entire spec file as is using cat AND completely removes the AWK filters that match the English keywords (GIVEN/WHEN/THEN/AND/BUT). This eliminates language-related matching and ensures zero drift in the acceptance criteria of Chinese or non-English specifications.
• JSON structural validation: comet-guard.sh now verifies the structure of spec-context.json (required fields:) The coverage of source file references such as change, phase, mode, files, and context_hash has replaced the previous markdown check based on English titles. The guard will capture damaged or incomplete JSON before the phase transition.
• JSON file roles: The files array of spec-context.json now contains the role field (the spec file is spec, and the proposal/design/tasks are supporting), completely removing the projection array that depends on the language.
• —full warning in beta mode: Running comet-handoff.sh --full in beta mode will now issue a clear warning to make the ignored flag visible.
• CodeGraph step in comet update: comet update now prompts to install/update CodeGraph while updating the skill file, using the same platform detection and CLI installation process as initialization.
• Rules and hooks distribution in comet update: comet update will now distribute the anti-drift stage guard rules and hooks to all installed platforms while updating the skill file, ensuring that the rules and hooks remain synchronized after the Comet upgrade.
• Archive confirmation gate: Chinese /comet-archive will now pause before running the archive script to obtain the user’s explicit confirmation, giving the user one last chance to make adjustments or re-verify before the master spec merge and change the archive.
• English archive confirmation parity: The English Comet skill is now consistent with the confirmed Chinese archive confirmation workflow, including /comet-archive, /comet-verify, /comet, hotfix and tweak guidelines.
• Archive reopen transition: New comet-state transition <change-name> archive-reopen has been added, allowing users who reject the final archive confirmation to return from phase: archive to phase: verify for adjustment or re-verification without the need for manual editing of .comet.yaml.
• OpenSpec clarification gate: Now, /comet-open requires that a requirements clarification summary be confirmed before creating a proposal, design, or tasks product to prevent a complete OpenSpec change from being generated immediately after a round of Q&A.
• PRD split preflight: Chinese and English /comet-open now sort large PRDS before creating OpenSpec products, allowing users to split independent functions into multiple Comet Changes while keeping each accepted split item on the state machine path of /comet-open. Solve #62.
• Skill invocation wording guidance: Repository guidance has been added in CLAUDE.md, requiring the new skill trigger description to use the existing “use the Skill tool to load…” Use the wording and place the context details after the skill is loaded.
• Anti-drift phase guard rule: New .claude/rules/comet-phase-guard.md has been added. In each round of dialogue, Comet stage awareness, skill invocation requirements, script execution requirements, user confirmation levels, and context compression recovery guidelines are re-injected to prevent long context attention drift from disrupting the 5-stage workflow. It takes effect as a soft reminder on all platforms.
• Anti-drift phase guard hook: A new comet-hook-guard.sh PreToolUse hook (configured in .claude/settings.local.json) has been added. When the current Comet Change is in the open, design or archive stage, file writing is forcibly blocked, providing a platform-specific hard execution layer that the model cannot bypass. Add the paths of openspec/*, docs/superpowers/*, .claude/* and .comet/* to the whitelist.
• Platform rules/hooks distribution in comet init: comet init now distributes the anti-drift phase guard rules and hook-guard scripts to all supported platforms during initialization. Revised the platform definition: Cline uses .clinerules/ (instead of .cline/rules/) in the project root directory, GitHub Copilot uses .github/instructions/*.instructions.md with applyTo frontmatter, and Kiro uses .kiro/steering/. Gemini CLI does not have a rule directory (using the gemini.md file). rulesDir/rulesFormat have been added to 8 platforms lacking rule configuration, and supportsHooks/hookFormat have been added to 7 platforms. hook installation supports seven format variants: Claude Code, Gemini, Windsurf, Copilot, Qwen, Kiro and Qoder.
• Systematic debugging gate: The Chinese and English build and hotfix skills now require loading Superpowers’ systematic-debugging when crashes, unexpected behaviors, test failures, or build failures occur during the implementation phase. Ensure that root cause analysis is conducted and regression tests are written in the current change before fixing the source code.
• ** Verification-pre-completion gate**: Chinese and English /comet-verify now require Superpowers’ verification-before-completion to load before performing lightweight or full Verification checks, and enforce evidence-based confirmations before any completed declarations.
• Platform-neutral confirmation gates: Chinese and English Comet skill and recovery messages now reference the user input/confirmation mechanism of the current platform and remove the hard-coded dependency on AskUserQuestion to prevent Codex users from being directed to use tools that may not exist, while retaining obstructive user decisions.
• ** Preset Upgrade path **: hotfix and tweak skill now include the set <name> phase design step when upgrading to full workflow to prevent the comet-design entry check from failing after workflow switching.
• Build-complete conditional field reset: The build-complete conversion retains verification_report and branch_status when the previous verify_result is fail, so that the verification-fail →build→build-complete revalidation loop does not lose data.
• Open phase recovery granularity: The open phase recovery now distinguishes three states (all products completed/no products completed/partially completed), and provides specific recovery operations for each state.
• 50% scope threshold option: The build skill now provides “Continue in the current change” as a third option when the change exceeds 50% range, avoiding forced splitting of the change.
• Worktree plan commit: build skill now explicitly instructs that when using worktree isolation, the plan file should be committed first before creating the worktree.

​

Removed

• openspec/config.yaml: The unused sample OpenSpec configuration file (containing only placeholder comments) has been removed.

​

Fixed

• Subagent task persistence: /comet-build now requires each sub-agent scheduling prompt to select completed tasks for persistence in the Superpowers plan before submission and update the corresponding OpenSpec tasks.md entry during mapping. The build Guard will block unselected Superpowers scheduled tasks. Before the build recovery checks the recent git history /diff or schedules more work, it will simultaneously report the OpenSpec and the progress of the schedule. Prevent the re-running of completed sub-agent work (#79) when resuming after interruption or context compression
• skip-all skipping uninstalled components: comet init no longer considers previously skipped components as installed. Selecting Skips-All now only skippes the actual existing components. Uninstalled OpenSpec, Superpowers, Comet or CodeGraph components will still display the installation prompt normally (#73).
• Update JSON output for rules/hooks: comet update --json now includes the distribution results of rules and hooks in addition to the skill update results, and has error isolation for each target, so that the failure of a single platform does not disrupt the entire update output.
• Duplicate YAML fields: replace_yaml_field in comet-state.sh now removes duplicates from all fields after replacement, retaining only the last occurrence of each key. Previously, multiple calls to cmd_set for the same field (for example, in the Verifice-Fail → re-validation loop) might leave duplicate lines in .comet.yaml, interfering with downstream parsers. Fix #77.
• Hook config format: installClaudeCodeHooks and .claude/settings.local.json now use the correct array format of matcher + hooks: [{ type, command }] instead of the flat { matcher, command, description } format, and fix the schema check error of /doctor.
• Archive delta merge: comet-archive.sh now entrusts the archive spec update to the delta merge semantics of OpenSpec, eliminating the practice of directly overwriting the main spec with change spec to prevent the chapter titles of ADDED/MODIFIED/REMOVED/RENAMED from leaking into the stable spec. Solve #69.
• Brainstorming depth: Chinese and English /comet-design no longer tell Superpowers’ brainstorming to skip context exploration. Therefore, unclear goals, scopes, non-goals, acceptance scenarios or constraints must be clarified before creating the design document.
• Command injection prevention: The run_command_string() in comet-guard.sh now rejects build/verify commands containing shell metacharacters (;, |, &, $, backquotes) to prevent command injection through the command field of .comet.yaml.
• Path traversal prevention: comet-state.sh cmd_set now verifies whether the path field (design_doc, plan, verification_report, handoff_context, handoff_hash) contains the .. traversal sequence before writing.
• Design guard enforcement: The design guard now requires that the full workflow must have design_doc (FAIL instead of WARN) to prevent advancing phases without design documentation.
• **branch_status preservation on Verific-fail **: The verify-fail transformation no longer resets branch_status and retains the branch processing status in the revalidation loop.
• UTC date consistency: All scripts now use date -u +%Y-%m-%d to set created_at, verified_at and archive naming, eliminating the issue of local /UTC date inconsistency.
• macOS SCRIPT_DIR resolution: All scripts use portable $(cd "$(dirname "$0")" && pwd -P) instead of readlink -f to ensure cross-platform compatibility.
• Archive directory resolution fallback: comet-archive.sh resolve_archive_dir() now searches in the *-$CHANGE mode when there is an exact UT-based path mismatch, fixing the test reliability issue in different time zones.
• Temp file permissions: All mktemp calls now set chmod 600 to the temporary file before writing sensitive data.
• Pipe hash error propagation: The hash calculations in comet-handoff.sh and comet-guard.sh now capture the pipe output into the variable first, and then pass it through the pipe to the hash stream to prevent silent failure under pipefail.

​

Tests

• Auto-transition regression: New additions include default value initialization for auto_transition, enumeration verification, default value propagation for .comet/config.yaml projects, and schema verification. As well as the state machine for manually switching and automatically advancing branches in build/design/open/verify skill and skill coverage testing (#74).
• comet-state next regression: Added shell script coverage testing, covering the next step analysis in scenarios such as full/hotfix/tweak workflows, manual handover mode, completed archiving (NEXT: done), and failure behaviors when .comet.yaml is missing.
• Skill handoff wording regression update: Updated the skill content assertion to validate the handover wording of the next driver (NEXT: auto|manual|done), and synchronized the expectation check in both Chinese and English.
• Output language regression: A new skill coverage test has been added verify that Comet propagates the language that triggers user requests to OpenSpec and Superpowers in each skill of open, design, build, Verify, hotfix, tweak, and archive Step (#53)
• Review gate regression: A new skill coverage test has been added to verify that the executing-plans build mode requires the requesting-code-review level before the build→verify conversion, and the expectations for init-e2e have been updated (#76).
• skip-all regression: Added comet init coverage testing to verify the skip -all just skip the installed components, will still be prompted to install not installed OpenSpec/Superpowers/Comet/CodeGraph components (# 73 ).
• --hash-only flag coverage: Added test verification of correct hash output, change directory verification, required file verification, and no regeneration of handover files.
• Context benchmark runner coverage: Added token savings calculation for test verification benchmark tests, usage/conclusion parsing of Codex JSONL, and the ability to generate reports without calling Codex in dry-run mode.
• Flaky test timeout fix: The design guard test without design_doc now has a definite 20-second timeout to prevent Windows bash startup jitter.
• Chinese spec coverage: The beta handover test uses Chinese spec content to verify that all contents (titles, descriptions, non-keyword steps) can be projected as is regardless of the language.
• JSON corruption detection: New test verification: When the spec-context.json structure is invalid, the guard will prevent design from exiting.
• —full beta warning: Added a test verification warning message and confirmed that the beta file will still be generated when --full is passed in.
• Doctor CodeGraph check: comet doctor now reports the availability of the CodeGraph CLI and the initialization status of the project (whether .codegraph/ exists).
• Archive confirmation regression: A new Chinese skill coverage test has been added to verify that /comet-archive needs to finally confirm the level before executing the archive script.
• English archive confirmation regression: Added English skill coverage, including final archive confirmation, archive reopening guidelines, and hotfix/tweak preset blocking points.
• Phase write guard hook coverage: Ten new tests have been added for comet-hook-guard.sh, covering stage-based write blocking (open/design/archive blocking). build/verify allows, whitelist paths (openspec, docs/superpowers,.claude), bypassing of archived changes, and allowing when there are no active changes.
• Archive reopen regression: A new state machine coverage test has been added, covering returning unarchived changes from archive confirmation to validation, as well as refusing to reopen attempts after archived: true.
• Archive spec merge regression: A new shell script coverage test has been added, covering that when archiving the delta spec, the title of the requirement section that only has delta is not copied to the stable master spec.
• OpenSpec proposal regression: New Chinese and English skill coverage tests have been added, covering the clarification stage before product creation, the default ban on one-time openspec-propose, and the retention of the Superpowers brainstorming clarification process.
• Skill authoring regression: A new coverage test has been added to verify that the necessary skill invocation wording patterns are recorded in CLAUDE.md.
• Debug gate regression: New Chinese skill protection coverage test has been added, covering systematic debugging calls, minimum failure test requirements, and keeping crash validation within the current change.
• Confirmation mechanism regression: A new coverage test has been added to verify that the Chinese workflow decision level is no longer hard-coded AskUserQuestion, and the restored output will guide the agent to use the platform-independent confirmation mechanism.
• PRD split workflow regression: New Chinese-English skill coverage tests have been added, covering PRD split selection in the open stage, /comet-open state initialization, repeated sorting blocking, split completion selection, and minimum recovery guidance.
• tdd_mode state machine regression: New coverage tests have been added, covering the initialization default values of tdd_mode (full is null, hotfix is direct), enumeration validation, build exit guard, hotfix bypass, and the rejection of illegal values by schema validation.
• Review fix regression: New coverage tests have been added, covering the retention of conditional verification_report during re-validation, the retention of branch_status during Verific-fail, the rejection of path traversal in design_doc, and the rejection of command injection in build_command. And the design guard is enforced when there is no design_doc in full workflow.
• Context compression regression: New coverage tests have been added, covering the default values of project configuration, context_compression snapshots at the change level, environment variable coverage during change initialization, generation of beta spec projections, and guard rejection when beta projections lack requirements or scene titles.

​

Added

• ** Plan-Ready build pause state**: Add build_pause as a dedicated pause marker for the build phase, enabling Comet to pause after generating the Plan without confusing this pause with the actual execution method.
• Plan-ready pause design: A new design document on the model switching pause workflow has been added, covering recovery behavior, expiration pause handling, and remedial measures for missing plans.

​

Changed

• Build recovery routing: /comet and /comet-build can now recognize build_pause: plan-ready, reuse the existing plan, and recover from workspace isolation and execution mode selection instead of regenerating the plan.
• Bilingual workflow documentation: Both the Chinese and English Comet skills now describe the plan-ready pause point, clearly stating that build_pause is not build_mode, and the same status field is recorded in the two Readmes.

​

Fixed

• GitHub Copilot Superpowers skill names: Comet skills now calls the Superpowers bare skill name installed by the GitHub Copilot skills path to avoid workflow blocking caused by unresolvable superpowers:* aliases.
• Windows bash resolution: Comet now parses the available bash executable file through COMET_BASH, rejects the Windows WSL launcher PATH, and uses the parsed executable file for nested script calls, preventing the guard, handovers, and archiving processes from reverting to the corrupted PATH bash.
• Shell test runner bash resolution: run-bats.js now parses available Bash through COMET_TEST_BASH, COMET_BASH, PATH, or Git Bash default values to avoid using a corrupted Windows WSL launcher when running shell tests from Node.
• Schema validation fatal output: Guard validation now retains the final fatal schema validation message after printing the validator diagnostic information, making invalid .comet.yaml failures easier to identify.

​

Tests

• Superpowers skill invocation regression: Added test coverage to ensure that the accompanying Comet skill text does not reference Superpowers aliases with plugin prefixes.
• Comet bash execution regression: Added test coverage, including nested script calls, included command examples, and shell test runner, to ensure that Comet uses the parsed bash PATH instead of the original PATH bash.
• Plan-ready pause regression: Added shell script test coverage, including build_pause initialization, schema validation, state update, and build recovery output.
• README state-field regression: Add README test coverage to ensure that build_pause appears in the examples and field descriptions of the Chinese and English documents.

​

Added

• Context compaction recovery (--recover): comet-state check <name> <phase> --recover outputs a structured recovery context, including stage status, field progress, number of tasks, and recovery operations, for context compression of the agent to quickly locate breakpoints and restore operations.
• Red Flags Anti-Rationalization List: Five new red flag warnings (make decisions for users, skip confirmation, replace historical preferences, agree without objection, pass without verification) have been added to the master scheduling skill to help the agent identify its own tendency to exceed authority.
• Uncertainty Degradation Principles: Add the SUGGESTION > WARNING > CRITICAL degradation rule in verify skill. Only build failures, test failures and security issues will be marked as CRITICAL; Ambiguous issues must be downgraded.
• Anti-Automatic Selection Guardian: Add anti-automatic selection rules for naming and range in the open skill. Name changes must be specified by the user or confirmed through AskUserQuestion. The scope shall not be arbitrarily expanded or reduced.
• File Existence Verification: Before entering the user confirmation, the open skill will verify that the proposal/design/tasks file is not empty to prevent empty files from skipping the check.
• Idempotency Description: Add idempotence descriptions for all skill stages (open/design/build/verify), clearly stating which operations can be safely retried and which fields need to be confirmed before skipping.

​

Changed

• AskUserQuestion Tool Clarification: All 7 decision blocking points (open confirmation, brainstorming confirmation, build workflow, verify failed decision, spec offset handling, branch handling, upgrade condition) are uniformly required to use the AskUserQuestion tool. Plain text prompts are prohibited.
• Decision Points Expanded from 6 to 7: The proposal/design/tasks review confirmation in the open phase is now the first decision point.
• Spec Drift Single-Choice Question Format: The spec drift processing in the verify stage is changed to AskUserQuestion single-choice questions (choose one of A/B/C), and there are no implicit default options anymore.
• Completely synchronized Chinese and English skills: The contents, structures and option formats of the 7 Chinese skills and the 7 English skills are fully aligned.

​

Fixed

• Crash due to unbound variables in set -u: When comet-state check --recover is missing tasks.md during the build phase, the undeclared pending variable will cause the script to exit directly; The issue has now been fixed by moving the local declaration forward and adding an explicit branch tasks.md MISSING to the recovery operation chain.
• Path truncation risk: field_status using ${var%% *} for design_doc may truncate paths containing Spaces; It has been changed to ${var% }, with only the trailing Spaces removed.
• Inconsistent reading style for optional fields: direct_override uses || echo "", while other optional fields use || true; It is now unified as || true, which is consistent with cmd_scale.

​

Tests

• Eight new check --recover and boundary test cases, covering the open/build/verify/design/archive five stages, and the absence of the tasks. The md and all tasks completed scenarios such as boundary.
• The total number of tests increased from 34 to 42, and all passed.

​

Changed

• Command execution security: All command executions in the OpenSpec and Superpowers installation paths were refactored from spawn with shell interpretation to execFileSync, eliminating the shell injection risk surface and enhancing cross-platform reliability (#88bf487)

​

Fixed

• OpenSpec global install path for OpenCode: comet init --scope global will now migrate OpenSpec skills from the hard-coded ~/.opencode/ directory to the ~/.config/opencode/ directory actually read by OpenCode, and add the self-deletion guard (#46, @gleami) when the source path is the same as the target path.
• Windows command execution: On Windows, the shell option was added for the execFileSync call, enabling the command shim (.cmd) to be parsed correctly
• Doctor .comet.yaml validation: comet doctor now verifies top-level keys and rejects unknown keys; At the same time, readDir errors other than ENOENT will no longer be swallowed (@felamin)
• CI JSON parsing: The CI workflow parses the command output by looking up the first { character, avoiding non-JSON prefix lines from disrupting JSON extraction (@yicochen)
• CI warning output: CI now only counts and prints warnings when a step actually fails, reducing noise during successful runs (@yicochen)
• Spawn stdio noise: Change the stdio of non-interactive spawn from inherit to ignore, so that the OpenSpec/Superpowers installer no longer prints irrelevant progress information to the console (@yicochen)

​

Tests

• Added test coverage for OpenCode’s global OpenSpec path migration, self-deletion guards, and home directory mocks
• A doctor test has been added for the top-level key verification of .comet.yaml and the error propagation of non-enoent readDir
• Fixed the timeout issue of the Git-based test “uses plan base-ref to scale verification”

​

Docs

• Improved the configuration guidance of README, providing clearer installation instructions and foldable reference panels (updated in both Chinese and English) (@hepeng)
• A contributor wall (@Joechan11) has been added in both README and readme-zh.

​

New Contributors

• @felanny made her first contribution in #38
• @Joechan11 first contributed in #44
• @bevishe made his first contribution in #47
• @kathy32 made her first contribution in #39
• @gleami first contributed in #46

​

Fixed

• OpenSpec all-workflows installation: Now, in addition to writing to the isolated XDG_CONFIG_HOME environment overwrite, comet init will also directly write the full workflow configuration to the platform-specific default configuration path (%APPDATA%\openspec\ on Windows, $XDG_CONFIG_HOME/openspec/ when setting on macOS/Linux, and otherwise ~/.config/openspec/). Ensure that all 11 OpenSpec workflows are always installed regardless of the user’s previous OpenSpec configuration status.

​

Added

• Script discovery helper: Added comet-env.sh, which centralizes script path resolution by sourcing peer scripts from its own directory, replacing the scattered COMET_SEARCH_ROOTS lookup logic in all Chinese and English skills.
• OpenCode global config directory: The OpenCode platform now supports independent globalSkillsDir (.config/opencode) for global installation, maintaining the distinction between project-level and user-level skills.
• Command error diagnostics: A new command-error.ts module has been added, which is used to extract and clean up the stderr/stdout of failed shell commands. It is used in conjunction with the OpenSpec and Superpowers installation paths to present actionable failure details.

​

Changed

• Build decision-making point wording: Strengthened the wording of workspace isolation and execution mode selection in the build Skill so that the agent cannot make choices for the user based on recommendation rules.
• Hotfix/Tweak upgrade wording: Restated the upgrade conditions and validation failure pause requirements in hotfix and tweak Skill for clearer blocking semantics.
• Comet user decision numbering: Fixed the problem of disordered numbering order in the list of user decision points in the Chinese comet Skill.

​

Fixed

• OpenSpec workflow installation: comet init is currently using --profile custom Run OpenSpec with a temporary configuration that enables all workflows (propose, explore, new, continue, apply, ff, sync, archive, bulk-archive, verify, onboard). Make sure that Comet installs more than just the default core workflow collection.
• OpenCode slash commands: comet init now generates OpenCode command files (commands/*.md), retaining the command names of /comet* while embedding the corresponding Comet workflow content, allowing OpenCode users to directly invoke /comet, /comet-open, etc.
• Lingma Superpowers path: comet init now enables Lingma to avoid the unsupported skills --agent lingma path and copies the temporarily stored Superpowers Skill to .lingma/skills to prevent the entire external installation batch from failing while retaining Lingma’s expected directory layout.
• Lingma global directory: The global Skill directory of Lingma is explicitly .lingma. User-level installation matches ~/.lingma/skills/{skill-name}/SKILL.md, and project installation matches .lingma/skills/{skill-name}/SKILL.md.
• Script discovery safety: When comet-env.sh is sourced, it no longer changes the caller’s shell options, returns failure when the bundled script is missing, and avoids the unreachable command diagnosis of ShellCheck.
• comet-state.sh field whitelist: Add created_at and base_ref to the cmd_set allowed field list to keep the validation consistent with the fields written during the initialization of .comet.yaml.

​

Tests

• Script discovery coverage: Added tests to verify all bundled script paths exported by comet-env.sh and to ensure that there is no inline COMET_SEARCH_ROOTS in Skill files.
• Script discovery safety: Regression test coverage has been added to glob for retaining shell options and expandable $HOME Skill directories when source.
• OpenCode Comet detection: Added tests for OpenCode to have both the Skill directory and the matching command file before reporting that Comet has been installed.
• OpenCode E2E init: Added end-to-end testing for OpenCode projects and global installations, including command file generation.
• OpenCode command content: Added tests to verify that the OpenCode command file retains the Comet command name and contains the complete content of the selected language workflow instead of a lightweight Skill delegating stub.
• English workflow safeguards: Added equivalence tests that match the requirements of existing Chinese workflow decision points.
• OpenSpec profile and diagnostics: Tests have been added for creating custom profiles, --profile custom flags, and printing stderr/stdout details when installation fails.
• Lingma Superpowers fallback: Added regression test coverage to verify that Lingma is excluded from the list of unsupported skills CLI agents and to use the cache installation before copying the Skill to .lingma.
• Lingma global install path: Added regression test coverage for installing Lingma Comet Skill to user .lingma/skills directory for comet init --scope global.

​

Added

• Workflow state metadata: The initialization of .comet.yaml now records base_ref and created_at, enabling scale assessment and verification to be inferred based on a stable change baseline.

​

Changed

• Comet decision points: Adjust the workflow skills in both Chinese and English so that design confirmation, build configuration, verify failure, spec drift, branch processing, and default upgrade will all pause and wait for explicit user selection, and remove automatic dependencies on default values or recommendations.
• Build workflow selection: Merge workspace isolation and execution mode selection into one build configuration step to reduce repetitive pauses, while still requiring the determination of isolation and build_mode before implementing continuation.
• Hotfix verification flow: Move the root-cause elimination before the build guard and require the default upgrade to switch workflow to full, keep the failed hotfix check at the build stage, and keep the full-flow upgrade consistent.
• Verification scale assessment: The scale check now reverts to base_ref of .comet.yaml and uses the four-file threshold for full verification to make the submitted build changes less likely to be overlooked.
• English skill parity: Synchronize English Comet Skill with Chinese workflow rules, including handover generation, dirty working tree processing, spec drift decision-making, and validation failure blocking.

​

Fixed

• Windows npm update: comet update now starts npm through the shell to make the package update path work reliably under the Windows command pad.
• Superpowers install diagnostics: A failed Superpowers installation now prints the cleaned stderr details, making the actionable reasons for the failed network or GitHub access directly visible.

​

Tests

• Workflow safeguard coverage: Added regression test coverage for Chinese Comet decision point requirements and Superpowers installation failure diagnosis.

​

Added

• Dirty worktree recovery protocol: Added shared comet/reference/dirty-worktree.md reference documentation in both Chinese and English, enabling the agent to consistently protect, inspect, and attribute worktree changes from users or mixed sources during recovery.

​

Changed

• Comet resume behavior: Updated /comet, build, verify, hotfix and tweak Skill, making manually edited code during interrupts regarded as code evidence rather than automatic state transitions; The agent must attribute the dirty work tree changes before continuing or advancing the guard.

​

Fixed

• Reference skill installation: Add the dirty working tree reference file to the Comet manifest so that the installed set of Chinese and English Skill can parse comet/reference/dirty-worktree.md.

​

Changed

• “Antigravity Skill Path” : The platform processing method has been updated. Project-level installation uses .agents/skills, while global-level installation uses the .gemini/antigravity/skills location of Antigravity, ensuring that init, doctor, and update are consistent with the directory model of Antigravity
• **README Information Architecture **: The Chinese and English README chapters have been restructured, and the command details, platform list, Skill table, script table, .comet.yaml field, and reliability description have been placed in a foldable reference panel
• **Spec Lifecycle Document **: Expanded the description of Comet Spec lifecycle management in the README, including OpenSpec/Superpowers artifact association, automatic handover, status update, validation, and archive synchronization
• ** Security Guide Location **: Move the warehouse maintenance security instructions from the README to CONTRIBUTING.md, allowing the README to focus on user-oriented Comet concepts and installation configurations

​

Fixed

• **Antigravity Global Installation **: Fixed comet init --scope global and related health checks, preventing Antigravity from installing or searching for global skills in the project-style .agents directory
• ** Missing skills Directory **: Before scanning the project-level and global-level skills directories, an explicit existence check has been added to ensure that the detection and update logic remains robust when skills/ exists in the platform directory but is missing

​

Tests

• **Antigravity Path Coverage **: Added regression testing to cover the detection and init E2E behavior of the Antigravity project-level/global-level Skill directories
• **README Structure Coverage **: The updated README command and reference structure were verified using the existing README test suite

​

Added

• ** Design Handover Script **: New comet-handoff.sh has been added. Generate deterministic and traceable context packages (streamlined or full mode) from OpenSpec artifacts to .comet/handoff/, and record handoff_context and handoff_hash in .comet.yaml
• “Handover guard inspection” During the design phase, the guard now verifies whether the handover context exists, hash freshness (detecting changes in OpenSpec after handover), markdown traceability tags, and the frontmatter field of the design document (comet_change, role: technical-design, canonical_spec: openspec).
• **handoff_context and handoff_hash fields **: A new .comet.yaml field has been added to track the handover packages generated by scripts, and it comes with schema validation (path existence, sha256 hexadecimal digest format)
• comet init --scope: A new --scope <global|project> CLI flag has been added for non-interactive range selection
• **CI init 2E job **: GitHub Actions now runs the real comet init on Ubuntu, macOS and Windows. Verify whether Comet Skill, Superpowers, OpenSpec and the working directory are located in the correct file system (both at the project level and the global level).

​

Changed

• ** Chinese Skill Document Update **: comet-design/SKILL.md and comet/SKILL.md now record the handover process, replacing the summaries written by the agent itself with context packages generated by scripts
• **JSON generation uses process substitution **: In comet-handoff.sh, write_json_context replaces the pipe subshell with < <(source_files), fixing the variable scope issue
• ** Error Message Formatting **: In comet-state.sh, the error messages of unknown fields are split from a single line of over 270 characters into multiple lines to enhance readability
• CLAUDE.md and AGENTS.md: Project-level descriptions have been added, covering test commands, shell script conventions, script dependency graphs, .comet.yaml state machine synchronization rules, and changelog formats

​

Fixed

• **YAML and frontmatter Resolution **: Comet scripts now ignore the unquoted tail comments in the .comet.yaml field values and accept the frontmatter of the design document after the UTF-8 BOM or the leading blank line to avoid misjudgment of guards and handover failures
• **Init E2E Installation Check ** CI now verifies the Skill artifacts owned by Comet in each supported platform directory and checks the OpenSpec/Superpowers installer status from comet init --json (both project-level and globally level installations are overwritten) to avoid misjudgment failures caused by external CLI dedicated directory layouts
• **Windows Global init E2E home directory ** CI now sets both USERPROFILE and HOME simultaneously during the global init check on Windows, which is consistent with the os.homedir() parsing method of Node to avoid misjudging the missing Skill
• **README Status Document **: The README example now shows the accurate default values of the .comet.yaml build status, the timing of verifying evidence, handover fields, and the behavior of creating a working directory only at the project level
• **Windows Superpowers init Timeout **: The timeout for the external installer of Superpowers has been increased to tolerate slower Windows npx skills add operation and reduce occasional failures of init E2E

​

Tests

• The newly added tests cover the --full handover mode, rejection of missing OpenSpec artifacts, detection of hash mismatch after handover, and frontmatter verification of design documents
• New comet initE2E testing has been added, covering project-level installation, global-level installation, skipping existing items with --yes, overlaying with --overwrite, and multi-platform detection
• The newly added regression test covers the tail comments of .comet.yaml and the design documents frontmatter with UTF-8 BOM or leading blank lines
• New CI workflow regression testing has been added, covering project-level and globally level installation checks for Comet with file and external OpenSpec/Superpowers installer status
• A new CI workflow regression test has been added, covering Windows global init using the temporary USERPROFILE home directory
• The newly added regression test covers the longer Superpowers installer timeout used by init

​

Fixed

• **OpenSpec Global Initialization **: The global scope of comet init now passes the home directory as the OpenSpec initialization target and removes the unsupported openspec init --global flag
• ** Cross-platform path reference **: The OpenSpec initialization target is enclosed in shell quotes for Windows, macOS, and Linux paths, including home directories with Spaces
• ** Installer parameter references **: The --tools values of OpenSpec and the --agent values of Superpowers are now enclosed in shell quotes. Under Windows, the OpenSpec path retains a trailing backslash before closing the quotes
• **Superpowers Multi-platform Installation **: The Superpowers installation now passes in duplicate --agent flags instead of comma-separated agent lists, which is consistent with the skills CLI behavior
• **Superpowers agent Mapping **: Update the Comet platform mapping to a valid skills CLI agent ID. Unsupported platform-specific ids will fall back to universal

​

Tests

• The newly added regression test covers the construction of OpenSpec global initialization commands under Windows, macOS and Linux
• New regression tests have been added to cover the backslash references at the end of OpenSpec Windows and the installation parameters in quotes
• New Superpowers coverage test: valid skills CLI agent mapping and multi-agent parameter format
• Smoke tests were conducted on the project-level and global-level initialization outputs of all 28 supported platforms in the isolated temporary directory

​

Added

• ** build decision Mandatory Verification **: The build guard and comet-state.sh transition build-complete now require isolation and build_mode to advance from build to verify
• ** Direct Mode Coverage **: The complete workflow must first set direct_override: true before build_mode: direct can be used; hotfix/tweak is still allowed by default
• ** Configurable Guard Commands **: The guard script now first reads build_command and verify_command from the Comet configuration in the changed .comet.yaml or the root directory of the repository. If they cannot be found, it will fall back to the automatically detected build command
• ** Archive Difference Preview **: Archive synchronization will print a unified diff before overwriting the existing master specification (when it is different from the delta specification)
• ** Cross-platform Script Smoke CI**: Added smoke test coverage for Ubuntu, macOS and Windows, targeting Comet shell scripts and portable shell tests
• **Shell Line Break Policy **: Added the .gitattributes rule, maintaining the use of LF line breaks in shell and Bats scripts

​

Changed

• ** Guard Failure Output **: Guard checks now retain and print command failure output, along with actionable Next: prompts for missing build decisions and unfinished tasks
• ** Command Processing **: Project commands are run through bash -lc. Maven uses mvnw or mvn.cmd when appropriate. The shell testing assistant tool handles the Windows Git Bash path
• ** Archiving Step counting **: Dry-run, delta synchronization, annotation, move, and archiving status steps now count the actual executed steps and no longer count duplicate operations
• ** English Documents and Skills **: Synchronize the English README and Comet Skill texts with the Chinese build decisions, command configurations, and archiving behavior descriptions

​

Fixed

• **macOS shell Script Status Update **: Replaced the GNU only supported sed -i write in comet-state.sh with a portable temporary file update method, fixing the CI failure when updating the scale, transition, and YAML fields on macOS
• ** Optional field Reading under pipefail **: Guard and status scripts are now fault-tolerant for missing optional YAML fields under set -euo pipefail and will not exit prematurely
• **Bash Detection Rollback **: The shell testing assistant tool can now handle the situation where the bash detection fails and will not crash due to the spawnSync output being empty
• ** Configuration Command persistence **: comet-state.sh set will now escape sed to replace metacharacters, ensuring that commands containing &, |, or backslashes are worth retaining
• ** Optional schema Field **: YAML validation can now recognize direct_override, build_command and verify_command
• ** YAML values in quotation marks **: The status, guard, and check scripts now only remove the enclosing quotation marks instead of deleting all the quotation mark characters in the values

​

Tests

• New test coverage Missing build decisions, blocking and allowing direct mode overwriting, configured build/validation commands, command metacharacter retention, unfinished task recovery output, archiving step counting, cross-platform path handling, BSD/GNU sed portability, optional YAML field reading under pipefail, and bash detection failure handling

​

Added

• **PR Title lint Workflow ** Added GitHub Actions verification Semantic PR titles are required and Comet-specific scopes (cli, commands, core, skills, assets, scripts, docs, ci, deps, release) should be used.
• ** Structured JSON output **: comet init --json and comet update --json now output machine-readable results instead of mixed human logs
• doctor --scope: comet doctor can diagnose the auto, project or global range, while auto will simultaneously check both project-level and global-level installations
• ** Next Status Prompt **: comet status will now prompt the next workflow command (/comet-open, /comet-design, /comet-build, /comet-verify, /comet-archive) in both text and JSON output.
• **README Resource Guard **: Added tests and prepublish verification to ensure that images in the README use NPM-friendly absolute urls

​

Changed

• **comet update retains Installed context **: update now detects existing Comet Skill targets within the project level/global level scope, retains the installed scope, detects whether the Skill is in Chinese or English, and only updates the platforms where Comet Skill has been installed
• **comet update Self-update npm Package **: update now prints and runs the npm update command corresponding to the detected package range before refreshing the installed Skill
• ** More friendly update output **: update will record npm commands, Skill copy commands for each target, the final npm status, the number of updated targets, the range, and the language summary
• **Init Overwrite process **: The interactive comet init now offers batch overwrite/skip options when multiple existing components are detected on the same platform
• **CLI Option verification **: update --language, update --scope, and doctor --scope now accept values through Commander’s choices verification
• **README CLI Documentation **: Updated the chapters on README commands in both Chinese and English, recording JSON output, doctor range, update behavior, status next step prompt, and init overwrite behavior
• **CONTRIBUTING Link **: A reference to the contribution guidelines has been added in the development sections of the Chinese and English README

​

Fixed

• **Doctor False Alarm **: comet doctor can now recognize the current .comet.yaml field, including verification_report and branch_status
• **npm README Image **: The README image now uses an absolute GitHub URL to ensure that the package page can be rendered correctly

​

Tests

• New test coverage added: update language/range detection, JSON output, friendly command display, status next step prompt, doctor current status verification, README image URL, init batch coverage selection, and PR title workflow configuration

​

Added

• ** Verification evidence mandatory verification **: The verify-pass advancement now requires verification_report (the file must exist) and branch_status: handled to be allowed to proceed to the next stage. The guards check these as hard and fast prerequisites
• ** verification_report and branch_status fields in .comet.yaml **: A new status field has been added to track and verify the report path and branch processing status
• ** Evidence Verification Steps in comet-verify (Chinese) **: Add Step 4, which requires creating a report file and recording the branch status before guarding the application
• **branch_status enumeration verification **: comet-state.sh set will verify branch_status as pending or handled
• ** Guard verify Check **: comet-guard.sh will now check verification_report exists and branch_status=handled in the verify stage
• **Bats Test CRLF Fix **: The Shell test removes \r from the script before execution, fixing Windows compatibility
• **test:shell Runner **: Replace the direct invocation of bats with node scripts/run-bats.js to support cross-platform compatibility

​

Changed

• **Hotfix root cause Check sequence adjustment **: Move the root cause elimination check before loading comet-verify ** (Step 3a is split into 3a/3b) to prevent it from being skipped in the verify process
• ** Simplify the Hotfix title description **: Replace the ambiguous “non-independent parallel process” with a direct “Quick bug-fixing workflow” that is clearly callable independently
• ** Remove non-operational steps in comet-design **: Step 3 (double-specification partitioning table) and Step 4 (document hierarchy) have been deleted - these are pure reference materials and do not contain agent operations
• ** Remove duplicate script Location blocks **: comet-open (Step 3) and comet-archive (Step 1) do not repeat the complete COMET_SEARCH_ROOTS find block when the variable has been cached
• ** Remove the 50% threshold that is repeated in comet-build **: Only mention it once in the threshold determination table and no longer repeat it in tables and lists
• ** General Error Handling **: In the comet main Skill’s error table, change “Maven compile/test” to “Build/test”, using language-independent wording
• **comet-state.sh Usage Help **: Fixed the order of check parameters (check <change-name> <phase>) in the help text

​

Fixed

• **comet-state.sh init Change Directory Resolution **: cmd_init now resolves change_dir before checking if .comet.yaml already exists, fixing the path resolution issue in nested directories
• **verify Phase Guard Deadlock **: The verify-pass propulsion now resets verification_report and branch_status when rolling back through verify-fail, preventing expired evidence from causing incorrect propulsion

​

Tests

• **comet-scripts.test.ts +66 lines **: New test coverage has been added to verify evidence blocking, branch status checking, and guard verify with evidence
• ** +12 lines in comet-state.bats **: New test coverage for enumeration verification of branch_status, removal of CRLF, and the existence of new fields in init output

​

Added

• **“Why Comet” Section **: The README now explains the design concept of Comet - HOW does it combine the WHAT management of OpenSpec with the How execution of Superpowers into a unified 5-stage pipeline
• **“Screenshots” Section **: Three new screenshots have been added to show the process of platform selection, initialization, and the actual execution of Skill
• **“What You’re Learning “Chapter **: A new chapter has been added, demonstrating Comet as a reference implementation for stable nested Skill triggering and multi-stage automatic flow modes
• **State Management YAML Example **: Expanded the documentation by adding complete .comet.yaml field examples, showing all key configuration values

​

Changed

• **comet-build Skill description **: It is clear that the execution mode (sub-agent or executing-plans) is chosen by the user based on the complexity of the task, rather than always being driven by the sub-agent
• ** Enhanced State Management Documentation **: Added instructions on how all states and stages are updated through scripts and completion checks are performed before the stage progresses

​

Fixed

• ** When comet init, Ctrl+Z/Ctrl+C crashes **: Wrap the inquirer prompt with try/catch to handle ExitPromptError, change it to display Cancelled. and exit clean, while hiding the original stack trace
• ** Repeat installation of Superpowers**: comet init now detects Superpowers (~/.claude/plugins/cache/) installed through the Claude Code plugin system and skips redundant npx skills add when the Superpowers plugin already exists

​

Fixed

• **CI pnpm version **: Added the packageManager field for pnpm/action-setup v4
• **Shell Script **: Fixed the spelling error of SCRIPT_DIR, renamed maven_compiles to build_passes (languagic-independent), fixed the path bug of check_nonempty, fixed the sed separator issue on the path value of cmd_set, and corrected the position of the shellcheck instruction
• **Node version **: The minimum version is upgraded to Node 20 (vitest v4 coverage requires node:inspector/promises)

​

Skill Reliability

• **SKILL.md dual-zone structure **: All 8 Skills are split into two parts: “Decision Core” (Stage detection, upgrade conditions, error handling) and “Reference Appendix” (Field reference, scripts, best practices)
• ** Quantified Upgrade conditions **: Hotfix/tweak now defines clear thresholds for upgrading to a full workflow (file count, cross-module coordination, architecture changes, etc.)
• ** Script location caching **: All skills use the ${VAR:-$(find ...)} environment variable caching mode to avoid repeated calls to find
• **manifest.json Fix **: The missing comet-state.sh and comet-archive.sh entries have been supplemented
• **comet-state.sh init Fix **: Now the workflow field will be written to .comet.yaml, fixing the previous issue where check design always failed

​

CLI Commands

• comet status: Displays the current active change stage, task progress, workflow mode, design documents and plans (supports --json)
• comet doctor: Diagnose installation health status - including OpenSpec CLI, working directory, Skill integrity on each platform, whether scripts exist, and the validity of .comet.yaml (supporting --json)
• comet update: Update the comet skill file to the latest version in the npm package (supporting --language, --scope)
• All commands support --json: init, status, doctor, and update can all output structured results

​

Engineering

• ** Test Suite **: 54 unit tests (5 suites), statement coverage rate 93.8%/function coverage rate 100%; 26 bats shell tests
• GitHub Actions CI: Perform build + lint + formatting + testing (Node 18/20/22) + shellcheck + bats when pushing /PR
• ESLint + Prettier: Code quality tools, invoked through pnpm lint/pnpm format
• ** Code Organization **: Split the monolithic init.ts (620 lines) into 5 focused core modules and 4 command modules
• ** Command Injection hardening **: Verify the platform/tool ID before constructing shell commands
• ** File-by-file error handling **: The copy loop continues to execute when a single file fails without interruption

​

Added

• comet-state.sh script: Unified state management, including 5 subcommands - init (create.comet.yaml), set (update with enumeration check), get (read fields), check (entry check), scale (check mode evaluation)
• check subcommand: Replace the text checklists in all 8 skills with scripted entry validation
• scale subcommand: Replace the prose decision rules in comet-verify with scripted scale evaluation

​

Changed

• All .comet.yaml writes go through comet-state.sh: No longer directly use sed -i — Perform enumeration check each time a field is written
• All skill Step 0 checklists replaced with check subcommand: a single command replaces text-based entry validation
• comet-guard.sh and comet-archive.sh use state.sh internally: All state changes are made through a unified interface
• Removed write-verification blocks: hotfix and tweak presets no longer include manual verification loops

​

Added

• comet-archive.sh script: One-click archiving automation - Verify entry status, synchronize delta spec to master spec (overwrite), add annotations for frontmatter of design doc and plan, move change to archive directory, update archived: true. Supports preview of --dry-run
• --apply mode for comet-guard.sh: Optional flag that automatically updates the .comet.yaml status field after all guard checks pass. There is no need to manually edit the status during stage transitions
• Idempotent frontmatter annotation: annotate_frontmatter() will skip the existing archived-with: lines and can be safely repeated

​

Changed

• Removed manual state editing: All stage conversions (design → build → verify → archive) are now changed to guard --apply instead of manually updating the .comet.yaml field and writing the verification loop
• Removed write-verification blocks: All [Write verification]/【Write verification】 patterns have been removed from the skills such as comet-open, comet-design, comet-build, comet-verify and comet-archive
• Removed ## ADDED/## MODIFIED/## REMOVED delta format: delta spec is now the complete spec; When archiving, directly overwrite the main spec and cancel fragment merging
• Removed step 2b from comet-open: Incremental modifications to existing capabilities are a new /comet-open — brainstorming will naturally read in the existing spec as context
• Simplified archive skill: Steps 1b to 5 are replaced with a comet-archive.sh call
• Updated comet/SKILL.md: The Script location section now records both the --apply mode and the archived script simultaneously

​

Removed

• few-shot YAML examples of the isolation, build_mode, and verify_mode fields (repeated with agent judgment)
• comet-archive’s dependency on openspec-archive-change skill (The archive script has handled all steps)

​

Added

• Workspace Isolation Selection: comet-build now prompts the user to choose between creating a branch or a worktree before execution begins (Step 3: Workspace Isolation)
• isolation field in .comet.yaml: A new required field (branch or worktree) has been added to record the user’s workspace isolation selection
• isolation enum validation: comet-yaml-validate.sh now validates isolation as a required field, with the allowed values being branch/worktree

​

Changed

• Step number adjustment for comet-build: Step 3 (Select the execution mode) → Step 4, Step 4 (Spec incremental update) → Step 5
• Hotfix and tweak default to using isolation: branch and no longer prompt users
• The REQUIRED_FIELDS and KNOWN_KEYS of comet-yaml-validate.sh have been updated, including isolation

​

Added

• Bilingual Comet skills: comet init now prompts to select the language (English/Chinese) and deploy the corresponding SKILL.md file
• Language-aware asset structure: English skills are placed in assets/skills/, and Chinese skills are placed in assets/skills-zh/
• languages field in manifest.json: Map the language ID to the resource directory for future expansion

​

Changed

• All 8 Comet SKILL.md files under assets/skills/ are now in English (the original Chinese version is retained in assets/skills-zh/).
• copyCometSkillsForPlatform accepts the parameters of languageSkillsDir; Script files are always obtained from the default skills/ directory
• By default, the --yes mode selects English

​

Fixed

• Superpowers redundant project level install: comet init now checks the global directory (~/{platform}/skills/) of all platforms selected by the user before installing Superpowers. If Superpowers has been globally installed on a selected platform, skip the project-level installation for that platform
• Unwanted .agents/ directory creation: comet init will now pass the --agent flag to skills add only for the platform chosen by the user. This avoids the skills CLI automatically detecting and installing to all platforms, thus eliminating the creation of redundant .agents/ directories
• OpenSpec global detection: Apply the same global directory rollback logic to OpenSpec detection to avoid reinstallation when it already exists globally on the selected platform

​

Changed

• hasSkills() accepts the selectedPlatforms parameters and limits the global detection range to the platform selected by the user
• installSuperpowersForPlatform() is replaced by installSuperpowersForPlatforms(), which accepts the platform ID and maps it to the agent name of the skills CLI via SKILLS_AGENT_MAP

​

Added

• State File Separation: The Comet workflow state is now stored in separate .comet.yaml files and is no longer placed in the subtree of .openspec.yaml
• Three-Layer Reliability Defense:
  • Entry verification at all stages, with [HARD STOP] diagnosis
  • All status changes adopt the mode of writing first and then checking
  • schema validation script (comet-yaml-validate.sh) supports field, enumeration and path validation
• Path Traversal Protection: Perform input validation on the change name to prevent directory traversal attacks
• Guard Script Integration: Automatically perform schema validation during stage transitions

​

Changed

• Update all 9 Comet skills and replace the comet: subtree of .openspec.yaml with .comet.yaml
• Improve error messages by replacing general placeholders with specific field values
• Improve the project structure documentation

​

Security

• Fixed the path traversal vulnerability caused by entering an unverified change name
• schema validation can now capture spelling mistakes and invalid enumeration values at the entry point