rpamis
diff --git a/‎.claude/settings.local.json‎
Lines changed: 15 additions & 0 deletions b/‎.claude/settings.local.json‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎.github/workflows/stale-prs.yml‎
Lines changed: 52 additions & 0 deletions b/‎.github/workflows/stale-prs.yml‎
Lines changed: 52 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 0 deletions b/‎.gitignore‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 117 additions & 2 deletions b/‎CHANGELOG.md‎
Lines changed: 117 additions & 2 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 9 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎CONTRIBUTING-zh.md‎
Lines changed: 263 additions & 0 deletions b/‎CONTRIBUTING-zh.md‎
Lines changed: 263 additions & 0 deletions
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash assets/skills/comet/scripts/comet-hook-guard.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,52 @@
+name: Stale PRs
+
+on:
+  schedule:
+    - cron: '30 3 * * *'
+  workflow_dispatch:
+    inputs:
+      dryRun:
+        description: 'Dry Run'
+        required: true
+        default: true
+        type: boolean
+      operationsPerRun:
+        description: 'Max GitHub API operations'
+        required: true
+        default: 30
+        type: number
+
+permissions:
+  issues: write
+  pull-requests: write
+  contents: read
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          debug-only: ${{ inputs.dryRun || false }}
+          operations-per-run: ${{ inputs.operationsPerRun || 500 }}
+          ascending: true
+          days-before-stale: 90
+          days-before-close: 30
+          days-before-issue-stale: -1
+          days-before-issue-close: -1
+          stale-issue-label: ""
+          stale-pr-label: 'stale'
+          stale-pr-message: |
+            This PR is being marked as stale since it has not had any activity in 90 days. If you
+            would like to keep this PR alive, please leave a comment asking for a review. If the PR has
+            merge conflicts, update it with the latest from the base branch.
+            <p>
+            If you are having difficulty finding a reviewer, please reach out to the project maintainers.
+            <p>
+            If this PR is no longer valid or desired, please feel free to close it. If no activity
+            occurs in the next 30 days, it will be automatically closed.
+          close-pr-label: 'closed-stale'
+          close-pr-message: |
+            This PR has been closed since it has not had any activity in 120 days. If you feel like this
+            was a mistake, or you would like to continue working on it, please feel free to re-open the
+            PR and ask for a review.
@@ -84,3 +84,5 @@ skills-lock.json
 
 # Superpowers docs (local only)
 docs/superpowers/
+
+.codegraph/
@@ -20,6 +20,7 @@ npx vitest run                                   # 全量测试
 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)
+comet-hook-guard.sh ← (独立脚本，由 .claude/settings.local.json 的 PreToolUse hook 调用)
 ```
 
 新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
@@ -35,6 +36,14 @@ comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
 
 skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再修改英文版本（`assets/skills/`）。
 
+## Skill 触发表述规范
+
+修改 skill 时，新增或调整依赖 skill 的触发方式必须和既有写法保持一致：
+
+- 中文统一使用：`**立即执行：** 使用 Skill 工具加载 <skill-name> 技能。禁止跳过此步骤。`
+- 英文统一使用：`**Immediately execute:** Use the Skill tool to load the <skill-name> skill. Skipping this step is prohibited.`
+- 后续输入、上下文或执行要求写在“技能加载后 / After the skill loads”段落，不要把 `ARGUMENTS`、`fast-forward` 等另一套调用术语混入触发句。
+
 ## Changelog 规范
 
 文件：`CHANGELOG.md`，新版本条目置顶。
 
@@ -0,0 +1,263 @@
+# Comet 贡献指南
+
+语言：[English](CONTRIBUTING.md) | [中文](CONTRIBUTING-zh.md)
+
+感谢你帮助改进 Comet。这份指南偏实操：说明如何配置项目、准备改动、维护分支、提交 PR，以及如何更新 Skill、shell 脚本等 Comet 特有资产。
+
+## 开始之前
+
+- 修复 bug 前，先确认是否已有 issue 或近期 PR 覆盖同一问题。
+- 较大的行为变更建议先开 issue 或 draft PR，避免方向还没对齐就写太多代码。
+- 每个贡献保持一个清晰目的；无关改动拆成多个 PR。
+- 添加测试，或说明为什么这次改动不需要测试。
+- 行为、命令、工作流或用户可见文案变化时，同步更新文档。
+
+## 开发环境
+
+```bash
+git clone https://github.com/rpamis/comet
+cd comet
+pnpm install
+pnpm build
+```
+
+Node.js 与 pnpm 版本以 lockfile 和 CI 支持范围为准。如果本地依赖安装或构建行为与 CI 不一致，请在 PR 中说明。
+
+## 常用命令
+
+| 命令                 | 用途                           |
+| -------------------- | ------------------------------ |
+| `pnpm dev`           | TypeScript watch 模式          |
+| `pnpm build`         | 编译 TypeScript                |
+| `pnpm test`          | 运行单元测试                   |
+| `pnpm test:coverage` | 运行测试并生成覆盖率           |
+| `pnpm test:shell`    | 运行 shell 脚本测试，需要 bats |
+| `pnpm lint`          | 运行 ESLint                    |
+| `pnpm format`        | 运行 Prettier                  |
+
+如果改动 shell 脚本，最常用的定向检查是：
+
+```bash
+npx vitest run test/ts/comet-scripts.test.ts
+```
+
+除纯文档改动外，开 PR 或更新 PR 前请运行完整验证：
+
+```bash
+pnpm build && pnpm lint && pnpm format:check && pnpm test
+```
+
+## 分支模型
+
+- `master` 是唯一权威的开发与发布基线。
+- 任务分支从最新 `master` 创建。
+- PR 目标分支是 `master`。
+- PR 使用 **Squash and merge** 合并。
+- 被 squash 的 PR 源分支视为一次性分支：合并后删除，或从 `master` 重新创建/重置后再使用。
+
+Squash merge 会在 `master` 上生成一个新提交。源分支如果仍保留原始多个提交，Git 不一定能识别两边历史包含的是等价变更。因此，不要把 `master` 继续 merge 回已经被 squash 的源分支。
+
+## 准备一个改动
+
+```bash
+git fetch origin
+git switch master
+git pull --ff-only origin master
+git switch -c <type>/<short-topic>
+```
+
+分支名要短且能说明改动，例如 `fix/dev-resync-docs` 或 `docs/contributing-guide`。
+
+开发过程中：
+
+- 提交保持便于 review 的粒度。
+- 优先在实现前或实现同时补测试。
+- 开发时运行定向测试。
+- 最终 diff 前重新运行格式化。
+- 避免大范围重写、无关格式化或无关元数据变更。
+
+## 让 PR 跟上 `master`
+
+如果 PR 分支落后 `master`，优先把任务分支 rebase 到最新 `master`：
+
+```bash
+git fetch origin
+git switch <your-branch>
+git rebase origin/master
+# 解决冲突后运行相关检查
+git push --force-with-lease
+```
+
+rebase 后需要改写远端分支历史，因此使用 `--force-with-lease`。它会保护你本地没有的远端更新；避免使用普通 `--force`。
+
+如果分支混入了无关提交，从 `origin/master` 新建干净分支，只 cherry-pick 属于这个 PR 的提交：
+
+```bash
+git fetch origin
+git switch -c <topic>-take-2 origin/master
+git cherry-pick <commit-1> <commit-2>
+# 运行检查
+git push --force-with-lease origin <topic>-take-2:<original-branch>
+```
+
+这样能保持 PR 容易 review，也能避免把无关工作合进去。
+
+## 共享 `dev` 分支
+
+如果保留共享 `dev` 分支，只把它当作临时工作入口。来自 `dev` 的 PR 被 squash 到 `master` 后，不要再把 `master` merge 回 `dev`。确认 `dev` 没有仍需保留的未 squash 工作后，把 `dev` 重置到 `origin/master`：
+
+```bash
+git fetch origin
+git switch dev
+git status --short
+git branch backup/dev-before-sync-YYYYMMDD
+git reset --hard origin/master
+git push --force-with-lease origin dev
+```
+
+如果 `dev` 里还有尚未合并到 `master` 的工作，先把这些工作移到从 `origin/master` 创建的新分支，再重置 `dev`。
+
+## 提交规范
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
+
+```text
+<type>: <description>
+```
+
+类型：`feat`、`fix`、`refactor`、`docs`、`test`、`chore`、`perf`、`ci`
+
+示例：
+
+```text
+docs: expand contribution workflow
+fix: preserve stderr when superpowers install fails
+test: cover comet state transitions
+```
+
+## PR 流程
+
+1. 更新 `master`，并从它创建任务分支。
+2. 实现聚焦的改动，并补充测试。
+3. 开发过程中运行定向检查。
+4. PR review 前运行 `pnpm build && pnpm lint && pnpm format:check && pnpm test`，纯文档改动除外。
+5. 向 `master` 开 PR。
+6. 说明改了什么、为什么改、如何验证。
+7. 用后续提交响应 review 反馈。
+8. PR 通过后使用 **Squash and merge**。
+9. 合并后删除或重新创建源分支；不要继续把 `master` merge 回被 squash 的分支。
+
+纯文档改动至少运行相关格式检查，例如：
+
+```bash
+npx prettier --check CONTRIBUTING.md CONTRIBUTING-zh.md README.md README-zh.md
+```
+
+## 项目结构
+
+```text
+src/
+├── cli/index.ts       # Commander 注册
+├── commands/          # 命令编排
+│   ├── init.ts        # comet init
+│   ├── status.ts      # comet status
+│   ├── doctor.ts      # comet doctor
+│   └── update.ts      # comet update
+├── core/              # 平台无关的核心逻辑
+│   ├── platforms.ts   # 平台定义
+│   ├── detect.ts      # 平台检测
+│   ├── skills.ts      # Skill 文件操作
+│   ├── openspec.ts    # OpenSpec 安装
+│   └── superpowers.ts # Superpowers 安装
+└── utils/
+    └── file-system.ts # 文件系统工具
+```
+
+## 新增平台
+
+1. 在 `src/core/platforms.ts` 的 `PLATFORMS` 中添加平台定义。
+2. 如果映射不同，在 `src/core/superpowers.ts` 中更新 `SKILLS_AGENT_MAP`。
+3. 添加或更新测试，覆盖检测、安装路径和生成说明。
+4. 如果平台对用户可见，同步更新 README 文档。
+
+## 新增或更新 Skill
+
+1. 先在 `assets/skills-zh/` 编写或更新中文版本。
+2. 确认措辞与行为。
+3. 再同步 `assets/skills/` 下的英文版本。
+4. 新增 Skill 时同步加入 `assets/manifest.json`。
+5. 视情况补充生成资产或安装行为的测试。
+
+Skill 设计建议：
+
+- **Decision Core first**：面向 Agent 的决策说明放在顶部，包括阶段检测、分发逻辑、错误处理。
+- **Reference Appendix**：字段说明、脚本位置、最佳实践放在底部。
+- 中文和英文版本要保持行为等价，表达可以自然不同。
+
+## Shell 脚本
+
+脚本位于 `assets/skills/comet/scripts/`，必须兼容 macOS、Linux 和 Windows Git Bash。
+
+规则：
+
+- 禁止使用 `sed -i`；GNU 与 BSD 行为不同。字段替换使用 `awk`。
+- 同时兼容 GNU 系统的 `sha256sum` 与 BSD/macOS 的 `shasum -a 256`。
+- 所有可选 `grep` 结果都加 `|| true`，避免 `pipefail` 误杀脚本。
+- 新增脚本必须加入 `test/ts/comet-scripts.test.ts` 的 `beforeEach` 拷贝列表。
+- 新增脚本必须加入 `assets/manifest.json`。
+
+脚本依赖关系：
+
+```text
+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)
+```
+
+如果两个脚本需要同一个小工具函数，例如 hash 或 YAML 解析，允许在各自脚本中独立实现，不强制抽共享 shell 库。
+
+## `.comet.yaml` 状态变更
+
+修改 `.comet.yaml` 状态文件字段时，需要同步三处：
+
+1. `assets/skills/comet/scripts/comet-state.sh`：`cmd_set` 白名单与 enum 校验。
+2. `assets/skills/comet/scripts/comet-yaml-validate.sh`：schema 校验与 `KNOWN_KEYS`。
+3. `test/ts/comet-scripts.test.ts`：测试中的 YAML 示例与断言。
+
+## Changelog
+
+用户可见行为变化需要更新 `CHANGELOG.md`。新版本条目置顶，版本号必须与 `package.json` 一致。
+
+格式：
+
+```markdown
+## What's Changed [x.y.z] - YYYY-MM-DD
+
+### Added
+
+- **功能名**: 描述做了什么以及为什么。
+
+### Changed
+
+### Fixed
+
+### Tests
+
+### Removed
+
+### Security
+```
+
+规范：
+
+- 分组顺序：Added、Changed、Fixed、Tests、Removed、Security。
+- 每条以 `- **粗体关键词**: ` 开头。
+- 描述行为变化和原因，不写实现细节流水账。
+- `### Tests` 汇总覆盖场景，不逐条列测试用例。
+
+## 安全
+
+- 发布前扫描 API key、secret、token、private key。
+- 保持 `.npmignore` 准确，避免 source-only 文件和本地配置发布到 npm。
+- 保持 `.gitignore` 覆盖 secret、凭据和 IDE 特定文件。
+- 使用用户提供的 change name 作为文件路径前，必须校验 path traversal。