@rpamis/comet 0.2.2 → 0.2.4

package/README.md

@@ -1,3 +1,19 @@
+<p align="center">
+  <a href="https://github.com/rpamis/comet">
+    <picture>
+      <source srcset="img/title-log.png">
+      <img src="img/title-log.png" alt="Comet logo">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rpamis/comet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rpamis/comet/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+</p>
+
 # @rpamis/comet
 
 ```
@@ -15,6 +31,16 @@
 
 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
+
+OpenSpec excels at managing requirements, creating proposals, managing Spec lifecycles, and archiving, but its proposals and tasks lack the detail of Superpowers brainstorming.
+
+Superpowers generates Spec documents after brainstorming, but these documents typically lack stateful design — after completing requirements, Specs only have tasks checked off in the document, and Agents even forget to check them off. This causes the Agent to re-examine documents and project code to verify on resumption, wasting many tokens.
+
+**Comet combines the strengths of both**, integrating the core workflow into 5 phases
+
+The main entry `/comet` supports current Spec state detection, suitable for long tasks — after completing and closing CC midway, just `/comet continue` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
+
 ## Install
 
 ```bash
@@ -38,6 +64,20 @@ comet init
 6. Deploy Comet skills (in your chosen language) to selected platforms
 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
 
+> [!TIP]
+> update version
+>
+> comet update or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
+
+## Screenshots
+
+<p align="center">
+  <img src="img/runner.png" alt="runner">
+</p>
+
+<p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
+<p align="center">Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes</p>
+
 ## Commands
 
 | Command | Description |
@@ -164,15 +204,23 @@ Comet uses a decoupled state architecture with separate YAML files:
 | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
 
 **Key Fields in `.comet.yaml`:**
-- `workflow`: `full`, `hotfix`, or `tweak`
-- `phase`: `design`, `build`, `verify`, `archive`
-- `design_doc`: Path to Superpowers Design Doc
-- `plan`: Path to implementation plan
-- `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
-- `isolation`: `branch` or `worktree`, workspace isolation method
-- `verify_mode`: `light` or `full`
-- `verify_result`: `pending`, `pass`, or `fail`
-- `archived`: Boolean indicating if change is archived
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: docs/superpowers/reports/YYYY-MM-DD-change-verify.md
+branch_status: pending
+verified_at: null
+archived: false
+```
+
+All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use Comet's built-in commands to read state and know the current Spec's situation.
 
 ### Reliability Features
 
@@ -189,12 +237,18 @@ Comet ensures agent execution reliability through automated state transitions:
    - Guard and archive scripts use `comet-state.sh` internally for state management
 
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-   - Validates required fields (10 fields)
-   - Validates enum values (7 enum types)
+   - Validates required fields (12 fields)
+   - Validates enum values (8 enum types)
    - Validates referenced file paths exist
    - Detects unknown/typos fields
 
-4. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+4. **Verification Evidence** — Guard enforces proof before phase advance
+   - `verify-pass` transition requires `verification_report` pointing to an existing report file
+   - `branch_status` must be `handled` before verify can pass
+   - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
+   - Prevents false phase advances when verification or branch handling was skipped
+
+5. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
@@ -231,6 +285,16 @@ your-project/
     └── plans/                   # Implementation plans
 ```
 
+## What You'll Learn
+
+Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
+
+Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The Comet project can serve as a reference:
+
+- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). Comet will trigger many capabilities from OpenSpec and Superpowers — how is this Prompt written?
+
+- **How to make combined Skills multi-phase auto-flow** — Not relying on manual intervention. Comet's 5-phase flow automatically triggers Skills for core processes except necessary user selections, while the **state machine mechanism** also ensures state transition reliability.
+
 ## Development
 
 ```bash
@@ -267,4 +331,4 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
 ## License
 
-MIT
+[MIT](LICENSE.md)

package/assets/manifest.json

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

package/assets/skills/comet/SKILL.md

@@ -25,13 +25,20 @@ Agents need only read this section for decision-making. Refer to the Reference A
 **Step 0: Active Change Discovery**
 
 1. Run `openspec list --json` to get all active changes
-2. For each change, check `docs/superpowers/specs/` and `docs/superpowers/plans/` for associated files to determine phase and progress
 
-| Situation | Action |
-|-----------|--------|
-| No active change | → Invoke `/comet-open` |
-| Exactly 1 active change | → Auto-select, enter Step 1 |
-| Multiple active changes | → List for user selection |
+| Active changes | User input | Behavior |
+|----------------|------------|----------|
+| None | any | → Invoke `/comet-open` |
+| Exactly 1 | `/comet <description>` | → **Ask**: continue this change or create a new change |
+| Multiple | `/comet <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
+| Exactly 1 | `/comet` with no description | → Auto-select, enter Step 1 |
+| Multiple | `/comet` with no description | → List changes for user selection |
+
+<IMPORTANT>
+When the user chooses "create a new change", **must invoke `/comet-open`**. Do not call `/opsx:new` directly.
+`/comet-open` performs dual initialization: OpenSpec artifacts plus `.comet.yaml` state.
+Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
+</IMPORTANT>
 
 **Preset detection**:
 - User describes as bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
@@ -41,14 +48,23 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
 
+**Resume rules**:
+- On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
+- If `phase: build`, read the next unchecked task from tasks.md and continue
+- If `phase: verify` and `verify_result: fail`, first run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build`
+- If `phase: open` but proposal/design/tasks are complete, run `bash "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: archive`, only invoke `/comet-archive`; after archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
+
 **Step 2: Phase Determination** (check in order, first match wins)
 
 1. `archived: true` or change moved to archive → Workflow complete
 2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive`
-3. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
-4. `phase: build` or has Design Doc but plan/execution incomplete → Invoke `/comet-build`
-5. `phase: design` or has change but no Design Doc → Invoke `/comet-design`
-6. No active change or state undeterminable → Invoke `/comet-open`
+3. `verify_result: fail` → run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build`
+4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
+5. `phase: build` or has Design Doc but plan/execution incomplete → Invoke `/comet-build`
+6. `phase: design` or has change but no Design Doc → Invoke `/comet-design`
+7. `phase: open` or active change exists but `.comet.yaml` is missing → Invoke `/comet-open`
+8. No active change → Invoke `/comet-open`
 
 If metadata conflicts with file state, use verifiable file state as source of truth and correct `.comet.yaml` before continuing.
 
@@ -74,7 +90,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
 | `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `bash $COMET_STATE set` then continue |
-| Maven compile/test fails | Return to build phase for fixes, do not enter verify |
+| Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
 ### Phase Transitions
@@ -84,6 +100,8 @@ A single `/comet` invocation starts from the detected phase and advances to the
 
 Flow chain: open → design → build → verify → archive
 
+**Continuous execution requirement**: starting from the detected phase, the agent must automatically continue through all later phases without waiting for another user command, except at explicit decision points. After a phase completes, immediately enter the next phase.
+
 Nodes requiring user participation:
 1. Confirm design approach during brainstorming
 2. Select execution mode during build phase
@@ -160,9 +178,16 @@ archived: false
 Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
 
 ```bash
-COMET_GUARD="${COMET_GUARD:-$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)}"
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_ARCHIVE" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  return 1
+fi
 ```
 
 **Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
@@ -171,6 +196,17 @@ COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh
 bash "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
+`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
+
+```bash
+bash "$COMET_STATE" transition <change-name> open-complete
+bash "$COMET_STATE" transition <change-name> design-complete
+bash "$COMET_STATE" transition <change-name> build-complete
+bash "$COMET_STATE" transition <change-name> verify-pass
+bash "$COMET_STATE" transition <change-name> verify-fail
+bash "$COMET_STATE" transition <archive-name> archived
+```
+
 **Archive script**: Complete all archive steps in one command:
 
 ```bash

package/assets/skills/comet/scripts/comet-archive.sh

@@ -224,7 +224,7 @@ else
   step_ok "Moved to: $ARCHIVE_DIR"
 fi
 
-# --- Step 8: Update archived: true in .comet.yaml ---
+# --- Step 8: Mark archived via comet-state transition ---
 
 STEPS_TOTAL=$((STEPS_TOTAL + 1))
 
@@ -235,7 +235,7 @@ if [ "$DRY_RUN" -eq 1 ]; then
   STEPS_OK=$((STEPS_OK + 1))
 else
   if [ -f "$ARCHIVE_YAML" ]; then
-    sed -i 's/^archived:.*/archived: true/' "$ARCHIVE_YAML"
+    bash "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null
     step_ok "archived: true"
   else
     step_fail "archived: true (.comet.yaml not found after move)"

package/assets/skills/comet/scripts/comet-guard.sh

@@ -37,10 +37,14 @@ validate_change_name "$1"
 CHANGE="$1"
 PHASE="$2"
 APPLY=0
+SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
 if [[ "${3:-}" == "--apply" ]]; then
   APPLY=1
 fi
 CHANGE_DIR="openspec/changes/$CHANGE"
+if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
+  CHANGE_DIR="openspec/changes/archive/$CHANGE"
+fi
 
 BLOCK=0
 check() {
@@ -81,7 +85,6 @@ file_nonempty() {
 }
 
 preflight() {
-  local expected_phase="$1"
 
   if [ ! -d "$CHANGE_DIR" ]; then
     red "FATAL: change directory not found: $CHANGE_DIR"
@@ -92,17 +95,9 @@ preflight() {
     exit 1
   fi
 
-  local actual_phase
-  actual_phase=$(yaml_field_value "phase" 2>/dev/null || true)
-  if [ "$actual_phase" != "$expected_phase" ]; then
-    red "FATAL: .comet.yaml phase is '$actual_phase', expected '$expected_phase'"
-    exit 1
-  fi
-
   # Schema validation
-  local script_dir validate_script
-  script_dir="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-  validate_script="$script_dir/comet-yaml-validate.sh"
+  local validate_script
+  validate_script="$SCRIPT_DIR/comet-yaml-validate.sh"
   if [ -f "$validate_script" ]; then
     if ! bash "$validate_script" "$CHANGE" 2>/dev/null; then
       bash "$validate_script" "$CHANGE"
@@ -116,8 +111,19 @@ build_passes() {
   if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
     return 0
   fi
-  # Attempt common build commands; succeeds if any pass
-  (npm run build 2>/dev/null) || (mvn compile -q 2>/dev/null) || (cargo build 2>/dev/null) || true
+  if [ -f "package.json" ] && grep -q '"build"' "package.json"; then
+    npm run build >/dev/null
+    return $?
+  fi
+  if [ -f "pom.xml" ]; then
+    mvn compile -q >/dev/null
+    return $?
+  fi
+  if [ -f "Cargo.toml" ]; then
+    cargo build >/dev/null
+    return $?
+  fi
+  return 1
 }
 
 verify_result_is_pass() {
@@ -126,6 +132,18 @@ verify_result_is_pass() {
   [ "$result" = "pass" ]
 }
 
+verification_report_exists() {
+  local report
+  report=$(yaml_field_value "verification_report" 2>/dev/null || true)
+  [ -n "$report" ] && [ "$report" != "null" ] && [ -f "$report" ]
+}
+
+branch_status_handled() {
+  local status
+  status=$(yaml_field_value "branch_status" 2>/dev/null || true)
+  [ "$status" = "handled" ]
+}
+
 archived_is_true() {
   local val
   val=$(yaml_field_value "archived" 2>/dev/null || true)
@@ -135,7 +153,7 @@ archived_is_true() {
 # --- Phase-specific checks ---
 
 guard_open() {
-  echo "=== Guard: open → design ===" >&2
+  echo "=== Guard: open → next ===" >&2
 
   check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
   check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
@@ -170,9 +188,10 @@ guard_build() {
 guard_verify() {
   echo "=== Guard: verify → archive ===" >&2
 
-  check "verify_result is pass" verify_result_is_pass
   check "tasks.md all tasks checked" tasks_all_done
   check "Build passes" build_passes
+  check "verification_report exists" verification_report_exists
+  check "branch_status=handled" branch_status_handled
 }
 
 guard_archive() {
@@ -184,50 +203,30 @@ guard_archive() {
 }
 
 apply_state_update() {
-  local state_sh="$script_dir/comet-state.sh"
+  local state_sh="$SCRIPT_DIR/comet-state.sh"
   local p="$1"
 
   if [ -f "$state_sh" ]; then
     case "$p" in
-      open)   bash "$state_sh" set "$CHANGE" phase design ;;
-      design) bash "$state_sh" set "$CHANGE" phase build ;;
-      build)
-        bash "$state_sh" set "$CHANGE" phase verify
-        bash "$state_sh" set "$CHANGE" verify_result pending
-        ;;
-      verify)
-        bash "$state_sh" set "$CHANGE" phase archive
-        bash "$state_sh" set "$CHANGE" verify_result pass
-        bash "$state_sh" set "$CHANGE" verified_at "$(date +%Y-%m-%d)"
-        ;;
+      open)   bash "$state_sh" transition "$CHANGE" open-complete ;;
+      design) bash "$state_sh" transition "$CHANGE" design-complete ;;
+      build)  bash "$state_sh" transition "$CHANGE" build-complete ;;
+      verify) bash "$state_sh" transition "$CHANGE" verify-pass ;;
     esac
   else
-    local yaml="$CHANGE_DIR/.comet.yaml"
-    case "$p" in
-      open)   sed -i 's/^phase:.*/phase: design/' "$yaml" ;;
-      design) sed -i 's/^phase:.*/phase: build/' "$yaml" ;;
-      build)  sed -i 's/^phase:.*/phase: verify/' "$yaml"; sed -i 's/^verify_result:.*/verify_result: pending/' "$yaml" ;;
-      verify)
-        sed -i 's/^phase:.*/phase: archive/' "$yaml"
-        sed -i 's/^verify_result:.*/verify_result: pass/' "$yaml"
-        if ! grep -q '^verified_at:' "$yaml" 2>/dev/null; then
-          echo "verified_at: $(date +%Y-%m-%d)" >> "$yaml"
-        else
-          sed -i "s/^verified_at:.*/verified_at: $(date +%Y-%m-%d)/" "$yaml"
-        fi
-        ;;
-    esac
+    red "FATAL: comet-state.sh not found; cannot apply state transition"
+    exit 1
   fi
 }
 
 # --- Main ---
 
 case "$PHASE" in
-  open)     preflight "design"  ; guard_open ;;
-  design)   preflight "build"   ; guard_design ;;
-  build)    preflight "verify"  ; guard_build ;;
-  verify)   preflight "archive" ; guard_verify ;;
-  archive)  preflight "archive" ; guard_archive ;;
+  open)     preflight ; guard_open ;;
+  design)   preflight ; guard_design ;;
+  build)    preflight ; guard_build ;;
+  verify)   preflight ; guard_verify ;;
+  archive)  preflight ; guard_archive ;;
   *)
     red "Unknown phase: $PHASE"
     echo "Valid phases: open, design, build, verify, archive" >&2
@@ -245,7 +244,10 @@ else
   if [ "$APPLY" -eq 1 ]; then
     apply_state_update "$PHASE"
     case "$PHASE" in
-      open)   green "  [APPLY] .comet.yaml updated: phase=design" ;;
+      open)
+        new_phase=$(grep "^phase:" "$CHANGE_DIR/.comet.yaml" | sed 's/^phase: *//' | tr -d '"' | tr -d "'")
+        green "  [APPLY] .comet.yaml updated: phase=$new_phase"
+        ;;
       design) green "  [APPLY] .comet.yaml updated: phase=build" ;;
       build)  green "  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending" ;;
       verify) green "  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass" ;;