docs: enhance README with rationale, screenshots, and learning guide

- Add "Why Comet" section explaining the fusion of OpenSpec + Superpowers
- Add "Screenshots" section with platform selection, init, and skill execution
- Add "What You'll Learn" section showcasing Comet as a reference
- Extend State Management with complete YAML example
- Clarify comet-build execution mode is user-selectable

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: benym

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.2.3] - 2026-05-19
+
+### Added
+
+- **"Why Comet" section**: README now explains the rationale behind Comet — how it combines OpenSpec's WHAT management with Superpowers' HOW execution into a unified 5-phase pipeline
+- **"Screenshots" section**: Added three screenshots demonstrating platform selection, initialization, and skill execution in action
+- **"What You'll Learn" section**: New section showcasing Comet as a reference for stable nested skill triggering and multi-phase auto-flow patterns
+- **State Management YAML example**: Extended documentation with complete `.comet.yaml` field example showing all key configuration values
+
+### Changed
+
+- **comet-build skill description**: Clarified that execution mode (subagent vs executing-plans) is user-selectable based on task complexity, not always subagent-driven
+- **Enhanced State Management docs**: Added explanation of how all states and phases are updated via scripts with completion validation before phase transitions
+
 ## What's Changed [0.2.2] - 2026-05-18
 
 ### Fixed

README-zh.md

@@ -15,6 +15,16 @@
 
 OpenSpec 处理 **WHAT**（大纲、提案、spec 生命周期、归档）。Superpowers 处理 **HOW**（技术设计、规划、执行、收尾）。Comet 将二者串联为五阶段自动化流水线。
 
+## 为什么需要 Comet
+
+OpenSpec 擅长管理需求、做提案、管理 Spec 生命周期和归档，但使用过程中 OpenSpec 的提案和 Task 没有像 Superpowers 头脑风暴那样细致。
+
+Superpowers 在头脑风暴后会产出 Spec 文档，但这个文档通常没有进行状态化设计——做完需求之后 Spec 仅在文档上对 Task 打勾，甚至 Agent 还会忘记打勾，造成下一次断点开始时，Agent 需要重新查看文档和项目代码来核验，产生较多 Token 浪费。
+
+**Comet 合并了两者的强项**，将核心流程整合为 5 个阶段
+
+主入口 `/comet` 支持当前 Spec 状态检测，适用于长任务——中途完成后关闭 CC，回来只需 `/comet 继续`，Comet 会自动读取活跃的 Spec（多个则列出选择），动态识别当前执行到哪个阶段，继续往下执行。
+
 ## 安装
 
 ```bash
@@ -38,7 +48,24 @@ comet init
 6. 将 Comet 技能（你选择的语言）部署到所选平台
 7. 创建 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 工作目录
 
-## 命令
+## 运行截图
+
+<p align="center">
+  <img src="img/select-platform.png" alt="平台选择" width="600">
+</p>
+<p align="center">支持分发中文、英文 Skill 版本，支持 28 个 AI Coding 平台</p>
+
+<p align="center">
+  <img src="img/init.png" alt="初始化" width="600">
+</p>
+<p align="center">自动安装 OpenSpec、Superpowers，一键配置开发环境</p>
+
+<p align="center">
+  <img src="img/skill-comet.png" alt="Skill 运行" width="600">
+</p>
+<p align="center">多阶段 Skill 入口，自动识别当前 Spec 阶段，核心流程自动触发，关键节点人工审核</p>
+
+## CLI命令
 
 | 命令 | 描述 |
 |---------|-------------|
@@ -101,8 +128,8 @@ comet init
 | `/comet-build` | 阶段 3：规划与构建（实现计划、代码提交） |
 | `/comet-verify` | 阶段 4：验证与完成（测试、验证报告） |
 | `/comet-archive` | 阶段 5：归档（delta spec 同步、状态标注） |
-| `/comet-hotfix` | 快捷路径：快速 bug 修复（跳过头脑风暴） |
-| `/comet-tweak` | 快捷路径：小改动（跳过头脑风暴和完整计划） |
+| `/comet-hotfix` | 快捷路径：快速 bug 修复（跳过头脑风暴，不需要能力设计） |
+| `/comet-tweak` | 快捷路径：小改动（文案调整、配置调整、文档或 Prompt 优化） |
 
 ### 守护与自动化脚本
 
@@ -164,15 +191,21 @@ Comet 使用解耦状态架构，YAML 文件独立管理：
 | `.comet.yaml` | Comet | 工作流阶段、执行模式、验证状态 |
 
 **`.comet.yaml` 关键字段：**
-- `workflow`：`full`、`hotfix` 或 `tweak`
-- `phase`：`design`、`build`、`verify`、`archive`
-- `design_doc`：Superpowers 设计文档路径
-- `plan`：实现计划路径
-- `build_mode`：`subagent-driven-development`、`executing-plans` 或 `direct`
-- `isolation`：`branch` 或 `worktree`，工作空间隔离方式
-- `verify_mode`：`light` 或 `full`
-- `verify_result`：`pending`、`pass` 或 `fail`
-- `archived`：布尔值，标识变更是否已归档
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+其中所有的状态和运行阶段都采用脚本更新，且**能够检验每个阶段是否真实完成任务，达到条件之后才会退出当前阶段，执行更新状态动作**。相比于将复杂的状态管理机制记录在 Skill 中，脚本的方式强保障了核心状态扭转的可靠性、YAML 文件的正确性，以及断点恢复的便捷——Agent 只需要通过 Comet 内置命令进行状态读取就能知道当前 Spec 所处的情况。
 
 ### 可靠性特性
 
@@ -231,6 +264,16 @@ your-project/
     └── plans/                   # 实现计划
 ```
 
+## 你能学到什么
+
+现有的 Skill 市场中有很多优秀的 Skill 项目，但普遍存在偏好性问题——用户可能只喜欢部分功能。比如同时使用 OpenSpec 和 Superpowers 时，可能只用 OpenSpec 的 Spec 管理能力，而编码上更喜欢 Superpowers 的 TDD 驱动。
+
+长期使用 Skill 的人都知道，这些能力是可以自由组合的，但具体怎么做依然需要真正的实践。Comet 项目可以作为参考：
+
+- **如何稳定触发嵌套 Skill** — 不是让 Agent 依靠文档描述做了"看起来像触发了 Skill"的操作（比如根据 Skill 描述写了文件），而是真正触发 Skill（核心特征：CC 上有 Skill 触发的打印）。Comet 中会触发大量来自 OpenSpec 和 Superpowers 的能力，这段 Prompt 是怎么写的？
+
+- **如何让组合 Skill 多阶段自动流转** — 不是靠人工介入。Comet 的 5 阶段流程，除必要的用户选择项外，核心流程能够自动进行 Skill 触发，同时**状态机机制**也能保障状态扭转的可靠性。
+
 ## 开发
 
 ```bash
@@ -265,9 +308,6 @@ pnpm format
 - `.npmignore` 阻止源码和配置文件进入 npm 包
 - `.gitignore` 覆盖 secrets、credentials、IDE configs 等
 
-## Community
-[linux.do](https://linux.do/) — Linux & Open Source Community
-
 ## License
 
 MIT

README.md

@@ -15,6 +15,16 @@
 
 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.
 
+## 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 completing and closing CC midway, just `/comet continue` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
+
 ## Install
 
 ```bash
@@ -38,6 +48,23 @@ comet init
 6. Deploy Comet skills (in your chosen language) to selected platforms
 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
 
+## Screenshots
+
+<p align="center">
+  <img src="img/select-platform.png" alt="Platform Selection" width="600">
+</p>
+<p align="center">Supports Chinese & English Skill distribution, 28 AI Coding platforms</p>
+
+<p align="center">
+  <img src="img/init.png" alt="Initialization" width="600">
+</p>
+<p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
+
+<p align="center">
+  <img src="img/skill-comet.png" alt="Skill Execution" width="600">
+</p>
+<p align="center">Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes</p>
+
 ## Commands
 
 | Command | Description |
@@ -164,15 +191,21 @@ Comet uses a decoupled state architecture with separate YAML files:
 | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
 
 **Key Fields in `.comet.yaml`:**
-- `workflow`: `full`, `hotfix`, or `tweak`
-- `phase`: `design`, `build`, `verify`, `archive`
-- `design_doc`: Path to Superpowers Design Doc
-- `plan`: Path to implementation plan
-- `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
-- `isolation`: `branch` or `worktree`, workspace isolation method
-- `verify_mode`: `light` or `full`
-- `verify_result`: `pending`, `pass`, or `fail`
-- `archived`: Boolean indicating if change is archived
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use Comet's built-in commands to read state and know the current Spec's situation.
 
 ### Reliability Features
 
@@ -231,6 +264,16 @@ your-project/
     └── plans/                   # Implementation plans
 ```
 
+## 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 will trigger many capabilities from OpenSpec and Superpowers — how is this Prompt written?
+
+- **How to make combined Skills multi-phase auto-flow** — Not relying on manual intervention. Comet's 5-phase flow automatically triggers Skills for core processes except necessary user selections, while the **state machine mechanism** also ensures state transition reliability.
+
 ## Development
 
 ```bash
@@ -265,9 +308,6 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 - `.npmignore` prevents source code and config files from entering the npm package
 - `.gitignore` covers secrets, credentials, IDE configs, and more
 
-## Community
-[linux.do](https://linux.do/) — Linux & Open Source Community
-
 ## License
 
 MIT

assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0",
+  "version": "0.2.3",
   "skills": [
     "comet/SKILL.md",
     "comet/scripts/comet-guard.sh",

assets/skills-zh/comet-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet-build
-description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
+description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并选择执行方式（subagent 或直接执行）实施。"
 ---
 
 # Comet 阶段 3：计划与构建（Build）

assets/skills/comet-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet-build
-description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and execute implementation through subagent-driven-development."
+description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and choose execution method (subagent or direct) for implementation."
 ---
 
 # Comet Phase 3: Plan and Build (Build)

img/init.png

@@ -1,6 +1,6 @@
 {
   "name": "@rpamis/comet",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "OpenSpec + Superpowers dual-star development workflow",
   "keywords": [
     "comet",