feat: improve cli update workflow

Author: benym

.github/workflows/pr-title-lint.yml

@@ -0,0 +1,46 @@
+name: PR Title Lint
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, ready_for_review]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint-pr-title:
+    name: Lint PR Title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          scopes: |
+            cli
+            commands
+            core
+            skills
+            assets
+            scripts
+            docs
+            ci
+            deps
+            release
+          requireScope: false
+          subjectPattern: ^.{1,72}$
+          subjectPatternError: |
+            PR title subject must be 72 characters or fewer.
+            Found: "{subject}" ({length} characters)

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.2.5] - 2026-05-22
+
+### Added
+
+- **PR title lint workflow**: Added GitHub Actions validation for semantic PR titles with Comet-specific scopes (`cli`, `commands`, `core`, `skills`, `assets`, `scripts`, `docs`, `ci`, `deps`, `release`)
+- **Structured JSON output**: `comet init --json` and `comet update --json` now emit machine-readable results instead of mixed human logs
+- **`doctor --scope`**: `comet doctor` can diagnose `auto`, `project`, or `global` scope, with `auto` checking both project and global installs
+- **Next-step status hint**: `comet status` now reports the next workflow command (`/comet-open`, `/comet-design`, `/comet-build`, `/comet-verify`, `/comet-archive`) in text and JSON output
+- **README asset guard**: Added tests and prepublish validation to keep README images on npm-friendly absolute URLs
+
+### Changed
+
+- **`comet update` preserves installed context**: Update now detects existing Comet skill targets across project/global scopes, preserves installed scope, detects Chinese vs English skills, and updates only platforms where Comet skills are already installed
+- **`comet update` self-updates npm package**: Update now prints and runs the matching npm update command for the detected package scope before refreshing installed skills
+- **Friendlier update output**: Update logs the npm command, per-target skill copy command, final npm status, updated target count, scope, and language summary
+- **Init overwrite flow**: Interactive `comet init` now offers a bulk overwrite/skip choice when multiple existing components are detected on the same platform
+- **CLI option validation**: `update --language`, `update --scope`, and `doctor --scope` now validate accepted values through Commander choices
+- **README CLI docs**: Updated English and Chinese README command sections to document JSON output, doctor scope, update behavior, status next-step hints, and init overwrite behavior
+- **CONTRIBUTING link**: Added contribution guide references to both English and Chinese README development sections
+
+### Fixed
+
+- **Doctor false positives**: `comet doctor` now recognizes current `.comet.yaml` fields including `verification_report` and `branch_status`
+- **npm README images**: README images now use absolute GitHub URLs so package pages can render them
+
+### Tests
+
+- Added coverage for update language/scope detection, JSON output, friendly command display, status next-step hints, doctor current-state validation, README image URLs, init bulk overwrite selection, and PR title workflow configuration
+
 ## What's Changed [0.2.4] - 2026-05-21
 
 ### Added

README-zh.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <a href="https://github.com/rpamis/comet">
+  <a href="https://github.com/rpamis/comet/blob/master/img/title-log.png">
     <picture>
-      <source srcset="img/title-log.png">
-      <img src="img/title-log.png" alt="Comet logo">
+      <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>
@@ -72,7 +72,7 @@ comet init
 ## 运行截图
 
 <p align="center">
-  <img src="img/runner.png" alt="runner">
+  <img src="https://github.com/rpamis/comet/blob/master/img/runner.png" alt="runner">
 </p>
 <p align="center">自动安装 OpenSpec、Superpowers，一键配置开发环境</p>
 <p align="center">多阶段 Skill 入口，自动识别当前 Spec 阶段，核心流程自动触发，关键节点人工审核</p>
@@ -82,9 +82,9 @@ comet init
 | 命令 | 描述 |
 |---------|-------------|
 | `comet init [path]` | 初始化 Comet 工作流 |
-| `comet status [path]` | 显示活跃更改和工作流状态 |
-| `comet doctor [path]` | 诊断 Comet 安装健康状态 |
-| `comet update [path]` | 更新 comet 技能到最新版本 |
+| `comet status [path]` | 显示活跃更改、任务进度和下一步工作流命令 |
+| `comet doctor [path]` | 诊断项目级/全局 Comet 安装健康状态 |
+| `comet update [path]` | 更新 npm 包和已安装的 Comet 技能 |
 | `comet --help` | 显示帮助 |
 | `comet --version` | 显示版本 |
 
@@ -97,13 +97,28 @@ comet init
 | `--overwrite` | 覆盖已安装的组件 |
 | `--json` | 输出结构化 JSON |
 
-### status / doctor / update 选项
+当同一平台检测到多个已安装组件时，交互式 init 会先提供一次批量选择：全部覆盖、全部跳过，或逐项选择。
 
-| 选项 | 适用于 | 描述 |
-|--------|-----------|-------------|
-| `--json` | `status`, `doctor` | 输出结构化 JSON |
-| `--language <lang>` | `update` | 技能语言 (`en`, `zh`) |
-| `--scope <scope>` | `update` | 安装范围 (`global`, `project`)|
+### status 选项
+
+| 选项 | 描述 |
+|--------|-------------|
+| `--json` | 输出活跃更改，并包含 `nextCommand` |
+
+### doctor 选项
+
+| 选项 | 描述 |
+|--------|-------------|
+| `--json` | 输出结构化诊断结果 |
+| `--scope <scope>` | 诊断 `auto`、`project` 或 `global` 范围（默认：`auto`） |
+
+### update 选项
+
+| 选项 | 描述 |
+|--------|-------------|
+| `--json` | 以 JSON 输出 npm 和 skill 更新结果 |
+| `--language <lang>` | 覆盖自动检测到的 skill 语言 (`en`, `zh`) |
+| `--scope <scope>` | 仅更新 `global` 或 `project` 范围 |
 
 ## 支持平台
 
@@ -296,6 +311,8 @@ your-project/
 
 ## 开发
 
+贡献流程、提交规范、PR 流程，以及新增平台或 Skill 的说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
 ```bash
 # 克隆
 git clone https://github.com/rpamis/comet

README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <a href="https://github.com/rpamis/comet">
+  <a href="https://github.com/rpamis/comet/blob/master/img/title-log.png">
     <picture>
-      <source srcset="img/title-log.png">
-      <img src="img/title-log.png" alt="Comet logo">
+      <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>
@@ -72,7 +72,7 @@ comet init
 ## Screenshots
 
 <p align="center">
-  <img src="img/runner.png" alt="runner">
+  <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>
@@ -83,9 +83,9 @@ comet init
 | Command | Description |
 |---------|-------------|
 | `comet init [path]` | Initialize Comet workflow |
-| `comet status [path]` | Show active changes and workflow status |
-| `comet doctor [path]` | Diagnose Comet installation health |
-| `comet update [path]` | Update comet skills to latest version |
+| `comet status [path]` | Show active changes, task progress, and next workflow command |
+| `comet doctor [path]` | Diagnose project/global Comet installation health |
+| `comet update [path]` | Update the npm package and installed Comet skills |
 | `comet --help` | Show help |
 | `comet --version` | Show version |
 
@@ -98,13 +98,28 @@ comet init
 | `--overwrite` | Overwrite already installed components |
 | `--json` | Output structured JSON |
 
-### status / doctor / update Options
+When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
 
-| Option | Applies to | Description |
-|--------|-----------|-------------|
-| `--json` | `status`, `doctor` | Output structured JSON |
-| `--language <lang>` | `update` | Language for skills (`en`, `zh`) |
-| `--scope <scope>` | `update` | Install scope (`global`, `project`)|
+### status Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output active changes with `nextCommand` |
+
+### doctor Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output structured diagnostic results |
+| `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
+
+### update Options
+
+| 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 |
 
 ## Supported Platforms
 
@@ -297,6 +312,8 @@ Long-term Skill users know these capabilities can be freely combined, but exactl
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
+
 ```bash
 # Clone
 git clone https://github.com/rpamis/comet

assets/manifest.json

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

package-lock.json

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

package.json

@@ -20,6 +20,7 @@ const SECRET_PATTERNS = [
 
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist']);
 const TEXT_EXTENSIONS = new Set(['.js', '.ts', '.json', '.md', '.txt', '.yml', '.yaml', '.toml']);
+const README_IMAGE_PATTERN = /\b(?:src|srcset)=["'](?:\.\/)?img\//;
 
 function* walkFiles(dir) {
   for (const entry of readdirSync(dir)) {
@@ -54,6 +55,13 @@ for (const filePath of walkFiles('.')) {
       found++;
     }
   }
+
+  if (/README(?:-zh)?\.md$/.test(filePath) && README_IMAGE_PATTERN.test(content)) {
+    console.error(
+      `[PACKAGE] npm README images must use absolute URLs, not local img/ paths: ${filePath}`,
+    );
+    found++;
+  }
 }
 
 if (found > 0) {

scripts/prepublish-check.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { createRequire } from 'module';
 import { initCommand } from '../commands/init.js';
 import { statusCommand } from '../commands/status.js';
@@ -46,6 +46,13 @@ program
   .command('doctor [path]')
   .description('Diagnose Comet installation health')
   .option('--json', 'Output as JSON')
+  .addOption(
+    new Option('--scope <scope>', 'Install scope to diagnose').choices([
+      'auto',
+      'global',
+      'project',
+    ]),
+  )
   .action(async (targetPath = '.', options) => {
     await doctorCommand(targetPath, options);
   });
@@ -54,8 +61,9 @@ program
   .command('update [path]')
   .description('Update comet skill files to latest version')
   .option('--json', 'Output as JSON')
-  .option('--language <lang>', 'Language for skills (en, zh)')
-  .option('--scope <scope>', 'Install scope (global, project)')
+  .addOption(new Option('--language <lang>', 'Language for skills').choices(['en', 'zh']))
+  .addOption(new Option('--scope <scope>', 'Install scope').choices(['global', 'project']))
+  .addOption(new Option('--skip-npm', 'Skip npm package self-update').hideHelp())
   .action(async (targetPath = '.', options) => {
     await updateCommand(targetPath, options);
   });