feat: enhance skills handling, openspec upgrades, and cli improvements (#106)

* fix(skills): resolve symlinks before copying skill files

When skill directories are symlinks (e.g. ~/.claude/skills/comet -> ~/.agents/skills/comet), copyFile and ensureDir wrote to the literal path instead of following the symlink target. Broken symlinks caused silent copy failures.

Added resolveSymlinkPath() to file-system.ts that walks up the path tree and follows readlink targets for broken symlinks. Applied to ensureDir, copyFile, and writeFile.

Fixes #85

* fix(openspec): always upgrade to latest and retry without --profile

Two changes to fix issue #84:

1. ensureOpenSpecCli now always installs/upgrades openspec to the
   latest version, even if an older version is already present. This
   ensures users get the --profile support and other improvements.

2. Added fallback logic: if openspec init fails with 'unknown option
   --profile' in stderr, retry without the flag. This handles edge
   cases where the upgrade fails but an older openspec remains.

The --profile flag is redundant since XDG_CONFIG_HOME config already
sets profile to 'custom', but it helps newer openspec versions.

Fixes #84

* fix: force LF line endings for JS/TS files to fix npm shebang issue on macOS

When npm packs the project on Windows, bin/comet.js shebang line gets
CRLF line endings, causing macOS to interpret '#!/usr/bin/env node\r'
instead of '#!/usr/bin/env node', resulting in 'command not found'.

Add explicit eol=lf rules for all text file extensions and binary
markers for image files in .gitattributes.

Fixes #82

* docs: add changelog for v0.3.8 and bump version

* feat(skills): extract subagent dispatch protocol and sync English skills

- Extract inline subagent-driven-development protocol from comet-build/SKILL.md
  into standalone comet/reference/subagent-dispatch.md (ZH + EN)
- Sync English comet-build/SKILL.md with Chinese optimizations: simplified
  subagent instructions, TDD constraints reference, context recovery guidance
- Add task-checkoff subcommand to comet-state.sh for targeted task verification
- Add phase guard recovery steps for subagent build mode after compaction
- Update tests: phase-guard assertions, task-checkoff edge cases, English
  SKILL.md assertions
- Update CHANGELOG.md for v0.3.8

* refactor(skills): extract shared protocol docs for progressive loading

Extract four reference documents from inline skill content to enable
on-demand loading and reduce per-invocation token cost:
- auto-transition.md: shared auto-transition protocol (7 sub-skills)
- context-recovery.md: context compression recovery steps (4 sub-skills)
- comet-yaml-fields.md: .comet.yaml field table (main SKILL.md)
- file-structure.md: directory structure reference (main SKILL.md)

Both Chinese and English versions updated. Key commands and state machine
hard constraints retained inline; full protocol details moved to reference.

Also fixes comet-tweak missing systematic-debugging handling (both langs),
and syncs phase guard rule with bilingual recovery references.

Estimated savings: 600-1500 tokens per skill invocation, ~4100 tokens
across a full workflow.

* fix(codegraph): use auto-detect install instead of platform filtering

CodeGraph's `codegraph install` auto-detects and configures all
installed agents (Claude Code, Cursor, Codex CLI, etc.). Passing
`--target` and `--location` manually caused Codex CLI to be
skipped with "does not support --location=local" because Codex
has no project-local config concept.

Simplify to `codegraph install --yes` and let CodeGraph handle
platform detection itself. Remove now-unused filterSupportedPlatforms
and CODEGRAPH_SUPPORTED_TARGETS.

Closes #98

* refactor(subagent): enhance subagent-driven development with strict Comet extensions

* feat: update documentation to reference decision point and debug gate protocols

* fix(hooks): preserve user-defined hooks during Comet hook configuration merging

* docs: design OpenSpec artifact rules compliance

* fix(SKILL): enforce explicit user confirmation and standard artifact loop for Comet workflow

* feat(cli): add command to remove Comet skills, rules, and hooks

* feat(cli): add version info and update check to init and update commands

* feat(cli): enforce official npm registry for comet package updates

* fix(core): detect OpenCode plugin-installed Superpowers correctly

* docs: design Pi slash command extension

* fix(pi): register Comet slash commands

* chore(docs): remove outdated docs

* fix(ci): correct Windows path escaping in init-e2e verification

The init-e2e workflow's Pi settings verification interpolated a Windows
$RUNNER_TEMP path (with backslashes) into a node -e require() JS string
literal, where \a and \_ were parsed as escape characters and mangled
the path (D:\a\_temp -> D:a_temp), failing the init-e2e (windows-latest)
runners on Node 20 and 22. Pass the path via process.env so it never
enters a JS string literal. Linux and macOS were unaffected.

Also reformat src/core/openspec.ts to satisfy prettier --check, which was
failing the format:check CI step.

* chore(ci): add husky pre-commit formatting hook

Add a husky + lint-staged pre-commit hook that runs prettier --write on
staged source files under src/ at every git commit (scope aligned with
CI format:check). Editor-agnostic, so it enforces formatting for all
contributors regardless of IDE or agent, preventing the prettier
formatting issues that broke CI from recurring.

prepare now installs the hook on pnpm install; .husky/ is excluded from
the published package via the files whitelist. Document the pre-commit
workflow in CLAUDE.md and AGENTS.md.

* fix: address PR #106 review findings

- file-system: symlink-safe removal during uninstall (removeFile/removeDir
  no longer resolve symlinks before deleting, so a symlinked dir's target is
  never recursively deleted); isDirEmpty no longer treats unreadable dirs as empty
- update: discard npm stdio in --json mode to avoid corrupting output; add
  codegraph field to the no-targets JSON branch for a stable shape; skip the
  npm-registry version check in JSON mode
- skills: coerce parsed hook groups to arrays before merge/filter so malformed
  hand-edited settings cannot throw during init/update
- init: skip the version check in JSON mode
- manifest: bump version 0.3.3 -> 0.3.8 to match package.json
- docs: add text fence language tags (MD040) in file-structure.md and
  subagent-dispatch.md, Chinese and English

* test(skills): handle malformed hook groups without throwing

Author: benym

.claude/settings.local.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash assets/skills/comet/scripts/comet-hook-guard.sh"
+            "command": "bash .claude/skills/comet/scripts/comet-hook-guard.sh"
           }
         ]
       }

.gitattributes

@@ -1,5 +1,17 @@
 * text=auto
 
+*.js text eol=lf
+*.mjs text eol=lf
+*.ts text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
 *.sh text eol=lf
 *.bash text eol=lf
 *.bats text eol=lf
+.husky/* text eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary

.github/workflows/ci.yml

@@ -138,6 +138,8 @@ jobs:
             check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.sh"
             check_file "$PROJ/$sd/comet/scripts/comet-archive.sh"
           done
+          check_file "$PROJ/.pi/extensions/comet-commands.ts"
+          PROJ="$PROJ" node -e "const s=require(process.env.PROJ+'/.pi/settings.json'); if(s.enableSkillCommands!==true) process.exit(1)"
           echo "All 29 platforms project Comet skills: OK"
         shell: bash
 
@@ -217,7 +219,7 @@ jobs:
                     .gemini/skills .amazonq/skills .qwen/skills .kilocode/skills \
                     .augment/skills .kiro/skills .kimi-code/skills .lingma/skills .junie/skills \
                     .codebuddy/skills .cospec/skills .crush/skills .factory/skills \
-                    .iflow/skills .pi/skills .qoder/skills .gemini/antigravity/skills \
+                    .iflow/skills .pi/agent/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"
@@ -226,6 +228,8 @@ jobs:
             check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.sh"
             check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.sh"
           done
+          check_file "$HOME_DIR/.pi/agent/extensions/comet-commands.ts"
+          HOME_DIR="$HOME_DIR" node -e "const s=require(process.env.HOME_DIR+'/.pi/agent/settings.json'); if(s.enableSkillCommands!==true) process.exit(1)"
           echo "All 29 platforms global Comet skills: OK"
         shell: bash
 

.gitignore

@@ -85,4 +85,6 @@ skills-lock.json
 # Superpowers docs (local only)
 docs/superpowers/
 
-.codegraph/
+.codegraph/
+
+.comet/

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

AGENTS.md

@@ -5,6 +5,21 @@ npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
+## 提交前检查
+
+仓库已配置 Git pre-commit 钩子（husky + lint-staged），每次 `git commit` 会自动对 `src/` 下的暂存源文件运行 `prettier --write`（与 CI `format:check` 范围一致），编辑器无关，所有贡献者生效。
+
+提交前建议手动确认（CI 会强制检查）：
+
+```bash
+pnpm format:check   # Prettier 格式检查
+pnpm lint           # ESLint
+pnpm build          # TypeScript 构建
+pnpm test           # 单元测试
+```
+
+注：本地 Windows 若 `core.autocrlf=true`，未改动的旧文件可能因 CRLF 被 `prettier --check` 误报；钩子只处理暂存文件，不受影响，旧文件下次编辑时会自动转为 LF。
+
 ## Shell 脚本规范
 
 脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
@@ -37,6 +52,12 @@ skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再
 
 ## Changelog 规范
 
+每次代码产生变更你都应该在完成后写Changelog，并确定是否需要升级版本号，版本号只会比master分支的版本号大一个版本，你需要确定一下当前master的版本号后做决定
+
+如果当前已经有了一个比master大的版本Changelog，则应该追加到同一个版本的Changelog条目下
+
+如果修改的是Skill内容，则需要等中英文完全同步之后再写Changelog
+
 文件：`CHANGELOG.md`，新版本条目置顶。
 
 ```
@@ -53,3 +74,11 @@ skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再
 - 按类型分组：Added → Changed → Fixed → Tests → Removed → Security
 - 描述侧重 **行为变更**（what + why），不是实现细节
 - `### Tests` 条目汇总新增测试覆盖的场景，不逐条列出测试用例
+
+## 修改Skill规范
+
+不能够直接修改Superpowers和OpenSpec的原始Skill
+
+## github规范
+
+不能未经过同意直接在github上评论或者提交PR

CHANGELOG.md

@@ -5,6 +5,21 @@ npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
+## 提交前检查
+
+仓库已配置 Git pre-commit 钩子（husky + lint-staged），每次 `git commit` 会自动对 `src/` 下的暂存源文件运行 `prettier --write`（与 CI `format:check` 范围一致），编辑器无关，所有贡献者生效。
+
+提交前建议手动确认（CI 会强制检查）：
+
+```bash
+pnpm format:check   # Prettier 格式检查
+pnpm lint           # ESLint
+pnpm build          # TypeScript 构建
+pnpm test           # 单元测试
+```
+
+注：本地 Windows 若 `core.autocrlf=true`，未改动的旧文件可能因 CRLF 被 `prettier --check` 误报；钩子只处理暂存文件，不受影响，旧文件下次编辑时会自动转为 LF。
+
 ## Shell 脚本规范
 
 脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
@@ -46,6 +61,12 @@ skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再
 
 ## Changelog 规范
 
+每次代码产生变更你都应该在完成后写Changelog，并确定是否需要升级版本号，版本号只会比master分支的版本号大一个版本，你需要确定一下当前master的版本号后做决定
+
+如果当前已经有了一个比master大的版本Changelog，则应该追加到同一个版本的Changelog条目下
+
+如果修改的是Skill内容，则需要等中英文完全同步之后再写Changelog
+
 文件：`CHANGELOG.md`，新版本条目置顶。
 
 ```
@@ -62,3 +83,11 @@ skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再
 - 按类型分组：Added → Changed → Fixed → Tests → Removed → Security
 - 描述侧重 **行为变更**（what + why），不是实现细节
 - `### Tests` 条目汇总新增测试覆盖的场景，不逐条列出测试用例
+
+## 修改Skill规范
+
+不能够直接修改Superpowers和OpenSpec的原始Skill
+
+## github规范
+
+不能未经过同意直接在github上评论或者提交PR

CLAUDE.md

@@ -198,14 +198,33 @@ npx skills add rpamis/comet
 
 </details>
 
+<details>
+<summary><code>comet uninstall [path]</code> — 卸载 Comet 技能、规则和钩子</summary>
+
+安全移除 Comet 分发的技能、规则和钩子，保留用户自定义的钩子和非 Comet 配置。
+
+| 选项                | 描述                              |
+|-------------------|---------------------------------|
+| `--force`         | 跳过确认提示                          |
+| `--scope <scope>` | 仅卸载 `global` 或 `project` 范围    |
+| `--json`          | 以 JSON 输出卸载结果                  |
+
+```bash
+comet uninstall              # 交互式 — 显示已安装目标，确认后卸载
+comet uninstall --force      # 非交互式 — 直接移除所有内容
+comet uninstall --scope project  # 仅移除项目级安装
+```
+
+</details>
+
 | 命令                | 描述   |
 |-------------------|------|
 | `comet --help`    | 显示帮助 |
 | `comet --version` | 显示版本 |
 
 ## 支持平台
 
-`comet init` 支持 28 个 AI 编码平台：
+`comet init` 支持 29 个 AI 编码平台：
 
 <details>
 <summary>查看完整平台列表</summary>

README-zh.md

@@ -217,6 +217,25 @@ Updates the npm package and refreshes installed Comet skills in detected project
 
 </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    |