rpamis · forggy0113 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,7 +9,7 @@
 - [ ] CLI commands (`init`, `status`, `doctor`, `update`)
 - [ ] Core installer / platform detection
 - [ ] Comet skills (`assets/skills/`, `assets/skills-zh/`)
-- [ ] Comet shell scripts (`assets/skills/comet/scripts/`)
+- [ ] Comet Node scripts (`assets/skills/comet/scripts/`)
 - [ ] Tests / CI
 - [ ] Documentation / changelog
 - [ ] Other:
@@ -23,7 +23,6 @@
 - [ ] `pnpm format:check`
 - [ ] `pnpm test`
 - [ ] `pnpm test -- test/ts/comet-scripts.test.ts`
-- [ ] `pnpm test:shell`
 - [ ] Not run:
 
 ## ✅ Checklist
@@ -33,7 +32,7 @@
 - [ ] `CHANGELOG.md` is updated when behavior changes
 - [ ] Skill changes were made in Chinese first when applicable, then synced to English
 - [ ] New scripts are included in `assets/manifest.json` and relevant tests
-- [ ] Shell scripts remain portable across macOS, Linux, and Windows Git Bash
+- [ ] Comet Node scripts remain portable across macOS, Linux, and Windows
 - [ ] No unrelated generated files or local artifacts are included
 
 ## 👀 Notes for Reviewers

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -34,27 +34,6 @@ jobs:
 
       - run: pnpm test:coverage
 
-  shellcheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run shellcheck
-        uses: ludeeus/action-shellcheck@2.0.0
-        with:
-          scandir: ./assets/skills/comet/scripts
-
-  bats-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install bats
-        run: sudo apt-get install -y bats
-
-      - name: Run shell tests
-        run: bats test/shell/*.bats
-
   script-smoke:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -77,9 +56,6 @@ jobs:
       - name: Run Comet script smoke tests
         run: pnpm test -- test/ts/comet-scripts.test.ts
 
-      - name: Run portable shell tests
-        run: pnpm test:shell
-
   init-e2e:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -132,11 +108,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .agents/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$PROJ/$sd/comet/SKILL.md"
-            check_file "$PROJ/$sd/comet/scripts/comet-guard.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-state.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-archive.sh"
+            check_file "$PROJ/$sd/comet/scripts/comet-guard.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-state.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-handoff.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-archive.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-env.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms project Comet skills: OK"
         shell: bash
@@ -220,11 +198,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .gemini/antigravity/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$HOME_DIR/$sd/comet/SKILL.md"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.sh"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-env.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms global Comet skills: OK"
         shell: bash

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,26 +6,27 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
+- **Cross-platform Comet scripts**: Converted script source to TypeScript (`src/scripts/`) with strict type annotations; `build.js` compiles them to JavaScript in `assets/skills/comet/scripts/` so bundled automation runs without Bash-specific script files on macOS, Linux, and Windows.
 - **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
 - **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
 
 ### Changed
 
 - **Build recovery routing**: `/comet` and `/comet-build` now recognize `build_pause: plan-ready`, reuse the existing plan, and resume at workspace isolation and execution-method selection instead of regenerating the plan.
+- **Comet script invocation**: Skills, manifest entries, docs, and CI now invoke Comet automation through `node comet-*.js` instead of Bash script entrypoints for simpler Windows compatibility.
 - **Bilingual workflow documentation**: Chinese and English Comet skills now describe the plan-ready pause point, clarify that `build_pause` is not `build_mode`, and document the same state field in both README files.
 
 ### Fixed
 
 - **GitHub Copilot Superpowers skill names**: Comet skills now invoke the bare Superpowers skill names installed by the GitHub Copilot skills path, avoiding blocked workflows caused by unresolved `superpowers:*` aliases.
-- **Windows bash resolution**: Comet now resolves a usable bash executable through `COMET_BASH`, rejects the Windows WSL launcher path, and uses the resolved executable for nested script calls so guard, handoff, and archive flows do not fall back to a broken PATH `bash`.
-- **Shell test runner bash resolution**: `run-bats.js` now resolves a usable bash through `COMET_TEST_BASH`, `COMET_BASH`, PATH, or Git Bash defaults, avoiding the broken Windows WSL launcher when running shell tests from Node.
+- **Windows script execution**: Comet guard, handoff, archive, state, and validation flows now use Node for internal script calls, avoiding failures caused by unavailable or incompatible Bash executables on Windows.
 - **Schema validation fatal output**: Guard validation now preserves the final fatal schema-validation message after printing validator diagnostics, making invalid `.comet.yaml` failures easier to recognize.
 
 ### Tests
 
 - **Superpowers skill invocation regression**: Added coverage that shipped Comet skill prose does not reference plugin-prefixed Superpowers aliases.
-- **Comet bash execution regression**: Added coverage for nested script calls, shipped command examples, and the shell test runner so Comet uses resolved bash paths instead of raw PATH `bash`.
-- **Plan-ready pause regression**: Added shell-script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
+- **Comet Node script regression**: Added coverage for nested script calls, shipped command examples, manifest entries, and environment discovery so Comet uses Node script entrypoints instead of Bash wrappers.
+- **Plan-ready pause regression**: Added Comet script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
 - **README state-field regression**: Added README coverage to ensure `build_pause` appears in examples and field descriptions for both English and Chinese documentation.
 
 ## What's Changed [0.3.5] - 2026-05-29

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,34 +1,35 @@
 ## 测试
 
 ```bash
-npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
+npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
-## Shell 脚本规范
+## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
+脚本源码位于 `src/scripts/`（TypeScript），经 `build.js` 编译输出到 `assets/skills/comet/scripts/`（JavaScript），必须跨平台兼容（macOS / Linux / Windows）：
 
-- **禁止** `sed -i`（GNU/BSD 不兼容），用 `awk` 做字段替换
-- 必须兼容 `sha256sum`（GNU）和 `shasum -a 256`（BSD/macOS）
-- 所有可选 grep 结果加 `|| true` 防止 `pipefail` 误杀
+- 使用 TypeScript 实现（`src/scripts/*.ts`），构建时编译为 `.js`
+- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
+- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
-```
-comet-state.sh ← comet-guard.sh, comet-handoff.sh, comet-archive.sh
-comet-yaml-validate.sh ← comet-guard.sh (preflight 阶段)
-comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
+```text
+comet-lib.ts ← comet-state.ts, comet-guard.ts, comet-handoff.ts, comet-archive.ts, comet-yaml-validate.ts, comet-env.ts
+comet-state.ts ← comet-guard.ts, comet-handoff.ts, comet-archive.ts
+comet-yaml-validate.ts ← comet-guard.ts (preflight 阶段)
+comet-handoff.ts ← comet-state.ts (写入 handoff_context/handoff_hash)
 ```
 
-新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
+新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
 
 ## .comet.yaml 状态机
 
 每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.sh` — `cmd_set` 白名单 + enum 验证
-2. `comet-yaml-validate.sh` — schema 校验 + KNOWN_KEYS
+1. `comet-state.js` — 可写字段白名单 + enum 验证
+2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
 3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
 
 ## 双语言 Skill

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -17,7 +17,6 @@ pnpm build
 | `pnpm build` | Compile TypeScript |
 | `pnpm test` | Run unit tests |
 | `pnpm test:coverage` | Run tests with coverage |
-| `pnpm test:shell` | Run shell script tests (requires bats) |
 | `pnpm lint` | Run ESLint |
 | `pnpm format` | Run Prettier |
 
@@ -54,6 +53,14 @@ src/
 │   ├── skills.ts      # Skill file operations
 │   ├── openspec.ts    # OpenSpec installation
 │   └── superpowers.ts # Superpowers installation
+├── scripts/           # Comet Node.js scripts (phase guards, state, archive)
+│   ├── comet-lib.ts   # Shared utilities
+│   ├── comet-state.ts # State machine (.comet.yaml)
+│   ├── comet-guard.ts # Phase guard checks
+│   ├── comet-handoff.ts # Design handoff
+│   ├── comet-archive.ts # Change archive
+│   ├── comet-env.ts   # Environment discovery
+│   └── comet-yaml-validate.ts # YAML validation
 └── utils/
     └── file-system.ts # File I/O utilities
 ```