@rpamis/comet 0.3.7 → 0.3.8

package/README.md

@@ -1,538 +1,558 @@
-<p align="center">
-  <a href="https://github.com/rpamis/comet/blob/master/img/title-log.png">
-    <picture>
-      <source srcset="https://github.com/rpamis/comet/blob/master/img/title-log.png">
-      <img src="https://github.com/rpamis/comet/blob/master/img/title-log.png" alt="Comet logo">
-    </picture>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rpamis/comet/ci.yml?branch=master&style=flat-square&label=CI" /></a>
-  <a href="https://deepwiki.com/rpamis/comet"><img alt="DeepWiki" src="https://img.shields.io/badge/DeepWiki-rpamis%2Fcomet-blue?style=flat-square" /></a>
-  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
-  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
-  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
-  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
-</p>
-
-# @rpamis/comet
-
-```
- ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
-██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
-██║     ██║   ██║██╔████╔██║█████╗     ██║
-██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
-╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
- ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝
-```
-
-> 中文版：[README-zh.md](README-zh.md)
-> [Bilibili video](https://www.bilibili.com/video/BV1y4Gi6CEo1/?spm_id_from=333.1387.homepage.video_card.click&vd_source=d22726fe6b108647dbebf1c5d8817377)
-> [DouYin](https://www.douyin.com/search/comet?aid=cd8fcc82-498b-4d59-8860-617deb719412&modal_id=7646429015808936293&type=general)
-
-**OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
-
-OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving).
-
-Superpowers handles **HOW** (technical design, planning, execution, wrap-up).
-
-Comet chains both into a five-phase automated pipeline.
-
-> [!IMPORTANT]
-> **0.3.7 Highlights** — One-step [CodeGraph](https://github.com/colbymchenry/codegraph) semantic code indexing (official: cost **↓16%**, tool calls **↓58%**); 
->
-> New **Beta context compression** cutting Build-phase input tokens by **25–30%**; 
-> New active context compression mechanism to release context consumed by reading specs and brainstorming, preserving window space for the subsequent Build phase.
-> 6 default-on workflow token optimizations; New `auto_transition` config for automatic or manual phase handoff; 
-> Hook+Rule anti-drift phase guard; Optional TDD mode and subagent dispatch confirmation; 
-> Large PRD split into multiple changes; Pre-archive confirmation with reopen, verify retry limit, systematic debugging interception, and verification completion check.
->
-> See [NEWS.md](NEWS.md) for details.
-
-## Why Comet
-
-OpenSpec excels at managing requirements, creating proposals, managing Spec lifecycles, and archiving, but its proposals
-and tasks lack the detail of Superpowers brainstorming.
-
-Superpowers generates Spec documents after brainstorming, but these documents typically lack stateful design — after
-completing requirements, Specs only have tasks checked off in the document, and Agents even forget to check them off.
-This causes the Agent to re-examine documents and project code to verify on resumption, wasting many tokens.
-
-**Comet combines the strengths of both**, integrating the core workflow into 5 phases
-
-The main entry `/comet` supports current Spec state detection, suitable for long tasks — after closing your AI coding
-session midway, just `/comet` and Comet will automatically read the active Spec (lists multiple for selection),
-dynamically identify which phase is currently executing, and continue.
-
-At the same time, Comet provides full Spec lifecycle management. During execution, it links OpenSpec change/spec
-artifacts with Superpowers design and planning documents, then automates handoff, state updates, validation, and archive
-sync so users do not have to repeatedly remind the Agent to keep documents synchronized and connected.
-
-## What You'll Learn
-
-Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may
-only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec
-management capabilities, but prefer Superpowers' TDD-driven approach for coding.
-
-Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real
-practice. The Comet project can serve as a reference:
-
-- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike
-  Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature:
-  Skill trigger prints on CC). Comet triggers many capabilities from OpenSpec and Superpowers. How is this Prompt
-  written?
-
-- **How to make combined Skills flow automatically across phases** — Not relying on manual intervention. Comet's 5-phase
-  flow can automatically trigger Skills for the core process except for necessary user choices, while the state machine
-  also protects state transition reliability.
-
-- **How to turn the Spec lifecycle into a resumable workflow** — Comet links OpenSpec change/spec artifacts with
-  Superpowers design and planning documents, then records phase, execution mode, verification results, and archive
-  status in `.comet.yaml`, so the Agent can resume after interruption instead of rereading documents and guessing
-  progress.
-
-- **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates,
-  validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design
-  doc", "remember to sync the spec", and "remember to archive the change".
-
-- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at
-  phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state
-  fields, verification evidence, and archive conditions before allowing the workflow to advance.
-
-- **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms,
-  project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as
-  Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package
-  structure.
-
-- **How to turn shell scripts into Agent workflow infrastructure** — Comet's scripts need to work across macOS, Linux,
-  and Windows Git Bash while handling hashes, YAML fields, state machines, and archive flows. It shows how to move
-  fragile workflow control out of scattered Prompt text and into testable, reusable tools.
-
-## Install
-
-Requirements:
-
-- Node.js 20+
-- npm/npx
-- Git
-- Bash-compatible shell for workflow scripts (Windows users should use Git Bash or an equivalent bash environment)
-
-```bash
-npm install -g @rpamis/comet
-```
-
-## Quick Start
-
-```bash
-cd your-project
-comet init
-```
-
-`comet init` will:
-
-1. Prompt you to select AI platforms (auto-detects existing configs)
-2. Choose install scope: project-level (current directory) or global (home directory)
-3. Select language for Comet skills: English or 中文
-4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
-5. Install [Superpowers](https://github.com/obra/superpowers) skills
-6. Deploy Comet skills (in your chosen language) to selected platforms
-7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories for project-scope installs
-
-> [!TIP]
-> update version
->
-> `comet update` or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
-
-## Support for OpenClaw and Hermes, and other AI platforms
-
-For platforms that use the generic `skills` CLI directly, you can install the Comet skill package with:
-
-```bash
-npx skills add rpamis/comet
-```
-
-## Screenshots
-
-<p align="center">
-  <img src="https://github.com/rpamis/comet/blob/master/img/runner.png" alt="runner">
-</p>
-
-<p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
-<p align="center">Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes</p>
-
-## Commands
-
-<details>
-<summary><code>comet init [path]</code> — Initialize Comet workflow</summary>
-
-Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
-
-| Option            | Description                                                                    |
-|-------------------|--------------------------------------------------------------------------------|
-| `--yes`           | Non-interactive mode, auto-select detected platforms (or all if none detected) |
-| `--scope <scope>` | Install scope: `project` or `global`                                           |
-| `--skip-existing` | Skip already installed components                                              |
-| `--overwrite`     | Overwrite already installed components                                         |
-| `--json`          | Output structured JSON                                                         |
-
-When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite
-all, skip all, or choose per component.
-
-</details>
-
-<details>
-<summary><code>comet status [path]</code> — Show active changes and next workflow command</summary>
-
-Displays active changes, task progress, and the recommended next Comet workflow command.
-
-| Option   | Description                              |
-|----------|------------------------------------------|
-| `--json` | Output active changes with `nextCommand` |
-
-</details>
-
-<details>
-<summary><code>comet doctor [path]</code> — Diagnose Comet installation health</summary>
-
-Checks project/global installation health, working directories, installed skills, scripts, and Comet state files.
-
-| Option            | Description                                                     |
-|-------------------|-----------------------------------------------------------------|
-| `--json`          | Output structured diagnostic results                            |
-| `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
-
-</details>
-
-<details>
-<summary><code>comet update [path]</code> — Update Comet package and skills</summary>
-
-Updates the npm package and refreshes installed Comet skills in detected project/global targets.
-
-| Option              | Description                                   |
-|---------------------|-----------------------------------------------|
-| `--json`            | Output npm and skill update results as JSON   |
-| `--language <lang>` | Override detected skill language (`en`, `zh`) |
-| `--scope <scope>`   | Update only `global` or `project` scope       |
-
-</details>
-
-| Command           | Description  |
-|-------------------|--------------|
-| `comet --help`    | Show help    |
-| `comet --version` | Show version |
-
-## Supported Platforms
-
-`comet init` supports 28 AI coding platforms:
-
-<details>
-<summary>View full platform list</summary>
-
-| Platform           | Skills Dir   | Platform   | Skills Dir    |
-|--------------------|--------------|------------|---------------|
-| Claude Code        | `.claude/`   | Cursor     | `.cursor/`    |
-| Codex              | `.codex/`    | OpenCode   | `.opencode/`  |
-| Windsurf           | `.windsurf/` | Cline      | `.cline/`     |
-| RooCode            | `.roo/`      | Continue   | `.continue/`  |
-| GitHub Copilot     | `.github/`   | Gemini CLI | `.gemini/`    |
-| Amazon Q Developer | `.amazonq/`  | Qwen Code  | `.qwen/`      |
-| Kilo Code          | `.kilocode/` | Auggie     | `.augment/`   |
-| Kiro               | `.kiro/`     | Lingma     | `.lingma/`    |
-| Junie              | `.junie/`    | CodeBuddy  | `.codebuddy/` |
-| CoStrict           | `.cospec/`   | Crush      | `.crush/`     |
-| Factory Droid      | `.factory/`  | iFlow      | `.iflow/`     |
-| Pi                 | `.pi/`       | Qoder      | `.qoder/`     |
-| Antigravity        | `.agents/`   | Bob Shell  | `.bob/`       |
-| ForgeCode          | `.forge/`    | Trae       | `.trae/`      |
-
-</details>
-
-Some platforms use different project and global directories. For example, OpenCode global installs use
-`.config/opencode`, Lingma global installs use `.lingma`, and Antigravity global installs use `.gemini/antigravity`.
-
-## Skills
-
-After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
-
-### Comet Skills
-
-<details>
-<summary>View Comet skills</summary>
-
-| Skill            | Description                                                    |
-|------------------|----------------------------------------------------------------|
-| `/comet`         | Main entry — auto-detects phase and dispatches to sub-commands |
-| `/comet-open`    | Phase 1: Open a change (proposal, design, task breakdown)      |
-| `/comet-design`  | Phase 2: Deep design (brainstorming, Design Doc)               |
-| `/comet-build`   | Phase 3: Plan and build (implementation plan, code commits)    |
-| `/comet-verify`  | Phase 4: Verify and finish (testing, verification report)      |
-| `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation)          |
-| `/comet-hotfix`  | Preset: Quick bug fix (skips brainstorming)                    |
-| `/comet-tweak`   | Preset: Small change (skips brainstorming and full plan)       |
-
-</details>
-
-### Guard & Automation Scripts
-
-<details>
-<summary>View script list</summary>
-
-| Script                   | Purpose                                                                                                                           |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `comet-env.sh`           | Script discovery helper — exports bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` |
-| `comet-guard.sh`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`                                          |
-| `comet-handoff.sh`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing                             |
-| `comet-archive.sh`       | One-command archive — validates state, syncs specs, moves to archive, updates status                                              |
-| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values                                                             |
-| `comet-hook-guard.sh`    | Phase write guard — PreToolUse hook, blocks file writes during open/design/archive phases                                         |
-| `comet-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                                             |
-
-</details>
-
-### OpenSpec Skills
-
-Spec lifecycle management: propose, explore, sync, verify, archive, and more.
-
-### Superpowers Skills
-
-Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
-
-## Workflow
-
-```
-/comet
-  ↓ auto-detect
-/comet-open  -->  /comet-design  -->  /comet-build  -->  /comet-verify  -->  /comet-archive
-(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)
-
-/comet-hotfix (preset path, skips brainstorming)
-  open  -->  build  -->  verify  -->  archive
-
-/comet-tweak (preset path, skips brainstorming and full plan)
-  open  -->  lightweight build  -->  light verify  -->  archive
-```
-
-### Five Phases
-
-| Phase              | Command          | Owner       | Artifacts                            |
-|--------------------|------------------|-------------|--------------------------------------|
-| 1. Open            | `/comet-open`    | OpenSpec    | proposal.md, design.md, tasks.md     |
-| 2. Deep Design     | `/comet-design`  | Superpowers | Design Doc, delta spec               |
-| 3. Plan & Build    | `/comet-build`   | Superpowers | Implementation plan, code commits    |
-| 4. Verify & Finish | `/comet-verify`  | Both        | Verification report, branch handling |
-| 5. Archive         | `/comet-archive` | OpenSpec    | delta→main spec sync, archive        |
-
-### Core Principles
-
-- **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
-- **Delta specs are living documents** — freely editable during Phase 3, synced at archive
-- **Keep tasks.md in sync** — check off each task as completed
-- **Commit frequently** — one commit per task, message reflects design intent
-- **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
-
-### State Management
-
-Comet uses a decoupled state architecture with separate YAML files:
-
-| File             | Owner    | Purpose                                             |
-|------------------|----------|-----------------------------------------------------|
-| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata                     |
-| `.comet.yaml`    | Comet    | Workflow phase, execution mode, verification status |
-
-All states and execution phases are updated via scripts, and each phase verifies that tasks are truly complete before
-advancing. Compared to storing complex state rules only in Skill text, this script-backed state machine gives Comet more
-reliable phase transitions, correct YAML, and easier breakpoint recovery; agents can read the current Spec situation
-through Comet's built-in commands.
-
-<details>
-<summary>View key .comet.yaml fields</summary>
-
-**Key Fields in `.comet.yaml`:**
-
-```yaml
-workflow: full
-auto_transition: true
-phase: build
-build_mode: subagent-driven-development
-build_pause: null
-isolation: branch
-verify_mode: null
-tdd_mode: null
-subagent_dispatch: null
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
-verify_result: pending
-verification_report: null
-branch_status: pending
-verified_at: null
-archived: false
-direct_override: false
-build_command: null
-verify_command: null
-handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
-handoff_hash: <sha256>
-```
-
-In full workflow, `build_mode`, `build_pause`, `isolation`, `verify_mode`, `tdd_mode`, and `subagent_dispatch` may
-temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `auto_transition` controls automatic vs manual skill invocation after phase completion — see [AUTO-TRANSITION.md](docs/AUTO-TRANSITION.md). `build_pause` records an internal build-phase pause point:
-`null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing
-isolation and execution mode. It is not an execution mode and must not be written into `build_mode`.
-`verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist
-plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override`
-is only needed for full-workflow direct builds, project commands may be absent unless configured, and
-`handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure
-`build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure
-output.
-
-</details>
-
-### Reliability Features
-
-Comet ensures agent execution reliability through automated state transitions:
-
-<details>
-<summary>View reliability features</summary>
-
-1. **Entry Verification** — Each phase validates preconditions before execution
-    - Checks file existence, state consistency, and phase transitions
-    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
-
-2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
-    - All phase transitions (open → design/build → verify → archive) use `guard --apply`
-    - No manual state editing required — eliminates write-verification errors
-    - `comet-state.sh` is the agents' exclusive interface for state operations
-    - Guard and archive scripts use `comet-state.sh` internally for state management
-
-3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-    - Validates required and optional fields
-    - Validates enum values, including `direct_override`
-    - Validates `design_doc`, `plan`, and `handoff_context` paths exist, plus `handoff_hash` format
-    - Detects unknown/typos fields
-
-4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
-    - `isolation` must be `branch` or `worktree`
-    - `build_mode` must be selected before leaving build
-    - `build_pause: plan-ready` is a recoverable pause after plan generation, not a `build_mode`
-    - Full workflow `build_mode: direct` requires `direct_override: true`
-
-5. **Verification Evidence** — Guard enforces proof before phase advance
-    - `verify-pass` transition requires `verification_report` pointing to an existing report file
-    - `branch_status` must be `handled` before verify can pass
-    - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
-    - Prevents false phase advances when verification or branch handling was skipped
-
-6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
-    - Validates entry state, merges delta specs into main specs through OpenSpec
-    - Annotates design doc and plan frontmatter
-    - Moves change to archive directory and updates `archived: true`
-    - Supports `--dry-run` for preview
-
-</details>
-
-## Project Structure
-
-```
-your-project/
-├── .comet/
-│   └── config.yaml              # Project-level global config (context_compression, auto_transition, etc.)
-├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
-│   ├── comet/SKILL.md
-│   │   └── scripts/
-│   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
-│   │       ├── comet-env.sh         # Script discovery helper
-│   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
-│   │       ├── comet-archive.sh     # One-command archive automation
-│   │       ├── comet-yaml-validate.sh # Schema validator
-│   │       ├── comet-hook-guard.sh   # Phase write guard (PreToolUse hook)
-│   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
-│   ├── comet-*/SKILL.md
-│   ├── openspec-*/SKILL.md
-│   └── brainstorming/SKILL.md
-├── openspec/                    # OpenSpec — WHAT
-│   ├── config.yaml
-│   └── changes/
-│       └── <name>/
-│           ├── .openspec.yaml       # OpenSpec state
-│           ├── .comet.yaml          # Comet workflow state (decoupled)
-│           ├── proposal.md
-│           ├── design.md
-│           ├── specs/<capability>/spec.md
-│           └── tasks.md
-└── docs/superpowers/            # Superpowers — HOW
-    ├── specs/                   # Design documents
-    └── plans/                   # Implementation plans
-```
-
-<details>
-<summary>Context Compression (Beta)</summary>
-
-Comet supports context compression at the Design → Build handoff. When enabled, `comet-handoff.sh` generates a compact
-context package that reduces Build-phase input tokens by **25–30%** without affecting implementation correctness.
-
-| Mode   | Behavior                                 | Token Savings |
-|--------|------------------------------------------|---------------|
-| `off`  | Full Spec excerpts in handoff context    | Baseline      |
-| `beta` | Design Doc + SHA256 hash references only | ~25–30%       |
-
-Key findings from benchmark testing:
-
-- **Test pass rate**: 100% across all tiers (compression does not affect correctness)
-- **Spec coverage**: 100% (off) vs 95% (beta) — minor edge-case detail loss
-- **Scaling**: Larger tasks yield higher absolute savings (up to 15,000 tokens for large-tier tasks)
-
-Enable in `.comet/config.yaml`: `context_compression: beta`
-
-See [CONTEXT-COMPRESSION.md](docs/CONTEXT-COMPRESSION.md) for the full benchmark report, compression principles, and
-reproduction steps.
-
-</details>
-
-<details>
-<summary>Auto Transition</summary>
-
-`auto_transition` controls whether Comet automatically invokes the next skill after a phase completes, or pauses for
-manual handoff. Phase advancement itself always happens — this setting only affects skill invocation.
-
-| Value  | Behavior |
-|--------|----------|
-| `true` | Auto-invoke the next skill after each phase (default) |
-| `false` | Pause after each phase; user manually triggers the next skill |
-
-Three-layer configuration with precedence: `COMET_AUTO_TRANSITION` env var > `.comet/config.yaml` (project) > `.comet.yaml` (change).
-
-See [AUTO-TRANSITION.md](docs/AUTO-TRANSITION.md) for configuration details, workflow mapping, and FAQ.
-
-</details>
-
-## Development
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) | [中文版](CONTRIBUTING-zh.md) for development setup, commit
-conventions, PR process, branch workflow, and guidance for adding platforms,
-skills, scripts, or changelog entries.
-
-See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
-
-## Roadmap
-
-Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
-
-## Contributors
-
-<a href="https://github.com/rpamis/comet/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=rpamis/comet&columns=12&anon=1" />
-</a>
-
-## License
-
-[MIT](LICENSE)
-
-## Community
-
+<p align="center">
+  <a href="https://github.com/rpamis/comet/blob/master/img/title-log.png">
+    <picture>
+      <source srcset="https://github.com/rpamis/comet/blob/master/img/title-log.png">
+      <img src="https://github.com/rpamis/comet/blob/master/img/title-log.png" alt="Comet logo">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rpamis/comet/ci.yml?branch=master&style=flat-square&label=CI" /></a>
+  <a href="https://deepwiki.com/rpamis/comet"><img alt="DeepWiki" src="https://img.shields.io/badge/DeepWiki-rpamis%2Fcomet-blue?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+</p>
+
+# @rpamis/comet
+
+```
+ ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
+██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
+██║     ██║   ██║██╔████╔██║█████╗     ██║
+██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
+╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
+ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝
+```
+
+> 中文版：[README-zh.md](README-zh.md)
+> [Bilibili video](https://www.bilibili.com/video/BV1y4Gi6CEo1/?spm_id_from=333.1387.homepage.video_card.click&vd_source=d22726fe6b108647dbebf1c5d8817377)
+> [DouYin](https://www.douyin.com/search/comet?aid=cd8fcc82-498b-4d59-8860-617deb719412&modal_id=7646429015808936293&type=general)
+
+**OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
+
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving).
+
+Superpowers handles **HOW** (technical design, planning, execution, wrap-up).
+
+Comet chains both into a five-phase automated pipeline.
+
+> [!IMPORTANT]
+> **0.3.7 Highlights** — One-step [CodeGraph](https://github.com/colbymchenry/codegraph) semantic code indexing (official: cost **↓16%**, tool calls **↓58%**); 
+>
+> New **Beta context compression** cutting Build-phase input tokens by **25–30%**; 
+> New active context compression mechanism to release context consumed by reading specs and brainstorming, preserving window space for the subsequent Build phase.
+> 6 default-on workflow token optimizations; New `auto_transition` config for automatic or manual phase handoff; 
+> Hook+Rule anti-drift phase guard; Optional TDD mode and subagent dispatch confirmation; 
+> Large PRD split into multiple changes; Pre-archive confirmation with reopen, verify retry limit, systematic debugging interception, and verification completion check.
+>
+> See [NEWS.md](NEWS.md) for details.
+
+## Why Comet
+
+OpenSpec excels at managing requirements, creating proposals, managing Spec lifecycles, and archiving, but its proposals
+and tasks lack the detail of Superpowers brainstorming.
+
+Superpowers generates Spec documents after brainstorming, but these documents typically lack stateful design — after
+completing requirements, Specs only have tasks checked off in the document, and Agents even forget to check them off.
+This causes the Agent to re-examine documents and project code to verify on resumption, wasting many tokens.
+
+**Comet combines the strengths of both**, integrating the core workflow into 5 phases
+
+The main entry `/comet` supports current Spec state detection, suitable for long tasks — after closing your AI coding
+session midway, just `/comet` and Comet will automatically read the active Spec (lists multiple for selection),
+dynamically identify which phase is currently executing, and continue.
+
+At the same time, Comet provides full Spec lifecycle management. During execution, it links OpenSpec change/spec
+artifacts with Superpowers design and planning documents, then automates handoff, state updates, validation, and archive
+sync so users do not have to repeatedly remind the Agent to keep documents synchronized and connected.
+
+## What You'll Learn
+
+Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may
+only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec
+management capabilities, but prefer Superpowers' TDD-driven approach for coding.
+
+Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real
+practice. The Comet project can serve as a reference:
+
+- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike
+  Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature:
+  Skill trigger prints on CC). Comet triggers many capabilities from OpenSpec and Superpowers. How is this Prompt
+  written?
+
+- **How to make combined Skills flow automatically across phases** — Not relying on manual intervention. Comet's 5-phase
+  flow can automatically trigger Skills for the core process except for necessary user choices, while the state machine
+  also protects state transition reliability.
+
+- **How to turn the Spec lifecycle into a resumable workflow** — Comet links OpenSpec change/spec artifacts with
+  Superpowers design and planning documents, then records phase, execution mode, verification results, and archive
+  status in `.comet.yaml`, so the Agent can resume after interruption instead of rereading documents and guessing
+  progress.
+
+- **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates,
+  validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design
+  doc", "remember to sync the spec", and "remember to archive the change".
+
+- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at
+  phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state
+  fields, verification evidence, and archive conditions before allowing the workflow to advance.
+
+- **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms,
+  project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as
+  Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package
+  structure.
+
+- **How to turn shell scripts into Agent workflow infrastructure** — Comet's scripts need to work across macOS, Linux,
+  and Windows Git Bash while handling hashes, YAML fields, state machines, and archive flows. It shows how to move
+  fragile workflow control out of scattered Prompt text and into testable, reusable tools.
+
+## Install
+
+Requirements:
+
+- Node.js 20+
+- npm/npx
+- Git
+- Bash-compatible shell for workflow scripts (Windows users should use Git Bash or an equivalent bash environment)
+
+```bash
+npm install -g @rpamis/comet
+```
+
+## Quick Start
+
+```bash
+cd your-project
+comet init
+```
+
+`comet init` will:
+
+1. Prompt you to select AI platforms (auto-detects existing configs)
+2. Choose install scope: project-level (current directory) or global (home directory)
+3. Select language for Comet skills: English or 中文
+4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
+5. Install [Superpowers](https://github.com/obra/superpowers) skills
+6. Deploy Comet skills (in your chosen language) to selected platforms
+7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories for project-scope installs
+
+> [!TIP]
+> update version
+>
+> `comet update` or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
+
+## Support for OpenClaw and Hermes, and other AI platforms
+
+For platforms that use the generic `skills` CLI directly, you can install the Comet skill package with:
+
+```bash
+npx skills add rpamis/comet
+```
+
+## Screenshots
+
+<p align="center">
+  <img src="https://github.com/rpamis/comet/blob/master/img/runner.png" alt="runner">
+</p>
+
+<p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
+<p align="center">Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes</p>
+
+## Commands
+
+<details>
+<summary><code>comet init [path]</code> — Initialize Comet workflow</summary>
+
+Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
+
+| Option            | Description                                                                    |
+|-------------------|--------------------------------------------------------------------------------|
+| `--yes`           | Non-interactive mode, auto-select detected platforms (or all if none detected) |
+| `--scope <scope>` | Install scope: `project` or `global`                                           |
+| `--skip-existing` | Skip already installed components                                              |
+| `--overwrite`     | Overwrite already installed components                                         |
+| `--json`          | Output structured JSON                                                         |
+
+When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite
+all, skip all, or choose per component.
+
+</details>
+
+<details>
+<summary><code>comet status [path]</code> — Show active changes and next workflow command</summary>
+
+Displays active changes, task progress, and the recommended next Comet workflow command.
+
+| Option   | Description                              |
+|----------|------------------------------------------|
+| `--json` | Output active changes with `nextCommand` |
+
+</details>
+
+<details>
+<summary><code>comet doctor [path]</code> — Diagnose Comet installation health</summary>
+
+Checks project/global installation health, working directories, installed skills, scripts, and Comet state files.
+
+| Option            | Description                                                     |
+|-------------------|-----------------------------------------------------------------|
+| `--json`          | Output structured diagnostic results                            |
+| `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
+
+</details>
+
+<details>
+<summary><code>comet update [path]</code> — Update Comet package and skills</summary>
+
+Updates the npm package and refreshes installed Comet skills in detected project/global targets.
+
+| Option              | Description                                   |
+|---------------------|-----------------------------------------------|
+| `--json`            | Output npm and skill update results as JSON   |
+| `--language <lang>` | Override detected skill language (`en`, `zh`) |
+| `--scope <scope>`   | Update only `global` or `project` scope       |
+
+</details>
+
+<details>
+<summary><code>comet uninstall [path]</code> — Remove Comet skills, rules, and hooks</summary>
+
+Safely removes Comet-distributed skills, rules, and hooks from all detected platforms. Preserves user-defined hooks and non-Comet configuration.
+
+| Option            | Description                                    |
+|-------------------|------------------------------------------------|
+| `--force`         | Skip confirmation prompt                       |
+| `--scope <scope>` | Uninstall only `global` or `project` scope     |
+| `--json`          | Output removal results as JSON                 |
+
+```bash
+comet uninstall              # Interactive — shows targets, asks for confirmation
+comet uninstall --force      # Non-interactive — removes everything immediately
+comet uninstall --scope project  # Only remove project-level installations
+```
+
+</details>
+
+| Command           | Description  |
+|-------------------|--------------|
+| `comet --help`    | Show help    |
+| `comet --version` | Show version |
+
+## Supported Platforms
+
+`comet init` supports 29 AI coding platforms:
+
+<details>
+<summary>View full platform list</summary>
+
+| Platform           | Skills Dir   | Platform   | Skills Dir    |
+|--------------------|--------------|------------|---------------|
+| Claude Code        | `.claude/`   | Cursor     | `.cursor/`    |
+| Codex              | `.codex/`    | OpenCode   | `.opencode/`  |
+| Windsurf           | `.windsurf/` | Cline      | `.cline/`     |
+| RooCode            | `.roo/`      | Continue   | `.continue/`  |
+| GitHub Copilot     | `.github/`   | Gemini CLI | `.gemini/`    |
+| Amazon Q Developer | `.amazonq/`  | Qwen Code  | `.qwen/`      |
+| Kilo Code          | `.kilocode/` | Auggie     | `.augment/`   |
+| Kimi Code          | `.kimi-code/`| Kiro       | `.kiro/`      |
+| Lingma             | `.lingma/`   | Junie      | `.junie/`     |
+| CodeBuddy          | `.codebuddy/`| CoStrict   | `.cospec/`    |
+| Crush              | `.crush/`    | Factory Droid | `.factory/` |
+| iFlow              | `.iflow/`    | Pi         | `.pi/`        |
+| Qoder              | `.qoder/`    | Antigravity | `.agents/`   |
+| Bob Shell          | `.bob/`      | ForgeCode  | `.forge/`     |
+| Trae               | `.trae/`     |            |               |
+
+</details>
+
+Some platforms use different project and global directories. For example, OpenCode global installs use
+`.config/opencode`, Lingma global installs use `.lingma`, and Antigravity global installs use `.gemini/antigravity`.
+
+## Skills
+
+After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
+
+### Comet Skills
+
+<details>
+<summary>View Comet skills</summary>
+
+| Skill            | Description                                                    |
+|------------------|----------------------------------------------------------------|
+| `/comet`         | Main entry — auto-detects phase and dispatches to sub-commands |
+| `/comet-open`    | Phase 1: Open a change (proposal, design, task breakdown)      |
+| `/comet-design`  | Phase 2: Deep design (brainstorming, Design Doc)               |
+| `/comet-build`   | Phase 3: Plan and build (implementation plan, code commits)    |
+| `/comet-verify`  | Phase 4: Verify and finish (testing, verification report)      |
+| `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation)          |
+| `/comet-hotfix`  | Preset: Quick bug fix (skips brainstorming)                    |
+| `/comet-tweak`   | Preset: Small change (skips brainstorming and full plan)       |
+
+</details>
+
+### Guard & Automation Scripts
+
+<details>
+<summary>View script list</summary>
+
+| Script                   | Purpose                                                                                                                           |
+|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `comet-env.sh`           | Script discovery helper — exports bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` |
+| `comet-guard.sh`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`                                          |
+| `comet-handoff.sh`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing                             |
+| `comet-archive.sh`       | One-command archive — validates state, syncs specs, moves to archive, updates status                                              |
+| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values                                                             |
+| `comet-hook-guard.sh`    | Phase write guard — PreToolUse hook, blocks file writes during open/design/archive phases                                         |
+| `comet-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                                             |
+
+</details>
+
+### OpenSpec Skills
+
+Spec lifecycle management: propose, explore, sync, verify, archive, and more.
+
+### Superpowers Skills
+
+Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
+
+## Workflow
+
+```
+/comet
+  ↓ auto-detect
+/comet-open  -->  /comet-design  -->  /comet-build  -->  /comet-verify  -->  /comet-archive
+(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)
+
+/comet-hotfix (preset path, skips brainstorming)
+  open  -->  build  -->  verify  -->  archive
+
+/comet-tweak (preset path, skips brainstorming and full plan)
+  open  -->  lightweight build  -->  light verify  -->  archive
+```
+
+### Five Phases
+
+| Phase              | Command          | Owner       | Artifacts                            |
+|--------------------|------------------|-------------|--------------------------------------|
+| 1. Open            | `/comet-open`    | OpenSpec    | proposal.md, design.md, tasks.md     |
+| 2. Deep Design     | `/comet-design`  | Superpowers | Design Doc, delta spec               |
+| 3. Plan & Build    | `/comet-build`   | Superpowers | Implementation plan, code commits    |
+| 4. Verify & Finish | `/comet-verify`  | Both        | Verification report, branch handling |
+| 5. Archive         | `/comet-archive` | OpenSpec    | delta→main spec sync, archive        |
+
+### Core Principles
+
+- **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
+- **Delta specs are living documents** — freely editable during Phase 3, synced at archive
+- **Keep tasks.md in sync** — check off each task as completed
+- **Commit frequently** — one commit per task, message reflects design intent
+- **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
+
+### State Management
+
+Comet uses a decoupled state architecture with separate YAML files:
+
+| File             | Owner    | Purpose                                             |
+|------------------|----------|-----------------------------------------------------|
+| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata                     |
+| `.comet.yaml`    | Comet    | Workflow phase, execution mode, verification status |
+
+All states and execution phases are updated via scripts, and each phase verifies that tasks are truly complete before
+advancing. Compared to storing complex state rules only in Skill text, this script-backed state machine gives Comet more
+reliable phase transitions, correct YAML, and easier breakpoint recovery; agents can read the current Spec situation
+through Comet's built-in commands.
+
+<details>
+<summary>View key .comet.yaml fields</summary>
+
+**Key Fields in `.comet.yaml`:**
+
+```yaml
+workflow: full
+auto_transition: true
+phase: build
+build_mode: subagent-driven-development
+build_pause: null
+isolation: branch
+verify_mode: null
+tdd_mode: null
+subagent_dispatch: null
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+verify_result: pending
+verification_report: null
+branch_status: pending
+verified_at: null
+archived: false
+direct_override: false
+build_command: null
+verify_command: null
+handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
+handoff_hash: <sha256>
+```
+
+In full workflow, `build_mode`, `build_pause`, `isolation`, `verify_mode`, `tdd_mode`, and `subagent_dispatch` may
+temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `auto_transition` controls automatic vs manual skill invocation after phase completion — see [AUTO-TRANSITION.md](docs/AUTO-TRANSITION.md). `build_pause` records an internal build-phase pause point:
+`null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing
+isolation and execution mode. It is not an execution mode and must not be written into `build_mode`.
+`verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist
+plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override`
+is only needed for full-workflow direct builds, project commands may be absent unless configured, and
+`handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure
+`build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure
+output.
+
+</details>
+
+### Reliability Features
+
+Comet ensures agent execution reliability through automated state transitions:
+
+<details>
+<summary>View reliability features</summary>
+
+1. **Entry Verification** — Each phase validates preconditions before execution
+    - Checks file existence, state consistency, and phase transitions
+    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
+
+2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
+    - All phase transitions (open → design/build → verify → archive) use `guard --apply`
+    - No manual state editing required — eliminates write-verification errors
+    - `comet-state.sh` is the agents' exclusive interface for state operations
+    - Guard and archive scripts use `comet-state.sh` internally for state management
+
+3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
+    - Validates required and optional fields
+    - Validates enum values, including `direct_override`
+    - Validates `design_doc`, `plan`, and `handoff_context` paths exist, plus `handoff_hash` format
+    - Detects unknown/typos fields
+
+4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
+    - `isolation` must be `branch` or `worktree`
+    - `build_mode` must be selected before leaving build
+    - `build_pause: plan-ready` is a recoverable pause after plan generation, not a `build_mode`
+    - Full workflow `build_mode: direct` requires `direct_override: true`
+
+5. **Verification Evidence** — Guard enforces proof before phase advance
+    - `verify-pass` transition requires `verification_report` pointing to an existing report file
+    - `branch_status` must be `handled` before verify can pass
+    - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
+    - Prevents false phase advances when verification or branch handling was skipped
+
+6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+    - Validates entry state, merges delta specs into main specs through OpenSpec
+    - Annotates design doc and plan frontmatter
+    - Moves change to archive directory and updates `archived: true`
+    - Supports `--dry-run` for preview
+
+</details>
+
+## Project Structure
+
+```
+your-project/
+├── .comet/
+│   └── config.yaml              # Project-level global config (context_compression, auto_transition, etc.)
+├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
+│   ├── comet/SKILL.md
+│   │   └── scripts/
+│   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-env.sh         # Script discovery helper
+│   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
+│   │       ├── comet-archive.sh     # One-command archive automation
+│   │       ├── comet-yaml-validate.sh # Schema validator
+│   │       ├── comet-hook-guard.sh   # Phase write guard (PreToolUse hook)
+│   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
+│   ├── comet-*/SKILL.md
+│   ├── openspec-*/SKILL.md
+│   └── brainstorming/SKILL.md
+├── openspec/                    # OpenSpec — WHAT
+│   ├── config.yaml
+│   └── changes/
+│       └── <name>/
+│           ├── .openspec.yaml       # OpenSpec state
+│           ├── .comet.yaml          # Comet workflow state (decoupled)
+│           ├── proposal.md
+│           ├── design.md
+│           ├── specs/<capability>/spec.md
+│           └── tasks.md
+└── docs/superpowers/            # Superpowers — HOW
+    ├── specs/                   # Design documents
+    └── plans/                   # Implementation plans
+```
+
+<details>
+<summary>Context Compression (Beta)</summary>
+
+Comet supports context compression at the Design → Build handoff. When enabled, `comet-handoff.sh` generates a compact
+context package that reduces Build-phase input tokens by **25–30%** without affecting implementation correctness.
+
+| Mode   | Behavior                                 | Token Savings |
+|--------|------------------------------------------|---------------|
+| `off`  | Full Spec excerpts in handoff context    | Baseline      |
+| `beta` | Design Doc + SHA256 hash references only | ~25–30%       |
+
+Key findings from benchmark testing:
+
+- **Test pass rate**: 100% across all tiers (compression does not affect correctness)
+- **Spec coverage**: 100% (off) vs 95% (beta) — minor edge-case detail loss
+- **Scaling**: Larger tasks yield higher absolute savings (up to 15,000 tokens for large-tier tasks)
+
+Enable in `.comet/config.yaml`: `context_compression: beta`
+
+See [CONTEXT-COMPRESSION.md](docs/CONTEXT-COMPRESSION.md) for the full benchmark report, compression principles, and
+reproduction steps.
+
+</details>
+
+<details>
+<summary>Auto Transition</summary>
+
+`auto_transition` controls whether Comet automatically invokes the next skill after a phase completes, or pauses for
+manual handoff. Phase advancement itself always happens — this setting only affects skill invocation.
+
+| Value  | Behavior |
+|--------|----------|
+| `true` | Auto-invoke the next skill after each phase (default) |
+| `false` | Pause after each phase; user manually triggers the next skill |
+
+Three-layer configuration with precedence: `COMET_AUTO_TRANSITION` env var > `.comet/config.yaml` (project) > `.comet.yaml` (change).
+
+See [AUTO-TRANSITION.md](docs/AUTO-TRANSITION.md) for configuration details, workflow mapping, and FAQ.
+
+</details>
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) | [中文版](CONTRIBUTING-zh.md) for development setup, commit
+conventions, PR process, branch workflow, and guidance for adding platforms,
+skills, scripts, or changelog entries.
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
+## Roadmap
+
+Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
+
+## Contributors
+
+<a href="https://github.com/rpamis/comet/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=rpamis/comet&columns=12&anon=1" />
+</a>
+
+## License
+
+[MIT](LICENSE)
+
+## Community
+
 <table align="center">
   <tr>
     <td align="center" width="180">
@@ -549,7 +569,7 @@ Track our development progress and upcoming features on the [Comet Roadmap](http
     </td>
   </tr>
 </table>
-
-## Reference
-
-[LINUX DO - 新的理想型社区](https://linux.do/)
+
+## Reference
+
+[LINUX DO - 新的理想型社区](https://linux.do/)