Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
@rpamis/comet
Advanced tools
@rpamis/comet - npm Package Compare versions
| # Dirty Worktree 协议 | ||
| 规范路径：`comet/reference/dirty-worktree.md` | ||
| 本协议由所有涉及代码修改的 comet 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。 | ||
| ## 1. 检查步骤 | ||
| 继续或开始修改前，必须先运行以下命令： | ||
| ```bash | ||
| git status --short | ||
| git diff --stat | ||
| git diff --cached --stat | ||
| git ls-files --others --exclude-standard | ||
| ``` | ||
| 必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。 | ||
| ## 2. 核心规则 | ||
| - 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源 | ||
| - dirty worktree 只代表代码事实，不会自动推进 `.comet.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 Comet 状态 | ||
| ## 3. 归因分类 | ||
| 将 dirty diff 分为三类： | ||
| 1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。将其纳入当前任务继续，不重复改同一处 | ||
| 2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃 | ||
| 3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段 | ||
| ## 4. 常见处理模式 | ||
| ### 已实现但 tasks.md 未勾选 | ||
| 先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。 | ||
| ### 暗示计划或范围已变化 | ||
| 按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。 | ||
| ### 模糊恢复意图 | ||
| 用户说"继续""接着跑""我改了一点""刚才不满意""重新弄""代码动过""先按现在的来"等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。 | ||
| ### open/design 阶段出现代码改动 | ||
| 若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段： | ||
| - 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard | ||
| - 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃 | ||
| - 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify | ||
| ## 5. 禁令 | ||
| - 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动 | ||
| - 禁止在 dirty diff 未解释清楚时判定验证通过 |
| # Dirty Worktree Protocol | ||
| Canonical path: `comet/reference/dirty-worktree.md` | ||
| This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol. | ||
| ## 1. Checks | ||
| Before continuing or starting code changes, run: | ||
| ```bash | ||
| git status --short | ||
| git diff --stat | ||
| git diff --cached --stat | ||
| git ls-files --others --exclude-standard | ||
| ``` | ||
| When needed, inspect `git diff`, `git diff --cached`, and newly created file contents. | ||
| ## 2. Core Rules | ||
| - The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources. | ||
| - A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard. | ||
| ## 3. Attribution | ||
| Classify dirty diffs into three groups: | ||
| 1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work. | ||
| 2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization. | ||
| 3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase. | ||
| ## 4. Common Patterns | ||
| ### Implemented But tasks.md Is Not Checked | ||
| Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill. | ||
| ### Plan Or Scope Changed | ||
| Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details. | ||
| ### Ambiguous Resume Intent | ||
| When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed. | ||
| ### Code Changes During open/design | ||
| If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly: | ||
| - If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build. | ||
| - If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization. | ||
| - Do not treat code changes made during open/design as completed implementation ready for verify. | ||
| ## 5. Prohibitions | ||
| - Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source. | ||
| - Do not mark verification as passed while dirty diff remains unexplained. |
@@ -5,2 +5,3 @@ { | ||
| "comet/SKILL.md", | ||
| "comet/reference/dirty-worktree.md", | ||
| "comet/scripts/comet-guard.sh", | ||
@@ -7,0 +8,0 @@ "comet/scripts/comet-state.sh", |
@@ -161,2 +161,4 @@ --- | ||
| - **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行 | ||
| - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理： | ||
| 1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 5「Spec 增量更新」分级处理 | ||
| - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交 | ||
@@ -163,0 +165,0 @@ |
@@ -66,2 +66,4 @@ --- | ||
| 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。 | ||
| **立即执行：** 按 tasks.md 逐个执行任务： | ||
@@ -68,0 +70,0 @@ |
@@ -69,2 +69,4 @@ --- | ||
| 继续或开始修改前，按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。若归因后发现范围超出 tweak，按本文件“升级条件”处理。 | ||
| **立即执行：** 按 tasks.md 逐个执行任务： | ||
@@ -71,0 +73,0 @@ |
@@ -23,3 +23,3 @@ --- | ||
| COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}" | ||
| bash "$COMET_STATE" check <name> verify | ||
| bash "$COMET_STATE" check <change-name> verify | ||
| ``` | ||
@@ -34,3 +34,3 @@ | ||
| ```bash | ||
| bash "$COMET_STATE" scale <name> | ||
| bash "$COMET_STATE" scale <change-name> | ||
| ``` | ||
@@ -40,6 +40,18 @@ | ||
| 验证开始前，按 `comet/reference/dirty-worktree.md` 协议检查并处理未提交改动。verify 阶段的特殊处理： | ||
| 1. 若 dirty diff 属于当前 change 且涉及实现、测试、tasks、delta spec 或 design doc 变更，不在 verify 阶段直接修复或提交；先记录失败并回退到 build 阶段 | ||
| 2. 若 dirty diff 只是 verify 本阶段产物（例如验证报告草稿、分支处理记录），可继续在 verify 阶段完成并记录状态 | ||
| 3. 若 dirty diff 已实现但 tasks.md 未勾选，视为 build 状态滞后；先记录失败并回退到 build 阶段，由 `/comet-build` 验证实现、补勾任务并提交 | ||
| 回退到 build 阶段： | ||
| ```bash | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
| 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核： | ||
| ```bash | ||
| PLAN=$(bash "$COMET_STATE" get <name> plan) | ||
| PLAN=$(bash "$COMET_STATE" get <change-name> plan) | ||
| BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//') | ||
@@ -52,3 +64,3 @@ git diff --stat "$BASE_REF"...HEAD | ||
| ```bash | ||
| bash "$COMET_STATE" set <name> verify_mode full | ||
| bash "$COMET_STATE" set <change-name> verify_mode full | ||
| ``` | ||
@@ -61,3 +73,3 @@ | ||
| 1. tasks.md 全部任务已完成 `[x]` | ||
| 2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照 tasks 内容） | ||
| 2. 改动文件与 tasks.md 描述一致（`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` 对照 tasks 内容） | ||
| 3. 编译通过（执行项目对应的构建命令，如 `npm run build`、`mvn compile`、`cargo build` 等） | ||
@@ -72,3 +84,3 @@ 4. 相关测试通过 | ||
| ```bash | ||
| bash "$COMET_STATE" transition <name> verify-fail | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
@@ -102,3 +114,3 @@ | ||
| ```bash | ||
| bash "$COMET_STATE" transition <name> verify-fail | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
@@ -137,4 +149,4 @@ | ||
| bash "$COMET_STATE" set <name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md | ||
| bash "$COMET_STATE" set <name> branch_status handled | ||
| bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md | ||
| bash "$COMET_STATE" set <change-name> branch_status handled | ||
| ``` | ||
@@ -141,0 +153,0 @@ |
@@ -55,2 +55,3 @@ --- | ||
| - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段 | ||
| - 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复 | ||
| - 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续 | ||
@@ -57,0 +58,0 @@ - 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build` |
@@ -161,2 +161,4 @@ --- | ||
| - **After context compaction**: read `.comet.yaml` to confirm the phase is still build, read the plan header `base-ref`, then read tasks.md to find the next unchecked task | ||
| - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling: | ||
| 1. After attribution, if the diff implies plan or spec changes, handle it through Step 5 "Spec Incremental Updates" | ||
| - **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits | ||
@@ -163,0 +165,0 @@ |
@@ -50,2 +50,8 @@ --- | ||
| Verify initialized state: | ||
| ```bash | ||
| bash "$COMET_STATE" check <name> open | ||
| ``` | ||
| Run phase guard to transition open → build: | ||
@@ -61,2 +67,4 @@ | ||
| Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions". | ||
| **Immediately execute:** Execute tasks one by one according to tasks.md: | ||
@@ -63,0 +71,0 @@ |
@@ -53,2 +53,8 @@ --- | ||
| Verify initialized state: | ||
| ```bash | ||
| bash "$COMET_STATE" check <name> open | ||
| ``` | ||
| Run phase guard to transition open → build: | ||
@@ -64,2 +70,4 @@ | ||
| Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the scope exceeds tweak, handle it through this file's "Upgrade Conditions". | ||
| **Immediately execute:** Execute tasks one by one according to tasks.md: | ||
@@ -66,0 +74,0 @@ |
@@ -23,3 +23,3 @@ --- | ||
| COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}" | ||
| bash "$COMET_STATE" check <name> verify | ||
| bash "$COMET_STATE" check <change-name> verify | ||
| ``` | ||
@@ -34,3 +34,3 @@ | ||
| ```bash | ||
| bash "$COMET_STATE" scale <name> | ||
| bash "$COMET_STATE" scale <change-name> | ||
| ``` | ||
@@ -40,6 +40,18 @@ | ||
| Before verification starts, inspect and handle uncommitted changes through `comet/reference/dirty-worktree.md`. Verify-specific handling: | ||
| 1. If dirty diff belongs to the current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify; record failure and return to build | ||
| 2. If dirty diff is only a verify-phase artifact, such as a verification report draft or branch-handling record, continue in verify and record state | ||
| 3. If dirty diff has implemented work but tasks.md is unchecked, treat it as stale build state; record failure and return to build so `/comet-build` verifies the implementation, checks off tasks, and commits | ||
| Return to build: | ||
| ```bash | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
| Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range: | ||
| ```bash | ||
| PLAN=$(bash "$COMET_STATE" get <name> plan) | ||
| PLAN=$(bash "$COMET_STATE" get <change-name> plan) | ||
| BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//') | ||
@@ -52,3 +64,3 @@ git diff --stat "$BASE_REF"...HEAD | ||
| ```bash | ||
| bash "$COMET_STATE" set <name> verify_mode full | ||
| bash "$COMET_STATE" set <change-name> verify_mode full | ||
| ``` | ||
@@ -61,3 +73,3 @@ | ||
| 1. All tasks in tasks.md completed `[x]` | ||
| 2. Changed files consistent with tasks.md description (compare `git diff --stat` against task content) | ||
| 2. Changed files consistent with tasks.md description (compare `git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` against task content) | ||
| 3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`) | ||
@@ -72,3 +84,3 @@ 4. Related tests pass | ||
| ```bash | ||
| bash "$COMET_STATE" transition <name> verify-fail | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
@@ -102,3 +114,3 @@ | ||
| ```bash | ||
| bash "$COMET_STATE" transition <name> verify-fail | ||
| bash "$COMET_STATE" transition <change-name> verify-fail | ||
| ``` | ||
@@ -128,2 +140,15 @@ | ||
| ### 4. Record Verification Evidence | ||
| The verification report must be written to disk and recorded in `.comet.yaml`; branch handling must also be written to state after it completes. Do not manually set `verify_result: pass`; guard performs the transition. | ||
| ```bash | ||
| mkdir -p docs/superpowers/reports | ||
| # Write this verification result to a report file, for example: | ||
| # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md | ||
| bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md | ||
| bash "$COMET_STATE" set <change-name> branch_status handled | ||
| ``` | ||
| ## Exit Conditions | ||
@@ -133,2 +158,4 @@ | ||
| - Branch handled | ||
| - `.comet.yaml` `verification_report` points to an existing verification report file | ||
| - `.comet.yaml` has `branch_status: handled` | ||
| - **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, it uses `comet-state transition verify-pass` to advance to `phase: archive` | ||
@@ -135,0 +162,0 @@ |
@@ -25,9 +25,15 @@ --- | ||
| **Step 0: Active Change Discovery** | ||
| **Step 0: Active Change Discovery and Intent Detection** | ||
| 1. Run `openspec list --json` to get all active changes | ||
| 1. Detect presets first; if hotfix/tweak matches, invoke the corresponding preset skill directly and do not enter the normal open branch | ||
| 2. When no preset matches, run `openspec list --json` to get all active changes | ||
| **Preset detection has highest priority**: | ||
| - User explicitly describes a bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix` | ||
| - User explicitly describes copy/config/docs/prompt small adjustment + meets tweak conditions → directly invoke `/comet-tweak` | ||
| - No preset match → follow the table below | ||
| | Active changes | User input | Behavior | | ||
| |----------------|------------|----------| | ||
| | None | any | → Invoke `/comet-open` | | ||
| | None | non-preset input | → Invoke `/comet-open` | | ||
| | Exactly 1 | `/comet <description>` | → **Ask**: continue this change or create a new change | | ||
@@ -44,6 +50,2 @@ | Multiple | `/comet <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection | | ||
| **Preset detection**: | ||
| - User describes as bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix` | ||
| - User describes as copy, config, docs, prompt or small non-bug adjustment + meets tweak conditions → directly invoke `/comet-tweak` | ||
| **Step 1: Read `.comet.yaml` state metadata** | ||
@@ -55,2 +57,3 @@ | ||
| - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection | ||
| - If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them | ||
| - If `phase: build`, read the next unchecked task from tasks.md and continue | ||
@@ -57,0 +60,0 @@ - If `phase: verify` and `verify_result: fail`, first run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build` |
+1
-1
| { | ||
| "name": "@rpamis/comet", | ||
| "version": "0.2.9", | ||
| "version": "0.3.0", | ||
| "description": "OpenSpec + Superpowers dual-star development workflow", | ||
@@ -5,0 +5,0 @@ "keywords": [ |
+15
-1
@@ -35,4 +35,8 @@ <p align="center"> | ||
| 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. | ||
| 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 | ||
@@ -98,2 +102,8 @@ | ||
| ## Support for OpenClaw and Hermes, and other AI platforms | ||
| ```bash | ||
| npx skills add rpamis/comet | ||
| ``` | ||
| ## Screenshots | ||
@@ -394,2 +404,6 @@ | ||
| ## Star History | ||
| [](https://star-history.com/#rpamis/comet&Date) | ||
| ## License | ||
@@ -396,0 +410,0 @@ |
New alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Fixed alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
306054
3.93%- Number of package files
77
2.67%- Lines of code
1426
0.07%- Number of lines in readme file
412
3.52%No dependency changes