@rpamis/comet 0.3.6 → 0.3.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -29,6 +29,7 @@
 
 > 中文版：[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.
 
@@ -38,37 +39,75 @@ 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.
+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.
+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.
+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.
+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.
+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:
+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 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 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 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 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 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 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.
+- **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
 
@@ -130,14 +169,15 @@ npx skills add rpamis/comet
 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.
+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>
 
@@ -147,7 +187,7 @@ When multiple existing components are found on the same platform, interactive in
 Displays active changes, task progress, and the recommended next Comet workflow command.
 
 | Option   | Description                              |
-| -------- | ---------------------------------------- |
+|----------|------------------------------------------|
 | `--json` | Output active changes with `nextCommand` |
 
 </details>
@@ -158,7 +198,7 @@ Displays active changes, task progress, and the recommended next Comet workflow
 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`) |
 
@@ -170,7 +210,7 @@ Checks project/global installation health, working directories, installed skills
 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       |
@@ -178,7 +218,7 @@ Updates the npm package and refreshes installed Comet skills in detected project
 </details>
 
 | Command           | Description  |
-| ----------------- | ------------ |
+|-------------------|--------------|
 | `comet --help`    | Show help    |
 | `comet --version` | Show version |
 
@@ -190,7 +230,7 @@ Updates the npm package and refreshes installed Comet skills in detected project
 <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/`     |
@@ -208,7 +248,8 @@ Updates the npm package and refreshes installed Comet skills in detected project
 
 </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`.
+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
 
@@ -220,7 +261,7 @@ After `comet init`, three groups of skills are installed to the selected platfor
 <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)               |
@@ -237,14 +278,15 @@ After `comet init`, three groups of skills are installed to the selected platfor
 <details>
 <summary>View script list</summary>
 
-| Script                   | Purpose                                                                                               |
-| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| 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-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
+| `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>
 
@@ -274,7 +316,7 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 ### 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    |
@@ -294,11 +336,14 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 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.
+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>
@@ -307,11 +352,14 @@ All states and execution phases are updated via scripts, and each phase verifies
 
 ```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
@@ -326,7 +374,16 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `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.
+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>
 
@@ -338,38 +395,38 @@ Comet ensures agent execution reliability through automated state transitions:
 <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
+    - 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
+    - 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
+    - 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`
+    - `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
+    - `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, syncs delta specs to main specs
-   - Annotates design doc and plan frontmatter
-   - Moves change to archive directory and updates `archived: true`
-   - Supports `--dry-run` for preview
+    - 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>
 
@@ -377,6 +434,8 @@ Comet ensures agent execution reliability through automated state transitions:
 
 ```
 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/
@@ -385,6 +444,7 @@ your-project/
 │   │       ├── 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
@@ -404,9 +464,52 @@ your-project/
     └── 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) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
+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.
 
@@ -430,13 +533,22 @@ Track our development progress and upcoming features on the [Comet Roadmap](http
 
 ## Community
 
-<p align="center">
-  <img src="https://github.com/rpamis/comet/blob/master/img/wechat.jpg" alt="WeChat Group" width="200" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://github.com/rpamis/comet/blob/master/img/qq.jpg" alt="QQ Group" width="200" />
-</p>
-
-<p align="center">WeChat Group &nbsp;&nbsp;|&nbsp;&nbsp; QQ Group</p>
+<table align="center">
+  <tr>
+    <td align="center" width="180">
+      <img src="https://github.com/rpamis/comet/blob/master/img/douyin.png" width="120" height="120"><br>
+      <b>DouYin (Recommended)</b>
+    </td>
+    <td align="center" width="180">
+      <img src="https://github.com/rpamis/comet/blob/master/img/wechat.jpg" width="120" height="120"><br>
+      <b>WeChat</b>
+    </td>
+    <td align="center" width="180">
+      <img src="https://github.com/rpamis/comet/blob/master/img/qq.jpg" width="120" height="120"><br>
+      <b>QQ</b>
+    </td>
+  </tr>
+</table>
 
 ## Reference
 

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.2",
+  "version": "0.3.3",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/dirty-worktree.md",
@@ -9,6 +9,7 @@
     "comet/scripts/comet-handoff.sh",
     "comet/scripts/comet-archive.sh",
     "comet/scripts/comet-yaml-validate.sh",
+    "comet/scripts/comet-hook-guard.sh",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",
@@ -17,6 +18,15 @@
     "comet-hotfix/SKILL.md",
     "comet-tweak/SKILL.md"
   ],
+  "rules": [
+    "comet/rules/comet-phase-guard.md"
+  ],
+  "hooks": {
+    "comet/scripts/comet-hook-guard.sh": {
+      "matcher": "Write|Edit",
+      "description": "Block code writes in wrong Comet phase (open/design/archive)"
+    }
+  },
   "languages": [
     { "id": "en", "name": "English", "skillsDir": "skills" },
     { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }